@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/patterns/versori-patterns-kv-state-management.md

@@ -1,1533 +1,1533 @@
-# Versori KV State Management
-
-**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**: Use Versori KV storage for duplicate prevention, checkpoints, and file tracking
-
-**Complexity**: Low-Medium
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~400 lines
-
-## What You'll Build
-
-- VersoriKV adapter setup
-- File tracking (prevent duplicates)
-- Checkpoint/resume capabilities
-- Batch processing state
-- Error tracking and retry logic
-
-## SDK Methods Used
-
-- `VersoriKVAdapter(openKv())` - Wrap Versori KV for StateService
-- `VersoriFileTracker(openKv())` - Simple file tracking
-- `VersoriIndexedFileTracker(openKv())` - File tracking with listing support
-- `StateService(logger)` - High-level state operations
-- `stateService.isFileProcessed(kv, key)` - Check if processed
-- `stateService.acquireLock(lockName, kv, timeoutMinutes)` - Distributed locking
-- `stateService.getSyncState(kv, workflowId)` - Get sync state
-- `stateService.updateSyncState(kv, files, workflowId)` - Update sync state
-- `stateService.getDailyJob(kv, workflowId)` - Get daily job
-- `stateService.setDailyJob(kv, workflowId, jobId, hours)` - Store daily job
-
----
-
-## 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
-
-```
-kv-state-management/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── webhook/
-    │   │   └── file-ingestion.ts         # Webhook: File processing
-    │   │
-    │   └── scheduled/
-    │       └── daily-sync.ts             # Scheduled: Daily sync
-    │
-    ├── services/
-    │   └── state-management.service.ts    # Shared state logic (reusable)
-    │
-    └── config/
-        └── state-config.json             # 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
-
----
-
-## Complete Working Code
-
-### Pattern 1: Simple File Duplicate Prevention
-
-**Use Case**: Prevent reprocessing the same files in ingestion workflows.
-
-```typescript
-import { webhook, fn } from '@versori/run';
-// FC Connect SDK+
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Simple file tracking pattern
- * Perfect for basic duplicate prevention without complex state management
- */
-export const simpleFileIngestion = webhook('ingest-files', {
-  response: { mode: 'sync' }
-})
-  .then(fn('check-and-process-files', async (ctx) => {
-    const { openKv, log, data } = ctx;
-
-    // Initialize simple file tracker
-    const fileTracker = new VersoriFileTracker(openKv(':project:'), 'inventory-ingestion');
-
-    // Sample files to process
-    const files = data.files || [
-      { name: 'inventory-2025-01-15.csv', url: 's3://bucket/file1.csv' },
-      { name: 'inventory-2025-01-16.csv', url: 's3://bucket/file2.csv' }
-    ];
-
-    const processedFiles = [];
-    const skippedFiles = [];
-
-    for (const file of files) {
-      // Check if file was already processed
-      const wasProcessed = await fileTracker.wasFileProcessed(file.name);
-
-      if (wasProcessed) {
-        log.info(`⏭️ [FileTracking] Skipping already processed file: ${file.name}`);
-        skippedFiles.push(file.name);
-        continue;
-      }
-
-      try {
-        // Process the file (your ingestion logic here)
-        log.info(`🚀 [Processing] Processing file: ${file.name}`);
-        const recordCount = await processFile(file);
-
-        // Mark as processed with metadata
-        await fileTracker.markFileProcessed(file.name, {
-          recordCount,
-          processedBy: 'webhook-ingestion',
-          source: file.url
-        });
-
-        processedFiles.push({ name: file.name, recordCount });
-        log.info(`✅ [Success] Successfully processed: ${file.name} (${recordCount} records)`);
-      } catch (error) {
-        // ? Enhanced: Error logging with recommendations
-        log.error('[KVStateManagement] Failed to process file', {
-          fileName: file.name,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-          recommendation: error.message?.includes('parse') || error.message?.includes('format')
-            ? 'Check file format and structure - ensure file is valid'
-            : error.message?.includes('mapping') || error.message?.includes('field')
-            ? 'Check mapping configuration and verify file column structure'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and data source availability'
-            : 'Review error details and check file processing logic'
-        });
-        throw error; // Fail workflow so we can retry later
-      }
-    }
-
-    // Track last processed file
-    if (processedFiles.length > 0) {
-      const lastFile = processedFiles[processedFiles.length - 1];
-      await fileTracker.setLastProcessedFile(lastFile.name);
-    }
-
-    return {
-      success: true,
-      processed: processedFiles,
-      skipped: skippedFiles,
-      lastProcessedFile: await fileTracker.getLastProcessedFile()
-    };
-  }));
-
-// Helper function (implement based on your data source)
-async function processFile(file: { name: string; url: string }): Promise<number> {
-  // Your file processing logic
-  return 1000; // Return record count
-}
-```
-
-**Key Points**:
-
-- `VersoriFileTracker` is lightweight - perfect for simple use cases
-- Automatic duplicate prevention with `wasFileProcessed()`
-- Stores metadata like record count with each file
-- Tracks last processed file for incremental processing
-
----
-
-### Pattern 2: Distributed Locking with StateService
-
-**Use Case**: Prevent concurrent workflow executions with distributed locks.
-
-```typescript
-import { schedule, fn } from '@versori/run';
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Distributed locking pattern
- * Prevents multiple instances from running simultaneously
- */
-export const scheduledIngestionWithLock = schedule('inventory-sync', '0 */6 * * *')
-  .then(fn('acquire-lock', async (ctx) => {
-    const { openKv, log } = ctx;
-
-    // Create StateService with KV adapter
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-
-    // Try to acquire lock (15 minute timeout)
-    const lockName = 'inventory-sync-lock';
-    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
-
-    if (!lockAcquired) {
-      log.warn('⚠️ [Lock] Lock already held, skipping this run');
-      return {
-        shouldSkip: true,
-        reason: 'Lock already held by another instance'
-      };
-    }
-
-    log.info('🔐 [Lock] Lock acquired successfully');
-    return {
-      shouldSkip: false,
-      lockName,
-      kvAdapter,
-      stateService
-    };
-  }))
-  .then(fn('process-with-lock', async ({ data, log }) => {
-    if (data.shouldSkip) {
-      return data;
-    }
-
-    const { kvAdapter, stateService, lockName } = data;
-
-    try {
-      // Your ingestion logic here
-      log.info('🚀 [Processing] Processing inventory sync...');
-      await performIngestion();
-      log.info('✅ [Success] Ingestion completed successfully');
-
-      return { success: true };
-    } finally {
-      // ALWAYS release lock in finally block
-      await stateService.releaseLock(lockName, kvAdapter);
-      log.info('🔓 [Lock] Lock released');
-    }
-  }))
-  .catch(fn('handle-error-and-release-lock', async ({ data, error, log }) => {
-    // Ensure lock is released even on error
-    if (data?.stateService && data?.lockName && data?.kvAdapter) {
-      await data.stateService.releaseLock(data.lockName, data.kvAdapter);
-      log.info('🔓 [Lock] Lock released after error');
-    }
-
-    log.error('❌ [Error] Ingestion failed', error as Error);
-    return { success: false, error: (error as Error).message };
-  }));
-
-async function performIngestion(): Promise<void> {
-  // Your ingestion logic
-  await new Promise(resolve => setTimeout(resolve, 1000));
-}
-```
-
-**Key Points**:
-
-- Distributed locking prevents concurrent executions
-- Stale lock detection (automatically overrides expired locks)
-- Lock timeout ensures recovery from crashes
-- ALWAYS release locks in finally blocks
-- Proper error handling to prevent lock leaks
-
----
-
-### Pattern 3: Checkpoint & Resume
-
-**Use Case**: Save progress during long-running workflows and resume from last checkpoint.
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-interface CheckpointData {
-  currentBatch: number;
-  totalBatches: number;
-  processedRecords: number;
-  lastProcessedId: string;
-  startTime: string;
-}
-
-/**
- * Checkpoint & resume pattern
- * Useful for long-running batch processing that might fail partway through
- */
-export const batchProcessingWithCheckpoints = webhook('process-batches', {
-  response: { mode: 'sync' }
-})
-  .then(fn('check-checkpoint', async (ctx) => {
-    const { openKv, log, data } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-    const workflowId = 'batch-processing';
-    const checkpointKey = `checkpoint:${workflowId}`;
-
-    // Try to restore from checkpoint
-    const syncState = await stateService.getSyncState(kvAdapter, workflowId);
-    let checkpoint: CheckpointData | null = null;
-
-    if (syncState.isInitialized) {
-      // Check if there's a saved checkpoint (stored in custom state)
-      const stored = await kvAdapter.get([checkpointKey]);
-      if (stored?.value) {
-        checkpoint = stored.value as CheckpointData;
-        log.info('♻️ [Checkpoint] Resuming from checkpoint', checkpoint);
-      }
-    }
-
-    // Get batches to process
-    const allBatches = data.batches || generateBatches(100); // 100 batches total
-
-    // Determine starting point
-    const startBatch = checkpoint ? checkpoint.currentBatch : 0;
-    const processedSoFar = checkpoint ? checkpoint.processedRecords : 0;
-
-    return {
-      batches: allBatches,
-      startBatch,
-      processedSoFar,
-      kvAdapter,
-      stateService,
-      workflowId,
-      checkpointKey,
-      startTime: checkpoint?.startTime || new Date().toISOString()
-    };
-  }))
-  .then(fn('process-with-checkpoints', async ({ data, log }) => {
-    const {
-      batches,
-      startBatch,
-      processedSoFar,
-      kvAdapter,
-      stateService,
-      workflowId,
-      checkpointKey,
-      startTime
-    } = data;
-
-    let processedRecords = processedSoFar;
-
-    // Process batches starting from checkpoint
-    for (let i = startBatch; i < batches.length; i++) {
-      const batch = batches[i];
-
-      try {
-        log.info(`🚀 [Processing] Processing batch ${i + 1}/${batches.length}`);
-
-        // Process the batch
-        const result = await processBatch(batch);
-        processedRecords += result.recordCount;
-
-        // Save checkpoint after each batch (or every N batches)
-        if ((i + 1) % 10 === 0 || i === batches.length - 1) {
-          const checkpoint: CheckpointData = {
-            currentBatch: i + 1,
-            totalBatches: batches.length,
-            processedRecords,
-            lastProcessedId: result.lastId,
-            startTime
-          };
-
-          await kvAdapter.set([checkpointKey], checkpoint);
-          log.info(`💾 [Checkpoint] Checkpoint saved at batch ${i + 1}`);
-        }
-      } catch (error) {
-        // ? Enhanced: Error logging with recommendations
-        log.error('[KVStateManagement] Batch processing failed', {
-          batchNumber: i + 1,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('mutation') || error.message?.includes('GraphQL')
-            ? 'Check GraphQL mutation syntax and batch payload structure'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details - checkpoint saved for retry'
-        });
-
-        // Save checkpoint at failure point
-        const checkpoint: CheckpointData = {
-          currentBatch: i, // Retry this batch
-          totalBatches: batches.length,
-          processedRecords,
-          lastProcessedId: batch[0]?.id || '',
-          startTime
-        };
-
-        await kvAdapter.set([checkpointKey], checkpoint);
-        throw error; // Fail workflow so it can be retried
-      }
-    }
-
-    // All batches processed - clear checkpoint
-    await kvAdapter.delete([checkpointKey]);
-    log.info('✅ [Checkpoint] All batches processed, checkpoint cleared');
-
-    // Update final sync state
-    await stateService.updateSyncState(kvAdapter, [{
-      fileName: 'batch-processing-complete',
-      lastModified: new Date().toISOString(),
-      recordCount: processedRecords
-    }], workflowId);
-
-    return {
-      success: true,
-      totalBatches: batches.length,
-      processedRecords,
-      duration: Date.now() - new Date(startTime).getTime()
-    };
-  }));
-
-function generateBatches(count: number): any[] {
-  return Array.from({ length: count }, (_, i) => ({
-    id: `batch-${i + 1}`,
-    data: []
-  }));
-}
-
-async function processBatch(batch: any): Promise<{ recordCount: number; lastId: string }> {
-  // Your batch processing logic
-  await new Promise(resolve => setTimeout(resolve, 100));
-  return { recordCount: 50, lastId: batch.id };
-}
-```
-
-**Key Points**:
-
-- Save checkpoints periodically (not after every operation)
-- Store enough context to resume exactly where you left off
-- Clear checkpoint after successful completion
-- On failure, checkpoint allows resuming without reprocessing
-
----
-
-### Pattern 4: Daily Job Management
-
-**Use Case**: Reuse jobs across multiple batches throughout the day (DAILY strategy).
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import {
-  StateService,
-  VersoriKVAdapter,
-  createClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Daily job management pattern
- * Reuses a single job for multiple batches within a day
- */
-export const dailyJobIngestion = webhook('ingest-daily', {
-  response: { mode: 'sync' }
-})
-  .then(fn('get-or-create-job', async (ctx) => {
-    // Destructure context inside function body
-    const { openKv, log, connections, activation } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv());
-    const stateService = new StateService(log);
-    const workflowId = 'daily-inventory-ingestion';
-
-    // Check for existing daily job
-    const existingJob = await stateService.getDailyJob(kvAdapter, workflowId);
-
-    let jobId: string;
-    let isNewJob = false;
-
-    if (existingJob && existingJob.jobId) {
-      // Reuse existing job
-      jobId = existingJob.jobId;
-      log.info(`♻️ [DailyJob] Reusing daily job: ${jobId}`, {
-        createdAt: existingJob.createdAt,
-        expiresAt: existingJob.expiresAt
-      });
-    } else {
-      // Create new job
-      const client = await createClient(ctx); // Auto-detects Versori context
-
-      const job = await client.createJob({
-        name: `daily-inventory-${new Date().toISOString().split('T')[0]}`,
-        retailerId: activation.getVariable('fluentRetailerId') as string
-      });
-
-      jobId = job.id;
-      isNewJob = true;
-
-      // Store job for 24 hours
-      await stateService.setDailyJob(kvAdapter, workflowId, jobId, 24);
-      log.info(`🆕 [DailyJob] Created new daily job: ${jobId}`);
-    }
-
-    return {
-      jobId,
-      isNewJob,
-      kvAdapter,
-      stateService,
-      workflowId,
-      client: await createClient(ctx) // Auto-detects Versori context
-    };
-  }))
-  .then(fn('send-batches-to-job', async ({ data, log }) => {
-    const { jobId, client, kvAdapter, stateService, workflowId } = data;
-
-    // Your batches to process
-    const batches = [
-      { entities: [{ skuRef: 'SKU001', qty: 100 }] },
-      { entities: [{ skuRef: 'SKU002', qty: 200 }] }
-    ];
-
-    const batchResults = [];
-
-    for (const batch of batches) {
-      try {
-        const result = await client.sendBatch(jobId, {
-          action: 'UPSERT',
-          entityType: 'INVENTORY_CATALOGUE',
-          entities: batch.entities
-        });
-
-        batchResults.push({ success: true, batchId: result.id });
-        log.info(`✅ [Batch] Batch sent to job ${jobId}: ${result.id}`);
-      } catch (error) {
-        // ? Enhanced: Error logging with recommendations
-        log.error('[KVStateManagement] Batch submission failed', {
-          batchId: result?.id,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('batch') || error.message?.includes('job')
-            ? 'Check batch API payload and job status'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details and check batch submission payload'
-        });
-        batchResults.push({ success: false, error: (error as Error).message });
-      }
-    }
-
-    // Update sync state with processed records
-    await stateService.updateSyncState(kvAdapter, [{
-      fileName: `daily-batch-${new Date().toISOString()}`,
-      lastModified: new Date().toISOString(),
-      recordCount: batches.reduce((sum, b) => sum + b.entities.length, 0)
-    }], workflowId);
-
-    return {
-      success: true,
-      jobId,
-      batchCount: batchResults.length,
-      successCount: batchResults.filter(r => r.success).length
-    };
-  }));
-```
-
-**Key Points**:
-
-- Single job per day reduces API overhead
-- Job expires automatically after 24 hours
-- Tracks batch count per job
-- Perfect for high-frequency ingestion workflows
-
----
-
-### Pattern 5: Error State Management
-
-**Use Case**: Track errors and implement retry logic with exponential backoff.
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-interface ErrorState {
-  fileName: string;
-  attemptCount: number;
-  lastError: string;
-  lastAttemptAt: string;
-  firstFailedAt: string;
-  nextRetryAt: string;
-}
-
-/**
- * Error state management pattern
- * Tracks failures and implements smart retry logic
- */
-export const retryableIngestion = webhook('ingest-with-retry', {
-  response: { mode: 'sync' }
-})
-  .then(fn('process-with-retry-tracking', async (ctx) => {
-    const { openKv, log, data } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const files = data.files || ['file1.csv', 'file2.csv', 'file3.csv'];
-
-    const results = {
-      succeeded: [] as string[],
-      failed: [] as string[],
-      skipped: [] as string[]
-    };
-
-    for (const fileName of files) {
-      const errorStateKey = ['error-state', fileName];
-
-      // Check if file has error state
-      const errorStateResult = await kvAdapter.get(errorStateKey);
-      const errorState = errorStateResult?.value as ErrorState | undefined;
-
-      // Check if we should retry
-      if (errorState) {
-        const nextRetry = new Date(errorState.nextRetryAt);
-        const now = new Date();
-
-        if (now < nextRetry) {
-          log.info(`⏭️ [Retry] Skipping ${fileName} until ${errorState.nextRetryAt}`, {
-            attemptCount: errorState.attemptCount,
-            lastError: errorState.lastError
-          });
-          results.skipped.push(fileName);
-          continue;
-        }
-
-        // Max retry attempts reached?
-        if (errorState.attemptCount >= 5) {
-          log.warn(`⚠️ [Retry] Max retries exceeded for ${fileName}, requires manual intervention`);
-          results.skipped.push(fileName);
-          continue;
-        }
-
-        log.info(`♻️ [Retry] Retrying ${fileName} (attempt ${errorState.attemptCount + 1})`, {
-          lastError: errorState.lastError,
-          firstFailedAt: errorState.firstFailedAt
-        });
-      }
-
-      try {
-        // Process the file
-        await processFileWithPossibleFailure(fileName);
-
-        // Success! Clear error state
-        if (errorState) {
-          await kvAdapter.delete(errorStateKey);
-          log.info(`✅ [Retry] File recovered after ${errorState.attemptCount} retries: ${fileName}`);
-        }
-
-        results.succeeded.push(fileName);
-      } catch (error) {
-        // ? Enhanced: Error logging with recommendations
-        const errorMessage = (error as Error).message;
-        const attemptCount = errorState ? errorState.attemptCount + 1 : 1;
-        const now = new Date();
-
-        // Calculate next retry with exponential backoff
-        const backoffMinutes = Math.pow(2, attemptCount) * 5; // 5, 10, 20, 40, 80 minutes
-        const nextRetryAt = new Date(now.getTime() + backoffMinutes * 60 * 1000);
-
-        // Save error state
-        const newErrorState: ErrorState = {
-          fileName,
-          attemptCount,
-          lastError: errorMessage,
-          lastAttemptAt: now.toISOString(),
-          firstFailedAt: errorState?.firstFailedAt || now.toISOString(),
-          nextRetryAt: nextRetryAt.toISOString()
-        };
-
-        await kvAdapter.set(errorStateKey, newErrorState);
-
-        log.error('[KVStateManagement] File processing failed', {
-          fileName,
-          attemptCount,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-          nextRetryAt: nextRetryAt.toISOString(),
-          backoffMinutes,
-          recommendation: error.message?.includes('parse') || error.message?.includes('format')
-            ? 'Check file format and structure - ensure file is valid'
-            : error.message?.includes('mapping') || error.message?.includes('field')
-            ? 'Check mapping configuration and verify file column structure'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and data source availability'
-            : `Will retry after ${backoffMinutes} minutes - review error details`
-        });
-
-        results.failed.push(fileName);
-      }
-    }
-
-    return {
-      success: true,
-      results,
-      summary: {
-        succeeded: results.succeeded.length,
-        failed: results.failed.length,
-        skipped: results.skipped.length
-      }
-    };
-  }))
-  .then(fn('cleanup-old-errors', async (ctx) => {
-    const { openKv, log, data } = ctx;
-
-    // Cleanup error states older than 7 days
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
-
-    // Note: This requires tracking error state keys separately
-    // In production, use VersoriIndexedFileTracker pattern
-
-    log.info('Error state cleanup completed');
-    return data;
-  }));
-
-async function processFileWithPossibleFailure(fileName: string): Promise<void> {
-  // Simulate random failures for demonstration
-  if (Math.random() < 0.3) {
-    throw new Error('Simulated processing failure');
-  }
-  await new Promise(resolve => setTimeout(resolve, 100));
-}
-```
-
-**Key Points**:
-
-- Exponential backoff prevents overwhelming failing systems
-- Track first failure time for monitoring
-- Max retry limit prevents infinite loops
-- Clear error state on success
-- Skip files until retry time
-
----
-
-### Pattern 6: Advanced File Tracking with Indexing
-
-**Use Case**: Track files with ability to list all processed files.
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { VersoriIndexedFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Advanced file tracking with indexing
- * Allows listing all processed files (overcomes Versori KV list limitation)
- */
-export const indexedFileTracking = webhook('manage-files', {
-  response: { mode: 'sync' }
-})
-  .then(fn('track-and-manage-files', async (ctx) => {
-    const { openKv, log, data } = ctx;
-
-    // Initialize indexed file tracker
-    const fileTracker = new VersoriIndexedFileTracker(openKv(':project:'), 'inventory-ingestion');
-    const operation = data.operation || 'process'; // process, list, stats, cleanup
-
-    switch (operation) {
-      case 'process': {
-        const files = data.files || ['file1.csv', 'file2.csv'];
-
-        for (const file of files) {
-          // Process file
-          log.info(`🚀 [Processing] Processing: ${file}`);
-          const recordCount = Math.floor(Math.random() * 1000) + 100;
-
-          // Mark as processed (automatically updates index)
-          await fileTracker.markFileProcessed(file, {
-            recordCount,
-            source: 's3://bucket/' + file,
-            processingDuration: 1234
-          });
-        }
-
-        return { success: true, processed: files.length };
-      }
-
-      case 'list': {
-        // List all processed files
-        const processedFiles = await fileTracker.listProcessedFiles();
-        log.info(`📋 [Index] Found ${processedFiles.length} processed files`);
-
-        return {
-          success: true,
-          files: processedFiles.map(f => ({
-            name: f.fileName,
-            processedAt: f.metadata?.processedAt,
-            recordCount: f.metadata?.recordCount
-          }))
-        };
-      }
-
-      case 'stats': {
-        // Get processing statistics
-        const stats = await fileTracker.getStats();
-        log.info('📊 [Index] File processing statistics', stats);
-
-        return {
-          success: true,
-          stats
-        };
-      }
-
-      case 'cleanup': {
-        // Clear all processed files
-        const result = await fileTracker.clearAllProcessedFiles();
-        log.info(`🧹 [Index] Cleanup complete: ${result.success} deleted, ${result.failed} failed`);
-
-        return {
-          success: true,
-          deleted: result.success,
-          failed: result.failed
-        };
-      }
-
-      case 'remove': {
-        // Remove specific file
-        const fileName = data.fileName;
-        if (!fileName) {
-          throw new Error('fileName required for remove operation');
-        }
-
-        await fileTracker.removeProcessedFile(fileName);
-        log.info(`🗑️ [Index] Removed file: ${fileName}`);
-
-        return { success: true, removed: fileName };
-      }
-
-      default:
-        throw new Error(`Unknown operation: ${operation}`);
-    }
-  }));
-```
-
-**Key Points**:
-
-- Maintains internal index to overcome Versori KV list limitation
-- List all processed files
-- Get aggregate statistics
-- Cleanup operations
-- Automatic index maintenance
-
----
-
-### Pattern 7: MemoryInterpreter for In-Memory State
-
-**Use Case**: Store interpreter state in memory for long-running connections (SFTP, database connections).
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-interface MemoryInterpreterState {
-  sftpConnections: Map<string, any>;
-  lastActivity: Map<string, number>;
-  connectionPool: any[];
-}
-
-/**
- * MemoryInterpreter pattern
- * Maintains in-memory state for connection pools and active sessions
- */
-export const connectionManager = webhook('manage-connections', {
-  response: { mode: 'sync' }
-})
-  .then(fn('initialize-memory-state', async (ctx) => {
-    const { openKv, log } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateKey = ['memory-interpreter', 'connections'];
-
-    // Load existing state or initialize new
-    const existingState = await kvAdapter.get(stateKey);
-
-    const memoryState: MemoryInterpreterState = existingState?.value || {
-      sftpConnections: new Map(),
-      lastActivity: new Map(),
-      connectionPool: []
-    };
-
-    log.info('🧠 [MemoryInterpreter] State initialized', {
-      activeConnections: memoryState.sftpConnections.size,
-      poolSize: memoryState.connectionPool.length
-    });
-
-    return {
-      kvAdapter,
-      stateKey,
-      memoryState
-    };
-  }))
-  .then(fn('process-with-memory-state', async ({ data, log }) => {
-    const { kvAdapter, stateKey, memoryState } = data;
-
-    // Use memory state for processing
-    const connectionId = 'sftp-main';
-    const now = Date.now();
-
-    // Check if connection is stale (> 5 minutes inactive)
-    const lastActivity = memoryState.lastActivity.get(connectionId);
-    const isStale = lastActivity && (now - lastActivity) > 5 * 60 * 1000;
-
-    if (isStale) {
-      log.info('♻️ [MemoryInterpreter] Refreshing stale connection', {
-        connectionId,
-        lastActivity: new Date(lastActivity).toISOString()
-      });
-
-      // Refresh connection
-      memoryState.sftpConnections.delete(connectionId);
-    }
-
-    // Update activity timestamp
-    memoryState.lastActivity.set(connectionId, now);
-
-    // Persist updated state
-    await kvAdapter.set(stateKey, {
-      sftpConnections: Array.from(memoryState.sftpConnections.entries()),
-      lastActivity: Array.from(memoryState.lastActivity.entries()),
-      connectionPool: memoryState.connectionPool
-    });
-
-    log.info('💾 [MemoryInterpreter] State persisted', {
-      connections: memoryState.sftpConnections.size,
-      lastUpdate: new Date(now).toISOString()
-    });
-
-    return {
-      success: true,
-      activeConnections: memoryState.sftpConnections.size,
-      lastActivity: now
-    };
-  }));
-```
-
-**Key Points**:
-
-- Use MemoryInterpreter for connection pools and active sessions
-- Persist state to KV to survive workflow restarts
-- Implement stale connection detection and refresh
-- Track activity timestamps for connection reuse
-- Serialize/deserialize Maps and complex objects properly
-
----
-
-### Pattern 8: Connection Validation
-
-**Use Case**: Validate data source connections before processing to catch configuration errors early.
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import {
-  SftpDataSource,
-  S3DataSource,
-  createClient
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Connection validation pattern
- * Validates all data sources before processing
- */
-export const validatedIngestion = webhook('ingest-with-validation', {
-  response: { mode: 'sync' }
-})
-  .then(fn('validate-connections', async (ctx) => {
-    const { log, activation } = ctx;
-
-    log.info('🔍 [Validation] Starting connection validation');
-
-    // Validate SFTP connection
-    const sftp = new SftpDataSource(
-      {
-        type: 'SFTP_XML',
-        connectionId: 'sftp-validation',
-        name: 'validated-sftp',
-        settings: {
-          host: activation.getVariable('sftpHost'),
-          port: parseInt(activation.getVariable('sftpPort') || '22', 10),
-          username: activation.getVariable('sftpUsername'),
-          password: activation.getVariable('sftpPassword'),
-          remotePath: '/incoming/',
-          encoding: 'utf8',
-          requireAbsolutePaths: true
-        }
-      },
-      log
-    );
-
-    try {
-      await sftp.validateConnection();
-      log.info('✅ [Validation] SFTP connection validated successfully');
-    } catch (error) {
-      log.error('❌ [Validation] SFTP connection failed', {
-        error: error instanceof Error ? error.message : String(error),
-        recommendation: error.message?.includes('authentication')
-          ? 'Check SFTP username and password in connection configuration'
-          : error.message?.includes('timeout')
-          ? 'Check SFTP host and port - ensure server is reachable'
-          : error.message?.includes('host')
-          ? 'Verify SFTP host address is correct'
-          : 'Review SFTP connection settings and server logs'
-      });
-      throw error;
-    }
-
-    // Validate S3 connection
-    const s3 = new S3DataSource(
-      {
-        type: 'S3_CSV',
-        connectionId: 's3-validation',
-        name: 'validated-s3',
-        settings: {
-          region: activation.getVariable('awsRegion') || 'us-east-1',
-          bucket: activation.getVariable('s3Bucket'),
-          prefix: 'incoming/',
-          accessKeyId: activation.getVariable('awsAccessKeyId'),
-          secretAccessKey: activation.getVariable('awsSecretAccessKey')
-        }
-      },
-      log
-    );
-
-    try {
-      await s3.validateConnection();
-      log.info('✅ [Validation] S3 connection validated successfully');
-    } catch (error) {
-      log.error('❌ [Validation] S3 connection failed', {
-        error: error instanceof Error ? error.message : String(error),
-        recommendation: error.message?.includes('credentials')
-          ? 'Check AWS access key and secret in connection configuration'
-          : error.message?.includes('bucket')
-          ? 'Verify S3 bucket exists and credentials have access'
-          : error.message?.includes('region')
-          ? 'Check AWS region is correct for the bucket'
-          : 'Review S3 connection settings and IAM permissions'
-      });
-      throw error;
-    }
-
-    // Validate Fluent Commerce API connection
-    const client = await createClient(ctx);
-    const retailerId = activation.getVariable('fluentRetailerId');
-
-    if (!retailerId) {
-      log.error('❌ [Validation] Missing retailerId activation variable');
-      throw new Error('fluentRetailerId is required for Fluent API operations');
-    }
-
-    client.setRetailerId(retailerId);
-
-    try {
-      // Test connection with a simple query
-      const testQuery = `query { retailers { edges { node { id } } } }`;
-      await client.graphql({ query: testQuery });
-      log.info('✅ [Validation] Fluent Commerce API connection validated');
-    } catch (error) {
-      log.error('❌ [Validation] Fluent Commerce API connection failed', {
-        error: error instanceof Error ? error.message : String(error),
-        recommendation: error.message?.includes('401') || error.message?.includes('authentication')
-          ? 'Verify fluent_commerce connection OAuth2 credentials'
-          : error.message?.includes('GraphQL')
-          ? 'Check GraphQL query syntax and permissions'
-          : 'Review Fluent Commerce API connection settings'
-      });
-      throw error;
-    }
-
-    log.info('✅ [Validation] All connections validated successfully');
-
-    return {
-      sftp,
-      s3,
-      client,
-      validated: true
-    };
-  }))
-  .then(fn('process-with-validated-connections', async ({ data, log }) => {
-    const { sftp, s3, client } = data;
-
-    log.info('🚀 [Processing] Starting ingestion with validated connections');
-
-    try {
-      // Your ingestion logic here with validated connections
-      const files = await sftp.listFiles({ remotePath: '/incoming/' });
-
-      log.info('📋 [Processing] Files discovered', { count: files.length });
-
-      // Process files...
-
-      return {
-        success: true,
-        filesProcessed: files.length
-      };
-    } finally {
-      // Always dispose connections
-      await sftp.dispose();
-      await s3.dispose();
-      log.info('🧹 [Cleanup] Connections disposed');
-    }
-  }));
-```
-
-**Key Points**:
-
-- Always validate connections before processing
-- Provide detailed error messages with recommendations
-- Use emoji logging for visual scanning
-- Fail fast on configuration errors
-- Dispose connections in finally blocks
-
----
-
-## Production Best Practices
-
-### 1. Emoji Logging for Operations Visibility
-
-Use emoji prefixes in logs for quick visual scanning:
-
-```typescript
-log.info('🔍 [Discovery] Scanning SFTP directory');
-log.info('✅ [Success] File processed successfully');
-log.error('❌ [Error] Connection failed', { error });
-log.warn('⚠️ [Warning] Partial batch failure');
-log.info('🧹 [Cleanup] Archiving processed files');
-log.info('🧠 [MemoryInterpreter] State synchronized');
-log.info('💾 [Persistence] State saved to KV');
-log.info('♻️ [Refresh] Stale connection renewed');
-log.info('🚀 [Start] Processing batch');
-log.info('📋 [Info] Configuration loaded');
-log.info('🔐 [Auth] Token refreshed');
-```
-
-**Benefits:**
-- Quick visual scanning in production logs
-- Easy pattern recognition for operations
-- Faster debugging and troubleshooting
-- Better collaboration across teams
-
-### 2. Connection Validation Pattern
-
-Always validate connections before processing:
-
-```typescript
-// ✅ CORRECT - Validate early
-const sftp = new SftpDataSource(config, log);
-await sftp.validateConnection();
-log.info('✅ Connection validated');
-
-// Process files...
-
-// ❌ WRONG - Discover errors during processing
-const sftp = new SftpDataSource(config, log);
-const files = await sftp.listFiles();  // Might fail here!
-```
-
-### 3. Error Handling with Recommendations
-
-Provide actionable recommendations in error logs:
-
-```typescript
-catch (error) {
-  log.error('❌ [Processing] File processing failed', {
-    fileName: file.name,
-    error: error instanceof Error ? error.message : String(error),
-    recommendation: error.message?.includes('authentication')
-      ? 'Check connection credentials in Connections section'
-      : error.message?.includes('timeout')
-      ? 'Check network connectivity and increase timeout settings'
-      : error.message?.includes('parse')
-      ? 'Verify file format matches expected structure'
-      : 'Review error details and check file processing logic'
-  });
-}
-```
-
-### 4. Resource Cleanup Pattern
-
-Always dispose data sources in finally blocks:
-
-```typescript
-const sftp = new SftpDataSource(config, log);
-try {
-  await sftp.validateConnection();
-  // Process files...
-} finally {
-  await sftp.dispose();
-  log.info('🧹 [Cleanup] SFTP connection disposed');
-}
-```
-
-### 5. MemoryInterpreter State Management
-
-Use MemoryInterpreter for connection pools and session state:
-
-```typescript
-// Persist complex objects to KV
-await kvAdapter.set(['memory-interpreter', 'state'], {
-  connections: Array.from(connectionMap.entries()),
-  lastActivity: Array.from(activityMap.entries()),
-  pool: connectionPool
-});
-
-// Restore from KV
-const state = await kvAdapter.get(['memory-interpreter', 'state']);
-const connectionMap = new Map(state.value.connections);
-```
-
-### 6. JobTracker Integration
-
-Use JobTracker for production monitoring:
-
-```typescript
-const tracker = new JobTracker(openKv(':project:'), log);
-const jobId = `job-${Date.now()}`;
-
-await tracker.createJob(jobId, {
-  triggeredBy: 'schedule',
-  stage: 'initialization',
-  startTime: Date.now()
-});
-
-try {
-  // Process...
-  await tracker.markCompleted(jobId, { filesProcessed: 10 });
-} catch (error) {
-  await tracker.markFailed(jobId, error.message);
-}
-```
-
----
-
-## Testing State Management
-
-### Local Testing Pattern
-
-```typescript
-/**
- * Test state management locally
- */
-export const testStateManagement = webhook('test-state', {
-  response: { mode: 'sync' }
-})
-  .then(fn('test-operations', async (ctx) => {
-    const { openKv, log } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-
-    // Test 1: Lock acquire and release
-    log.info('🧪 [Test] Test 1: Lock management');
-    const lockAcquired = await stateService.acquireLock('test-lock', kvAdapter, 5);
-    log.info(`🔐 [Test] Lock acquired: ${lockAcquired}`);
-
-    // Try to acquire again (should fail)
-    const lockAcquired2 = await stateService.acquireLock('test-lock', kvAdapter, 5);
-    log.info(`⚠️ [Test] Second lock acquired: ${lockAcquired2} (should be false)`);
-
-    // Release lock
-    await stateService.releaseLock('test-lock', kvAdapter);
-    log.info('🔓 [Test] Lock released');
-
-    // Test 2: File tracking
-    log.info('🧪 [Test] Test 2: File tracking');
-    const fileTracker = new VersoriFileTracker(openKv(':project:'), 'test');
-    await fileTracker.markFileProcessed('test-file.csv', { recordCount: 100 });
-    const wasProcessed = await fileTracker.wasFileProcessed('test-file.csv');
-    log.info(`✅ [Test] File processed: ${wasProcessed} (should be true)`);
-
-    const lastFile = await fileTracker.getLastProcessedFile();
-    await fileTracker.setLastProcessedFile('test-file.csv');
-    const newLastFile = await fileTracker.getLastProcessedFile();
-    log.info(`📋 [Test] Last file: ${newLastFile}`);
-
-    // Test 3: Sync state
-    log.info('🧪 [Test] Test 3: Sync state');
-    await stateService.updateSyncState(kvAdapter, [{
-      fileName: 'test.csv',
-      lastModified: new Date().toISOString(),
-      recordCount: 100
-    }], 'test-workflow');
-
-    const syncState = await stateService.getSyncState(kvAdapter, 'test-workflow');
-    log.info('💾 [Test] Sync state', syncState);
-
-    // Test 4: Daily job
-    log.info('🧪 [Test] Test 4: Daily job');
-    await stateService.setDailyJob(kvAdapter, 'test-workflow', 'job-123', 24);
-    const dailyJob = await stateService.getDailyJob(kvAdapter, 'test-workflow');
-    log.info('📋 [Test] Daily job', dailyJob);
-
-    return {
-      success: true,
-      message: '✅ All state management tests passed'
-    };
-  }));
-```
-
----
-
-## Common Issues & Solutions
-
-### Issue 1: Lock Not Released After Error
-
-**Problem**: Workflow crashes and lock is never released, blocking future runs.
-
-**Solution**: Always use try/finally or .catch() to ensure lock release:
-
-```typescript
-export const safeWorkflow = schedule('safe-job', '0 * * * *')
-  .then(fn('work', async (ctx) => {
-    const { openKv, log } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-    const lockName = 'safe-lock';
-
-    try {
-      await stateService.acquireLock(lockName, kvAdapter, 15);
-      // Your work here
-      await doWork();
-    } finally {
-      // Always release, even on error
-      await stateService.releaseLock(lockName, kvAdapter);
-    }
-  }));
-```
-
-Or use the catch pattern:
-
-```typescript
-export const workflowWithCatch = schedule('job', '0 * * * *')
-  .then(fn('acquire', async (ctx) => {
-    const { openKv, log } = ctx;
-
-    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-    const stateService = new StateService(log);
-    await stateService.acquireLock('my-lock', kvAdapter, 15);
-    return { kvAdapter, stateService };
-  }))
-  .then(fn('work', async ({ data }) => {
-    // Work here
-    return data;
-  }))
-  .catch(fn('cleanup', async ({ data }) => {
-    // Release lock on any error
-    if (data?.stateService) {
-      await data.stateService.releaseLock('my-lock', data.kvAdapter);
-    }
-    throw new Error('Workflow failed');
-  }));
-```
-
----
-
-### Issue 2: Stale Lock Detection
-
-**Problem**: Lock holder crashed and never released lock.
-
-**Solution**: Use lock timeout - StateService automatically overrides stale locks:
-
-```typescript
-// Lock with 15 minute timeout
-const acquired = await stateService.acquireLock('my-lock', kvAdapter, 15);
-
-// If lock is older than 15 minutes, it will be overridden automatically
-// This prevents permanent deadlocks from crashed processes
-```
-
-**How it works**:
-
-- Each lock stores `expiresAt` timestamp
-- `acquireLock()` checks if existing lock is expired
-- Expired locks are automatically overridden
-- Recent locks return false (lock not acquired)
-
----
-
-### Issue 3: Cannot List Processed Files
-
-**Problem**: Versori KV doesn't support list operations, can't enumerate processed files.
-
-**Solution**: Use `VersoriIndexedFileTracker` which maintains an index:
-
-```typescript
-// Instead of VersoriFileTracker
-const fileTracker = new VersoriFileTracker(openKv(':project:'));
-
-// Use VersoriIndexedFileTracker
-const indexedTracker = new VersoriIndexedFileTracker(openKv(':project:'));
-
-// Now you can list files
-const allFiles = await indexedTracker.listProcessedFiles();
-const stats = await indexedTracker.getStats();
-```
-
-**How it works**:
-
-- Maintains separate index key with list of all file names
-- Index updated atomically when files are marked/removed
-- Enables listing without KV list support
-
----
-
-### Issue 4: Checkpoint Corruption
-
-**Problem**: Checkpoint data gets corrupted or becomes invalid.
-
-**Solution**: Add validation and version to checkpoint data:
-
-```typescript
-interface VersionedCheckpoint {
-  version: number; // Schema version
-  data: CheckpointData;
-  checksum?: string; // Optional integrity check
-  savedAt: string;
-}
-
-async function saveCheckpoint(
-  kvAdapter: VersoriKVAdapter,
-  key: string[],
-  data: CheckpointData
-): Promise<void> {
-  const checkpoint: VersionedCheckpoint = {
-    version: 1,
-    data,
-    savedAt: new Date().toISOString()
-  };
-
-  await kvAdapter.set(key, checkpoint);
-}
-
-async function loadCheckpoint(
-  kvAdapter: VersoriKVAdapter,
-  key: string[]
-): Promise<CheckpointData | null> {
-  try {
-    const result = await kvAdapter.get(key);
-    if (!result?.value) return null;
-
-    const checkpoint = result.value as VersionedCheckpoint;
-
-    // Validate version
-    if (checkpoint.version !== 1) {
-      console.warn('Checkpoint version mismatch, ignoring');
-      return null;
-    }
-
-    // Check if checkpoint is too old (e.g., > 7 days)
-    const savedAt = new Date(checkpoint.savedAt);
-    const age = Date.now() - savedAt.getTime();
-    if (age > 7 * 24 * 60 * 60 * 1000) {
-      console.warn('Checkpoint too old, starting fresh');
-      return null;
-    }
-
-    return checkpoint.data;
-  } catch (error) {
-    console.error('Failed to load checkpoint', error);
-    return null; // Start fresh on corruption
-  }
-}
-```
-
----
-
-## Best Practices Summary
-
-### Core State Management Practices
-
-1. **Always Release Locks**: Use try/finally or .catch() to ensure locks are released
-2. **Use Lock Timeouts**: Set appropriate timeouts (15-30 minutes typical)
-3. **Checkpoint Periodically**: Not too often (overhead) or too rarely (lost progress)
-4. **Validate Restored State**: Check checkpoint age and integrity before using
-5. **Clear Completed Checkpoints**: Remove checkpoint data after successful completion
-6. **Use Indexed Tracker for Listing**: VersoriKV doesn't support list operations natively
-7. **Track Error State**: Implement exponential backoff for retries
-8. **Monitor Lock Ages**: Alert on locks held longer than expected
-9. **Namespace Your Keys**: Use prefixes to organize KV data (`workflow:resource:identifier`)
-10. **Document Key Schemas**: Keep track of what data is stored under which keys
-
-### Production Patterns (NEW)
-
-11. **Use Emoji Logging**: Add emoji prefixes for quick visual scanning in logs (see Pattern 8)
-12. **Validate Connections Early**: Always call `validateConnection()` before processing (see Pattern 8)
-13. **Provide Error Recommendations**: Include actionable recommendations in error logs
-14. **Dispose Resources**: Always dispose data sources in finally blocks
-15. **Use MemoryInterpreter**: For connection pools and session state (see Pattern 7)
-16. **Integrate JobTracker**: Track job lifecycle for production monitoring
-
----
-
-## Related Guides
-
-- **01-inventory-ingestion.md** - Complete ingestion workflow using state management
-- **02-inventory-extraction.md** - Extraction workflow with checkpoints
-- **04-batch-archival.md** - Archiving batch data to S3 (uses daily jobs)
-- **05-error-handling.md** - Advanced error handling patterns
-- **StateService full reference**: `../../02-CORE-GUIDES/ingestion/modules/07-state-management.md`
-
----
-
-## Summary
-
-This guide covered comprehensive state management patterns for Versori connectors:
-
-1. **Simple File Tracking** - Prevent duplicate processing with VersoriFileTracker
-2. **Distributed Locking** - Prevent concurrent executions with StateService
-3. **Checkpoints** - Save progress and resume long-running workflows
-4. **Daily Jobs** - Reuse jobs across batches throughout the day
-5. **Error States** - Track failures and implement smart retry logic
-6. **Indexed Tracking** - List and manage processed files
-7. **MemoryInterpreter** (NEW) - In-memory state for connection pools
-8. **Connection Validation** (NEW) - Validate connections before processing
-
-**Key Takeaways**:
-
-- VersoriFileTracker for simple duplicate prevention
-- StateService for distributed locking and sync state
-- VersoriIndexedFileTracker when you need to list files
-- Always release locks in finally blocks
-- Checkpoint periodically to enable resume
-- Validate restored state before using
-- Use exponential backoff for retries
-- **Use emoji logging for production visibility** (NEW)
-- **Validate connections early with `validateConnection()`** (NEW)
-- **Use MemoryInterpreter for connection pool state** (NEW)
-- **Provide actionable error recommendations** (NEW)
-
-State management is critical for robust production workflows. These patterns ensure your connectors are reliable, resumable, and prevent duplicate processing.
+# Versori KV State Management
+
+**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**: Use Versori KV storage for duplicate prevention, checkpoints, and file tracking
+
+**Complexity**: Low-Medium
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~400 lines
+
+## What You'll Build
+
+- VersoriKV adapter setup
+- File tracking (prevent duplicates)
+- Checkpoint/resume capabilities
+- Batch processing state
+- Error tracking and retry logic
+
+## SDK Methods Used
+
+- `VersoriKVAdapter(openKv())` - Wrap Versori KV for StateService
+- `VersoriFileTracker(openKv())` - Simple file tracking
+- `VersoriIndexedFileTracker(openKv())` - File tracking with listing support
+- `StateService(logger)` - High-level state operations
+- `stateService.isFileProcessed(kv, key)` - Check if processed
+- `stateService.acquireLock(lockName, kv, timeoutMinutes)` - Distributed locking
+- `stateService.getSyncState(kv, workflowId)` - Get sync state
+- `stateService.updateSyncState(kv, files, workflowId)` - Update sync state
+- `stateService.getDailyJob(kv, workflowId)` - Get daily job
+- `stateService.setDailyJob(kv, workflowId, jobId, hours)` - Store daily job
+
+---
+
+## 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
+
+```
+kv-state-management/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── webhook/
+    │   │   └── file-ingestion.ts         # Webhook: File processing
+    │   │
+    │   └── scheduled/
+    │       └── daily-sync.ts             # Scheduled: Daily sync
+    │
+    ├── services/
+    │   └── state-management.service.ts    # Shared state logic (reusable)
+    │
+    └── config/
+        └── state-config.json             # 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
+
+---
+
+## Complete Working Code
+
+### Pattern 1: Simple File Duplicate Prevention
+
+**Use Case**: Prevent reprocessing the same files in ingestion workflows.
+
+```typescript
+import { webhook, fn } from '@versori/run';
+// FC Connect SDK+
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Simple file tracking pattern
+ * Perfect for basic duplicate prevention without complex state management
+ */
+export const simpleFileIngestion = webhook('ingest-files', {
+  response: { mode: 'sync' }
+})
+  .then(fn('check-and-process-files', async (ctx) => {
+    const { openKv, log, data } = ctx;
+
+    // Initialize simple file tracker
+    const fileTracker = new VersoriFileTracker(openKv(':project:'), 'inventory-ingestion');
+
+    // Sample files to process
+    const files = data.files || [
+      { name: 'inventory-2025-01-15.csv', url: 's3://bucket/file1.csv' },
+      { name: 'inventory-2025-01-16.csv', url: 's3://bucket/file2.csv' }
+    ];
+
+    const processedFiles = [];
+    const skippedFiles = [];
+
+    for (const file of files) {
+      // Check if file was already processed
+      const wasProcessed = await fileTracker.wasFileProcessed(file.name);
+
+      if (wasProcessed) {
+        log.info(`⏭️ [FileTracking] Skipping already processed file: ${file.name}`);
+        skippedFiles.push(file.name);
+        continue;
+      }
+
+      try {
+        // Process the file (your ingestion logic here)
+        log.info(`🚀 [Processing] Processing file: ${file.name}`);
+        const recordCount = await processFile(file);
+
+        // Mark as processed with metadata
+        await fileTracker.markFileProcessed(file.name, {
+          recordCount,
+          processedBy: 'webhook-ingestion',
+          source: file.url
+        });
+
+        processedFiles.push({ name: file.name, recordCount });
+        log.info(`✅ [Success] Successfully processed: ${file.name} (${recordCount} records)`);
+      } catch (error) {
+        // ? Enhanced: Error logging with recommendations
+        log.error('[KVStateManagement] Failed to process file', {
+          fileName: file.name,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+          recommendation: error.message?.includes('parse') || error.message?.includes('format')
+            ? 'Check file format and structure - ensure file is valid'
+            : error.message?.includes('mapping') || error.message?.includes('field')
+            ? 'Check mapping configuration and verify file column structure'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and data source availability'
+            : 'Review error details and check file processing logic'
+        });
+        throw error; // Fail workflow so we can retry later
+      }
+    }
+
+    // Track last processed file
+    if (processedFiles.length > 0) {
+      const lastFile = processedFiles[processedFiles.length - 1];
+      await fileTracker.setLastProcessedFile(lastFile.name);
+    }
+
+    return {
+      success: true,
+      processed: processedFiles,
+      skipped: skippedFiles,
+      lastProcessedFile: await fileTracker.getLastProcessedFile()
+    };
+  }));
+
+// Helper function (implement based on your data source)
+async function processFile(file: { name: string; url: string }): Promise<number> {
+  // Your file processing logic
+  return 1000; // Return record count
+}
+```
+
+**Key Points**:
+
+- `VersoriFileTracker` is lightweight - perfect for simple use cases
+- Automatic duplicate prevention with `wasFileProcessed()`
+- Stores metadata like record count with each file
+- Tracks last processed file for incremental processing
+
+---
+
+### Pattern 2: Distributed Locking with StateService
+
+**Use Case**: Prevent concurrent workflow executions with distributed locks.
+
+```typescript
+import { schedule, fn } from '@versori/run';
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Distributed locking pattern
+ * Prevents multiple instances from running simultaneously
+ */
+export const scheduledIngestionWithLock = schedule('inventory-sync', '0 */6 * * *')
+  .then(fn('acquire-lock', async (ctx) => {
+    const { openKv, log } = ctx;
+
+    // Create StateService with KV adapter
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+
+    // Try to acquire lock (15 minute timeout)
+    const lockName = 'inventory-sync-lock';
+    const lockAcquired = await stateService.acquireLock(lockName, kvAdapter, 15);
+
+    if (!lockAcquired) {
+      log.warn('⚠️ [Lock] Lock already held, skipping this run');
+      return {
+        shouldSkip: true,
+        reason: 'Lock already held by another instance'
+      };
+    }
+
+    log.info('🔐 [Lock] Lock acquired successfully');
+    return {
+      shouldSkip: false,
+      lockName,
+      kvAdapter,
+      stateService
+    };
+  }))
+  .then(fn('process-with-lock', async ({ data, log }) => {
+    if (data.shouldSkip) {
+      return data;
+    }
+
+    const { kvAdapter, stateService, lockName } = data;
+
+    try {
+      // Your ingestion logic here
+      log.info('🚀 [Processing] Processing inventory sync...');
+      await performIngestion();
+      log.info('✅ [Success] Ingestion completed successfully');
+
+      return { success: true };
+    } finally {
+      // ALWAYS release lock in finally block
+      await stateService.releaseLock(lockName, kvAdapter);
+      log.info('🔓 [Lock] Lock released');
+    }
+  }))
+  .catch(fn('handle-error-and-release-lock', async ({ data, error, log }) => {
+    // Ensure lock is released even on error
+    if (data?.stateService && data?.lockName && data?.kvAdapter) {
+      await data.stateService.releaseLock(data.lockName, data.kvAdapter);
+      log.info('🔓 [Lock] Lock released after error');
+    }
+
+    log.error('❌ [Error] Ingestion failed', error as Error);
+    return { success: false, error: (error as Error).message };
+  }));
+
+async function performIngestion(): Promise<void> {
+  // Your ingestion logic
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+```
+
+**Key Points**:
+
+- Distributed locking prevents concurrent executions
+- Stale lock detection (automatically overrides expired locks)
+- Lock timeout ensures recovery from crashes
+- ALWAYS release locks in finally blocks
+- Proper error handling to prevent lock leaks
+
+---
+
+### Pattern 3: Checkpoint & Resume
+
+**Use Case**: Save progress during long-running workflows and resume from last checkpoint.
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+interface CheckpointData {
+  currentBatch: number;
+  totalBatches: number;
+  processedRecords: number;
+  lastProcessedId: string;
+  startTime: string;
+}
+
+/**
+ * Checkpoint & resume pattern
+ * Useful for long-running batch processing that might fail partway through
+ */
+export const batchProcessingWithCheckpoints = webhook('process-batches', {
+  response: { mode: 'sync' }
+})
+  .then(fn('check-checkpoint', async (ctx) => {
+    const { openKv, log, data } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+    const workflowId = 'batch-processing';
+    const checkpointKey = `checkpoint:${workflowId}`;
+
+    // Try to restore from checkpoint
+    const syncState = await stateService.getSyncState(kvAdapter, workflowId);
+    let checkpoint: CheckpointData | null = null;
+
+    if (syncState.isInitialized) {
+      // Check if there's a saved checkpoint (stored in custom state)
+      const stored = await kvAdapter.get([checkpointKey]);
+      if (stored?.value) {
+        checkpoint = stored.value as CheckpointData;
+        log.info('♻️ [Checkpoint] Resuming from checkpoint', checkpoint);
+      }
+    }
+
+    // Get batches to process
+    const allBatches = data.batches || generateBatches(100); // 100 batches total
+
+    // Determine starting point
+    const startBatch = checkpoint ? checkpoint.currentBatch : 0;
+    const processedSoFar = checkpoint ? checkpoint.processedRecords : 0;
+
+    return {
+      batches: allBatches,
+      startBatch,
+      processedSoFar,
+      kvAdapter,
+      stateService,
+      workflowId,
+      checkpointKey,
+      startTime: checkpoint?.startTime || new Date().toISOString()
+    };
+  }))
+  .then(fn('process-with-checkpoints', async ({ data, log }) => {
+    const {
+      batches,
+      startBatch,
+      processedSoFar,
+      kvAdapter,
+      stateService,
+      workflowId,
+      checkpointKey,
+      startTime
+    } = data;
+
+    let processedRecords = processedSoFar;
+
+    // Process batches starting from checkpoint
+    for (let i = startBatch; i < batches.length; i++) {
+      const batch = batches[i];
+
+      try {
+        log.info(`🚀 [Processing] Processing batch ${i + 1}/${batches.length}`);
+
+        // Process the batch
+        const result = await processBatch(batch);
+        processedRecords += result.recordCount;
+
+        // Save checkpoint after each batch (or every N batches)
+        if ((i + 1) % 10 === 0 || i === batches.length - 1) {
+          const checkpoint: CheckpointData = {
+            currentBatch: i + 1,
+            totalBatches: batches.length,
+            processedRecords,
+            lastProcessedId: result.lastId,
+            startTime
+          };
+
+          await kvAdapter.set([checkpointKey], checkpoint);
+          log.info(`💾 [Checkpoint] Checkpoint saved at batch ${i + 1}`);
+        }
+      } catch (error) {
+        // ? Enhanced: Error logging with recommendations
+        log.error('[KVStateManagement] Batch processing failed', {
+          batchNumber: i + 1,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('mutation') || error.message?.includes('GraphQL')
+            ? 'Check GraphQL mutation syntax and batch payload structure'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details - checkpoint saved for retry'
+        });
+
+        // Save checkpoint at failure point
+        const checkpoint: CheckpointData = {
+          currentBatch: i, // Retry this batch
+          totalBatches: batches.length,
+          processedRecords,
+          lastProcessedId: batch[0]?.id || '',
+          startTime
+        };
+
+        await kvAdapter.set([checkpointKey], checkpoint);
+        throw error; // Fail workflow so it can be retried
+      }
+    }
+
+    // All batches processed - clear checkpoint
+    await kvAdapter.delete([checkpointKey]);
+    log.info('✅ [Checkpoint] All batches processed, checkpoint cleared');
+
+    // Update final sync state
+    await stateService.updateSyncState(kvAdapter, [{
+      fileName: 'batch-processing-complete',
+      lastModified: new Date().toISOString(),
+      recordCount: processedRecords
+    }], workflowId);
+
+    return {
+      success: true,
+      totalBatches: batches.length,
+      processedRecords,
+      duration: Date.now() - new Date(startTime).getTime()
+    };
+  }));
+
+function generateBatches(count: number): any[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `batch-${i + 1}`,
+    data: []
+  }));
+}
+
+async function processBatch(batch: any): Promise<{ recordCount: number; lastId: string }> {
+  // Your batch processing logic
+  await new Promise(resolve => setTimeout(resolve, 100));
+  return { recordCount: 50, lastId: batch.id };
+}
+```
+
+**Key Points**:
+
+- Save checkpoints periodically (not after every operation)
+- Store enough context to resume exactly where you left off
+- Clear checkpoint after successful completion
+- On failure, checkpoint allows resuming without reprocessing
+
+---
+
+### Pattern 4: Daily Job Management
+
+**Use Case**: Reuse jobs across multiple batches throughout the day (DAILY strategy).
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import {
+  StateService,
+  VersoriKVAdapter,
+  createClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Daily job management pattern
+ * Reuses a single job for multiple batches within a day
+ */
+export const dailyJobIngestion = webhook('ingest-daily', {
+  response: { mode: 'sync' }
+})
+  .then(fn('get-or-create-job', async (ctx) => {
+    // Destructure context inside function body
+    const { openKv, log, connections, activation } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv());
+    const stateService = new StateService(log);
+    const workflowId = 'daily-inventory-ingestion';
+
+    // Check for existing daily job
+    const existingJob = await stateService.getDailyJob(kvAdapter, workflowId);
+
+    let jobId: string;
+    let isNewJob = false;
+
+    if (existingJob && existingJob.jobId) {
+      // Reuse existing job
+      jobId = existingJob.jobId;
+      log.info(`♻️ [DailyJob] Reusing daily job: ${jobId}`, {
+        createdAt: existingJob.createdAt,
+        expiresAt: existingJob.expiresAt
+      });
+    } else {
+      // Create new job
+      const client = await createClient(ctx); // Auto-detects Versori context
+
+      const job = await client.createJob({
+        name: `daily-inventory-${new Date().toISOString().split('T')[0]}`,
+        retailerId: activation.getVariable('fluentRetailerId') as string
+      });
+
+      jobId = job.id;
+      isNewJob = true;
+
+      // Store job for 24 hours
+      await stateService.setDailyJob(kvAdapter, workflowId, jobId, 24);
+      log.info(`🆕 [DailyJob] Created new daily job: ${jobId}`);
+    }
+
+    return {
+      jobId,
+      isNewJob,
+      kvAdapter,
+      stateService,
+      workflowId,
+      client: await createClient(ctx) // Auto-detects Versori context
+    };
+  }))
+  .then(fn('send-batches-to-job', async ({ data, log }) => {
+    const { jobId, client, kvAdapter, stateService, workflowId } = data;
+
+    // Your batches to process
+    const batches = [
+      { entities: [{ skuRef: 'SKU001', qty: 100 }] },
+      { entities: [{ skuRef: 'SKU002', qty: 200 }] }
+    ];
+
+    const batchResults = [];
+
+    for (const batch of batches) {
+      try {
+        const result = await client.sendBatch(jobId, {
+          action: 'UPSERT',
+          entityType: 'INVENTORY_CATALOGUE',
+          entities: batch.entities
+        });
+
+        batchResults.push({ success: true, batchId: result.id });
+        log.info(`✅ [Batch] Batch sent to job ${jobId}: ${result.id}`);
+      } catch (error) {
+        // ? Enhanced: Error logging with recommendations
+        log.error('[KVStateManagement] Batch submission failed', {
+          batchId: result?.id,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('batch') || error.message?.includes('job')
+            ? 'Check batch API payload and job status'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details and check batch submission payload'
+        });
+        batchResults.push({ success: false, error: (error as Error).message });
+      }
+    }
+
+    // Update sync state with processed records
+    await stateService.updateSyncState(kvAdapter, [{
+      fileName: `daily-batch-${new Date().toISOString()}`,
+      lastModified: new Date().toISOString(),
+      recordCount: batches.reduce((sum, b) => sum + b.entities.length, 0)
+    }], workflowId);
+
+    return {
+      success: true,
+      jobId,
+      batchCount: batchResults.length,
+      successCount: batchResults.filter(r => r.success).length
+    };
+  }));
+```
+
+**Key Points**:
+
+- Single job per day reduces API overhead
+- Job expires automatically after 24 hours
+- Tracks batch count per job
+- Perfect for high-frequency ingestion workflows
+
+---
+
+### Pattern 5: Error State Management
+
+**Use Case**: Track errors and implement retry logic with exponential backoff.
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+interface ErrorState {
+  fileName: string;
+  attemptCount: number;
+  lastError: string;
+  lastAttemptAt: string;
+  firstFailedAt: string;
+  nextRetryAt: string;
+}
+
+/**
+ * Error state management pattern
+ * Tracks failures and implements smart retry logic
+ */
+export const retryableIngestion = webhook('ingest-with-retry', {
+  response: { mode: 'sync' }
+})
+  .then(fn('process-with-retry-tracking', async (ctx) => {
+    const { openKv, log, data } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const files = data.files || ['file1.csv', 'file2.csv', 'file3.csv'];
+
+    const results = {
+      succeeded: [] as string[],
+      failed: [] as string[],
+      skipped: [] as string[]
+    };
+
+    for (const fileName of files) {
+      const errorStateKey = ['error-state', fileName];
+
+      // Check if file has error state
+      const errorStateResult = await kvAdapter.get(errorStateKey);
+      const errorState = errorStateResult?.value as ErrorState | undefined;
+
+      // Check if we should retry
+      if (errorState) {
+        const nextRetry = new Date(errorState.nextRetryAt);
+        const now = new Date();
+
+        if (now < nextRetry) {
+          log.info(`⏭️ [Retry] Skipping ${fileName} until ${errorState.nextRetryAt}`, {
+            attemptCount: errorState.attemptCount,
+            lastError: errorState.lastError
+          });
+          results.skipped.push(fileName);
+          continue;
+        }
+
+        // Max retry attempts reached?
+        if (errorState.attemptCount >= 5) {
+          log.warn(`⚠️ [Retry] Max retries exceeded for ${fileName}, requires manual intervention`);
+          results.skipped.push(fileName);
+          continue;
+        }
+
+        log.info(`♻️ [Retry] Retrying ${fileName} (attempt ${errorState.attemptCount + 1})`, {
+          lastError: errorState.lastError,
+          firstFailedAt: errorState.firstFailedAt
+        });
+      }
+
+      try {
+        // Process the file
+        await processFileWithPossibleFailure(fileName);
+
+        // Success! Clear error state
+        if (errorState) {
+          await kvAdapter.delete(errorStateKey);
+          log.info(`✅ [Retry] File recovered after ${errorState.attemptCount} retries: ${fileName}`);
+        }
+
+        results.succeeded.push(fileName);
+      } catch (error) {
+        // ? Enhanced: Error logging with recommendations
+        const errorMessage = (error as Error).message;
+        const attemptCount = errorState ? errorState.attemptCount + 1 : 1;
+        const now = new Date();
+
+        // Calculate next retry with exponential backoff
+        const backoffMinutes = Math.pow(2, attemptCount) * 5; // 5, 10, 20, 40, 80 minutes
+        const nextRetryAt = new Date(now.getTime() + backoffMinutes * 60 * 1000);
+
+        // Save error state
+        const newErrorState: ErrorState = {
+          fileName,
+          attemptCount,
+          lastError: errorMessage,
+          lastAttemptAt: now.toISOString(),
+          firstFailedAt: errorState?.firstFailedAt || now.toISOString(),
+          nextRetryAt: nextRetryAt.toISOString()
+        };
+
+        await kvAdapter.set(errorStateKey, newErrorState);
+
+        log.error('[KVStateManagement] File processing failed', {
+          fileName,
+          attemptCount,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+          nextRetryAt: nextRetryAt.toISOString(),
+          backoffMinutes,
+          recommendation: error.message?.includes('parse') || error.message?.includes('format')
+            ? 'Check file format and structure - ensure file is valid'
+            : error.message?.includes('mapping') || error.message?.includes('field')
+            ? 'Check mapping configuration and verify file column structure'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and data source availability'
+            : `Will retry after ${backoffMinutes} minutes - review error details`
+        });
+
+        results.failed.push(fileName);
+      }
+    }
+
+    return {
+      success: true,
+      results,
+      summary: {
+        succeeded: results.succeeded.length,
+        failed: results.failed.length,
+        skipped: results.skipped.length
+      }
+    };
+  }))
+  .then(fn('cleanup-old-errors', async (ctx) => {
+    const { openKv, log, data } = ctx;
+
+    // Cleanup error states older than 7 days
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+    // Note: This requires tracking error state keys separately
+    // In production, use VersoriIndexedFileTracker pattern
+
+    log.info('Error state cleanup completed');
+    return data;
+  }));
+
+async function processFileWithPossibleFailure(fileName: string): Promise<void> {
+  // Simulate random failures for demonstration
+  if (Math.random() < 0.3) {
+    throw new Error('Simulated processing failure');
+  }
+  await new Promise(resolve => setTimeout(resolve, 100));
+}
+```
+
+**Key Points**:
+
+- Exponential backoff prevents overwhelming failing systems
+- Track first failure time for monitoring
+- Max retry limit prevents infinite loops
+- Clear error state on success
+- Skip files until retry time
+
+---
+
+### Pattern 6: Advanced File Tracking with Indexing
+
+**Use Case**: Track files with ability to list all processed files.
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { VersoriIndexedFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Advanced file tracking with indexing
+ * Allows listing all processed files (overcomes Versori KV list limitation)
+ */
+export const indexedFileTracking = webhook('manage-files', {
+  response: { mode: 'sync' }
+})
+  .then(fn('track-and-manage-files', async (ctx) => {
+    const { openKv, log, data } = ctx;
+
+    // Initialize indexed file tracker
+    const fileTracker = new VersoriIndexedFileTracker(openKv(':project:'), 'inventory-ingestion');
+    const operation = data.operation || 'process'; // process, list, stats, cleanup
+
+    switch (operation) {
+      case 'process': {
+        const files = data.files || ['file1.csv', 'file2.csv'];
+
+        for (const file of files) {
+          // Process file
+          log.info(`🚀 [Processing] Processing: ${file}`);
+          const recordCount = Math.floor(Math.random() * 1000) + 100;
+
+          // Mark as processed (automatically updates index)
+          await fileTracker.markFileProcessed(file, {
+            recordCount,
+            source: 's3://bucket/' + file,
+            processingDuration: 1234
+          });
+        }
+
+        return { success: true, processed: files.length };
+      }
+
+      case 'list': {
+        // List all processed files
+        const processedFiles = await fileTracker.listProcessedFiles();
+        log.info(`📋 [Index] Found ${processedFiles.length} processed files`);
+
+        return {
+          success: true,
+          files: processedFiles.map(f => ({
+            name: f.fileName,
+            processedAt: f.metadata?.processedAt,
+            recordCount: f.metadata?.recordCount
+          }))
+        };
+      }
+
+      case 'stats': {
+        // Get processing statistics
+        const stats = await fileTracker.getStats();
+        log.info('📊 [Index] File processing statistics', stats);
+
+        return {
+          success: true,
+          stats
+        };
+      }
+
+      case 'cleanup': {
+        // Clear all processed files
+        const result = await fileTracker.clearAllProcessedFiles();
+        log.info(`🧹 [Index] Cleanup complete: ${result.success} deleted, ${result.failed} failed`);
+
+        return {
+          success: true,
+          deleted: result.success,
+          failed: result.failed
+        };
+      }
+
+      case 'remove': {
+        // Remove specific file
+        const fileName = data.fileName;
+        if (!fileName) {
+          throw new Error('fileName required for remove operation');
+        }
+
+        await fileTracker.removeProcessedFile(fileName);
+        log.info(`🗑️ [Index] Removed file: ${fileName}`);
+
+        return { success: true, removed: fileName };
+      }
+
+      default:
+        throw new Error(`Unknown operation: ${operation}`);
+    }
+  }));
+```
+
+**Key Points**:
+
+- Maintains internal index to overcome Versori KV list limitation
+- List all processed files
+- Get aggregate statistics
+- Cleanup operations
+- Automatic index maintenance
+
+---
+
+### Pattern 7: MemoryInterpreter for In-Memory State
+
+**Use Case**: Store interpreter state in memory for long-running connections (SFTP, database connections).
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+interface MemoryInterpreterState {
+  sftpConnections: Map<string, any>;
+  lastActivity: Map<string, number>;
+  connectionPool: any[];
+}
+
+/**
+ * MemoryInterpreter pattern
+ * Maintains in-memory state for connection pools and active sessions
+ */
+export const connectionManager = webhook('manage-connections', {
+  response: { mode: 'sync' }
+})
+  .then(fn('initialize-memory-state', async (ctx) => {
+    const { openKv, log } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateKey = ['memory-interpreter', 'connections'];
+
+    // Load existing state or initialize new
+    const existingState = await kvAdapter.get(stateKey);
+
+    const memoryState: MemoryInterpreterState = existingState?.value || {
+      sftpConnections: new Map(),
+      lastActivity: new Map(),
+      connectionPool: []
+    };
+
+    log.info('🧠 [MemoryInterpreter] State initialized', {
+      activeConnections: memoryState.sftpConnections.size,
+      poolSize: memoryState.connectionPool.length
+    });
+
+    return {
+      kvAdapter,
+      stateKey,
+      memoryState
+    };
+  }))
+  .then(fn('process-with-memory-state', async ({ data, log }) => {
+    const { kvAdapter, stateKey, memoryState } = data;
+
+    // Use memory state for processing
+    const connectionId = 'sftp-main';
+    const now = Date.now();
+
+    // Check if connection is stale (> 5 minutes inactive)
+    const lastActivity = memoryState.lastActivity.get(connectionId);
+    const isStale = lastActivity && (now - lastActivity) > 5 * 60 * 1000;
+
+    if (isStale) {
+      log.info('♻️ [MemoryInterpreter] Refreshing stale connection', {
+        connectionId,
+        lastActivity: new Date(lastActivity).toISOString()
+      });
+
+      // Refresh connection
+      memoryState.sftpConnections.delete(connectionId);
+    }
+
+    // Update activity timestamp
+    memoryState.lastActivity.set(connectionId, now);
+
+    // Persist updated state
+    await kvAdapter.set(stateKey, {
+      sftpConnections: Array.from(memoryState.sftpConnections.entries()),
+      lastActivity: Array.from(memoryState.lastActivity.entries()),
+      connectionPool: memoryState.connectionPool
+    });
+
+    log.info('💾 [MemoryInterpreter] State persisted', {
+      connections: memoryState.sftpConnections.size,
+      lastUpdate: new Date(now).toISOString()
+    });
+
+    return {
+      success: true,
+      activeConnections: memoryState.sftpConnections.size,
+      lastActivity: now
+    };
+  }));
+```
+
+**Key Points**:
+
+- Use MemoryInterpreter for connection pools and active sessions
+- Persist state to KV to survive workflow restarts
+- Implement stale connection detection and refresh
+- Track activity timestamps for connection reuse
+- Serialize/deserialize Maps and complex objects properly
+
+---
+
+### Pattern 8: Connection Validation
+
+**Use Case**: Validate data source connections before processing to catch configuration errors early.
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import {
+  SftpDataSource,
+  S3DataSource,
+  createClient
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Connection validation pattern
+ * Validates all data sources before processing
+ */
+export const validatedIngestion = webhook('ingest-with-validation', {
+  response: { mode: 'sync' }
+})
+  .then(fn('validate-connections', async (ctx) => {
+    const { log, activation } = ctx;
+
+    log.info('🔍 [Validation] Starting connection validation');
+
+    // Validate SFTP connection
+    const sftp = new SftpDataSource(
+      {
+        type: 'SFTP_XML',
+        connectionId: 'sftp-validation',
+        name: 'validated-sftp',
+        settings: {
+          host: activation.getVariable('sftpHost'),
+          port: parseInt(activation.getVariable('sftpPort') || '22', 10),
+          username: activation.getVariable('sftpUsername'),
+          password: activation.getVariable('sftpPassword'),
+          remotePath: '/incoming/',
+          encoding: 'utf8',
+          requireAbsolutePaths: true
+        }
+      },
+      log
+    );
+
+    try {
+      await sftp.validateConnection();
+      log.info('✅ [Validation] SFTP connection validated successfully');
+    } catch (error) {
+      log.error('❌ [Validation] SFTP connection failed', {
+        error: error instanceof Error ? error.message : String(error),
+        recommendation: error.message?.includes('authentication')
+          ? 'Check SFTP username and password in connection configuration'
+          : error.message?.includes('timeout')
+          ? 'Check SFTP host and port - ensure server is reachable'
+          : error.message?.includes('host')
+          ? 'Verify SFTP host address is correct'
+          : 'Review SFTP connection settings and server logs'
+      });
+      throw error;
+    }
+
+    // Validate S3 connection
+    const s3 = new S3DataSource(
+      {
+        type: 'S3_CSV',
+        connectionId: 's3-validation',
+        name: 'validated-s3',
+        settings: {
+          region: activation.getVariable('awsRegion') || 'us-east-1',
+          bucket: activation.getVariable('s3Bucket'),
+          prefix: 'incoming/',
+          accessKeyId: activation.getVariable('awsAccessKeyId'),
+          secretAccessKey: activation.getVariable('awsSecretAccessKey')
+        }
+      },
+      log
+    );
+
+    try {
+      await s3.validateConnection();
+      log.info('✅ [Validation] S3 connection validated successfully');
+    } catch (error) {
+      log.error('❌ [Validation] S3 connection failed', {
+        error: error instanceof Error ? error.message : String(error),
+        recommendation: error.message?.includes('credentials')
+          ? 'Check AWS access key and secret in connection configuration'
+          : error.message?.includes('bucket')
+          ? 'Verify S3 bucket exists and credentials have access'
+          : error.message?.includes('region')
+          ? 'Check AWS region is correct for the bucket'
+          : 'Review S3 connection settings and IAM permissions'
+      });
+      throw error;
+    }
+
+    // Validate Fluent Commerce API connection
+    const client = await createClient(ctx);
+    const retailerId = activation.getVariable('fluentRetailerId');
+
+    if (!retailerId) {
+      log.error('❌ [Validation] Missing retailerId activation variable');
+      throw new Error('fluentRetailerId is required for Fluent API operations');
+    }
+
+    client.setRetailerId(retailerId);
+
+    try {
+      // Test connection with a simple query
+      const testQuery = `query { retailers { edges { node { id } } } }`;
+      await client.graphql({ query: testQuery });
+      log.info('✅ [Validation] Fluent Commerce API connection validated');
+    } catch (error) {
+      log.error('❌ [Validation] Fluent Commerce API connection failed', {
+        error: error instanceof Error ? error.message : String(error),
+        recommendation: error.message?.includes('401') || error.message?.includes('authentication')
+          ? 'Verify fluent_commerce connection OAuth2 credentials'
+          : error.message?.includes('GraphQL')
+          ? 'Check GraphQL query syntax and permissions'
+          : 'Review Fluent Commerce API connection settings'
+      });
+      throw error;
+    }
+
+    log.info('✅ [Validation] All connections validated successfully');
+
+    return {
+      sftp,
+      s3,
+      client,
+      validated: true
+    };
+  }))
+  .then(fn('process-with-validated-connections', async ({ data, log }) => {
+    const { sftp, s3, client } = data;
+
+    log.info('🚀 [Processing] Starting ingestion with validated connections');
+
+    try {
+      // Your ingestion logic here with validated connections
+      const files = await sftp.listFiles({ remotePath: '/incoming/' });
+
+      log.info('📋 [Processing] Files discovered', { count: files.length });
+
+      // Process files...
+
+      return {
+        success: true,
+        filesProcessed: files.length
+      };
+    } finally {
+      // Always dispose connections
+      await sftp.dispose();
+      await s3.dispose();
+      log.info('🧹 [Cleanup] Connections disposed');
+    }
+  }));
+```
+
+**Key Points**:
+
+- Always validate connections before processing
+- Provide detailed error messages with recommendations
+- Use emoji logging for visual scanning
+- Fail fast on configuration errors
+- Dispose connections in finally blocks
+
+---
+
+## Production Best Practices
+
+### 1. Emoji Logging for Operations Visibility
+
+Use emoji prefixes in logs for quick visual scanning:
+
+```typescript
+log.info('🔍 [Discovery] Scanning SFTP directory');
+log.info('✅ [Success] File processed successfully');
+log.error('❌ [Error] Connection failed', { error });
+log.warn('⚠️ [Warning] Partial batch failure');
+log.info('🧹 [Cleanup] Archiving processed files');
+log.info('🧠 [MemoryInterpreter] State synchronized');
+log.info('💾 [Persistence] State saved to KV');
+log.info('♻️ [Refresh] Stale connection renewed');
+log.info('🚀 [Start] Processing batch');
+log.info('📋 [Info] Configuration loaded');
+log.info('🔐 [Auth] Token refreshed');
+```
+
+**Benefits:**
+- Quick visual scanning in production logs
+- Easy pattern recognition for operations
+- Faster debugging and troubleshooting
+- Better collaboration across teams
+
+### 2. Connection Validation Pattern
+
+Always validate connections before processing:
+
+```typescript
+// ✅ CORRECT - Validate early
+const sftp = new SftpDataSource(config, log);
+await sftp.validateConnection();
+log.info('✅ Connection validated');
+
+// Process files...
+
+// ❌ WRONG - Discover errors during processing
+const sftp = new SftpDataSource(config, log);
+const files = await sftp.listFiles();  // Might fail here!
+```
+
+### 3. Error Handling with Recommendations
+
+Provide actionable recommendations in error logs:
+
+```typescript
+catch (error) {
+  log.error('❌ [Processing] File processing failed', {
+    fileName: file.name,
+    error: error instanceof Error ? error.message : String(error),
+    recommendation: error.message?.includes('authentication')
+      ? 'Check connection credentials in Connections section'
+      : error.message?.includes('timeout')
+      ? 'Check network connectivity and increase timeout settings'
+      : error.message?.includes('parse')
+      ? 'Verify file format matches expected structure'
+      : 'Review error details and check file processing logic'
+  });
+}
+```
+
+### 4. Resource Cleanup Pattern
+
+Always dispose data sources in finally blocks:
+
+```typescript
+const sftp = new SftpDataSource(config, log);
+try {
+  await sftp.validateConnection();
+  // Process files...
+} finally {
+  await sftp.dispose();
+  log.info('🧹 [Cleanup] SFTP connection disposed');
+}
+```
+
+### 5. MemoryInterpreter State Management
+
+Use MemoryInterpreter for connection pools and session state:
+
+```typescript
+// Persist complex objects to KV
+await kvAdapter.set(['memory-interpreter', 'state'], {
+  connections: Array.from(connectionMap.entries()),
+  lastActivity: Array.from(activityMap.entries()),
+  pool: connectionPool
+});
+
+// Restore from KV
+const state = await kvAdapter.get(['memory-interpreter', 'state']);
+const connectionMap = new Map(state.value.connections);
+```
+
+### 6. JobTracker Integration
+
+Use JobTracker for production monitoring:
+
+```typescript
+const tracker = new JobTracker(openKv(':project:'), log);
+const jobId = `job-${Date.now()}`;
+
+await tracker.createJob(jobId, {
+  triggeredBy: 'schedule',
+  stage: 'initialization',
+  startTime: Date.now()
+});
+
+try {
+  // Process...
+  await tracker.markCompleted(jobId, { filesProcessed: 10 });
+} catch (error) {
+  await tracker.markFailed(jobId, error.message);
+}
+```
+
+---
+
+## Testing State Management
+
+### Local Testing Pattern
+
+```typescript
+/**
+ * Test state management locally
+ */
+export const testStateManagement = webhook('test-state', {
+  response: { mode: 'sync' }
+})
+  .then(fn('test-operations', async (ctx) => {
+    const { openKv, log } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+
+    // Test 1: Lock acquire and release
+    log.info('🧪 [Test] Test 1: Lock management');
+    const lockAcquired = await stateService.acquireLock('test-lock', kvAdapter, 5);
+    log.info(`🔐 [Test] Lock acquired: ${lockAcquired}`);
+
+    // Try to acquire again (should fail)
+    const lockAcquired2 = await stateService.acquireLock('test-lock', kvAdapter, 5);
+    log.info(`⚠️ [Test] Second lock acquired: ${lockAcquired2} (should be false)`);
+
+    // Release lock
+    await stateService.releaseLock('test-lock', kvAdapter);
+    log.info('🔓 [Test] Lock released');
+
+    // Test 2: File tracking
+    log.info('🧪 [Test] Test 2: File tracking');
+    const fileTracker = new VersoriFileTracker(openKv(':project:'), 'test');
+    await fileTracker.markFileProcessed('test-file.csv', { recordCount: 100 });
+    const wasProcessed = await fileTracker.wasFileProcessed('test-file.csv');
+    log.info(`✅ [Test] File processed: ${wasProcessed} (should be true)`);
+
+    const lastFile = await fileTracker.getLastProcessedFile();
+    await fileTracker.setLastProcessedFile('test-file.csv');
+    const newLastFile = await fileTracker.getLastProcessedFile();
+    log.info(`📋 [Test] Last file: ${newLastFile}`);
+
+    // Test 3: Sync state
+    log.info('🧪 [Test] Test 3: Sync state');
+    await stateService.updateSyncState(kvAdapter, [{
+      fileName: 'test.csv',
+      lastModified: new Date().toISOString(),
+      recordCount: 100
+    }], 'test-workflow');
+
+    const syncState = await stateService.getSyncState(kvAdapter, 'test-workflow');
+    log.info('💾 [Test] Sync state', syncState);
+
+    // Test 4: Daily job
+    log.info('🧪 [Test] Test 4: Daily job');
+    await stateService.setDailyJob(kvAdapter, 'test-workflow', 'job-123', 24);
+    const dailyJob = await stateService.getDailyJob(kvAdapter, 'test-workflow');
+    log.info('📋 [Test] Daily job', dailyJob);
+
+    return {
+      success: true,
+      message: '✅ All state management tests passed'
+    };
+  }));
+```
+
+---
+
+## Common Issues & Solutions
+
+### Issue 1: Lock Not Released After Error
+
+**Problem**: Workflow crashes and lock is never released, blocking future runs.
+
+**Solution**: Always use try/finally or .catch() to ensure lock release:
+
+```typescript
+export const safeWorkflow = schedule('safe-job', '0 * * * *')
+  .then(fn('work', async (ctx) => {
+    const { openKv, log } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+    const lockName = 'safe-lock';
+
+    try {
+      await stateService.acquireLock(lockName, kvAdapter, 15);
+      // Your work here
+      await doWork();
+    } finally {
+      // Always release, even on error
+      await stateService.releaseLock(lockName, kvAdapter);
+    }
+  }));
+```
+
+Or use the catch pattern:
+
+```typescript
+export const workflowWithCatch = schedule('job', '0 * * * *')
+  .then(fn('acquire', async (ctx) => {
+    const { openKv, log } = ctx;
+
+    const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+    const stateService = new StateService(log);
+    await stateService.acquireLock('my-lock', kvAdapter, 15);
+    return { kvAdapter, stateService };
+  }))
+  .then(fn('work', async ({ data }) => {
+    // Work here
+    return data;
+  }))
+  .catch(fn('cleanup', async ({ data }) => {
+    // Release lock on any error
+    if (data?.stateService) {
+      await data.stateService.releaseLock('my-lock', data.kvAdapter);
+    }
+    throw new Error('Workflow failed');
+  }));
+```
+
+---
+
+### Issue 2: Stale Lock Detection
+
+**Problem**: Lock holder crashed and never released lock.
+
+**Solution**: Use lock timeout - StateService automatically overrides stale locks:
+
+```typescript
+// Lock with 15 minute timeout
+const acquired = await stateService.acquireLock('my-lock', kvAdapter, 15);
+
+// If lock is older than 15 minutes, it will be overridden automatically
+// This prevents permanent deadlocks from crashed processes
+```
+
+**How it works**:
+
+- Each lock stores `expiresAt` timestamp
+- `acquireLock()` checks if existing lock is expired
+- Expired locks are automatically overridden
+- Recent locks return false (lock not acquired)
+
+---
+
+### Issue 3: Cannot List Processed Files
+
+**Problem**: Versori KV doesn't support list operations, can't enumerate processed files.
+
+**Solution**: Use `VersoriIndexedFileTracker` which maintains an index:
+
+```typescript
+// Instead of VersoriFileTracker
+const fileTracker = new VersoriFileTracker(openKv(':project:'));
+
+// Use VersoriIndexedFileTracker
+const indexedTracker = new VersoriIndexedFileTracker(openKv(':project:'));
+
+// Now you can list files
+const allFiles = await indexedTracker.listProcessedFiles();
+const stats = await indexedTracker.getStats();
+```
+
+**How it works**:
+
+- Maintains separate index key with list of all file names
+- Index updated atomically when files are marked/removed
+- Enables listing without KV list support
+
+---
+
+### Issue 4: Checkpoint Corruption
+
+**Problem**: Checkpoint data gets corrupted or becomes invalid.
+
+**Solution**: Add validation and version to checkpoint data:
+
+```typescript
+interface VersionedCheckpoint {
+  version: number; // Schema version
+  data: CheckpointData;
+  checksum?: string; // Optional integrity check
+  savedAt: string;
+}
+
+async function saveCheckpoint(
+  kvAdapter: VersoriKVAdapter,
+  key: string[],
+  data: CheckpointData
+): Promise<void> {
+  const checkpoint: VersionedCheckpoint = {
+    version: 1,
+    data,
+    savedAt: new Date().toISOString()
+  };
+
+  await kvAdapter.set(key, checkpoint);
+}
+
+async function loadCheckpoint(
+  kvAdapter: VersoriKVAdapter,
+  key: string[]
+): Promise<CheckpointData | null> {
+  try {
+    const result = await kvAdapter.get(key);
+    if (!result?.value) return null;
+
+    const checkpoint = result.value as VersionedCheckpoint;
+
+    // Validate version
+    if (checkpoint.version !== 1) {
+      console.warn('Checkpoint version mismatch, ignoring');
+      return null;
+    }
+
+    // Check if checkpoint is too old (e.g., > 7 days)
+    const savedAt = new Date(checkpoint.savedAt);
+    const age = Date.now() - savedAt.getTime();
+    if (age > 7 * 24 * 60 * 60 * 1000) {
+      console.warn('Checkpoint too old, starting fresh');
+      return null;
+    }
+
+    return checkpoint.data;
+  } catch (error) {
+    console.error('Failed to load checkpoint', error);
+    return null; // Start fresh on corruption
+  }
+}
+```
+
+---
+
+## Best Practices Summary
+
+### Core State Management Practices
+
+1. **Always Release Locks**: Use try/finally or .catch() to ensure locks are released
+2. **Use Lock Timeouts**: Set appropriate timeouts (15-30 minutes typical)
+3. **Checkpoint Periodically**: Not too often (overhead) or too rarely (lost progress)
+4. **Validate Restored State**: Check checkpoint age and integrity before using
+5. **Clear Completed Checkpoints**: Remove checkpoint data after successful completion
+6. **Use Indexed Tracker for Listing**: VersoriKV doesn't support list operations natively
+7. **Track Error State**: Implement exponential backoff for retries
+8. **Monitor Lock Ages**: Alert on locks held longer than expected
+9. **Namespace Your Keys**: Use prefixes to organize KV data (`workflow:resource:identifier`)
+10. **Document Key Schemas**: Keep track of what data is stored under which keys
+
+### Production Patterns (NEW)
+
+11. **Use Emoji Logging**: Add emoji prefixes for quick visual scanning in logs (see Pattern 8)
+12. **Validate Connections Early**: Always call `validateConnection()` before processing (see Pattern 8)
+13. **Provide Error Recommendations**: Include actionable recommendations in error logs
+14. **Dispose Resources**: Always dispose data sources in finally blocks
+15. **Use MemoryInterpreter**: For connection pools and session state (see Pattern 7)
+16. **Integrate JobTracker**: Track job lifecycle for production monitoring
+
+---
+
+## Related Guides
+
+- **01-inventory-ingestion.md** - Complete ingestion workflow using state management
+- **02-inventory-extraction.md** - Extraction workflow with checkpoints
+- **04-batch-archival.md** - Archiving batch data to S3 (uses daily jobs)
+- **05-error-handling.md** - Advanced error handling patterns
+- **StateService full reference**: `../../02-CORE-GUIDES/ingestion/modules/07-state-management.md`
+
+---
+
+## Summary
+
+This guide covered comprehensive state management patterns for Versori connectors:
+
+1. **Simple File Tracking** - Prevent duplicate processing with VersoriFileTracker
+2. **Distributed Locking** - Prevent concurrent executions with StateService
+3. **Checkpoints** - Save progress and resume long-running workflows
+4. **Daily Jobs** - Reuse jobs across batches throughout the day
+5. **Error States** - Track failures and implement smart retry logic
+6. **Indexed Tracking** - List and manage processed files
+7. **MemoryInterpreter** (NEW) - In-memory state for connection pools
+8. **Connection Validation** (NEW) - Validate connections before processing
+
+**Key Takeaways**:
+
+- VersoriFileTracker for simple duplicate prevention
+- StateService for distributed locking and sync state
+- VersoriIndexedFileTracker when you need to list files
+- Always release locks in finally blocks
+- Checkpoint periodically to enable resume
+- Validate restored state before using
+- Use exponential backoff for retries
+- **Use emoji logging for production visibility** (NEW)
+- **Validate connections early with `validateConnection()`** (NEW)
+- **Use MemoryInterpreter for connection pool state** (NEW)
+- **Provide actionable error recommendations** (NEW)
+
+State management is critical for robust production workflows. These patterns ensure your connectors are reliable, resumable, and prevent duplicate processing.