@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/business-examples/business-examples-inter-location-transfers.md

@@ -1,2162 +1,2162 @@
-# Versori Inter-Location Transfer Processing
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Webhook-triggered or scheduled workflow for processing inventory transfers between warehouses/stores with in-transit tracking
-
-**Complexity**: Medium
-
-**Runtime**: Versori Platform (Webhook/Scheduled)
-
-**Estimated Lines**: ~1,200 lines (modular, production-ready)
-
-## What You'll Build
-
-- Versori webhook/scheduled workflow for transfer requests
-- CSV and JSON input format support
-- Parse transfer data (source, destination, items, quantities)
-- Create paired dispatch/receipt mutations (GraphQL)
-- In-transit inventory tracking with VersoriKV
-- Variance handling (damaged items, shortages)
-- Rollback logic on failure
-- Email notifications on completion
-- Approval workflow for variances > 5%
-
-## SDK Methods Used
-
-- `createClient(ctx)` - Auto-detects Versori context
-- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - Map transfers to GraphQL mutations
-- `mapper.mapWithNodes(sourceData)` - Transform transfer data (resolvers from constructor)
-- `client.graphql(payload)` - Execute mutations
-- `VersoriKVAdapter(openKv())` - State management
-- `StateService(logger)` - Distributed locking
-- `UniversalMapper(mappingConfig)` - CSV field mapping
-- `CSVParserService()` - Parse CSV transfer files
-
----
-
-## Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-inter-location-transfers/
-├── index.ts                              # Entry point - registers all workflows
-└── src/
-    ├── workflows/
-    │   ├── webhook/
-    │   │   ├── initiate-transfer.ts      # Webhook: Process transfer requests
-    │   │   ├── receive-transfer.ts       # Webhook: Receipt confirmation
-    │   │   └── export-transfer-report.ts # Webhook: Export reports
-    │   │
-    │   └── scheduled/
-    │       └── reconcile-transfers.ts    # Scheduled: Daily reconciliation
-    │
-    ├── services/
-    │   └── transfer.service.ts           # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── transfer-mapping.json         # Mapping configuration
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Scalable (add new workflows without cluttering)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Easy to modify individual workflows without affecting others
-
----
-
-## Use Case Profile
-
-- **Volume**: Medium (50-500 transfers/day)
-- **Latency**: Near real-time (< 5 minutes)
-- **Complexity**: Medium (paired mutations, state tracking, variance handling)
-- **Pattern**: Webhook/scheduled → parse → dispatch mutation → receipt mutation → state tracking
-
----
-
-## Complete Working Code
-
-### 1. Entry Point: `index.ts`
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * ⚠️ CRITICAL PATTERN: MemoryInterpreter Setup
- * This pattern ensures workflows execute in the correct Versori runtime context
- * and prevents "unexpected export" errors during deployment.
- *
- * COMPONENTS:
- * 1. Import ALL workflows (scheduled, webhook, etc.)
- * 2. Create MemoryInterpreter with workflow array
- * 3. NO direct exports - interpreter handles workflow registration
- *
- * File Structure:
- * - src/workflows/scheduled/ → Time-based triggers (cron)
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- */
-
-import { MemoryInterpreter } from '@versori/run';
-
-// Import webhook workflows
-import { initiateTransfer } from './src/workflows/webhook/initiate-transfer';
-import { receiveTransfer } from './src/workflows/webhook/receive-transfer';
-import { exportTransferReport } from './src/workflows/webhook/export-transfer-report';
-
-// Import scheduled workflows
-import { reconcileTransfers } from './src/workflows/scheduled/reconcile-transfers';
-
-// ✅ CORRECT: Register via MemoryInterpreter (Versori standard)
-new MemoryInterpreter([
-  // Webhooks (HTTP-based triggers)
-  initiateTransfer,
-  receiveTransfer,
-  exportTransferReport,
-
-  // Scheduled (time-based triggers)
-  reconcileTransfers,
-]);
-
-// ❌ WRONG: Direct exports cause "unexpected export" errors
-// export { initiateTransfer, receiveTransfer, reconcileTransfers };
-
-/**
- * What Gets Exposed:
- * ✅ initiateTransfer → https://{workspace}.versori.run/initiate-transfer
- * ✅ receiveTransfer → https://{workspace}.versori.run/receive-transfer
- * ✅ exportTransferReport → https://{workspace}.versori.run/export-transfer-report
- * ❌ reconcileTransfers → NOT exposed (runs automatically on cron)
- */
-```
-
----
-
-### 2. Service File: `src/services/transfer.service.ts`
-
-```typescript
-/**
- * Transfer Service - Shared orchestration logic
- *
- * This service provides reusable business logic for transfer processing:
- * - Dispatch mutations (remove from source)
- * - Receipt mutations (add to destination)
- * - Variance calculation and approval
- * - Rollback logic on failure
- * - State management with VersoriKV
- * - Distributed locking for concurrency
- *
- * All business logic is centralized here - workflows just delegate to service functions.
- */
-
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno
-import {
-  createClient,
-  GraphQLMutationMapper,
-  UniversalMapper,
-  VersoriKVAdapter,
-  StateService,
-  CSVParserService,
-  S3DataSource,
-} from '@fluentcommerce/fc-connect-sdk';
-
-import type {
-  FluentClient,
-  Logger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Transfer data interfaces
- */
-export interface TransferRequest {
-  transferId: string;
-  sourceLocationRef: string;
-  destinationLocationRef: string;
-  requestedDate: string;
-  expectedDeliveryDate?: string;
-  items: TransferItem[];
-  metadata?: {
-    reason?: string;
-    priority?: string;
-    requestedBy?: string;
-  };
-}
-
-export interface TransferItem {
-  skuRef: string;
-  requestedQty: number;
-  actualQty?: number; // For receipt confirmation
-  condition?: string;
-  notes?: string;
-}
-
-export interface TransferState {
-  transferId: string;
-  status: 'PENDING' | 'DISPATCHED' | 'IN_TRANSIT' | 'RECEIVED' | 'FAILED' | 'ROLLED_BACK';
-  dispatchMutationId?: string;
-  receiptMutationId?: string;
-  dispatchedAt?: string;
-  receivedAt?: string;
-  variance?: VarianceDetails;
-  originalRequest?: TransferRequest;
-  receiptData?: any;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface VarianceDetails {
-  hasVariance: boolean;
-  variancePercentage: number;
-  requiresApproval: boolean;
-  items: {
-    skuRef: string;
-    expected: number;
-    actual: number;
-    difference: number;
-    reason?: string;
-  }[];
-}
-
-export interface TransferResult {
-  success: boolean;
-  transferId?: string;
-  status?: string;
-  dispatchMutationId?: string;
-  receiptMutationId?: string;
-  variance?: VarianceDetails;
-  error?: string;
-  currentStatus?: string;
-  message?: string;
-  recommendation?: string;
-}
-
-/**
- * Process transfer request (dispatch from source)
- *
- * This function orchestrates the complete transfer dispatch:
- * 1. Client initialization with retailerId
- * 2. Lock acquisition for concurrency control
- * 3. Transfer state initialization
- * 4. Dispatch mutation creation
- * 5. State updates and cleanup
- *
- * @param ctx - Versori context object
- * @param transferRequest - Transfer request data
- */
-export async function processTransferRequest(
-  ctx: any,
-  transferRequest: TransferRequest
-): Promise<TransferResult> {
-  const { log, activation, openKv } = ctx;
-  const startTime = Date.now();
-
-  log.info('═══════════════════════════════════════════════════════');
-  log.info('🚀 TRANSFER REQUEST PROCESSING STARTED', {
-    transferId: transferRequest.transferId,
-    sourceLocation: transferRequest.sourceLocationRef,
-    destinationLocation: transferRequest.destinationLocationRef,
-    itemCount: transferRequest.items.length,
-  });
-  log.info('═══════════════════════════════════════════════════════');
-
-  try {
-    // Initialize client with retailerId and validateConnection
-    log.info('🔧 Initializing Fluent Commerce client...');
-    const client = await createClient({ ...ctx, validateConnection: true });
-    const fluentRetailerId = activation.getVariable('fluentRetailerId');
-
-    if (!fluentRetailerId) {
-      log.error('❌ Missing required fluentRetailerId activation variable');
-      return {
-        success: false,
-        error: 'fluentRetailerId activation variable is required',
-        recommendation: 'Please configure fluentRetailerId in the Activation Variables section',
-      };
-    }
-
-    client.setRetailerId(fluentRetailerId);
-    log.info('✅ Client initialized', { retailerId: fluentRetailerId });
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-
-    // Check if transfer already processed
-    log.info('🔍 Checking transfer state...');
-    const existingState = await getTransferState(kvAdapter, transferRequest.transferId);
-
-    if (existingState && existingState.status !== 'FAILED') {
-      log.warn('⚠️ Transfer already processed', {
-        transferId: transferRequest.transferId,
-        status: existingState.status,
-      });
-      return {
-        success: false,
-        error: 'Transfer already processed',
-        transferId: transferRequest.transferId,
-        currentStatus: existingState.status,
-      };
-    }
-
-    // Acquire lock to prevent concurrent processing
-    log.info('🔒 Acquiring transfer lock...');
-    const lockName = `transfer-lock:${transferRequest.transferId}`;
-    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
-
-    if (!lockAcquired) {
-      log.warn('⚠️ Could not acquire lock - transfer already being processed');
-      return {
-        success: false,
-        error: 'Transfer is already being processed',
-        transferId: transferRequest.transferId,
-      };
-    }
-
-    try {
-      // Create initial transfer state
-      log.info('📝 Initializing transfer state...');
-      const transferState: TransferState = {
-        transferId: transferRequest.transferId,
-        status: 'PENDING',
-        originalRequest: transferRequest,
-        createdAt: new Date().toISOString(),
-        updatedAt: new Date().toISOString(),
-      };
-      await saveTransferState(kvAdapter, transferState);
-      log.info('✅ Transfer state initialized');
-
-      // Step 1: Create dispatch mutation (remove from source)
-      log.info('📦 Creating dispatch mutation...');
-      const dispatchStartTime = Date.now();
-      const dispatchResult = await createDispatchMutation(client, transferRequest, log);
-
-      if (!dispatchResult.success) {
-        throw new Error(`Dispatch failed: ${dispatchResult.error}`);
-      }
-
-      const dispatchDuration = Date.now() - dispatchStartTime;
-      log.info('✅ Dispatch mutation created', {
-        mutationId: dispatchResult.mutationId,
-        duration: `${dispatchDuration}ms`,
-      });
-
-      // Update state with dispatch info
-      transferState.status = 'DISPATCHED';
-      transferState.dispatchMutationId = dispatchResult.mutationId;
-      transferState.dispatchedAt = new Date().toISOString();
-      transferState.updatedAt = new Date().toISOString();
-      await saveTransferState(kvAdapter, transferState);
-
-      // Step 2: Mark as in-transit
-      transferState.status = 'IN_TRANSIT';
-      transferState.updatedAt = new Date().toISOString();
-      await saveTransferState(kvAdapter, transferState);
-      log.info('✅ Transfer marked as in-transit');
-
-      const totalDuration = Date.now() - startTime;
-      log.info('═══════════════════════════════════════════════════════');
-      log.info('✅ TRANSFER REQUEST COMPLETED', {
-        transferId: transferRequest.transferId,
-        status: 'IN_TRANSIT',
-        duration: `${totalDuration}ms`,
-      });
-      log.info('═══════════════════════════════════════════════════════');
-
-      // For webhook trigger, return success after dispatch
-      // Receipt will be confirmed via separate webhook
-      return {
-        success: true,
-        transferId: transferRequest.transferId,
-        status: 'IN_TRANSIT',
-        dispatchMutationId: dispatchResult.mutationId,
-        message: 'Transfer dispatched successfully, awaiting receipt confirmation',
-      };
-    } finally {
-      // Always release lock
-      log.info('🔓 Releasing transfer lock...');
-      await stateService.releaseLock(lockName, kvAdapter);
-    }
-  } catch (error: any) {
-    const duration = Date.now() - startTime;
-    log.error('═══════════════════════════════════════════════════════');
-    log.error('❌ TRANSFER REQUEST FAILED', {
-      transferId: transferRequest.transferId,
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      duration: `${duration}ms`,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check mapping configuration and verify transfer request payload structure'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : error.message?.includes('lock') || error.message?.includes('concurrent')
-        ? 'Concurrent transfer processing detected - retry after lock release'
-        : 'Review error details and check transfer request payload structure',
-    });
-    log.error('═══════════════════════════════════════════════════════');
-
-    return {
-      success: false,
-      error: error.message,
-      transferId: transferRequest.transferId,
-    };
-  }
-}
-
-/**
- * Process receipt confirmation (add to destination)
- */
-export async function processReceiptConfirmation(
-  ctx: any,
-  receiptData: { transferId: string; receivedDate: string; items: TransferItem[] }
-): Promise<TransferResult> {
-  const { log, activation, openKv } = ctx;
-  const startTime = Date.now();
-
-  log.info('═══════════════════════════════════════════════════════');
-  log.info('📦 RECEIPT CONFIRMATION STARTED', {
-    transferId: receiptData.transferId,
-    itemCount: receiptData.items.length,
-  });
-  log.info('═══════════════════════════════════════════════════════');
-
-  try {
-    const client = await createClient({ ...ctx, validateConnection: true });
-    const fluentRetailerId = activation.getVariable('fluentRetailerId');
-
-    if (fluentRetailerId) {
-      client.setRetailerId(fluentRetailerId);
-    }
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-
-    // Get transfer state
-    log.info('🔍 Retrieving transfer state...');
-    const transferState = await getTransferState(kvAdapter, receiptData.transferId);
-
-    if (!transferState) {
-      throw new Error('Transfer not found');
-    }
-
-    if (transferState.status !== 'IN_TRANSIT') {
-      throw new Error(`Invalid transfer status: ${transferState.status}`);
-    }
-
-    // Acquire lock
-    log.info('🔒 Acquiring transfer lock...');
-    const lockName = `transfer-lock:${receiptData.transferId}`;
-    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
-
-    if (!lockAcquired) {
-      throw new Error('Could not acquire lock');
-    }
-
-    try {
-      // Calculate variance
-      log.info('🔍 Calculating variance...');
-      const variance = calculateVariance(
-        transferState.originalRequest?.items || receiptData.items,
-        receiptData.items
-      );
-      transferState.variance = variance;
-      transferState.receiptData = receiptData;
-
-      log.info('📊 Variance calculated', {
-        hasVariance: variance.hasVariance,
-        variancePercentage: variance.variancePercentage.toFixed(2) + '%',
-        requiresApproval: variance.requiresApproval,
-      });
-
-      // Check if variance requires approval (> 5%)
-      if (variance.requiresApproval) {
-        transferState.status = 'PENDING';
-        transferState.updatedAt = new Date().toISOString();
-        await saveTransferState(kvAdapter, transferState);
-
-        log.warn('⚠️ Variance requires approval', {
-          variancePercentage: variance.variancePercentage.toFixed(2) + '%',
-        });
-
-        // Send email notification
-        await sendVarianceNotification(receiptData.transferId, variance, activation, log);
-
-        const duration = Date.now() - startTime;
-        log.info('═══════════════════════════════════════════════════════');
-        log.info('⚠️ RECEIPT PENDING APPROVAL', {
-          transferId: receiptData.transferId,
-          duration: `${duration}ms`,
-        });
-        log.info('═══════════════════════════════════════════════════════');
-
-        return {
-          success: true,
-          status: 'PENDING_APPROVAL',
-          transferId: receiptData.transferId,
-          variance,
-          message: 'Variance requires manual approval',
-        };
-      }
-
-      // Create receipt mutation (add to destination)
-      log.info('📦 Creating receipt mutation...');
-      const receiptStartTime = Date.now();
-      const receiptResult = await createReceiptMutation(
-        client,
-        receiptData.transferId,
-        receiptData.items,
-        transferState,
-        log
-      );
-
-      if (!receiptResult.success) {
-        throw new Error(`Receipt failed: ${receiptResult.error}`);
-      }
-
-      const receiptDuration = Date.now() - receiptStartTime;
-      log.info('✅ Receipt mutation created', {
-        mutationId: receiptResult.mutationId,
-        duration: `${receiptDuration}ms`,
-      });
-
-      // Update state
-      transferState.status = 'RECEIVED';
-      transferState.receiptMutationId = receiptResult.mutationId;
-      transferState.receivedAt = new Date().toISOString();
-      transferState.updatedAt = new Date().toISOString();
-      await saveTransferState(kvAdapter, transferState);
-
-      // Send completion notification
-      await sendCompletionNotification(receiptData.transferId, transferState, activation, log);
-
-      const totalDuration = Date.now() - startTime;
-      log.info('═══════════════════════════════════════════════════════');
-      log.info('✅ RECEIPT CONFIRMATION COMPLETED', {
-        transferId: receiptData.transferId,
-        duration: `${totalDuration}ms`,
-      });
-      log.info('═══════════════════════════════════════════════════════');
-
-      return {
-        success: true,
-        status: 'RECEIVED',
-        transferId: receiptData.transferId,
-        receiptMutationId: receiptResult.mutationId,
-        variance: variance.hasVariance ? variance : undefined,
-      };
-    } finally {
-      log.info('🔓 Releasing transfer lock...');
-      await stateService.releaseLock(lockName, kvAdapter);
-    }
-  } catch (error: any) {
-    const duration = Date.now() - startTime;
-    log.error('═══════════════════════════════════════════════════════');
-    log.error('❌ RECEIPT CONFIRMATION FAILED', {
-      transferId: receiptData.transferId,
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      duration: `${duration}ms`,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('not found') || error.message?.includes('missing')
-        ? 'Transfer not found - verify transferId and check transfer state in KV store'
-        : error.message?.includes('status') || error.message?.includes('invalid')
-        ? 'Invalid transfer status - ensure transfer is in IN_TRANSIT status'
-        : error.message?.includes('lock') || error.message?.includes('concurrent')
-        ? 'Concurrent receipt processing detected - retry after lock release'
-        : error.message?.includes('variance') || error.message?.includes('approval')
-        ? 'Variance requires approval - check variance calculation and approval workflow'
-        : 'Review error details and check receipt confirmation payload structure',
-    });
-    log.error('═══════════════════════════════════════════════════════');
-
-    return {
-      success: false,
-      error: error.message,
-      transferId: receiptData.transferId,
-    };
-  }
-}
-
-/**
- * Process variance approval/rejection
- */
-export async function processVarianceApproval(
-  ctx: any,
-  approvalData: { transferId: string; approved: boolean; notes?: string }
-): Promise<TransferResult> {
-  const { log, activation, openKv } = ctx;
-  const { transferId, approved, notes } = approvalData;
-  const startTime = Date.now();
-
-  log.info('═══════════════════════════════════════════════════════');
-  log.info('📝 VARIANCE APPROVAL PROCESSING', {
-    transferId,
-    approved,
-  });
-  log.info('═══════════════════════════════════════════════════════');
-
-  try {
-    const client = await createClient({ ...ctx, validateConnection: true });
-    const fluentRetailerId = activation.getVariable('fluentRetailerId');
-
-    if (fluentRetailerId) {
-      client.setRetailerId(fluentRetailerId);
-    }
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-
-    const transferState = await getTransferState(kvAdapter, transferId);
-    if (!transferState) {
-      throw new Error('Transfer not found');
-    }
-
-    const lockName = `transfer-lock:${transferId}`;
-    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
-    if (!lockAcquired) {
-      throw new Error('Could not acquire lock');
-    }
-
-    try {
-      if (!approved) {
-        // Rollback: reverse the dispatch
-        log.info('❌ Variance rejected - rolling back transfer...');
-        const rollbackResult = await rollbackTransfer(client, transferState, log);
-
-        transferState.status = 'ROLLED_BACK';
-        transferState.updatedAt = new Date().toISOString();
-        await saveTransferState(kvAdapter, transferState);
-
-        const duration = Date.now() - startTime;
-        log.info('═══════════════════════════════════════════════════════');
-        log.info('✅ TRANSFER ROLLED BACK', {
-          transferId,
-          duration: `${duration}ms`,
-        });
-        log.info('═══════════════════════════════════════════════════════');
-
-        return {
-          success: true,
-          status: 'ROLLED_BACK',
-          transferId,
-          message: 'Transfer rolled back due to variance rejection',
-        };
-      }
-
-      // Approved: complete receipt with actual quantities
-      log.info('✅ Variance approved - completing receipt...');
-      const receiptData = transferState.receiptData;
-      if (!receiptData) {
-        throw new Error('Receipt data not found in transfer state');
-      }
-
-      const receiptResult = await createReceiptMutation(
-        client,
-        transferId,
-        receiptData.items,
-        transferState,
-        log
-      );
-
-      if (!receiptResult.success) {
-        throw new Error(`Receipt failed: ${receiptResult.error}`);
-      }
-
-      transferState.status = 'RECEIVED';
-      transferState.receiptMutationId = receiptResult.mutationId;
-      transferState.receivedAt = new Date().toISOString();
-      transferState.updatedAt = new Date().toISOString();
-      await saveTransferState(kvAdapter, transferState);
-
-      const duration = Date.now() - startTime;
-      log.info('═══════════════════════════════════════════════════════');
-      log.info('✅ VARIANCE APPROVAL COMPLETED', {
-        transferId,
-        duration: `${duration}ms`,
-      });
-      log.info('═══════════════════════════════════════════════════════');
-
-      return {
-        success: true,
-        status: 'RECEIVED',
-        transferId,
-        receiptMutationId: receiptResult.mutationId,
-      };
-    } finally {
-      await stateService.releaseLock(lockName, kvAdapter);
-    }
-  } catch (error: any) {
-    const duration = Date.now() - startTime;
-    log.error('═══════════════════════════════════════════════════════');
-    log.error('❌ VARIANCE APPROVAL FAILED', {
-      transferId,
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      duration: `${duration}ms`,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('not found') || error.message?.includes('missing')
-        ? 'Transfer not found or receipt data missing - verify transferId and transfer state'
-        : error.message?.includes('lock') || error.message?.includes('concurrent')
-        ? 'Concurrent approval processing detected - retry after lock release'
-        : error.message?.includes('receipt') || error.message?.includes('mutation')
-        ? 'Check receipt mutation payload and inventory availability at destination'
-        : 'Review error details and check variance approval payload structure',
-    });
-    log.error('═══════════════════════════════════════════════════════');
-
-    return {
-      success: false,
-      error: error.message,
-      transferId,
-    };
-  }
-}
-
-/**
- * Run reconciliation (scheduled)
- */
-export async function runReconciliation(
-  ctx: any,
-  jobId: string,
-  tracker: any
-): Promise<any> {
-  const { log, openKv } = ctx;
-  const startTime = Date.now();
-
-  log.info('═══════════════════════════════════════════════════════');
-  log.info('🔄 RECONCILIATION STARTED', { jobId });
-  log.info('═══════════════════════════════════════════════════════');
-
-  try {
-    await tracker.updateJob(jobId, { stage: 'discovery', status: 'processing' });
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-
-    // Find all in-transit transfers older than 24 hours
-    log.info('🔍 Discovering stale transfers...');
-    const allTransfers = await getAllTransferStates(kvAdapter);
-    const staleTransfers = allTransfers.filter(t => {
-      if (t.status !== 'IN_TRANSIT') return false;
-      const dispatchedAt = new Date(t.dispatchedAt || t.createdAt);
-      const hoursSinceDispatch = (Date.now() - dispatchedAt.getTime()) / (1000 * 60 * 60);
-      return hoursSinceDispatch > 24;
-    });
-
-    log.info('📊 Stale transfers found', { count: staleTransfers.length });
-
-    await tracker.updateJob(jobId, {
-      stage: 'processing',
-      metadata: { staleCount: staleTransfers.length },
-    });
-
-    // Process each stale transfer (generate alerts, etc.)
-    let alertsSent = 0;
-    for (const transfer of staleTransfers) {
-      log.warn('⚠️ Stale transfer detected', {
-        transferId: transfer.transferId,
-        status: transfer.status,
-        age: Math.floor((Date.now() - new Date(transfer.dispatchedAt || transfer.createdAt).getTime()) / (1000 * 60 * 60)) + ' hours',
-      });
-      // Send alert email (implement as needed)
-      alertsSent++;
-    }
-
-    const duration = Date.now() - startTime;
-    const result = {
-      staleTransfersFound: staleTransfers.length,
-      alertsSent,
-      duration: `${duration}ms`,
-    };
-
-    log.info('═══════════════════════════════════════════════════════');
-    log.info('✅ RECONCILIATION COMPLETED', result);
-    log.info('═══════════════════════════════════════════════════════');
-
-    return result;
-  } catch (error: any) {
-    const duration = Date.now() - startTime;
-    log.error('═══════════════════════════════════════════════════════');
-    log.error('❌ RECONCILIATION FAILED', {
-      jobId,
-      error: error instanceof Error ? error.message : String(error),
-      duration: `${duration}ms`,
-    });
-    log.error('═══════════════════════════════════════════════════════');
-    throw error;
-  }
-}
-
-/**
- * Helper: Create dispatch mutation (remove from source location)
- */
-async function createDispatchMutation(
-  client: FluentClient,
-  transferRequest: TransferRequest,
-  log: Logger
-): Promise<{ success: boolean; mutationId?: string; error?: string }> {
-  try {
-    const dispatchMapper = new GraphQLMutationMapper(
-      {
-        version: '1.0.0',
-        mutation: 'updateInventoryQuantity',
-        sourceFormat: 'json',
-        fields: {
-          'input.ref': {
-            resolver: 'custom.generateDispatchRef',
-          },
-          'input.locationRef': {
-            source: 'sourceLocationRef',
-          },
-          'input.items[]': {
-            source: 'items',
-            fields: {
-              skuRef: { source: 'skuRef' },
-              qty: {
-                source: 'requestedQty',
-                resolver: 'custom.negateQty', // Make negative for dispatch
-              },
-              type: { value: 'DISPATCH' },
-              status: { value: 'AVAILABLE' },
-            },
-          },
-        },
-        returnFields: ['id', 'ref'],
-      } as any,
-      client,
-      log
-    );
-
-    // Custom resolvers
-    const resolvers = {
-      'custom.generateDispatchRef': () => {
-        return `DISPATCH-${transferRequest.transferId}-${Date.now()}`;
-      },
-      'custom.negateQty': (qty: any) => {
-        return -Math.abs(qty);
-      },
-    };
-
-    const result = await dispatchMapper.mapWithNodes(transferRequest, resolvers, {
-      config: {},
-      helpers: {},
-    });
-
-    if (!result.success) {
-      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
-    }
-
-    // Execute mutation (query is auto-generated in result)
-    const response = await client.graphql({
-      query: result.query,
-      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
-    });
-
-    return {
-      success: true,
-      mutationId: response.data?.updateInventoryQuantity?.id,
-    };
-  } catch (error: any) {
-    log.error('❌ Dispatch mutation failed', {
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check dispatch mapping configuration and verify transfer request structure'
-        : error.message?.includes('inventory') || error.message?.includes('quantity')
-        ? 'Check available inventory quantity at source location'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : 'Review error details and check dispatch mutation payload',
-    });
-
-    return {
-      success: false,
-      error: error.message,
-    };
-  }
-}
-
-/**
- * Helper: Create receipt mutation (add to destination location)
- */
-async function createReceiptMutation(
-  client: FluentClient,
-  transferId: string,
-  items: TransferItem[],
-  transferState: TransferState,
-  log: Logger
-): Promise<{ success: boolean; mutationId?: string; error?: string }> {
-  try {
-    const receiptMapper = new GraphQLMutationMapper(
-      {
-        version: '1.0.0',
-        mutation: 'updateInventoryQuantity',
-        sourceFormat: 'json',
-        fields: {
-          'input.ref': {
-            value: `RECEIPT-${transferId}-${Date.now()}`,
-          },
-          'input.locationRef': {
-            source: 'destinationLocationRef',
-          },
-          'input.items[]': {
-            source: 'items',
-            fields: {
-              skuRef: { source: 'skuRef' },
-              qty: {
-                source: 'actualQty',
-                defaultValue: { source: 'requestedQty' }, // Use requested if actual not provided
-              },
-              type: { value: 'RECEIPT' },
-              status: { value: 'AVAILABLE' },
-            },
-          },
-        },
-        returnFields: ['id', 'ref'],
-      } as any,
-      client,
-      log
-    );
-
-    const sourceData = {
-      destinationLocationRef: transferState.originalRequest?.destinationLocationRef,
-      items,
-    };
-
-    const result = await receiptMapper.mapWithNodes(sourceData, {}, { config: {}, helpers: {} });
-
-    if (!result.success) {
-      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
-    }
-
-    // Execute mutation (query is auto-generated in result)
-    const response = await client.graphql({
-      query: result.query,
-      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
-    });
-
-    return {
-      success: true,
-      mutationId: response.data?.updateInventoryQuantity?.id,
-    };
-  } catch (error: any) {
-    log.error('❌ Receipt mutation failed', {
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check receipt mapping configuration and verify receipt data structure'
-        : error.message?.includes('inventory') || error.message?.includes('quantity')
-        ? 'Check actual quantity values and variance calculation'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : 'Review error details and check receipt mutation payload',
-    });
-
-    return {
-      success: false,
-      error: error.message,
-    };
-  }
-}
-
-/**
- * Helper: Rollback transfer (reverse dispatch)
- */
-async function rollbackTransfer(
-  client: FluentClient,
-  transferState: TransferState,
-  log: Logger
-): Promise<{ success: boolean; error?: string }> {
-  try {
-    const originalRequest = transferState.originalRequest;
-
-    if (!originalRequest) {
-      throw new Error('Cannot rollback: original request data missing');
-    }
-
-    const rollbackMapper = new GraphQLMutationMapper(
-      {
-        version: '1.0.0',
-        mutation: 'updateInventoryQuantity',
-        sourceFormat: 'json',
-        fields: {
-          'input.ref': {
-            value: `ROLLBACK-${transferState.transferId}-${Date.now()}`,
-          },
-          'input.locationRef': {
-            source: 'sourceLocationRef',
-          },
-          'input.items[]': {
-            source: 'items',
-            fields: {
-              skuRef: { source: 'skuRef' },
-              qty: { source: 'requestedQty' }, // Add back to source
-              type: { value: 'ROLLBACK' },
-              status: { value: 'AVAILABLE' },
-            },
-          },
-        },
-        returnFields: ['id', 'ref'],
-      } as any,
-      client,
-      log
-    );
-
-    const result = await rollbackMapper.mapWithNodes(
-      originalRequest,
-      {},
-      { config: {}, helpers: {} }
-    );
-
-    if (!result.success) {
-      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
-    }
-
-    // Execute mutation (query is auto-generated in result)
-    await client.graphql({
-      query: result.query,
-      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
-    });
-
-    return { success: true };
-  } catch (error: any) {
-    log.error('❌ Rollback failed', {
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check rollback mapping configuration and verify transfer state structure'
-        : error.message?.includes('original') || error.message?.includes('missing')
-        ? 'Original transfer request data missing - verify transfer state in KV store'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : 'Review error details and check rollback mutation payload',
-    });
-
-    return {
-      success: false,
-      error: error.message,
-    };
-  }
-}
-
-/**
- * Helper: Calculate variance between expected and actual quantities
- */
-function calculateVariance(
-  expectedItems: TransferItem[],
-  actualItems: TransferItem[]
-): VarianceDetails {
-  const varianceItems = [];
-  let totalExpected = 0;
-  let totalActual = 0;
-
-  for (const expectedItem of expectedItems) {
-    const actualItem = actualItems.find(i => i.skuRef === expectedItem.skuRef);
-    const expectedQty = expectedItem.requestedQty;
-    const actualQty = actualItem?.actualQty ?? expectedQty;
-
-    totalExpected += expectedQty;
-    totalActual += actualQty;
-
-    if (expectedQty !== actualQty) {
-      varianceItems.push({
-        skuRef: expectedItem.skuRef,
-        expected: expectedQty,
-        actual: actualQty,
-        difference: actualQty - expectedQty,
-        reason: actualItem?.notes,
-      });
-    }
-  }
-
-  const variancePercentage =
-    totalExpected > 0 ? Math.abs((totalActual - totalExpected) / totalExpected) * 100 : 0;
-
-  return {
-    hasVariance: varianceItems.length > 0,
-    variancePercentage,
-    requiresApproval: variancePercentage > 5, // > 5% requires approval
-    items: varianceItems,
-  };
-}
-
-/**
- * Helper: Get transfer state from KV
- */
-async function getTransferState(
-  kvAdapter: VersoriKVAdapter,
-  transferId: string
-): Promise<TransferState | null> {
-  const stateKey = ['transfer-state', transferId];
-  const result = await kvAdapter.get(stateKey);
-  return result?.value as TransferState | null;
-}
-
-/**
- * Helper: Save transfer state to KV
- */
-async function saveTransferState(
-  kvAdapter: VersoriKVAdapter,
-  transferState: TransferState
-): Promise<void> {
-  const stateKey = ['transfer-state', transferState.transferId];
-  await kvAdapter.set(stateKey, transferState);
-}
-
-/**
- * Helper: Get all transfer states (for reconciliation)
- */
-async function getAllTransferStates(
-  kvAdapter: VersoriKVAdapter
-): Promise<TransferState[]> {
-  // Note: This is a simplified implementation
-  // In production, you'd use KV list operations with proper pagination
-  const transfers: TransferState[] = [];
-
-  // Implementation would depend on your KV structure
-  // This is a placeholder showing the expected return type
-
-  return transfers;
-}
-
-/**
- * Helper: Send variance notification email
- */
-async function sendVarianceNotification(
-  transferId: string,
-  variance: VarianceDetails,
-  activation: any,
-  log: any
-): Promise<void> {
-  const emailTo = activation.getVariable('varianceNotificationEmail') as string;
-  if (!emailTo) {
-    log.warn('⚠️ Variance notification email not configured', { transferId });
-    return;
-  }
-
-  // Email sending implementation
-  // Use Versori email connector or external service
-  log.info('📧 Sending variance notification', {
-    transferId,
-    emailTo,
-    variancePercentage: variance.variancePercentage.toFixed(2) + '%',
-  });
-}
-
-/**
- * Helper: Send completion notification
- */
-async function sendCompletionNotification(
-  transferId: string,
-  transferState: TransferState,
-  activation: any,
-  log: any
-): Promise<void> {
-  const emailTo = activation.getVariable('completionNotificationEmail') as string;
-  if (!emailTo) return;
-
-  log.info('📧 Sending completion notification', {
-    transferId,
-    emailTo,
-  });
-}
-```
-
----
-
-### 3. Workflow: Initiate Transfer (`src/workflows/webhook/initiate-transfer.ts`)
-
-```typescript
-/**
- * Webhook: Initiate Transfer
- *
- * Endpoint: POST https://{workspace}.versori.run/initiate-transfer
- * Request body: TransferRequest (JSON)
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: transfer.service.ts
- */
-
-import { webhook, http } from '@versori/run';
-import { processTransferRequest } from '../../services/transfer.service';
-
-export const initiateTransfer = webhook('initiate-transfer', {
-  response: { mode: 'sync' },
-  connection: 'initiate-transfer', // Versori validates API key
-}).then(
-  http('process-transfer-request', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-    const jobId = `transfer-${Date.now()}`;
-
-    log.info('═══════════════════════════════════════════════════════');
-    log.info('📦 TRANSFER REQUEST RECEIVED', { jobId });
-    log.info('═══════════════════════════════════════════════════════');
-
-    try {
-      const result = await processTransferRequest(ctx, data);
-
-      if (result.success) {
-        log.info('✅ TRANSFER REQUEST COMPLETED', { jobId, result });
-      } else {
-        log.error('❌ TRANSFER REQUEST FAILED', { jobId, error: result.error });
-      }
-
-      return { success: result.success, jobId, ...result };
-    } catch (e: any) {
-      log.error('❌ TRANSFER REQUEST FAILED', { jobId, error: e.message });
-      return { success: false, jobId, error: e.message };
-    }
-  })
-);
-```
-
----
-
-### 4. Workflow: Receive Transfer (`src/workflows/webhook/receive-transfer.ts`)
-
-```typescript
-/**
- * Webhook: Receive Transfer (Receipt Confirmation)
- *
- * Endpoint: POST https://{workspace}.versori.run/receive-transfer
- * Request body: { transferId, receivedDate, items[] }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: transfer.service.ts
- */
-
-import { webhook, http } from '@versori/run';
-import { processReceiptConfirmation } from '../../services/transfer.service';
-
-export const receiveTransfer = webhook('receive-transfer', {
-  response: { mode: 'sync' },
-  connection: 'receive-transfer',
-}).then(
-  http('process-receipt-confirmation', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-    const jobId = `receipt-${Date.now()}`;
-
-    log.info('═══════════════════════════════════════════════════════');
-    log.info('📦 RECEIPT CONFIRMATION RECEIVED', { jobId, transferId: data.transferId });
-    log.info('═══════════════════════════════════════════════════════');
-
-    try {
-      const result = await processReceiptConfirmation(ctx, data);
-
-      if (result.success) {
-        log.info('✅ RECEIPT CONFIRMATION COMPLETED', { jobId, result });
-      } else {
-        log.error('❌ RECEIPT CONFIRMATION FAILED', { jobId, error: result.error });
-      }
-
-      return { success: result.success, jobId, ...result };
-    } catch (e: any) {
-      log.error('❌ RECEIPT CONFIRMATION FAILED', { jobId, error: e.message });
-      return { success: false, jobId, error: e.message };
-    }
-  })
-);
-```
-
----
-
-### 5. Workflow: Reconcile Transfers (`src/workflows/scheduled/reconcile-transfers.ts`)
-
-```typescript
-/**
- * Scheduled Workflow: Transfer Reconciliation
- *
- * Runs automatically daily at 1 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Finds stale in-transit transfers (> 24 hours) and generates alerts
- * Uses JobTracker for status tracking
- */
-
-import { schedule, http } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { runReconciliation } from '../../services/transfer.service';
-
-export const reconcileTransfers = schedule(
-  'reconcile-transfers',
-  '0 1 * * *' // Daily at 1 AM UTC
-).then(
-  http('run-reconciliation', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, openKv } = ctx;
-    const jobId = `reconcile-${Date.now()}`;
-
-    log.info('═══════════════════════════════════════════════════════');
-    log.info('🔄 RECONCILIATION STARTED', { jobId });
-    log.info('═══════════════════════════════════════════════════════');
-
-    const tracker = new JobTracker(openKv(':project:'), log);
-    await tracker.createJob(jobId, { triggeredBy: 'schedule' });
-
-    try {
-      const result = await runReconciliation(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-
-      log.info('✅ RECONCILIATION COMPLETED', { jobId, result });
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-
-      log.error('❌ RECONCILIATION FAILED', { jobId, error: e.message });
-      return { success: false, jobId, error: e.message };
-    }
-  })
-);
-```
-
----
-
-### 6. Workflow: Export Transfer Report (`src/workflows/webhook/export-transfer-report.ts`)
-
-```typescript
-/**
- * Webhook: Export Transfer Report
- *
- * Endpoint: POST https://{workspace}.versori.run/export-transfer-report
- * Request body: { startDate, endDate }
- *
- * Pattern: webhook().then(fn()) - no external API needed, only KV storage
- * Queries KV store for transfer states and generates report
- */
-
-import { webhook, fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const exportTransferReport = webhook('export-transfer-report', {
-  response: { mode: 'sync' },
-  connection: 'export-transfer-report',
-}).then(
-  fn('generate-report', async ctx => {
-    const { log, openKv, data } = ctx;
-    const { startDate, endDate } = data;
-
-    log.info('═══════════════════════════════════════════════════════');
-    log.info('📊 TRANSFER REPORT EXPORT', { startDate, endDate });
-    log.info('═══════════════════════════════════════════════════════');
-
-    try {
-      const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-
-      // Query transfer states (simplified - implement proper date filtering)
-      const transfers: any[] = []; // getAllTransferStates(kvAdapter, startDate, endDate);
-
-      const report = {
-        period: { startDate, endDate },
-        totalTransfers: transfers.length,
-        byStatus: {
-          pending: transfers.filter(t => t.status === 'PENDING').length,
-          dispatched: transfers.filter(t => t.status === 'DISPATCHED').length,
-          inTransit: transfers.filter(t => t.status === 'IN_TRANSIT').length,
-          received: transfers.filter(t => t.status === 'RECEIVED').length,
-          failed: transfers.filter(t => t.status === 'FAILED').length,
-          rolledBack: transfers.filter(t => t.status === 'ROLLED_BACK').length,
-        },
-        transfers: transfers.map(t => ({
-          transferId: t.transferId,
-          status: t.status,
-          sourceLocation: t.originalRequest?.sourceLocationRef,
-          destinationLocation: t.originalRequest?.destinationLocationRef,
-          itemCount: t.originalRequest?.items?.length || 0,
-          createdAt: t.createdAt,
-          completedAt: t.receivedAt || t.updatedAt,
-        })),
-      };
-
-      log.info('✅ REPORT GENERATED', {
-        totalTransfers: report.totalTransfers,
-        byStatus: report.byStatus,
-      });
-
-      return { success: true, report };
-    } catch (e: any) {
-      log.error('❌ REPORT EXPORT FAILED', { error: e.message });
-      return { success: false, error: e.message };
-    }
-  })
-);
-```
-
----
-
-## Configuration
-
-### Activation Variables Configuration
-
-```bash
-# Required Variables
-fluentRetailerId=my-retailer-id
-
-# S3 Configuration (for CSV-based transfers)
-s3TransferBucket=my-transfers-bucket
-awsAccessKeyId=AKIAXXXXXXXXXXXX
-awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-awsRegion=us-east-1
-s3TransferPrefix=transfers/
-
-# Email Notifications
-varianceNotificationEmail=warehouse-manager@company.com
-completionNotificationEmail=logistics@company.com
-```
-
-### GraphQL Mutation Mapping Configuration: `config/transfer-mappings.json`
-
-```json
-{
-  "dispatch": {
-    "version": "1.0.0",
-    "mutation": "updateInventoryQuantity",
-    "sourceFormat": "json",
-    "fields": {
-      "input.ref": {
-        "resolver": "custom.generateDispatchRef"
-      },
-      "input.locationRef": {
-        "source": "sourceLocationRef",
-        "required": true
-      },
-      "input.items": {
-        "source": "items",
-        "isArray": true,
-        "fields": {
-          "skuRef": {
-            "source": "skuRef",
-            "required": true
-          },
-          "qty": {
-            "source": "requestedQty",
-            "resolver": "custom.negateQty",
-            "required": true
-          },
-          "type": {
-            "value": "DISPATCH"
-          },
-          "status": {
-            "value": "AVAILABLE"
-          }
-        }
-      }
-    },
-    "returnFields": ["id", "ref"]
-  },
-  "receipt": {
-    "version": "1.0.0",
-    "mutation": "updateInventoryQuantity",
-    "sourceFormat": "json",
-    "fields": {
-      "input.ref": {
-        "resolver": "custom.generateReceiptRef"
-      },
-      "input.locationRef": {
-        "source": "destinationLocationRef",
-        "required": true
-      },
-      "input.items": {
-        "source": "items",
-        "isArray": true,
-        "fields": {
-          "skuRef": {
-            "source": "skuRef",
-            "required": true
-          },
-          "qty": {
-            "source": "actualQty",
-            "required": true
-          },
-          "type": {
-            "value": "RECEIPT"
-          },
-          "status": {
-            "value": "AVAILABLE"
-          }
-        }
-      }
-    },
-    "returnFields": ["id", "ref"]
-  }
-}
-```
-
----
-
-## Input/Output Examples
-
-### CSV Input Format Example: `sample-transfer.csv`
-
-```csv
-transfer_id,source_location,destination_location,requested_date,expected_delivery,items
-TRF-001,WH-EAST,STORE-NYC,2025-01-15,2025-01-17,"[{""sku"":""SKU-001"",""qty"":100},{""sku"":""SKU-002"",""qty"":50}]"
-TRF-002,WH-WEST,STORE-LA,2025-01-15,2025-01-18,"[{""sku"":""SKU-003"",""qty"":200}]"
-```
-
-### JSON Input Format Example
-
-```json
-{
-  "transferId": "TRF-001",
-  "sourceLocationRef": "WH-EAST",
-  "destinationLocationRef": "STORE-NYC",
-  "requestedDate": "2025-01-15T10:00:00Z",
-  "expectedDeliveryDate": "2025-01-17T10:00:00Z",
-  "items": [
-    {
-      "skuRef": "SKU-001",
-      "requestedQty": 100,
-      "condition": "NEW"
-    },
-    {
-      "skuRef": "SKU-002",
-      "requestedQty": 50,
-      "condition": "NEW"
-    }
-  ],
-  "metadata": {
-    "reason": "Store restocking",
-    "priority": "HIGH",
-    "requestedBy": "manager@store.com"
-  }
-}
-```
-
-### Receipt Confirmation Format
-
-```json
-{
-  "transferId": "TRF-001",
-  "receivedDate": "2025-01-17T14:30:00Z",
-  "items": [
-    {
-      "skuRef": "SKU-001",
-      "requestedQty": 100,
-      "actualQty": 98,
-      "notes": "2 units damaged in transit"
-    },
-    {
-      "skuRef": "SKU-002",
-      "requestedQty": 50,
-      "actualQty": 50
-    }
-  ]
-}
-```
-
----
-
-## Versori Workflow Structure
-
-### Workflow Flow Diagram
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Transfer Request                          │
-│          (Webhook JSON or Scheduled CSV)                     │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       ├─ Acquire Lock
-                       │
-                       ├─ Initialize Transfer State (PENDING)
-                       │
-                       ├─ Create Dispatch Mutation
-                       │   └─ Remove from Source Location
-                       │
-                       ├─ Update State (IN_TRANSIT)
-                       │
-                       └─ Release Lock
-                       │
-┌──────────────────────┴──────────────────────────────────────┐
-│                    Receipt Confirmation                      │
-│                      (Webhook JSON)                          │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       ├─ Acquire Lock
-                       │
-                       ├─ Calculate Variance
-                       │   ├─ If > 5% → Require Approval
-                       │   │   └─ Send Email Notification
-                       │   │
-                       │   └─ If <= 5% → Auto-Approve
-                       │
-                       ├─ Create Receipt Mutation
-                       │   └─ Add to Destination Location
-                       │
-                       ├─ Update State (RECEIVED)
-                       │
-                       ├─ Send Completion Notification
-                       │
-                       └─ Release Lock
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: Paired Mutations (Dispatch + Receipt)
-
-**Dispatch Mutation** (Remove from source):
-
-```typescript
-const dispatchPayload = {
-  input: {
-    ref: 'DISPATCH-TRF-001-1234567890',
-    locationRef: 'WH-EAST',
-    items: [
-      {
-        skuRef: 'SKU-001',
-        qty: -100, // Negative quantity for removal
-        type: 'DISPATCH',
-        status: 'AVAILABLE',
-      },
-    ],
-  },
-};
-```
-
-**Receipt Mutation** (Add to destination):
-
-```typescript
-const receiptPayload = {
-  input: {
-    ref: 'RECEIPT-TRF-001-1234567891',
-    locationRef: 'STORE-NYC',
-    items: [
-      {
-        skuRef: 'SKU-001',
-        qty: 98, // Actual quantity received
-        type: 'RECEIPT',
-        status: 'AVAILABLE',
-      },
-    ],
-  },
-};
-```
-
-**Why Paired Mutations?**
-
-- **Atomicity**: Each mutation is atomic (all-or-nothing)
-- **Audit Trail**: Separate records for dispatch and receipt
-- **Rollback**: Can reverse dispatch if receipt fails
-- **Variance Tracking**: Compare dispatch vs receipt quantities
-
-### Pattern 2: In-Transit Inventory Tracking
-
-**VersoriKV State Schema**:
-
-```typescript
-interface TransferState {
-  transferId: string;
-  status: 'PENDING' | 'DISPATCHED' | 'IN_TRANSIT' | 'RECEIVED' | 'FAILED' | 'ROLLED_BACK';
-  dispatchMutationId?: string;
-  receiptMutationId?: string;
-  dispatchedAt?: string;
-  receivedAt?: string;
-  variance?: VarianceDetails;
-  createdAt: string;
-  updatedAt: string;
-}
-```
-
-**State Transitions**:
-
-```
-PENDING → DISPATCHED → IN_TRANSIT → RECEIVED
-                  ↓
-              FAILED → ROLLED_BACK
-```
-
-**Tracking Benefits**:
-
-- Know what's in transit at any time
-- Query transfer status via API
-- Handle partial receipts
-- Track transit times for analytics
-
-### Pattern 3: Variance Handling
-
-**Variance Calculation**:
-
-```typescript
-function calculateVariance(expected: TransferItem[], actual: TransferItem[]): VarianceDetails {
-  let totalExpected = 0;
-  let totalActual = 0;
-  const varianceItems = [];
-
-  for (const expectedItem of expected) {
-    const actualItem = actual.find(i => i.skuRef === expectedItem.skuRef);
-    const expectedQty = expectedItem.requestedQty;
-    const actualQty = actualItem?.actualQty ?? expectedQty;
-
-    totalExpected += expectedQty;
-    totalActual += actualQty;
-
-    if (expectedQty !== actualQty) {
-      varianceItems.push({
-        skuRef: expectedItem.skuRef,
-        expected: expectedQty,
-        actual: actualQty,
-        difference: actualQty - expectedQty,
-        reason: actualItem?.notes,
-      });
-    }
-  }
-
-  const variancePercentage = Math.abs((totalActual - totalExpected) / totalExpected) * 100;
-
-  return {
-    hasVariance: varianceItems.length > 0,
-    variancePercentage,
-    requiresApproval: variancePercentage > 5,
-    items: varianceItems,
-  };
-}
-```
-
-**Approval Thresholds**:
-
-- **< 5% variance**: Auto-approve (minor discrepancies expected)
-- **> 5% variance**: Require manual approval
-- **Email notification**: Sent to warehouse manager
-- **Approval webhook**: `/approve-variance` endpoint
-
-### Pattern 4: Rollback on Failure
-
-**When to Rollback**:
-
-- Receipt mutation fails
-- Variance rejected by manager
-- Destination location unavailable
-- Critical validation errors
-
-**Rollback Implementation**:
-
-```typescript
-async function rollbackTransfer(
-  client: any,
-  transferState: TransferState,
-  log: Logger
-): Promise<void> {
-  // Create reverse dispatch mutation (add back to source)
-  const rollbackPayload = {
-    input: {
-      ref: `ROLLBACK-${transferState.transferId}`,
-      locationRef: originalSourceLocation,
-      items: originalItems.map(item => ({
-        skuRef: item.skuRef,
-        qty: item.requestedQty, // Positive quantity (add back)
-        type: 'ROLLBACK',
-        status: 'AVAILABLE',
-      })),
-    },
-  };
-
-  await client.graphql({
-    query: rollbackMutation,
-    variables: rollbackPayload,
-  });
-
-  // Update state
-  transferState.status = 'ROLLED_BACK';
-  await saveTransferState(kvAdapter, transferState);
-}
-```
-
-**Rollback Guarantees**:
-
-- Inventory returned to source location
-- Audit trail preserved (ROLLBACK type)
-- State updated to ROLLED_BACK
-- Prevents inventory loss
-
-### Pattern 5: Multi-Leg Transfers (A → B → C)
-
-For complex transfers through intermediate locations:
-
-```typescript
-interface MultiLegTransfer {
-  transferId: string;
-  legs: TransferLeg[];
-  currentLeg: number;
-  overallStatus: string;
-}
-
-interface TransferLeg {
-  legId: string;
-  sourceLocationRef: string;
-  destinationLocationRef: string;
-  status: string;
-  dispatchedAt?: string;
-  receivedAt?: string;
-}
-
-async function processMultiLegTransfer(
-  transfer: MultiLegTransfer,
-  client: any,
-  log: Logger
-): Promise<void> {
-  for (let i = transfer.currentLeg; i < transfer.legs.length; i++) {
-    const leg = transfer.legs[i];
-
-    // Dispatch from current location
-    await createDispatchMutation(
-      client,
-      {
-        ...transfer,
-        sourceLocationRef: leg.sourceLocationRef,
-        destinationLocationRef: leg.destinationLocationRef,
-      },
-      log
-    );
-
-    // Wait for receipt confirmation (via webhook)
-    // State management tracks current leg
-    transfer.currentLeg = i;
-    await saveTransferState(kvAdapter, transfer);
-
-    // Receipt confirmation advances to next leg
-  }
-
-  transfer.overallStatus = 'COMPLETED';
-  await saveTransferState(kvAdapter, transfer);
-}
-```
-
----
-
-## Testing
-
-### 1. Test Dispatch Request
-
-```bash
-curl -X POST https://your-workspace.versori.run/initiate-transfer \
-  -H "Content-Type: application/json" \
-  -d '{
-    "transferId": "TEST-001",
-    "sourceLocationRef": "WH-TEST",
-    "destinationLocationRef": "STORE-TEST",
-    "requestedDate": "2025-01-15T10:00:00Z",
-    "items": [
-      {
-        "skuRef": "TEST-SKU-001",
-        "requestedQty": 10
-      }
-    ]
-  }'
-```
-
-Expected response:
-
-```json
-{
-  "success": true,
-  "transferId": "TEST-001",
-  "status": "IN_TRANSIT",
-  "dispatchMutationId": "12345",
-  "message": "Transfer dispatched successfully, awaiting receipt confirmation"
-}
-```
-
-### 2. Test Receipt Confirmation (No Variance)
-
-```bash
-curl -X POST https://your-workspace.versori.run/receive-transfer \
-  -H "Content-Type: application/json" \
-  -d '{
-    "transferId": "TEST-001",
-    "receivedDate": "2025-01-17T14:00:00Z",
-    "items": [
-      {
-        "skuRef": "TEST-SKU-001",
-        "requestedQty": 10,
-        "actualQty": 10
-      }
-    ]
-  }'
-```
-
-Expected response:
-
-```json
-{
-  "success": true,
-  "status": "RECEIVED",
-  "transferId": "TEST-001",
-  "receiptMutationId": "12346"
-}
-```
-
-### 3. Test Receipt with Variance
-
-```bash
-curl -X POST https://your-workspace.versori.run/receive-transfer \
-  -H "Content-Type: application/json" \
-  -d '{
-    "transferId": "TEST-002",
-    "receivedDate": "2025-01-17T14:00:00Z",
-    "items": [
-      {
-        "skuRef": "TEST-SKU-001",
-        "requestedQty": 100,
-        "actualQty": 90,
-        "notes": "10 units damaged"
-      }
-    ]
-  }'
-```
-
-Expected response (variance > 5%):
-
-```json
-{
-  "success": true,
-  "status": "PENDING_APPROVAL",
-  "transferId": "TEST-002",
-  "variance": {
-    "hasVariance": true,
-    "variancePercentage": 10,
-    "requiresApproval": true,
-    "items": [
-      {
-        "skuRef": "TEST-SKU-001",
-        "expected": 100,
-        "actual": 90,
-        "difference": -10,
-        "reason": "10 units damaged"
-      }
-    ]
-  },
-  "message": "Variance requires manual approval"
-}
-```
-
----
-
-## Common Issues & Solutions
-
-### Issue 1: Duplicate Transfer Processing
-
-**Symptoms:**
-
-- Same transfer processed multiple times
-- Double dispatch/receipt
-
-**Root Cause:**
-
-- Lock not acquired
-- Transfer state not checked
-
-**Solution:**
-
-```typescript
-// Always check existing state before processing
-const existingState = await getTransferState(kvAdapter, transferId);
-if (existingState && existingState.status !== 'FAILED') {
-  log.warn('Transfer already processed', { transferId, status: existingState.status });
-  return { success: false, error: 'Already processed' };
-}
-
-// Always acquire lock
-const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
-if (!lockAcquired) {
-  throw new Error('Could not acquire lock');
-}
-```
-
-### Issue 2: Variance Not Detected
-
-**Symptoms:**
-
-- Receipts with different quantities not flagged
-- No approval required
-
-**Root Cause:**
-
-- Variance calculation logic incorrect
-- Percentage threshold too high
-
-**Solution:**
-
-```typescript
-// Ensure variance calculation includes all items
-function calculateVariance(expected: TransferItem[], actual: TransferItem[]): VarianceDetails {
-  // Check EVERY item, not just first mismatch
-  for (const expectedItem of expected) {
-    const actualItem = actual.find(i => i.skuRef === expectedItem.skuRef);
-    if (!actualItem) {
-      // Item completely missing
-      varianceItems.push({
-        skuRef: expectedItem.skuRef,
-        expected: expectedItem.requestedQty,
-        actual: 0,
-        difference: -expectedItem.requestedQty,
-        reason: 'Item not received',
-      });
-    }
-  }
-
-  // Calculate percentage correctly
-  const variancePercentage =
-    totalExpected > 0 ? Math.abs((totalActual - totalExpected) / totalExpected) * 100 : 0;
-
-  return {
-    hasVariance: varianceItems.length > 0,
-    variancePercentage,
-    requiresApproval: variancePercentage > 5, // Adjust threshold as needed
-    items: varianceItems,
-  };
-}
-```
-
-### Issue 3: Rollback Fails
-
-**Symptoms:**
-
-- Transfer marked as ROLLED_BACK but inventory not restored
-- GraphQL mutation errors
-
-**Root Cause:**
-
-- Original request data not stored in state
-- Rollback mutation invalid
-
-**Solution:**
-
-```typescript
-// Store original request when creating transfer state
-const transferState: TransferState = {
-  transferId,
-  status: 'PENDING',
-  originalRequest: transferRequest, // Store for rollback
-  // ... other fields
-};
-await saveTransferState(kvAdapter, transferState);
-
-// Validate rollback payload before sending
-async function rollbackTransfer(client: any, transferState: TransferState, log: Logger) {
-  const originalRequest = transferState.originalRequest;
-  if (!originalRequest) {
-    throw new Error('Cannot rollback: original request data missing');
-  }
-
-  // Validate items exist
-  if (!originalRequest.items || originalRequest.items.length === 0) {
-    throw new Error('Cannot rollback: no items in original request');
-  }
-
-  // Create rollback mutation...
-}
-```
-
-### Issue 4: Email Notifications Not Sent
-
-**Symptoms:**
-
-- No emails for variance or completion
-- Silent failures
-
-**Root Cause:**
-
-- Email service not configured
-- Missing activation variables
-- Email connector not connected
-
-**Solution:**
-
-```typescript
-async function sendVarianceNotification(
-  transferId: string,
-  variance: VarianceDetails,
-  activation: any,
-  log: any
-): Promise<void> {
-  const emailTo = activation.getVariable('varianceNotificationEmail') as string;
-
-  if (!emailTo) {
-    log.warn('Variance notification email not configured', { transferId });
-    return; // Don't fail transfer if email not configured
-  }
-
-  try {
-    // Send email via Versori connector or external service
-    // Example: SendGrid, AWS SES, etc.
-    await sendEmail({
-      to: emailTo,
-      subject: `Transfer Variance Requires Approval: ${transferId}`,
-      body: formatVarianceEmail(transferId, variance),
-    });
-
-    log.info('Variance notification sent', { transferId, emailTo });
-  } catch (error: any) {
-    // Log error but don't fail transfer
-    log.error('Failed to send variance notification', error, { transferId });
-  }
-}
-```
-
----
-
-## Related Guides
-
-- **02-scheduled-csv-inventory.md** - CSV processing patterns
-- **03-kv-state-management.md** - State tracking and locking
-- **04-webhook-xml-response.md** - Webhook response patterns
-- **GraphQL Mutation Mapping**: `../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
-- **Universal Mapping**: `../../02-CORE-GUIDES/mapping/readme.md`
-
----
-
-## Summary
-
-This guide demonstrated inter-location transfer processing with:
-
-1. **Paired Mutations**: Dispatch and receipt for audit trail
-2. **In-Transit Tracking**: VersoriKV state management
-3. **Variance Handling**: Automatic approval thresholds and manual review
-4. **Rollback Logic**: Restore inventory on failure
-5. **Multi-Format Support**: JSON webhooks and CSV scheduled imports
-6. **Email Notifications**: Variance alerts and completion notices
-
-**Key Takeaways**:
-
-- Use paired mutations for complete audit trail
-- Track transfer state in VersoriKV for visibility
-- Implement variance thresholds (e.g., 5%) for auto-approval
-- Always store original request for rollback capability
-- Use distributed locking to prevent duplicate processing
-- Handle both webhook and scheduled triggers
-
-**Production Considerations**:
-
-- Monitor variance approval queue
-- Set up alerts for stuck transfers
-- Track average transit times
-- Implement retry logic for transient failures
-- Add comprehensive logging for debugging
-- Test rollback scenarios thoroughly
+# Versori Inter-Location Transfer Processing
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Webhook-triggered or scheduled workflow for processing inventory transfers between warehouses/stores with in-transit tracking
+
+**Complexity**: Medium
+
+**Runtime**: Versori Platform (Webhook/Scheduled)
+
+**Estimated Lines**: ~1,200 lines (modular, production-ready)
+
+## What You'll Build
+
+- Versori webhook/scheduled workflow for transfer requests
+- CSV and JSON input format support
+- Parse transfer data (source, destination, items, quantities)
+- Create paired dispatch/receipt mutations (GraphQL)
+- In-transit inventory tracking with VersoriKV
+- Variance handling (damaged items, shortages)
+- Rollback logic on failure
+- Email notifications on completion
+- Approval workflow for variances > 5%
+
+## SDK Methods Used
+
+- `createClient(ctx)` - Auto-detects Versori context
+- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - Map transfers to GraphQL mutations
+- `mapper.mapWithNodes(sourceData)` - Transform transfer data (resolvers from constructor)
+- `client.graphql(payload)` - Execute mutations
+- `VersoriKVAdapter(openKv())` - State management
+- `StateService(logger)` - Distributed locking
+- `UniversalMapper(mappingConfig)` - CSV field mapping
+- `CSVParserService()` - Parse CSV transfer files
+
+---
+
+## Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+inter-location-transfers/
+├── index.ts                              # Entry point - registers all workflows
+└── src/
+    ├── workflows/
+    │   ├── webhook/
+    │   │   ├── initiate-transfer.ts      # Webhook: Process transfer requests
+    │   │   ├── receive-transfer.ts       # Webhook: Receipt confirmation
+    │   │   └── export-transfer-report.ts # Webhook: Export reports
+    │   │
+    │   └── scheduled/
+    │       └── reconcile-transfers.ts    # Scheduled: Daily reconciliation
+    │
+    ├── services/
+    │   └── transfer.service.ts           # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── transfer-mapping.json         # Mapping configuration
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Scalable (add new workflows without cluttering)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Easy to modify individual workflows without affecting others
+
+---
+
+## Use Case Profile
+
+- **Volume**: Medium (50-500 transfers/day)
+- **Latency**: Near real-time (< 5 minutes)
+- **Complexity**: Medium (paired mutations, state tracking, variance handling)
+- **Pattern**: Webhook/scheduled → parse → dispatch mutation → receipt mutation → state tracking
+
+---
+
+## Complete Working Code
+
+### 1. Entry Point: `index.ts`
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * ⚠️ CRITICAL PATTERN: MemoryInterpreter Setup
+ * This pattern ensures workflows execute in the correct Versori runtime context
+ * and prevents "unexpected export" errors during deployment.
+ *
+ * COMPONENTS:
+ * 1. Import ALL workflows (scheduled, webhook, etc.)
+ * 2. Create MemoryInterpreter with workflow array
+ * 3. NO direct exports - interpreter handles workflow registration
+ *
+ * File Structure:
+ * - src/workflows/scheduled/ → Time-based triggers (cron)
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ */
+
+import { MemoryInterpreter } from '@versori/run';
+
+// Import webhook workflows
+import { initiateTransfer } from './src/workflows/webhook/initiate-transfer';
+import { receiveTransfer } from './src/workflows/webhook/receive-transfer';
+import { exportTransferReport } from './src/workflows/webhook/export-transfer-report';
+
+// Import scheduled workflows
+import { reconcileTransfers } from './src/workflows/scheduled/reconcile-transfers';
+
+// ✅ CORRECT: Register via MemoryInterpreter (Versori standard)
+new MemoryInterpreter([
+  // Webhooks (HTTP-based triggers)
+  initiateTransfer,
+  receiveTransfer,
+  exportTransferReport,
+
+  // Scheduled (time-based triggers)
+  reconcileTransfers,
+]);
+
+// ❌ WRONG: Direct exports cause "unexpected export" errors
+// export { initiateTransfer, receiveTransfer, reconcileTransfers };
+
+/**
+ * What Gets Exposed:
+ * ✅ initiateTransfer → https://{workspace}.versori.run/initiate-transfer
+ * ✅ receiveTransfer → https://{workspace}.versori.run/receive-transfer
+ * ✅ exportTransferReport → https://{workspace}.versori.run/export-transfer-report
+ * ❌ reconcileTransfers → NOT exposed (runs automatically on cron)
+ */
+```
+
+---
+
+### 2. Service File: `src/services/transfer.service.ts`
+
+```typescript
+/**
+ * Transfer Service - Shared orchestration logic
+ *
+ * This service provides reusable business logic for transfer processing:
+ * - Dispatch mutations (remove from source)
+ * - Receipt mutations (add to destination)
+ * - Variance calculation and approval
+ * - Rollback logic on failure
+ * - State management with VersoriKV
+ * - Distributed locking for concurrency
+ *
+ * All business logic is centralized here - workflows just delegate to service functions.
+ */
+
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno
+import {
+  createClient,
+  GraphQLMutationMapper,
+  UniversalMapper,
+  VersoriKVAdapter,
+  StateService,
+  CSVParserService,
+  S3DataSource,
+} from '@fluentcommerce/fc-connect-sdk';
+
+import type {
+  FluentClient,
+  Logger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Transfer data interfaces
+ */
+export interface TransferRequest {
+  transferId: string;
+  sourceLocationRef: string;
+  destinationLocationRef: string;
+  requestedDate: string;
+  expectedDeliveryDate?: string;
+  items: TransferItem[];
+  metadata?: {
+    reason?: string;
+    priority?: string;
+    requestedBy?: string;
+  };
+}
+
+export interface TransferItem {
+  skuRef: string;
+  requestedQty: number;
+  actualQty?: number; // For receipt confirmation
+  condition?: string;
+  notes?: string;
+}
+
+export interface TransferState {
+  transferId: string;
+  status: 'PENDING' | 'DISPATCHED' | 'IN_TRANSIT' | 'RECEIVED' | 'FAILED' | 'ROLLED_BACK';
+  dispatchMutationId?: string;
+  receiptMutationId?: string;
+  dispatchedAt?: string;
+  receivedAt?: string;
+  variance?: VarianceDetails;
+  originalRequest?: TransferRequest;
+  receiptData?: any;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface VarianceDetails {
+  hasVariance: boolean;
+  variancePercentage: number;
+  requiresApproval: boolean;
+  items: {
+    skuRef: string;
+    expected: number;
+    actual: number;
+    difference: number;
+    reason?: string;
+  }[];
+}
+
+export interface TransferResult {
+  success: boolean;
+  transferId?: string;
+  status?: string;
+  dispatchMutationId?: string;
+  receiptMutationId?: string;
+  variance?: VarianceDetails;
+  error?: string;
+  currentStatus?: string;
+  message?: string;
+  recommendation?: string;
+}
+
+/**
+ * Process transfer request (dispatch from source)
+ *
+ * This function orchestrates the complete transfer dispatch:
+ * 1. Client initialization with retailerId
+ * 2. Lock acquisition for concurrency control
+ * 3. Transfer state initialization
+ * 4. Dispatch mutation creation
+ * 5. State updates and cleanup
+ *
+ * @param ctx - Versori context object
+ * @param transferRequest - Transfer request data
+ */
+export async function processTransferRequest(
+  ctx: any,
+  transferRequest: TransferRequest
+): Promise<TransferResult> {
+  const { log, activation, openKv } = ctx;
+  const startTime = Date.now();
+
+  log.info('═══════════════════════════════════════════════════════');
+  log.info('🚀 TRANSFER REQUEST PROCESSING STARTED', {
+    transferId: transferRequest.transferId,
+    sourceLocation: transferRequest.sourceLocationRef,
+    destinationLocation: transferRequest.destinationLocationRef,
+    itemCount: transferRequest.items.length,
+  });
+  log.info('═══════════════════════════════════════════════════════');
+
+  try {
+    // Initialize client with retailerId and validateConnection
+    log.info('🔧 Initializing Fluent Commerce client...');
+    const client = await createClient({ ...ctx, validateConnection: true });
+    const fluentRetailerId = activation.getVariable('fluentRetailerId');
+
+    if (!fluentRetailerId) {
+      log.error('❌ Missing required fluentRetailerId activation variable');
+      return {
+        success: false,
+        error: 'fluentRetailerId activation variable is required',
+        recommendation: 'Please configure fluentRetailerId in the Activation Variables section',
+      };
+    }
+
+    client.setRetailerId(fluentRetailerId);
+    log.info('✅ Client initialized', { retailerId: fluentRetailerId });
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+
+    // Check if transfer already processed
+    log.info('🔍 Checking transfer state...');
+    const existingState = await getTransferState(kvAdapter, transferRequest.transferId);
+
+    if (existingState && existingState.status !== 'FAILED') {
+      log.warn('⚠️ Transfer already processed', {
+        transferId: transferRequest.transferId,
+        status: existingState.status,
+      });
+      return {
+        success: false,
+        error: 'Transfer already processed',
+        transferId: transferRequest.transferId,
+        currentStatus: existingState.status,
+      };
+    }
+
+    // Acquire lock to prevent concurrent processing
+    log.info('🔒 Acquiring transfer lock...');
+    const lockName = `transfer-lock:${transferRequest.transferId}`;
+    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
+
+    if (!lockAcquired) {
+      log.warn('⚠️ Could not acquire lock - transfer already being processed');
+      return {
+        success: false,
+        error: 'Transfer is already being processed',
+        transferId: transferRequest.transferId,
+      };
+    }
+
+    try {
+      // Create initial transfer state
+      log.info('📝 Initializing transfer state...');
+      const transferState: TransferState = {
+        transferId: transferRequest.transferId,
+        status: 'PENDING',
+        originalRequest: transferRequest,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      await saveTransferState(kvAdapter, transferState);
+      log.info('✅ Transfer state initialized');
+
+      // Step 1: Create dispatch mutation (remove from source)
+      log.info('📦 Creating dispatch mutation...');
+      const dispatchStartTime = Date.now();
+      const dispatchResult = await createDispatchMutation(client, transferRequest, log);
+
+      if (!dispatchResult.success) {
+        throw new Error(`Dispatch failed: ${dispatchResult.error}`);
+      }
+
+      const dispatchDuration = Date.now() - dispatchStartTime;
+      log.info('✅ Dispatch mutation created', {
+        mutationId: dispatchResult.mutationId,
+        duration: `${dispatchDuration}ms`,
+      });
+
+      // Update state with dispatch info
+      transferState.status = 'DISPATCHED';
+      transferState.dispatchMutationId = dispatchResult.mutationId;
+      transferState.dispatchedAt = new Date().toISOString();
+      transferState.updatedAt = new Date().toISOString();
+      await saveTransferState(kvAdapter, transferState);
+
+      // Step 2: Mark as in-transit
+      transferState.status = 'IN_TRANSIT';
+      transferState.updatedAt = new Date().toISOString();
+      await saveTransferState(kvAdapter, transferState);
+      log.info('✅ Transfer marked as in-transit');
+
+      const totalDuration = Date.now() - startTime;
+      log.info('═══════════════════════════════════════════════════════');
+      log.info('✅ TRANSFER REQUEST COMPLETED', {
+        transferId: transferRequest.transferId,
+        status: 'IN_TRANSIT',
+        duration: `${totalDuration}ms`,
+      });
+      log.info('═══════════════════════════════════════════════════════');
+
+      // For webhook trigger, return success after dispatch
+      // Receipt will be confirmed via separate webhook
+      return {
+        success: true,
+        transferId: transferRequest.transferId,
+        status: 'IN_TRANSIT',
+        dispatchMutationId: dispatchResult.mutationId,
+        message: 'Transfer dispatched successfully, awaiting receipt confirmation',
+      };
+    } finally {
+      // Always release lock
+      log.info('🔓 Releasing transfer lock...');
+      await stateService.releaseLock(lockName, kvAdapter);
+    }
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    log.error('═══════════════════════════════════════════════════════');
+    log.error('❌ TRANSFER REQUEST FAILED', {
+      transferId: transferRequest.transferId,
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      duration: `${duration}ms`,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check mapping configuration and verify transfer request payload structure'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : error.message?.includes('lock') || error.message?.includes('concurrent')
+        ? 'Concurrent transfer processing detected - retry after lock release'
+        : 'Review error details and check transfer request payload structure',
+    });
+    log.error('═══════════════════════════════════════════════════════');
+
+    return {
+      success: false,
+      error: error.message,
+      transferId: transferRequest.transferId,
+    };
+  }
+}
+
+/**
+ * Process receipt confirmation (add to destination)
+ */
+export async function processReceiptConfirmation(
+  ctx: any,
+  receiptData: { transferId: string; receivedDate: string; items: TransferItem[] }
+): Promise<TransferResult> {
+  const { log, activation, openKv } = ctx;
+  const startTime = Date.now();
+
+  log.info('═══════════════════════════════════════════════════════');
+  log.info('📦 RECEIPT CONFIRMATION STARTED', {
+    transferId: receiptData.transferId,
+    itemCount: receiptData.items.length,
+  });
+  log.info('═══════════════════════════════════════════════════════');
+
+  try {
+    const client = await createClient({ ...ctx, validateConnection: true });
+    const fluentRetailerId = activation.getVariable('fluentRetailerId');
+
+    if (fluentRetailerId) {
+      client.setRetailerId(fluentRetailerId);
+    }
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+
+    // Get transfer state
+    log.info('🔍 Retrieving transfer state...');
+    const transferState = await getTransferState(kvAdapter, receiptData.transferId);
+
+    if (!transferState) {
+      throw new Error('Transfer not found');
+    }
+
+    if (transferState.status !== 'IN_TRANSIT') {
+      throw new Error(`Invalid transfer status: ${transferState.status}`);
+    }
+
+    // Acquire lock
+    log.info('🔒 Acquiring transfer lock...');
+    const lockName = `transfer-lock:${receiptData.transferId}`;
+    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
+
+    if (!lockAcquired) {
+      throw new Error('Could not acquire lock');
+    }
+
+    try {
+      // Calculate variance
+      log.info('🔍 Calculating variance...');
+      const variance = calculateVariance(
+        transferState.originalRequest?.items || receiptData.items,
+        receiptData.items
+      );
+      transferState.variance = variance;
+      transferState.receiptData = receiptData;
+
+      log.info('📊 Variance calculated', {
+        hasVariance: variance.hasVariance,
+        variancePercentage: variance.variancePercentage.toFixed(2) + '%',
+        requiresApproval: variance.requiresApproval,
+      });
+
+      // Check if variance requires approval (> 5%)
+      if (variance.requiresApproval) {
+        transferState.status = 'PENDING';
+        transferState.updatedAt = new Date().toISOString();
+        await saveTransferState(kvAdapter, transferState);
+
+        log.warn('⚠️ Variance requires approval', {
+          variancePercentage: variance.variancePercentage.toFixed(2) + '%',
+        });
+
+        // Send email notification
+        await sendVarianceNotification(receiptData.transferId, variance, activation, log);
+
+        const duration = Date.now() - startTime;
+        log.info('═══════════════════════════════════════════════════════');
+        log.info('⚠️ RECEIPT PENDING APPROVAL', {
+          transferId: receiptData.transferId,
+          duration: `${duration}ms`,
+        });
+        log.info('═══════════════════════════════════════════════════════');
+
+        return {
+          success: true,
+          status: 'PENDING_APPROVAL',
+          transferId: receiptData.transferId,
+          variance,
+          message: 'Variance requires manual approval',
+        };
+      }
+
+      // Create receipt mutation (add to destination)
+      log.info('📦 Creating receipt mutation...');
+      const receiptStartTime = Date.now();
+      const receiptResult = await createReceiptMutation(
+        client,
+        receiptData.transferId,
+        receiptData.items,
+        transferState,
+        log
+      );
+
+      if (!receiptResult.success) {
+        throw new Error(`Receipt failed: ${receiptResult.error}`);
+      }
+
+      const receiptDuration = Date.now() - receiptStartTime;
+      log.info('✅ Receipt mutation created', {
+        mutationId: receiptResult.mutationId,
+        duration: `${receiptDuration}ms`,
+      });
+
+      // Update state
+      transferState.status = 'RECEIVED';
+      transferState.receiptMutationId = receiptResult.mutationId;
+      transferState.receivedAt = new Date().toISOString();
+      transferState.updatedAt = new Date().toISOString();
+      await saveTransferState(kvAdapter, transferState);
+
+      // Send completion notification
+      await sendCompletionNotification(receiptData.transferId, transferState, activation, log);
+
+      const totalDuration = Date.now() - startTime;
+      log.info('═══════════════════════════════════════════════════════');
+      log.info('✅ RECEIPT CONFIRMATION COMPLETED', {
+        transferId: receiptData.transferId,
+        duration: `${totalDuration}ms`,
+      });
+      log.info('═══════════════════════════════════════════════════════');
+
+      return {
+        success: true,
+        status: 'RECEIVED',
+        transferId: receiptData.transferId,
+        receiptMutationId: receiptResult.mutationId,
+        variance: variance.hasVariance ? variance : undefined,
+      };
+    } finally {
+      log.info('🔓 Releasing transfer lock...');
+      await stateService.releaseLock(lockName, kvAdapter);
+    }
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    log.error('═══════════════════════════════════════════════════════');
+    log.error('❌ RECEIPT CONFIRMATION FAILED', {
+      transferId: receiptData.transferId,
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      duration: `${duration}ms`,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('not found') || error.message?.includes('missing')
+        ? 'Transfer not found - verify transferId and check transfer state in KV store'
+        : error.message?.includes('status') || error.message?.includes('invalid')
+        ? 'Invalid transfer status - ensure transfer is in IN_TRANSIT status'
+        : error.message?.includes('lock') || error.message?.includes('concurrent')
+        ? 'Concurrent receipt processing detected - retry after lock release'
+        : error.message?.includes('variance') || error.message?.includes('approval')
+        ? 'Variance requires approval - check variance calculation and approval workflow'
+        : 'Review error details and check receipt confirmation payload structure',
+    });
+    log.error('═══════════════════════════════════════════════════════');
+
+    return {
+      success: false,
+      error: error.message,
+      transferId: receiptData.transferId,
+    };
+  }
+}
+
+/**
+ * Process variance approval/rejection
+ */
+export async function processVarianceApproval(
+  ctx: any,
+  approvalData: { transferId: string; approved: boolean; notes?: string }
+): Promise<TransferResult> {
+  const { log, activation, openKv } = ctx;
+  const { transferId, approved, notes } = approvalData;
+  const startTime = Date.now();
+
+  log.info('═══════════════════════════════════════════════════════');
+  log.info('📝 VARIANCE APPROVAL PROCESSING', {
+    transferId,
+    approved,
+  });
+  log.info('═══════════════════════════════════════════════════════');
+
+  try {
+    const client = await createClient({ ...ctx, validateConnection: true });
+    const fluentRetailerId = activation.getVariable('fluentRetailerId');
+
+    if (fluentRetailerId) {
+      client.setRetailerId(fluentRetailerId);
+    }
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+
+    const transferState = await getTransferState(kvAdapter, transferId);
+    if (!transferState) {
+      throw new Error('Transfer not found');
+    }
+
+    const lockName = `transfer-lock:${transferId}`;
+    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
+    if (!lockAcquired) {
+      throw new Error('Could not acquire lock');
+    }
+
+    try {
+      if (!approved) {
+        // Rollback: reverse the dispatch
+        log.info('❌ Variance rejected - rolling back transfer...');
+        const rollbackResult = await rollbackTransfer(client, transferState, log);
+
+        transferState.status = 'ROLLED_BACK';
+        transferState.updatedAt = new Date().toISOString();
+        await saveTransferState(kvAdapter, transferState);
+
+        const duration = Date.now() - startTime;
+        log.info('═══════════════════════════════════════════════════════');
+        log.info('✅ TRANSFER ROLLED BACK', {
+          transferId,
+          duration: `${duration}ms`,
+        });
+        log.info('═══════════════════════════════════════════════════════');
+
+        return {
+          success: true,
+          status: 'ROLLED_BACK',
+          transferId,
+          message: 'Transfer rolled back due to variance rejection',
+        };
+      }
+
+      // Approved: complete receipt with actual quantities
+      log.info('✅ Variance approved - completing receipt...');
+      const receiptData = transferState.receiptData;
+      if (!receiptData) {
+        throw new Error('Receipt data not found in transfer state');
+      }
+
+      const receiptResult = await createReceiptMutation(
+        client,
+        transferId,
+        receiptData.items,
+        transferState,
+        log
+      );
+
+      if (!receiptResult.success) {
+        throw new Error(`Receipt failed: ${receiptResult.error}`);
+      }
+
+      transferState.status = 'RECEIVED';
+      transferState.receiptMutationId = receiptResult.mutationId;
+      transferState.receivedAt = new Date().toISOString();
+      transferState.updatedAt = new Date().toISOString();
+      await saveTransferState(kvAdapter, transferState);
+
+      const duration = Date.now() - startTime;
+      log.info('═══════════════════════════════════════════════════════');
+      log.info('✅ VARIANCE APPROVAL COMPLETED', {
+        transferId,
+        duration: `${duration}ms`,
+      });
+      log.info('═══════════════════════════════════════════════════════');
+
+      return {
+        success: true,
+        status: 'RECEIVED',
+        transferId,
+        receiptMutationId: receiptResult.mutationId,
+      };
+    } finally {
+      await stateService.releaseLock(lockName, kvAdapter);
+    }
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    log.error('═══════════════════════════════════════════════════════');
+    log.error('❌ VARIANCE APPROVAL FAILED', {
+      transferId,
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      duration: `${duration}ms`,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('not found') || error.message?.includes('missing')
+        ? 'Transfer not found or receipt data missing - verify transferId and transfer state'
+        : error.message?.includes('lock') || error.message?.includes('concurrent')
+        ? 'Concurrent approval processing detected - retry after lock release'
+        : error.message?.includes('receipt') || error.message?.includes('mutation')
+        ? 'Check receipt mutation payload and inventory availability at destination'
+        : 'Review error details and check variance approval payload structure',
+    });
+    log.error('═══════════════════════════════════════════════════════');
+
+    return {
+      success: false,
+      error: error.message,
+      transferId,
+    };
+  }
+}
+
+/**
+ * Run reconciliation (scheduled)
+ */
+export async function runReconciliation(
+  ctx: any,
+  jobId: string,
+  tracker: any
+): Promise<any> {
+  const { log, openKv } = ctx;
+  const startTime = Date.now();
+
+  log.info('═══════════════════════════════════════════════════════');
+  log.info('🔄 RECONCILIATION STARTED', { jobId });
+  log.info('═══════════════════════════════════════════════════════');
+
+  try {
+    await tracker.updateJob(jobId, { stage: 'discovery', status: 'processing' });
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+
+    // Find all in-transit transfers older than 24 hours
+    log.info('🔍 Discovering stale transfers...');
+    const allTransfers = await getAllTransferStates(kvAdapter);
+    const staleTransfers = allTransfers.filter(t => {
+      if (t.status !== 'IN_TRANSIT') return false;
+      const dispatchedAt = new Date(t.dispatchedAt || t.createdAt);
+      const hoursSinceDispatch = (Date.now() - dispatchedAt.getTime()) / (1000 * 60 * 60);
+      return hoursSinceDispatch > 24;
+    });
+
+    log.info('📊 Stale transfers found', { count: staleTransfers.length });
+
+    await tracker.updateJob(jobId, {
+      stage: 'processing',
+      metadata: { staleCount: staleTransfers.length },
+    });
+
+    // Process each stale transfer (generate alerts, etc.)
+    let alertsSent = 0;
+    for (const transfer of staleTransfers) {
+      log.warn('⚠️ Stale transfer detected', {
+        transferId: transfer.transferId,
+        status: transfer.status,
+        age: Math.floor((Date.now() - new Date(transfer.dispatchedAt || transfer.createdAt).getTime()) / (1000 * 60 * 60)) + ' hours',
+      });
+      // Send alert email (implement as needed)
+      alertsSent++;
+    }
+
+    const duration = Date.now() - startTime;
+    const result = {
+      staleTransfersFound: staleTransfers.length,
+      alertsSent,
+      duration: `${duration}ms`,
+    };
+
+    log.info('═══════════════════════════════════════════════════════');
+    log.info('✅ RECONCILIATION COMPLETED', result);
+    log.info('═══════════════════════════════════════════════════════');
+
+    return result;
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    log.error('═══════════════════════════════════════════════════════');
+    log.error('❌ RECONCILIATION FAILED', {
+      jobId,
+      error: error instanceof Error ? error.message : String(error),
+      duration: `${duration}ms`,
+    });
+    log.error('═══════════════════════════════════════════════════════');
+    throw error;
+  }
+}
+
+/**
+ * Helper: Create dispatch mutation (remove from source location)
+ */
+async function createDispatchMutation(
+  client: FluentClient,
+  transferRequest: TransferRequest,
+  log: Logger
+): Promise<{ success: boolean; mutationId?: string; error?: string }> {
+  try {
+    const dispatchMapper = new GraphQLMutationMapper(
+      {
+        version: '1.0.0',
+        mutation: 'updateInventoryQuantity',
+        sourceFormat: 'json',
+        fields: {
+          'input.ref': {
+            resolver: 'custom.generateDispatchRef',
+          },
+          'input.locationRef': {
+            source: 'sourceLocationRef',
+          },
+          'input.items[]': {
+            source: 'items',
+            fields: {
+              skuRef: { source: 'skuRef' },
+              qty: {
+                source: 'requestedQty',
+                resolver: 'custom.negateQty', // Make negative for dispatch
+              },
+              type: { value: 'DISPATCH' },
+              status: { value: 'AVAILABLE' },
+            },
+          },
+        },
+        returnFields: ['id', 'ref'],
+      } as any,
+      client,
+      log
+    );
+
+    // Custom resolvers
+    const resolvers = {
+      'custom.generateDispatchRef': () => {
+        return `DISPATCH-${transferRequest.transferId}-${Date.now()}`;
+      },
+      'custom.negateQty': (qty: any) => {
+        return -Math.abs(qty);
+      },
+    };
+
+    const result = await dispatchMapper.mapWithNodes(transferRequest, resolvers, {
+      config: {},
+      helpers: {},
+    });
+
+    if (!result.success) {
+      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
+    }
+
+    // Execute mutation (query is auto-generated in result)
+    const response = await client.graphql({
+      query: result.query,
+      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
+    });
+
+    return {
+      success: true,
+      mutationId: response.data?.updateInventoryQuantity?.id,
+    };
+  } catch (error: any) {
+    log.error('❌ Dispatch mutation failed', {
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check dispatch mapping configuration and verify transfer request structure'
+        : error.message?.includes('inventory') || error.message?.includes('quantity')
+        ? 'Check available inventory quantity at source location'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : 'Review error details and check dispatch mutation payload',
+    });
+
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Helper: Create receipt mutation (add to destination location)
+ */
+async function createReceiptMutation(
+  client: FluentClient,
+  transferId: string,
+  items: TransferItem[],
+  transferState: TransferState,
+  log: Logger
+): Promise<{ success: boolean; mutationId?: string; error?: string }> {
+  try {
+    const receiptMapper = new GraphQLMutationMapper(
+      {
+        version: '1.0.0',
+        mutation: 'updateInventoryQuantity',
+        sourceFormat: 'json',
+        fields: {
+          'input.ref': {
+            value: `RECEIPT-${transferId}-${Date.now()}`,
+          },
+          'input.locationRef': {
+            source: 'destinationLocationRef',
+          },
+          'input.items[]': {
+            source: 'items',
+            fields: {
+              skuRef: { source: 'skuRef' },
+              qty: {
+                source: 'actualQty',
+                defaultValue: { source: 'requestedQty' }, // Use requested if actual not provided
+              },
+              type: { value: 'RECEIPT' },
+              status: { value: 'AVAILABLE' },
+            },
+          },
+        },
+        returnFields: ['id', 'ref'],
+      } as any,
+      client,
+      log
+    );
+
+    const sourceData = {
+      destinationLocationRef: transferState.originalRequest?.destinationLocationRef,
+      items,
+    };
+
+    const result = await receiptMapper.mapWithNodes(sourceData, {}, { config: {}, helpers: {} });
+
+    if (!result.success) {
+      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
+    }
+
+    // Execute mutation (query is auto-generated in result)
+    const response = await client.graphql({
+      query: result.query,
+      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
+    });
+
+    return {
+      success: true,
+      mutationId: response.data?.updateInventoryQuantity?.id,
+    };
+  } catch (error: any) {
+    log.error('❌ Receipt mutation failed', {
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check receipt mapping configuration and verify receipt data structure'
+        : error.message?.includes('inventory') || error.message?.includes('quantity')
+        ? 'Check actual quantity values and variance calculation'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : 'Review error details and check receipt mutation payload',
+    });
+
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Helper: Rollback transfer (reverse dispatch)
+ */
+async function rollbackTransfer(
+  client: FluentClient,
+  transferState: TransferState,
+  log: Logger
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const originalRequest = transferState.originalRequest;
+
+    if (!originalRequest) {
+      throw new Error('Cannot rollback: original request data missing');
+    }
+
+    const rollbackMapper = new GraphQLMutationMapper(
+      {
+        version: '1.0.0',
+        mutation: 'updateInventoryQuantity',
+        sourceFormat: 'json',
+        fields: {
+          'input.ref': {
+            value: `ROLLBACK-${transferState.transferId}-${Date.now()}`,
+          },
+          'input.locationRef': {
+            source: 'sourceLocationRef',
+          },
+          'input.items[]': {
+            source: 'items',
+            fields: {
+              skuRef: { source: 'skuRef' },
+              qty: { source: 'requestedQty' }, // Add back to source
+              type: { value: 'ROLLBACK' },
+              status: { value: 'AVAILABLE' },
+            },
+          },
+        },
+        returnFields: ['id', 'ref'],
+      } as any,
+      client,
+      log
+    );
+
+    const result = await rollbackMapper.mapWithNodes(
+      originalRequest,
+      {},
+      { config: {}, helpers: {} }
+    );
+
+    if (!result.success) {
+      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
+    }
+
+    // Execute mutation (query is auto-generated in result)
+    await client.graphql({
+      query: result.query,
+      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
+    });
+
+    return { success: true };
+  } catch (error: any) {
+    log.error('❌ Rollback failed', {
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check rollback mapping configuration and verify transfer state structure'
+        : error.message?.includes('original') || error.message?.includes('missing')
+        ? 'Original transfer request data missing - verify transfer state in KV store'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : 'Review error details and check rollback mutation payload',
+    });
+
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Helper: Calculate variance between expected and actual quantities
+ */
+function calculateVariance(
+  expectedItems: TransferItem[],
+  actualItems: TransferItem[]
+): VarianceDetails {
+  const varianceItems = [];
+  let totalExpected = 0;
+  let totalActual = 0;
+
+  for (const expectedItem of expectedItems) {
+    const actualItem = actualItems.find(i => i.skuRef === expectedItem.skuRef);
+    const expectedQty = expectedItem.requestedQty;
+    const actualQty = actualItem?.actualQty ?? expectedQty;
+
+    totalExpected += expectedQty;
+    totalActual += actualQty;
+
+    if (expectedQty !== actualQty) {
+      varianceItems.push({
+        skuRef: expectedItem.skuRef,
+        expected: expectedQty,
+        actual: actualQty,
+        difference: actualQty - expectedQty,
+        reason: actualItem?.notes,
+      });
+    }
+  }
+
+  const variancePercentage =
+    totalExpected > 0 ? Math.abs((totalActual - totalExpected) / totalExpected) * 100 : 0;
+
+  return {
+    hasVariance: varianceItems.length > 0,
+    variancePercentage,
+    requiresApproval: variancePercentage > 5, // > 5% requires approval
+    items: varianceItems,
+  };
+}
+
+/**
+ * Helper: Get transfer state from KV
+ */
+async function getTransferState(
+  kvAdapter: VersoriKVAdapter,
+  transferId: string
+): Promise<TransferState | null> {
+  const stateKey = ['transfer-state', transferId];
+  const result = await kvAdapter.get(stateKey);
+  return result?.value as TransferState | null;
+}
+
+/**
+ * Helper: Save transfer state to KV
+ */
+async function saveTransferState(
+  kvAdapter: VersoriKVAdapter,
+  transferState: TransferState
+): Promise<void> {
+  const stateKey = ['transfer-state', transferState.transferId];
+  await kvAdapter.set(stateKey, transferState);
+}
+
+/**
+ * Helper: Get all transfer states (for reconciliation)
+ */
+async function getAllTransferStates(
+  kvAdapter: VersoriKVAdapter
+): Promise<TransferState[]> {
+  // Note: This is a simplified implementation
+  // In production, you'd use KV list operations with proper pagination
+  const transfers: TransferState[] = [];
+
+  // Implementation would depend on your KV structure
+  // This is a placeholder showing the expected return type
+
+  return transfers;
+}
+
+/**
+ * Helper: Send variance notification email
+ */
+async function sendVarianceNotification(
+  transferId: string,
+  variance: VarianceDetails,
+  activation: any,
+  log: any
+): Promise<void> {
+  const emailTo = activation.getVariable('varianceNotificationEmail') as string;
+  if (!emailTo) {
+    log.warn('⚠️ Variance notification email not configured', { transferId });
+    return;
+  }
+
+  // Email sending implementation
+  // Use Versori email connector or external service
+  log.info('📧 Sending variance notification', {
+    transferId,
+    emailTo,
+    variancePercentage: variance.variancePercentage.toFixed(2) + '%',
+  });
+}
+
+/**
+ * Helper: Send completion notification
+ */
+async function sendCompletionNotification(
+  transferId: string,
+  transferState: TransferState,
+  activation: any,
+  log: any
+): Promise<void> {
+  const emailTo = activation.getVariable('completionNotificationEmail') as string;
+  if (!emailTo) return;
+
+  log.info('📧 Sending completion notification', {
+    transferId,
+    emailTo,
+  });
+}
+```
+
+---
+
+### 3. Workflow: Initiate Transfer (`src/workflows/webhook/initiate-transfer.ts`)
+
+```typescript
+/**
+ * Webhook: Initiate Transfer
+ *
+ * Endpoint: POST https://{workspace}.versori.run/initiate-transfer
+ * Request body: TransferRequest (JSON)
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: transfer.service.ts
+ */
+
+import { webhook, http } from '@versori/run';
+import { processTransferRequest } from '../../services/transfer.service';
+
+export const initiateTransfer = webhook('initiate-transfer', {
+  response: { mode: 'sync' },
+  connection: 'initiate-transfer', // Versori validates API key
+}).then(
+  http('process-transfer-request', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+    const jobId = `transfer-${Date.now()}`;
+
+    log.info('═══════════════════════════════════════════════════════');
+    log.info('📦 TRANSFER REQUEST RECEIVED', { jobId });
+    log.info('═══════════════════════════════════════════════════════');
+
+    try {
+      const result = await processTransferRequest(ctx, data);
+
+      if (result.success) {
+        log.info('✅ TRANSFER REQUEST COMPLETED', { jobId, result });
+      } else {
+        log.error('❌ TRANSFER REQUEST FAILED', { jobId, error: result.error });
+      }
+
+      return { success: result.success, jobId, ...result };
+    } catch (e: any) {
+      log.error('❌ TRANSFER REQUEST FAILED', { jobId, error: e.message });
+      return { success: false, jobId, error: e.message };
+    }
+  })
+);
+```
+
+---
+
+### 4. Workflow: Receive Transfer (`src/workflows/webhook/receive-transfer.ts`)
+
+```typescript
+/**
+ * Webhook: Receive Transfer (Receipt Confirmation)
+ *
+ * Endpoint: POST https://{workspace}.versori.run/receive-transfer
+ * Request body: { transferId, receivedDate, items[] }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: transfer.service.ts
+ */
+
+import { webhook, http } from '@versori/run';
+import { processReceiptConfirmation } from '../../services/transfer.service';
+
+export const receiveTransfer = webhook('receive-transfer', {
+  response: { mode: 'sync' },
+  connection: 'receive-transfer',
+}).then(
+  http('process-receipt-confirmation', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+    const jobId = `receipt-${Date.now()}`;
+
+    log.info('═══════════════════════════════════════════════════════');
+    log.info('📦 RECEIPT CONFIRMATION RECEIVED', { jobId, transferId: data.transferId });
+    log.info('═══════════════════════════════════════════════════════');
+
+    try {
+      const result = await processReceiptConfirmation(ctx, data);
+
+      if (result.success) {
+        log.info('✅ RECEIPT CONFIRMATION COMPLETED', { jobId, result });
+      } else {
+        log.error('❌ RECEIPT CONFIRMATION FAILED', { jobId, error: result.error });
+      }
+
+      return { success: result.success, jobId, ...result };
+    } catch (e: any) {
+      log.error('❌ RECEIPT CONFIRMATION FAILED', { jobId, error: e.message });
+      return { success: false, jobId, error: e.message };
+    }
+  })
+);
+```
+
+---
+
+### 5. Workflow: Reconcile Transfers (`src/workflows/scheduled/reconcile-transfers.ts`)
+
+```typescript
+/**
+ * Scheduled Workflow: Transfer Reconciliation
+ *
+ * Runs automatically daily at 1 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Finds stale in-transit transfers (> 24 hours) and generates alerts
+ * Uses JobTracker for status tracking
+ */
+
+import { schedule, http } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { runReconciliation } from '../../services/transfer.service';
+
+export const reconcileTransfers = schedule(
+  'reconcile-transfers',
+  '0 1 * * *' // Daily at 1 AM UTC
+).then(
+  http('run-reconciliation', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, openKv } = ctx;
+    const jobId = `reconcile-${Date.now()}`;
+
+    log.info('═══════════════════════════════════════════════════════');
+    log.info('🔄 RECONCILIATION STARTED', { jobId });
+    log.info('═══════════════════════════════════════════════════════');
+
+    const tracker = new JobTracker(openKv(':project:'), log);
+    await tracker.createJob(jobId, { triggeredBy: 'schedule' });
+
+    try {
+      const result = await runReconciliation(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+
+      log.info('✅ RECONCILIATION COMPLETED', { jobId, result });
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+
+      log.error('❌ RECONCILIATION FAILED', { jobId, error: e.message });
+      return { success: false, jobId, error: e.message };
+    }
+  })
+);
+```
+
+---
+
+### 6. Workflow: Export Transfer Report (`src/workflows/webhook/export-transfer-report.ts`)
+
+```typescript
+/**
+ * Webhook: Export Transfer Report
+ *
+ * Endpoint: POST https://{workspace}.versori.run/export-transfer-report
+ * Request body: { startDate, endDate }
+ *
+ * Pattern: webhook().then(fn()) - no external API needed, only KV storage
+ * Queries KV store for transfer states and generates report
+ */
+
+import { webhook, fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const exportTransferReport = webhook('export-transfer-report', {
+  response: { mode: 'sync' },
+  connection: 'export-transfer-report',
+}).then(
+  fn('generate-report', async ctx => {
+    const { log, openKv, data } = ctx;
+    const { startDate, endDate } = data;
+
+    log.info('═══════════════════════════════════════════════════════');
+    log.info('📊 TRANSFER REPORT EXPORT', { startDate, endDate });
+    log.info('═══════════════════════════════════════════════════════');
+
+    try {
+      const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+
+      // Query transfer states (simplified - implement proper date filtering)
+      const transfers: any[] = []; // getAllTransferStates(kvAdapter, startDate, endDate);
+
+      const report = {
+        period: { startDate, endDate },
+        totalTransfers: transfers.length,
+        byStatus: {
+          pending: transfers.filter(t => t.status === 'PENDING').length,
+          dispatched: transfers.filter(t => t.status === 'DISPATCHED').length,
+          inTransit: transfers.filter(t => t.status === 'IN_TRANSIT').length,
+          received: transfers.filter(t => t.status === 'RECEIVED').length,
+          failed: transfers.filter(t => t.status === 'FAILED').length,
+          rolledBack: transfers.filter(t => t.status === 'ROLLED_BACK').length,
+        },
+        transfers: transfers.map(t => ({
+          transferId: t.transferId,
+          status: t.status,
+          sourceLocation: t.originalRequest?.sourceLocationRef,
+          destinationLocation: t.originalRequest?.destinationLocationRef,
+          itemCount: t.originalRequest?.items?.length || 0,
+          createdAt: t.createdAt,
+          completedAt: t.receivedAt || t.updatedAt,
+        })),
+      };
+
+      log.info('✅ REPORT GENERATED', {
+        totalTransfers: report.totalTransfers,
+        byStatus: report.byStatus,
+      });
+
+      return { success: true, report };
+    } catch (e: any) {
+      log.error('❌ REPORT EXPORT FAILED', { error: e.message });
+      return { success: false, error: e.message };
+    }
+  })
+);
+```
+
+---
+
+## Configuration
+
+### Activation Variables Configuration
+
+```bash
+# Required Variables
+fluentRetailerId=my-retailer-id
+
+# S3 Configuration (for CSV-based transfers)
+s3TransferBucket=my-transfers-bucket
+awsAccessKeyId=AKIAXXXXXXXXXXXX
+awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+awsRegion=us-east-1
+s3TransferPrefix=transfers/
+
+# Email Notifications
+varianceNotificationEmail=warehouse-manager@company.com
+completionNotificationEmail=logistics@company.com
+```
+
+### GraphQL Mutation Mapping Configuration: `config/transfer-mappings.json`
+
+```json
+{
+  "dispatch": {
+    "version": "1.0.0",
+    "mutation": "updateInventoryQuantity",
+    "sourceFormat": "json",
+    "fields": {
+      "input.ref": {
+        "resolver": "custom.generateDispatchRef"
+      },
+      "input.locationRef": {
+        "source": "sourceLocationRef",
+        "required": true
+      },
+      "input.items": {
+        "source": "items",
+        "isArray": true,
+        "fields": {
+          "skuRef": {
+            "source": "skuRef",
+            "required": true
+          },
+          "qty": {
+            "source": "requestedQty",
+            "resolver": "custom.negateQty",
+            "required": true
+          },
+          "type": {
+            "value": "DISPATCH"
+          },
+          "status": {
+            "value": "AVAILABLE"
+          }
+        }
+      }
+    },
+    "returnFields": ["id", "ref"]
+  },
+  "receipt": {
+    "version": "1.0.0",
+    "mutation": "updateInventoryQuantity",
+    "sourceFormat": "json",
+    "fields": {
+      "input.ref": {
+        "resolver": "custom.generateReceiptRef"
+      },
+      "input.locationRef": {
+        "source": "destinationLocationRef",
+        "required": true
+      },
+      "input.items": {
+        "source": "items",
+        "isArray": true,
+        "fields": {
+          "skuRef": {
+            "source": "skuRef",
+            "required": true
+          },
+          "qty": {
+            "source": "actualQty",
+            "required": true
+          },
+          "type": {
+            "value": "RECEIPT"
+          },
+          "status": {
+            "value": "AVAILABLE"
+          }
+        }
+      }
+    },
+    "returnFields": ["id", "ref"]
+  }
+}
+```
+
+---
+
+## Input/Output Examples
+
+### CSV Input Format Example: `sample-transfer.csv`
+
+```csv
+transfer_id,source_location,destination_location,requested_date,expected_delivery,items
+TRF-001,WH-EAST,STORE-NYC,2025-01-15,2025-01-17,"[{""sku"":""SKU-001"",""qty"":100},{""sku"":""SKU-002"",""qty"":50}]"
+TRF-002,WH-WEST,STORE-LA,2025-01-15,2025-01-18,"[{""sku"":""SKU-003"",""qty"":200}]"
+```
+
+### JSON Input Format Example
+
+```json
+{
+  "transferId": "TRF-001",
+  "sourceLocationRef": "WH-EAST",
+  "destinationLocationRef": "STORE-NYC",
+  "requestedDate": "2025-01-15T10:00:00Z",
+  "expectedDeliveryDate": "2025-01-17T10:00:00Z",
+  "items": [
+    {
+      "skuRef": "SKU-001",
+      "requestedQty": 100,
+      "condition": "NEW"
+    },
+    {
+      "skuRef": "SKU-002",
+      "requestedQty": 50,
+      "condition": "NEW"
+    }
+  ],
+  "metadata": {
+    "reason": "Store restocking",
+    "priority": "HIGH",
+    "requestedBy": "manager@store.com"
+  }
+}
+```
+
+### Receipt Confirmation Format
+
+```json
+{
+  "transferId": "TRF-001",
+  "receivedDate": "2025-01-17T14:30:00Z",
+  "items": [
+    {
+      "skuRef": "SKU-001",
+      "requestedQty": 100,
+      "actualQty": 98,
+      "notes": "2 units damaged in transit"
+    },
+    {
+      "skuRef": "SKU-002",
+      "requestedQty": 50,
+      "actualQty": 50
+    }
+  ]
+}
+```
+
+---
+
+## Versori Workflow Structure
+
+### Workflow Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Transfer Request                          │
+│          (Webhook JSON or Scheduled CSV)                     │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ├─ Acquire Lock
+                       │
+                       ├─ Initialize Transfer State (PENDING)
+                       │
+                       ├─ Create Dispatch Mutation
+                       │   └─ Remove from Source Location
+                       │
+                       ├─ Update State (IN_TRANSIT)
+                       │
+                       └─ Release Lock
+                       │
+┌──────────────────────┴──────────────────────────────────────┐
+│                    Receipt Confirmation                      │
+│                      (Webhook JSON)                          │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ├─ Acquire Lock
+                       │
+                       ├─ Calculate Variance
+                       │   ├─ If > 5% → Require Approval
+                       │   │   └─ Send Email Notification
+                       │   │
+                       │   └─ If <= 5% → Auto-Approve
+                       │
+                       ├─ Create Receipt Mutation
+                       │   └─ Add to Destination Location
+                       │
+                       ├─ Update State (RECEIVED)
+                       │
+                       ├─ Send Completion Notification
+                       │
+                       └─ Release Lock
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: Paired Mutations (Dispatch + Receipt)
+
+**Dispatch Mutation** (Remove from source):
+
+```typescript
+const dispatchPayload = {
+  input: {
+    ref: 'DISPATCH-TRF-001-1234567890',
+    locationRef: 'WH-EAST',
+    items: [
+      {
+        skuRef: 'SKU-001',
+        qty: -100, // Negative quantity for removal
+        type: 'DISPATCH',
+        status: 'AVAILABLE',
+      },
+    ],
+  },
+};
+```
+
+**Receipt Mutation** (Add to destination):
+
+```typescript
+const receiptPayload = {
+  input: {
+    ref: 'RECEIPT-TRF-001-1234567891',
+    locationRef: 'STORE-NYC',
+    items: [
+      {
+        skuRef: 'SKU-001',
+        qty: 98, // Actual quantity received
+        type: 'RECEIPT',
+        status: 'AVAILABLE',
+      },
+    ],
+  },
+};
+```
+
+**Why Paired Mutations?**
+
+- **Atomicity**: Each mutation is atomic (all-or-nothing)
+- **Audit Trail**: Separate records for dispatch and receipt
+- **Rollback**: Can reverse dispatch if receipt fails
+- **Variance Tracking**: Compare dispatch vs receipt quantities
+
+### Pattern 2: In-Transit Inventory Tracking
+
+**VersoriKV State Schema**:
+
+```typescript
+interface TransferState {
+  transferId: string;
+  status: 'PENDING' | 'DISPATCHED' | 'IN_TRANSIT' | 'RECEIVED' | 'FAILED' | 'ROLLED_BACK';
+  dispatchMutationId?: string;
+  receiptMutationId?: string;
+  dispatchedAt?: string;
+  receivedAt?: string;
+  variance?: VarianceDetails;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+**State Transitions**:
+
+```
+PENDING → DISPATCHED → IN_TRANSIT → RECEIVED
+                  ↓
+              FAILED → ROLLED_BACK
+```
+
+**Tracking Benefits**:
+
+- Know what's in transit at any time
+- Query transfer status via API
+- Handle partial receipts
+- Track transit times for analytics
+
+### Pattern 3: Variance Handling
+
+**Variance Calculation**:
+
+```typescript
+function calculateVariance(expected: TransferItem[], actual: TransferItem[]): VarianceDetails {
+  let totalExpected = 0;
+  let totalActual = 0;
+  const varianceItems = [];
+
+  for (const expectedItem of expected) {
+    const actualItem = actual.find(i => i.skuRef === expectedItem.skuRef);
+    const expectedQty = expectedItem.requestedQty;
+    const actualQty = actualItem?.actualQty ?? expectedQty;
+
+    totalExpected += expectedQty;
+    totalActual += actualQty;
+
+    if (expectedQty !== actualQty) {
+      varianceItems.push({
+        skuRef: expectedItem.skuRef,
+        expected: expectedQty,
+        actual: actualQty,
+        difference: actualQty - expectedQty,
+        reason: actualItem?.notes,
+      });
+    }
+  }
+
+  const variancePercentage = Math.abs((totalActual - totalExpected) / totalExpected) * 100;
+
+  return {
+    hasVariance: varianceItems.length > 0,
+    variancePercentage,
+    requiresApproval: variancePercentage > 5,
+    items: varianceItems,
+  };
+}
+```
+
+**Approval Thresholds**:
+
+- **< 5% variance**: Auto-approve (minor discrepancies expected)
+- **> 5% variance**: Require manual approval
+- **Email notification**: Sent to warehouse manager
+- **Approval webhook**: `/approve-variance` endpoint
+
+### Pattern 4: Rollback on Failure
+
+**When to Rollback**:
+
+- Receipt mutation fails
+- Variance rejected by manager
+- Destination location unavailable
+- Critical validation errors
+
+**Rollback Implementation**:
+
+```typescript
+async function rollbackTransfer(
+  client: any,
+  transferState: TransferState,
+  log: Logger
+): Promise<void> {
+  // Create reverse dispatch mutation (add back to source)
+  const rollbackPayload = {
+    input: {
+      ref: `ROLLBACK-${transferState.transferId}`,
+      locationRef: originalSourceLocation,
+      items: originalItems.map(item => ({
+        skuRef: item.skuRef,
+        qty: item.requestedQty, // Positive quantity (add back)
+        type: 'ROLLBACK',
+        status: 'AVAILABLE',
+      })),
+    },
+  };
+
+  await client.graphql({
+    query: rollbackMutation,
+    variables: rollbackPayload,
+  });
+
+  // Update state
+  transferState.status = 'ROLLED_BACK';
+  await saveTransferState(kvAdapter, transferState);
+}
+```
+
+**Rollback Guarantees**:
+
+- Inventory returned to source location
+- Audit trail preserved (ROLLBACK type)
+- State updated to ROLLED_BACK
+- Prevents inventory loss
+
+### Pattern 5: Multi-Leg Transfers (A → B → C)
+
+For complex transfers through intermediate locations:
+
+```typescript
+interface MultiLegTransfer {
+  transferId: string;
+  legs: TransferLeg[];
+  currentLeg: number;
+  overallStatus: string;
+}
+
+interface TransferLeg {
+  legId: string;
+  sourceLocationRef: string;
+  destinationLocationRef: string;
+  status: string;
+  dispatchedAt?: string;
+  receivedAt?: string;
+}
+
+async function processMultiLegTransfer(
+  transfer: MultiLegTransfer,
+  client: any,
+  log: Logger
+): Promise<void> {
+  for (let i = transfer.currentLeg; i < transfer.legs.length; i++) {
+    const leg = transfer.legs[i];
+
+    // Dispatch from current location
+    await createDispatchMutation(
+      client,
+      {
+        ...transfer,
+        sourceLocationRef: leg.sourceLocationRef,
+        destinationLocationRef: leg.destinationLocationRef,
+      },
+      log
+    );
+
+    // Wait for receipt confirmation (via webhook)
+    // State management tracks current leg
+    transfer.currentLeg = i;
+    await saveTransferState(kvAdapter, transfer);
+
+    // Receipt confirmation advances to next leg
+  }
+
+  transfer.overallStatus = 'COMPLETED';
+  await saveTransferState(kvAdapter, transfer);
+}
+```
+
+---
+
+## Testing
+
+### 1. Test Dispatch Request
+
+```bash
+curl -X POST https://your-workspace.versori.run/initiate-transfer \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transferId": "TEST-001",
+    "sourceLocationRef": "WH-TEST",
+    "destinationLocationRef": "STORE-TEST",
+    "requestedDate": "2025-01-15T10:00:00Z",
+    "items": [
+      {
+        "skuRef": "TEST-SKU-001",
+        "requestedQty": 10
+      }
+    ]
+  }'
+```
+
+Expected response:
+
+```json
+{
+  "success": true,
+  "transferId": "TEST-001",
+  "status": "IN_TRANSIT",
+  "dispatchMutationId": "12345",
+  "message": "Transfer dispatched successfully, awaiting receipt confirmation"
+}
+```
+
+### 2. Test Receipt Confirmation (No Variance)
+
+```bash
+curl -X POST https://your-workspace.versori.run/receive-transfer \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transferId": "TEST-001",
+    "receivedDate": "2025-01-17T14:00:00Z",
+    "items": [
+      {
+        "skuRef": "TEST-SKU-001",
+        "requestedQty": 10,
+        "actualQty": 10
+      }
+    ]
+  }'
+```
+
+Expected response:
+
+```json
+{
+  "success": true,
+  "status": "RECEIVED",
+  "transferId": "TEST-001",
+  "receiptMutationId": "12346"
+}
+```
+
+### 3. Test Receipt with Variance
+
+```bash
+curl -X POST https://your-workspace.versori.run/receive-transfer \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transferId": "TEST-002",
+    "receivedDate": "2025-01-17T14:00:00Z",
+    "items": [
+      {
+        "skuRef": "TEST-SKU-001",
+        "requestedQty": 100,
+        "actualQty": 90,
+        "notes": "10 units damaged"
+      }
+    ]
+  }'
+```
+
+Expected response (variance > 5%):
+
+```json
+{
+  "success": true,
+  "status": "PENDING_APPROVAL",
+  "transferId": "TEST-002",
+  "variance": {
+    "hasVariance": true,
+    "variancePercentage": 10,
+    "requiresApproval": true,
+    "items": [
+      {
+        "skuRef": "TEST-SKU-001",
+        "expected": 100,
+        "actual": 90,
+        "difference": -10,
+        "reason": "10 units damaged"
+      }
+    ]
+  },
+  "message": "Variance requires manual approval"
+}
+```
+
+---
+
+## Common Issues & Solutions
+
+### Issue 1: Duplicate Transfer Processing
+
+**Symptoms:**
+
+- Same transfer processed multiple times
+- Double dispatch/receipt
+
+**Root Cause:**
+
+- Lock not acquired
+- Transfer state not checked
+
+**Solution:**
+
+```typescript
+// Always check existing state before processing
+const existingState = await getTransferState(kvAdapter, transferId);
+if (existingState && existingState.status !== 'FAILED') {
+  log.warn('Transfer already processed', { transferId, status: existingState.status });
+  return { success: false, error: 'Already processed' };
+}
+
+// Always acquire lock
+const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
+if (!lockAcquired) {
+  throw new Error('Could not acquire lock');
+}
+```
+
+### Issue 2: Variance Not Detected
+
+**Symptoms:**
+
+- Receipts with different quantities not flagged
+- No approval required
+
+**Root Cause:**
+
+- Variance calculation logic incorrect
+- Percentage threshold too high
+
+**Solution:**
+
+```typescript
+// Ensure variance calculation includes all items
+function calculateVariance(expected: TransferItem[], actual: TransferItem[]): VarianceDetails {
+  // Check EVERY item, not just first mismatch
+  for (const expectedItem of expected) {
+    const actualItem = actual.find(i => i.skuRef === expectedItem.skuRef);
+    if (!actualItem) {
+      // Item completely missing
+      varianceItems.push({
+        skuRef: expectedItem.skuRef,
+        expected: expectedItem.requestedQty,
+        actual: 0,
+        difference: -expectedItem.requestedQty,
+        reason: 'Item not received',
+      });
+    }
+  }
+
+  // Calculate percentage correctly
+  const variancePercentage =
+    totalExpected > 0 ? Math.abs((totalActual - totalExpected) / totalExpected) * 100 : 0;
+
+  return {
+    hasVariance: varianceItems.length > 0,
+    variancePercentage,
+    requiresApproval: variancePercentage > 5, // Adjust threshold as needed
+    items: varianceItems,
+  };
+}
+```
+
+### Issue 3: Rollback Fails
+
+**Symptoms:**
+
+- Transfer marked as ROLLED_BACK but inventory not restored
+- GraphQL mutation errors
+
+**Root Cause:**
+
+- Original request data not stored in state
+- Rollback mutation invalid
+
+**Solution:**
+
+```typescript
+// Store original request when creating transfer state
+const transferState: TransferState = {
+  transferId,
+  status: 'PENDING',
+  originalRequest: transferRequest, // Store for rollback
+  // ... other fields
+};
+await saveTransferState(kvAdapter, transferState);
+
+// Validate rollback payload before sending
+async function rollbackTransfer(client: any, transferState: TransferState, log: Logger) {
+  const originalRequest = transferState.originalRequest;
+  if (!originalRequest) {
+    throw new Error('Cannot rollback: original request data missing');
+  }
+
+  // Validate items exist
+  if (!originalRequest.items || originalRequest.items.length === 0) {
+    throw new Error('Cannot rollback: no items in original request');
+  }
+
+  // Create rollback mutation...
+}
+```
+
+### Issue 4: Email Notifications Not Sent
+
+**Symptoms:**
+
+- No emails for variance or completion
+- Silent failures
+
+**Root Cause:**
+
+- Email service not configured
+- Missing activation variables
+- Email connector not connected
+
+**Solution:**
+
+```typescript
+async function sendVarianceNotification(
+  transferId: string,
+  variance: VarianceDetails,
+  activation: any,
+  log: any
+): Promise<void> {
+  const emailTo = activation.getVariable('varianceNotificationEmail') as string;
+
+  if (!emailTo) {
+    log.warn('Variance notification email not configured', { transferId });
+    return; // Don't fail transfer if email not configured
+  }
+
+  try {
+    // Send email via Versori connector or external service
+    // Example: SendGrid, AWS SES, etc.
+    await sendEmail({
+      to: emailTo,
+      subject: `Transfer Variance Requires Approval: ${transferId}`,
+      body: formatVarianceEmail(transferId, variance),
+    });
+
+    log.info('Variance notification sent', { transferId, emailTo });
+  } catch (error: any) {
+    // Log error but don't fail transfer
+    log.error('Failed to send variance notification', error, { transferId });
+  }
+}
+```
+
+---
+
+## Related Guides
+
+- **02-scheduled-csv-inventory.md** - CSV processing patterns
+- **03-kv-state-management.md** - State tracking and locking
+- **04-webhook-xml-response.md** - Webhook response patterns
+- **GraphQL Mutation Mapping**: `../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
+- **Universal Mapping**: `../../02-CORE-GUIDES/mapping/readme.md`
+
+---
+
+## Summary
+
+This guide demonstrated inter-location transfer processing with:
+
+1. **Paired Mutations**: Dispatch and receipt for audit trail
+2. **In-Transit Tracking**: VersoriKV state management
+3. **Variance Handling**: Automatic approval thresholds and manual review
+4. **Rollback Logic**: Restore inventory on failure
+5. **Multi-Format Support**: JSON webhooks and CSV scheduled imports
+6. **Email Notifications**: Variance alerts and completion notices
+
+**Key Takeaways**:
+
+- Use paired mutations for complete audit trail
+- Track transfer state in VersoriKV for visibility
+- Implement variance thresholds (e.g., 5%) for auto-approval
+- Always store original request for rollback capability
+- Use distributed locking to prevent duplicate processing
+- Handle both webhook and scheduled triggers
+
+**Production Considerations**:
+
+- Monitor variance approval queue
+- Set up alerts for stuck transfers
+- Track average transit times
+- Implement retry logic for transient failures
+- Add comprehensive logging for debugging
+- Test rollback scenarios thoroughly