@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-06-kv-storage.md

@@ -1,990 +1,990 @@
-# Module 6: KV Storage - State Management & File Tracking
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 6 of 8** | **Level**: Intermediate | **Time**: 25 minutes
-
----
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- ✅ Understand Versori KV storage architecture and capabilities
-- ✅ Use VersoriKVAdapter for low-level KV operations
-- ✅ Implement VersoriFileTracker for duplicate prevention
-- ✅ Master KV scoping and namespace patterns
-- ✅ Implement distributed locking for concurrent workflows
-- ✅ Optimize KV storage for performance and cost
-- ✅ Debug and troubleshoot KV storage issues
-
----
-
-## KV Storage Overview
-
-Versori provides a distributed key-value store accessible from all workflow types. It's designed for:
-
-| Use Case                | Pattern                      | SDK Component                               |
-| ----------------------- | ---------------------------- | ------------------------------------------- |
-| **File tracking**       | Prevent duplicate processing | `VersoriFileTracker`                        |
-| **State management**    | Workflow state persistence   | `StateService` + `VersoriKVAdapter`         |
-| **Distributed locking** | Prevent concurrent execution | `StateService.acquireLock()`                |
-| **Caching**             | Cache expensive API calls    | Native Versori KV with TTL                  |
-| **Rate limiting**       | Track request counts         | Native Versori KV (custom implementation)   |
-| **Incremental sync**    | Track last processed cursor  | `VersoriFileTracker.setLastProcessedFile()` |
-
----
-
-## KV Storage Basics
-
-### Opening KV Store
-
-```typescript
-import { fn } from '@versori/run';
-
-export const kvBasics = fn('kv-basics', async ctx => {
-  // Three scoping options:
-
-  // 1. Project scope - shared across ALL workflows
-  const projectKV = ctx.openKv(':project:');
-
-  // 2. Workflow scope - isolated to THIS workflow
-  const workflowKV = ctx.openKv(':workflow:my-workflow');
-
-  // 3. Custom scope - custom namespace
-  const customKV = ctx.openKv('custom:namespace:name');
-
-  return { message: 'KV stores opened' };
-});
-```
-
-### Basic Operations
-
-```typescript
-export const kvOperations = fn('kv-operations', async ctx => {
-  const kv = ctx.openKv(':project:');
-
-  // Set value
-  await kv.set('key', { foo: 'bar' });
-
-  // Set with TTL (30 minutes = 1800000ms)
-  await kv.set('cache:key', { data: [] }, { ttl: 1800000 });
-
-  // Get value
-  const value = await kv.get('key');
-  console.log(value); // { foo: 'bar' }
-
-  // Delete value
-  await kv.delete('key');
-
-  // Check existence
-  const exists = await kv.has('key'); // false
-
-  // List keys with prefix
-  const keys = await kv.list({ prefix: 'cache:' });
-
-  return { operations: 'complete' };
-});
-```
-
----
-
-## VersoriKVAdapter - Low-Level KV Operations
-
-The SDK provides `VersoriKVAdapter` which wraps the native Versori KV with additional features.
-
-### Creating Adapter
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const useAdapter = fn('use-adapter', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  // Now use adapter methods...
-});
-```
-
-### VersoriKVAdapter API Reference
-
-**IMPORTANT**: VersoriKVAdapter uses **array-based keys** `['key']` to match the SDK's `KVStore` interface.
-
-```typescript
-interface VersoriKVAdapter implements KVStore {
-  // Basic operations (use array keys: ['key'])
-  get(keys: string[]): Promise<{ value: unknown } | null>;
-  set(keys: string[], value: unknown): Promise<void>;
-  delete(keys: string[]): Promise<void>;
-
-  // Atomic operations (simplified - Versori doesn't support true atomicity)
-  atomic(): {
-    check(entries: Array<{ key: string[]; versionstamp: string | null }>): void;
-    set(key: string[], value: unknown): void;
-    commit(): Promise<boolean>;  // Returns true if all operations succeed
-  };
-}
-```
-
-**Key Limitations:**
-- ❌ **No versionstamp support** - Versori KV doesn't expose version stamps
-- ❌ **No expireIn/TTL option** in VersoriKVAdapter - use native Versori KV for TTL
-- ❌ **No list() method** - use native Versori KV with prefix patterns
-- ❌ **No atomic guarantees** - `atomic()` executes operations sequentially, not atomically
-- ❌ **No increment()** - use read-modify-write pattern
-
-**When to Use VersoriKVAdapter:**
-- ✅ You need SDK `KVStore` interface compatibility (e.g., for `StateService`)
-- ✅ You're using array-based key patterns `['namespace', 'key']`
-- ✅ Simple get/set/delete operations are sufficient
-
-**When to Use Native Versori KV:**
-- ✅ You need TTL/expiration support
-- ✅ You need to list keys with prefixes
-- ✅ You want string-based keys `'simple:key:name'`
-- ✅ You need increment operations
-- ✅ Better performance (no adapter overhead)
-
-### Practical Examples
-
-#### Example 1: Caching Expensive API Calls
-
-**Note**: For caching with TTL, use **native Versori KV** directly. VersoriKVAdapter doesn't support TTL.
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const cachedQuery = http(
-  'cached-query',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-
-    const cacheKey = 'cache:products:list';
-    const cacheTTL = 3600000; // 1 hour
-
-    // Try cache first (using native Versori KV)
-    let products = await kv.get(cacheKey);
-
-    if (products) {
-      ctx.log('info', 'Cache hit', { key: cacheKey });
-      return { source: 'cache', data: products };
-    }
-
-    // Cache miss - fetch from API
-    ctx.log('info', 'Cache miss - fetching from API');
-    const client = await createClient(ctx);
-
-    const result = await client.graphql({
-      query: `
-      query GetProducts($first: Int!) {
-        products(first: $first) {
-          edges {
-            node {
-              id
-              ref
-              name
-              status
-            }
-          }
-        }
-      }
-    `,
-      variables: { first: 100 },
-    });
-
-    products = result.data.products.edges.map(e => e.node);
-
-    // Store in cache with TTL (using native Versori KV)
-    await kv.set(cacheKey, products, { ttl: cacheTTL });
-
-    return { source: 'api', data: products };
-  }
-);
-```
-
-#### Example 2: Rate Limiting with Native Versori KV
-
-**Note**: VersoriKVAdapter doesn't have `increment()`, `expire()`, or `ttl()` methods. Use **native Versori KV** for rate limiting. StateService is for distributed locking, not rate limiting.
-
-```typescript
-import { fn } from '@versori/run';
-
-export const rateLimited = fn('rate-limited', async ctx => {
-  const kv = ctx.openKv(':project:');
-  
-  const userId = ctx.data?.userId || 'anonymous';
-  const rateLimitKey = `ratelimit:${userId}`;
-  const maxRequests = 100;
-  const windowMs = 3600000; // 1 hour
-
-  // Get current count using native Versori KV
-  const stored = await kv.get(rateLimitKey);
-  const data = stored as { count: number; resetAt: number } | undefined;
-
-  const now = Date.now();
-  let count = 0;
-  let resetAt = now + windowMs;
-
-  if (data && data.resetAt > now) {
-    // Within rate limit window
-    count = data.count + 1;
-    resetAt = data.resetAt;
-  } else {
-    // New window
-    count = 1;
-    resetAt = now + windowMs;
-  }
-
-  // Update count using native Versori KV
-  await kv.set(rateLimitKey, { count, resetAt });
-
-  // Check if rate limited
-  if (count > maxRequests) {
-    const retryAfter = Math.ceil((resetAt - now) / 1000);
-    return {
-      rateLimited: true,
-      retryAfter,
-      message: `Rate limit exceeded. Try again in ${retryAfter}s`,
-    };
-  }
-
-  // Process request
-  return {
-    rateLimited: false,
-    requestsRemaining: maxRequests - count,
-  };
-});
-```
-
-#### Example 3: Using VersoriKVAdapter for Workflow State
-
-**Note**: VersoriKVAdapter doesn't have `mset()` or `mget()` methods. For batch operations, use native Versori KV or loop through individual operations.
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const workflowState = fn('workflow-state', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  // Set workflow states (individual operations with array-based keys)
-  await adapter.set(['state', 'workflow1'], { status: 'running', startedAt: Date.now() });
-  await adapter.set(['state', 'workflow2'], { status: 'pending', queuedAt: Date.now() });
-  await adapter.set(['state', 'workflow3'], { status: 'completed', finishedAt: Date.now() });
-
-  // Get workflow states (individual operations)
-  const workflow1 = await adapter.get(['state', 'workflow1']);
-  const workflow2 = await adapter.get(['state', 'workflow2']);
-  const workflow3 = await adapter.get(['state', 'workflow3']);
-
-  const states = [workflow1?.value, workflow2?.value, workflow3?.value];
-
-  ctx.log('info', 'Workflow states retrieved', {
-    retrieved: states.filter(v => v !== null && v !== undefined).length,
-  });
-
-  return { states };
-});
-```
-
----
-
-## VersoriFileTracker - Duplicate Prevention
-
-The most common KV use case: tracking processed files to prevent duplicates.
-
-### VersoriFileTracker API Reference
-
-```typescript
-interface VersoriFileTracker {
-  // Check if file was processed
-  wasFileProcessed(fileName: string): Promise<boolean>;
-
-  // Mark file as processed with metadata
-  markFileProcessed(fileName: string, metadata?: { recordCount?: number }): Promise<void>;
-
-  // Incremental sync helpers
-  setLastProcessedFile(fileName: string): Promise<void>;
-  getLastProcessedFile(): Promise<string | null>;
-}
-```
-
-**Key Points**:
-
-- **Array-based keys internally**: Uses `prefix:processed-files:${fileName}` pattern
-- **Simple metadata**: Only stores `processedAt` timestamp and optional `recordCount`
-- **No list/clear methods**: For advanced queries, use native Versori KV with prefix patterns
-
-### Example 1: Basic File Tracking
-
-```typescript
-import { schedule } from '@versori/run';
-import { createClient, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Daily inventory sync with duplicate prevention
- *
- * Cron: 0 2 * * * (daily at 2 AM)
- */
-export const dailySyncWithTracking = schedule(
-  'daily-sync',
-  '0 2 * * *',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const tracker = new VersoriFileTracker(kv, 'daily-inventory-sync');
-
-    // Generate file name based on date
-    const today = new Date().toISOString().split('T')[0];
-    const fileName = `inventory-${today}.csv`;
-
-    // Check if already processed
-    if (await tracker.wasFileProcessed(fileName)) {
-      ctx.log('info', 'File already processed today', { fileName });
-      return {
-        skipped: true,
-        reason: 'Already processed',
-        fileName,
-      };
-    }
-
-    // Process file
-    ctx.log('info', 'Processing new file', { fileName });
-    const records = await fetchAndParseInventoryFile(fileName);
-
-    // Send to Fluent
-    const client = await createClient(ctx);
-    const job = await client.createJob({ name: `Daily Sync ${fileName}` });
-    await client.sendBatch(job.id, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: records,
-    });
-
-    // Mark as processed with metadata
-    await tracker.markFileProcessed(fileName, {
-      recordCount: records.length,
-      jobId: job.id,
-      timestamp: Date.now(),
-    });
-
-    ctx.log('info', 'File processed successfully', {
-      fileName,
-      recordCount: records.length,
-      jobId: job.id,
-    });
-
-    return {
-      success: true,
-      fileName,
-      recordCount: records.length,
-      jobId: job.id,
-    };
-  }
-);
-```
-
-### Example 2: Incremental Processing
-
-```typescript
-export const incrementalSync = schedule(
-  'incremental-sync',
-  '0 * * * *',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const tracker = new VersoriFileTracker(kv, 'incremental-sync');
-
-    // Get last processed file
-    const lastFile = await tracker.getLastProcessedFile();
-    ctx.log('info', 'Last processed file', { lastFile });
-
-    // List new files since last run
-    const newFiles = await listFilesAfter(lastFile);
-
-    if (newFiles.length === 0) {
-      ctx.log('info', 'No new files to process');
-      return { skipped: true, reason: 'No new files' };
-    }
-
-    const client = await createClient(ctx);
-    let totalProcessed = 0;
-
-    for (const file of newFiles) {
-      // Skip if already processed (safety check)
-      if (await tracker.wasFileProcessed(file.name)) {
-        ctx.log('warn', 'File already processed (safety skip)', { file: file.name });
-        continue;
-      }
-
-      // Process file
-      const records = await processFile(file);
-
-      // Send to Fluent
-      const job = await client.createJob({ name: `Incremental ${file.name}` });
-      await client.sendBatch(job.id, {
-        action: 'UPSERT',
-        entityType: 'INVENTORY',
-        entities: records,
-      });
-
-      // Mark as processed
-      await tracker.markFileProcessed(file.name, {
-        recordCount: records.length,
-        jobId: job.id,
-      });
-
-      // Update last processed file
-      await tracker.setLastProcessedFile(file.name);
-
-      totalProcessed += records.length;
-
-      ctx.log('info', 'File processed', {
-        fileName: file.name,
-        recordCount: records.length,
-      });
-    }
-
-    return {
-      success: true,
-      filesProcessed: newFiles.length,
-      recordsProcessed: totalProcessed,
-    };
-  }
-);
-```
-
-### Example 3: Checking Last Processed File
-
-**Note**: VersoriFileTracker doesn't have `listProcessedFiles()` or `getFileProcessingInfo()` methods. Use `getLastProcessedFile()` to track incremental sync state.
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-export const checkProcessingState = fn('check-state', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const tracker = new VersoriFileTracker(kv, 'daily-inventory-sync');
-
-  // Get last processed file
-  const lastFile = await tracker.getLastProcessedFile();
-
-  // Check if specific files were processed
-  const today = new Date().toISOString().split('T')[0];
-  const todayFile = `inventory-${today}.csv`;
-  const yesterday = new Date(Date.now() - 86400000).toISOString().split('T')[0];
-  const yesterdayFile = `inventory-${yesterday}.csv`;
-
-  const todayProcessed = await tracker.wasFileProcessed(todayFile);
-  const yesterdayProcessed = await tracker.wasFileProcessed(yesterdayFile);
-
-  ctx.log('info', 'Processing state', {
-    lastFile,
-    todayProcessed,
-    yesterdayProcessed,
-  });
-
-  return {
-    lastFile,
-    todayFile: {
-      name: todayFile,
-      processed: todayProcessed,
-    },
-    yesterdayFile: {
-      name: yesterdayFile,
-      processed: yesterdayProcessed,
-    },
-  };
-});
-```
-
-**For viewing all processed files**, use native Versori KV with prefix listing:
-
-```typescript
-export const listAllProcessedFiles = fn('list-processed', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const prefix = 'fc-sdk:processed-files:';
-
-  // List all keys with prefix (native Versori KV)
-  const keys = await kv.list({ prefix });
-
-  const files = [];
-  for (const key of keys) {
-    const fileName = key.replace(prefix, '');
-    const metadata = await kv.get(key);
-    files.push({
-      fileName,
-      processedAt: metadata?.processedAt,
-      recordCount: metadata?.recordCount,
-    });
-  }
-
-  // Sort by date (newest first)
-  files.sort(
-    (a, b) => new Date(b.processedAt || 0).getTime() - new Date(a.processedAt || 0).getTime()
-  );
-
-  return { totalFiles: files.length, files };
-});
-```
-
----
-
-## Distributed Locking
-
-Prevent concurrent execution of critical sections using distributed locks.
-
-### StateService with Locking
-
-```typescript
-import { schedule } from '@versori/run';
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Scheduled workflow with distributed locking
- *
- * Ensures only ONE instance runs at a time
- */
-export const criticalSection = schedule(
-  'critical',
-  '*/5 * * * *',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const kvAdapter = new VersoriKVAdapter(kv);
-    const stateService = new StateService(logger);
-
-    const lockName = 'critical-section';
-    const timeoutMinutes = 1; // 1 minute timeout
-
-    // Try to acquire lock (returns boolean)
-    const acquired = await stateService.acquireLock(lockName, kvAdapter, timeoutMinutes);
-
-    if (!acquired) {
-      ctx.log('warn', 'Lock acquisition failed - another instance is running', {
-        lockName,
-      });
-      return {
-        skipped: true,
-        reason: 'Another instance is running',
-      };
-    }
-
-    ctx.log('info', 'Lock acquired, starting critical section', {
-      lockName,
-    });
-
-    try {
-      // Critical section - only ONE workflow instance executes this
-      await performCriticalOperation(ctx);
-
-      ctx.log('info', 'Critical section completed successfully');
-
-      return { success: true };
-    } finally {
-      // Always release lock
-      await stateService.releaseLock(lockName, kvAdapter);
-      ctx.log('info', 'Lock released', { lockName });
-    }
-  }
-);
-```
-
-### Advanced Locking Pattern
-
-```typescript
-export const advancedLocking = schedule(
-  'advanced-locking',
-  '*/10 * * * *',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const kv = ctx.openKv(':project:');
-    const kvAdapter = new VersoriKVAdapter(kv);
-    const stateService = new StateService(logger);
-
-    const lockName = 'inventory-sync';
-    const timeoutMinutes = 5; // 5 minutes timeout
-    const maxRetries = 3;
-    const retryDelay = 5000; // 5 seconds
-
-    let acquired = false;
-    let attempts = 0;
-
-    // Retry lock acquisition
-    while (attempts < maxRetries) {
-      acquired = await stateService.acquireLock(lockName, kvAdapter, timeoutMinutes);
-
-      if (acquired) {
-        break;
-      }
-
-      attempts++;
-      ctx.log('info', `Lock acquisition failed, retrying... (${attempts}/${maxRetries})`);
-      await new Promise(resolve => setTimeout(resolve, retryDelay));
-    }
-
-    if (!acquired) {
-      ctx.log('error', 'Failed to acquire lock after retries', {
-        attempts,
-      });
-      return {
-        success: false,
-        error: 'Failed to acquire lock',
-        attempts,
-      };
-    }
-
-    try {
-      // Long-running operation
-      const result = await performLongOperation(ctx);
-
-      // Note: StateService doesn't have extendLock() - acquire a new lock if needed
-      // If operation needs more time, acquire a new lock before releasing
-      if (result.needsMoreTime) {
-        // Release current lock and acquire new one
-        await stateService.releaseLock(lockName, kvAdapter);
-        const reacquired = await stateService.acquireLock(lockName, kvAdapter, timeoutMinutes);
-        if (reacquired) {
-          ctx.log('info', 'Lock reacquired for extended operation');
-        }
-      }
-
-      return { success: true, result };
-    } catch (error) {
-      ctx.log('error', 'Operation failed', {
-        error: error instanceof Error ? error.message : String(error),
-      });
-      throw error;
-    } finally {
-      await stateService.releaseLock(lockName, kvAdapter);
-      ctx.log('info', 'Lock released');
-    }
-  }
-);
-```
-
----
-
-## KV Namespace Patterns
-
-### Scoping Best Practices
-
-| Namespace        | Use Case                    | Scope               | Example Key                  |
-| ---------------- | --------------------------- | ------------------- | ---------------------------- |
-| `:project:`      | Global config, shared state | All workflows       | `config:retailerId`          |
-| `:workflow:name` | Workflow-specific state     | Single workflow     | `state:lastRun`              |
-| `cache:*`        | Cached data                 | Project-wide        | `cache:products:list`        |
-| `lock:*`         | Distributed locks           | Project-wide        | `lock:inventory-sync`        |
-| `files:*`        | File tracking               | Workflow or project | `files:processed:2025-01-15` |
-| `ratelimit:*`    | Rate limiting               | Per user/IP         | `ratelimit:user:123`         |
-
-### Namespace Examples
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const namespaceExamples = fn('namespace-examples', async ctx => {
-  // 1. Project-level configuration (native Versori KV)
-  const projectKV = ctx.openKv(':project:');
-  await projectKV.set('config:retailerId', '1');
-  await projectKV.set('config:environment', 'production');
-
-  // 2. Workflow-specific state (native Versori KV)
-  const workflowKV = ctx.openKv(':workflow:inventory-sync');
-  await workflowKV.set('state:lastRun', new Date().toISOString());
-  await workflowKV.set('state:lastCursor', 'cursor-value');
-
-  // 3. Custom namespace for caching (native Versori KV with TTL)
-  const cacheKV = ctx.openKv('cache:inventory');
-  await cacheKV.set('products', [], { ttl: 3600000 });
-
-  // 4. Custom namespace with VersoriKVAdapter (requires array-based keys)
-  const filesKV = ctx.openKv('files:daily-sync');
-  const adapter = new VersoriKVAdapter(filesKV);
-  // VersoriKVAdapter ALWAYS uses array syntax: ['processed', '2025-01-15']
-  await adapter.set(['processed', '2025-01-15'], { processedAt: Date.now() });
-
-  return { namespacesConfigured: 4 };
-});
-```
-
----
-
-## Performance Optimization
-
-### 1. Minimize Individual KV Operations
-
-**Note**: VersoriKVAdapter doesn't have batch methods. Use native Versori KV for individual operations.
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-// ❌ Inefficient - N separate KV operations
-export const inefficientWrites = fn('inefficient', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  for (const item of items) {
-    await adapter.set(['item', item.id], item); // N operations
-  }
-});
-
-// ✅ Better - Use native Versori KV for multiple writes
-export const efficientWrites = fn('efficient', async ctx => {
-  const kv = ctx.openKv(':project:');
-
-  // Native KV operations are faster
-  for (const item of items) {
-    await kv.set(`item:${item.id}`, item);
-  }
-});
-
-// ✅ Best - Store as single aggregate if possible
-export const aggregateWrite = fn('aggregate', async ctx => {
-  const kv = ctx.openKv(':project:');
-
-  // Store all items in one key (if items are related)
-  await kv.set('items:batch', items); // 1 operation
-});
-```
-
-### 2. Set Appropriate TTLs
-
-```typescript
-// Cache duration guidelines:
-const TTL = {
-  VERY_SHORT: 60000, // 1 minute - volatile data
-  SHORT: 300000, // 5 minutes - frequently changing
-  MEDIUM: 1800000, // 30 minutes - semi-static
-  LONG: 3600000, // 1 hour - stable data
-  VERY_LONG: 86400000, // 24 hours - rarely changing
-  PERMANENT: undefined, // No TTL - manual cleanup
-};
-
-// Use based on data characteristics
-await adapter.set(['cache', 'products'], products, TTL.MEDIUM);
-await adapter.set(['cache', 'config'], config, TTL.VERY_LONG);
-await adapter.set(['session', 'user', '123'], session, TTL.SHORT);
-```
-
-### 3. Minimize KV Reads/Writes
-
-**Note**: VersoriKVAdapter doesn't have `increment()` method. Use read-modify-write pattern.
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-// ❌ Inefficient - read/write in loop
-export const inefficientCounter = fn('inefficient', async ctx => {
-  const kv = ctx.openKv(':project:');
-
-  for (let i = 0; i < 100; i++) {
-    const count = (await kv.get('counter')) || 0;
-    await kv.set('counter', count + 1); // 100 read + 100 write operations
-  }
-});
-
-// ✅ Better - Single read-modify-write
-export const efficientCounter = fn('efficient', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  // Get current count
-  const stored = await adapter.get(['counter']);
-  const currentCount = (stored?.value as number) || 0;
-
-  // Update once
-  await adapter.set(['counter'], currentCount + 100); // 1 read + 1 write
-
-  return { count: currentCount + 100 };
-});
-
-// ✅ Best - Use atomic operations if needed
-export const atomicCounter = fn('atomic', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const adapter = new VersoriKVAdapter(kv);
-
-  const atomic = adapter.atomic();
-  atomic.set(['counter'], 100);
-  const success = await atomic.commit();
-
-  return { success };
-});
-```
-
-### 4. Use Prefix-Based Cleanup
-
-**Note**: VersoriKVAdapter doesn't have `clear()` or `keys()` methods. Use **native Versori KV** for prefix-based operations.
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const cleanupCache = fn('cleanup-cache', async ctx => {
-  const kv = ctx.openKv(':project:');
-
-  // List all cache keys (native Versori KV)
-  const cacheKeys = await kv.list({ prefix: 'cache:' });
-
-  // Delete each cache entry
-  for (const key of cacheKeys) {
-    await kv.delete(key);
-  }
-
-  // Clear old sessions (older than 1 day)
-  const sessionKeys = await kv.list({ prefix: 'session:' });
-  const now = Date.now();
-  let deletedCount = 0;
-
-  for (const key of sessionKeys) {
-    const session = await kv.get(key);
-    if (session && now - session.createdAt > 86400000) {
-      await kv.delete(key);
-      deletedCount++;
-    }
-  }
-
-  ctx.log('info', 'Cleanup complete', {
-    cacheKeysDeleted: cacheKeys.length,
-    sessionsChecked: sessionKeys.length,
-    oldSessionsDeleted: deletedCount,
-  });
-
-  return {
-    cacheKeysDeleted: cacheKeys.length,
-    oldSessionsDeleted: deletedCount,
-  };
-});
-```
-
----
-
-## Troubleshooting KV Storage
-
-### Common Issues & Solutions
-
-| Issue                       | Symptoms                        | Solution                                             |
-| --------------------------- | ------------------------------- | ---------------------------------------------------- |
-| **Data not persisting**     | Values disappear after workflow | Check TTL settings, ensure no accidental `clear()`   |
-| **Namespace conflicts**     | Unexpected data in keys         | Use unique namespaces per workflow/feature           |
-| **Performance degradation** | Slow KV operations              | Use batch operations, optimize key structure         |
-| **Lock deadlocks**          | Workflows stuck waiting         | Ensure locks are always released in `finally` blocks |
-| **Memory issues**           | Large values causing errors     | Split large objects, use pagination                  |
-
-### Debug KV State
-
-**Note**: Use **native Versori KV** for listing and debugging operations.
-
-```typescript
-import { fn } from '@versori/run';
-
-export const debugKV = fn('debug-kv', async ctx => {
-  const kv = ctx.openKv(':project:');
-
-  // List all keys (native Versori KV)
-  const allKeys = await kv.list();
-
-  // Group by prefix
-  const grouped: Record<string, string[]> = {};
-  for (const key of allKeys) {
-    const prefix = key.split(':')[0];
-    if (!grouped[prefix]) {
-      grouped[prefix] = [];
-    }
-    grouped[prefix].push(key);
-  }
-
-  // Sample some values
-  const samples: Record<string, unknown> = {};
-  for (const [prefix, keys] of Object.entries(grouped)) {
-    const sampleKey = keys[0];
-    samples[sampleKey] = await kv.get(sampleKey);
-  }
-
-  ctx.log('info', 'KV Debug Info', {
-    totalKeys: allKeys.length,
-    namespaces: Object.keys(grouped),
-    keysByNamespace: Object.fromEntries(Object.entries(grouped).map(([k, v]) => [k, v.length])),
-    samples,
-  });
-
-  return {
-    totalKeys: allKeys.length,
-    namespaces: grouped,
-    keysByNamespace: Object.fromEntries(Object.entries(grouped).map(([k, v]) => [k, v.length])),
-    samples,
-  };
-});
-```
-
----
-
-## Key Takeaways
-
-- 🎯 **VersoriKVAdapter** provides array-based key interface matching SDK's KVStore (use `['key']` syntax)
-- 🎯 **Native Versori KV** recommended for TTL, increment, list, and prefix operations
-- 🎯 **VersoriFileTracker** prevents duplicate file processing with simple metadata (`wasFileProcessed`, `markFileProcessed`)
-- 🎯 **Distributed locking** via StateService ensures concurrent workflow safety
-- 🎯 **Namespace scoping** (`:project:`, `:workflow:`, custom) provides isolation
-- 🎯 **TTL optimization** reduces storage costs - use native Versori KV for TTL support
-- 🎯 **Minimize KV operations** - aggregate data when possible, avoid loops
-- 🎯 **Always release locks** in `finally` blocks to prevent deadlocks
-
----
-
-## Practice Exercise
-
-Create a workflow that:
-
-1. Uses VersoriFileTracker to prevent duplicate processing
-2. Implements distributed locking for critical section
-3. Caches expensive API results with 30-minute TTL
-4. Tracks processing statistics using atomic counters
-5. Provides debug endpoint to view KV state
-
-**Hints**:
-
-- Combine VersoriFileTracker + StateService + VersoriKVAdapter
-- Use appropriate TTLs for cache vs state
-- Implement cleanup for old cache entries
-- Use atomic increment for statistics
-
-**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
-
----
-
-## Next Steps
-
-Now that you've mastered KV storage, let's explore deployment patterns and monitoring.
-
-Continue to [Module 7: Deployment →](./platforms-versori-07-deployment.md) to learn about deploying connectors, CI/CD, monitoring, and production operations.
-
----
-
-## Related Documentation
-
-- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Using KV in workflows
-- [Module 7: Deployment](./platforms-versori-07-deployment.md) - Production deployment
-- [Module 8: Best Practices](./platforms-versori-08-best-practices.md) - Production patterns
-- [API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
-
----
-
-[← Previous: Module 5](./platforms-versori-05-connections.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 7: Deployment →](./platforms-versori-07-deployment.md)
+# Module 6: KV Storage - State Management & File Tracking
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 6 of 8** | **Level**: Intermediate | **Time**: 25 minutes
+
+---
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- ✅ Understand Versori KV storage architecture and capabilities
+- ✅ Use VersoriKVAdapter for low-level KV operations
+- ✅ Implement VersoriFileTracker for duplicate prevention
+- ✅ Master KV scoping and namespace patterns
+- ✅ Implement distributed locking for concurrent workflows
+- ✅ Optimize KV storage for performance and cost
+- ✅ Debug and troubleshoot KV storage issues
+
+---
+
+## KV Storage Overview
+
+Versori provides a distributed key-value store accessible from all workflow types. It's designed for:
+
+| Use Case                | Pattern                      | SDK Component                               |
+| ----------------------- | ---------------------------- | ------------------------------------------- |
+| **File tracking**       | Prevent duplicate processing | `VersoriFileTracker`                        |
+| **State management**    | Workflow state persistence   | `StateService` + `VersoriKVAdapter`         |
+| **Distributed locking** | Prevent concurrent execution | `StateService.acquireLock()`                |
+| **Caching**             | Cache expensive API calls    | Native Versori KV with TTL                  |
+| **Rate limiting**       | Track request counts         | Native Versori KV (custom implementation)   |
+| **Incremental sync**    | Track last processed cursor  | `VersoriFileTracker.setLastProcessedFile()` |
+
+---
+
+## KV Storage Basics
+
+### Opening KV Store
+
+```typescript
+import { fn } from '@versori/run';
+
+export const kvBasics = fn('kv-basics', async ctx => {
+  // Three scoping options:
+
+  // 1. Project scope - shared across ALL workflows
+  const projectKV = ctx.openKv(':project:');
+
+  // 2. Workflow scope - isolated to THIS workflow
+  const workflowKV = ctx.openKv(':workflow:my-workflow');
+
+  // 3. Custom scope - custom namespace
+  const customKV = ctx.openKv('custom:namespace:name');
+
+  return { message: 'KV stores opened' };
+});
+```
+
+### Basic Operations
+
+```typescript
+export const kvOperations = fn('kv-operations', async ctx => {
+  const kv = ctx.openKv(':project:');
+
+  // Set value
+  await kv.set('key', { foo: 'bar' });
+
+  // Set with TTL (30 minutes = 1800000ms)
+  await kv.set('cache:key', { data: [] }, { ttl: 1800000 });
+
+  // Get value
+  const value = await kv.get('key');
+  console.log(value); // { foo: 'bar' }
+
+  // Delete value
+  await kv.delete('key');
+
+  // Check existence
+  const exists = await kv.has('key'); // false
+
+  // List keys with prefix
+  const keys = await kv.list({ prefix: 'cache:' });
+
+  return { operations: 'complete' };
+});
+```
+
+---
+
+## VersoriKVAdapter - Low-Level KV Operations
+
+The SDK provides `VersoriKVAdapter` which wraps the native Versori KV with additional features.
+
+### Creating Adapter
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const useAdapter = fn('use-adapter', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  // Now use adapter methods...
+});
+```
+
+### VersoriKVAdapter API Reference
+
+**IMPORTANT**: VersoriKVAdapter uses **array-based keys** `['key']` to match the SDK's `KVStore` interface.
+
+```typescript
+interface VersoriKVAdapter implements KVStore {
+  // Basic operations (use array keys: ['key'])
+  get(keys: string[]): Promise<{ value: unknown } | null>;
+  set(keys: string[], value: unknown): Promise<void>;
+  delete(keys: string[]): Promise<void>;
+
+  // Atomic operations (simplified - Versori doesn't support true atomicity)
+  atomic(): {
+    check(entries: Array<{ key: string[]; versionstamp: string | null }>): void;
+    set(key: string[], value: unknown): void;
+    commit(): Promise<boolean>;  // Returns true if all operations succeed
+  };
+}
+```
+
+**Key Limitations:**
+- ❌ **No versionstamp support** - Versori KV doesn't expose version stamps
+- ❌ **No expireIn/TTL option** in VersoriKVAdapter - use native Versori KV for TTL
+- ❌ **No list() method** - use native Versori KV with prefix patterns
+- ❌ **No atomic guarantees** - `atomic()` executes operations sequentially, not atomically
+- ❌ **No increment()** - use read-modify-write pattern
+
+**When to Use VersoriKVAdapter:**
+- ✅ You need SDK `KVStore` interface compatibility (e.g., for `StateService`)
+- ✅ You're using array-based key patterns `['namespace', 'key']`
+- ✅ Simple get/set/delete operations are sufficient
+
+**When to Use Native Versori KV:**
+- ✅ You need TTL/expiration support
+- ✅ You need to list keys with prefixes
+- ✅ You want string-based keys `'simple:key:name'`
+- ✅ You need increment operations
+- ✅ Better performance (no adapter overhead)
+
+### Practical Examples
+
+#### Example 1: Caching Expensive API Calls
+
+**Note**: For caching with TTL, use **native Versori KV** directly. VersoriKVAdapter doesn't support TTL.
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const cachedQuery = http(
+  'cached-query',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+
+    const cacheKey = 'cache:products:list';
+    const cacheTTL = 3600000; // 1 hour
+
+    // Try cache first (using native Versori KV)
+    let products = await kv.get(cacheKey);
+
+    if (products) {
+      ctx.log('info', 'Cache hit', { key: cacheKey });
+      return { source: 'cache', data: products };
+    }
+
+    // Cache miss - fetch from API
+    ctx.log('info', 'Cache miss - fetching from API');
+    const client = await createClient(ctx);
+
+    const result = await client.graphql({
+      query: `
+      query GetProducts($first: Int!) {
+        products(first: $first) {
+          edges {
+            node {
+              id
+              ref
+              name
+              status
+            }
+          }
+        }
+      }
+    `,
+      variables: { first: 100 },
+    });
+
+    products = result.data.products.edges.map(e => e.node);
+
+    // Store in cache with TTL (using native Versori KV)
+    await kv.set(cacheKey, products, { ttl: cacheTTL });
+
+    return { source: 'api', data: products };
+  }
+);
+```
+
+#### Example 2: Rate Limiting with Native Versori KV
+
+**Note**: VersoriKVAdapter doesn't have `increment()`, `expire()`, or `ttl()` methods. Use **native Versori KV** for rate limiting. StateService is for distributed locking, not rate limiting.
+
+```typescript
+import { fn } from '@versori/run';
+
+export const rateLimited = fn('rate-limited', async ctx => {
+  const kv = ctx.openKv(':project:');
+  
+  const userId = ctx.data?.userId || 'anonymous';
+  const rateLimitKey = `ratelimit:${userId}`;
+  const maxRequests = 100;
+  const windowMs = 3600000; // 1 hour
+
+  // Get current count using native Versori KV
+  const stored = await kv.get(rateLimitKey);
+  const data = stored as { count: number; resetAt: number } | undefined;
+
+  const now = Date.now();
+  let count = 0;
+  let resetAt = now + windowMs;
+
+  if (data && data.resetAt > now) {
+    // Within rate limit window
+    count = data.count + 1;
+    resetAt = data.resetAt;
+  } else {
+    // New window
+    count = 1;
+    resetAt = now + windowMs;
+  }
+
+  // Update count using native Versori KV
+  await kv.set(rateLimitKey, { count, resetAt });
+
+  // Check if rate limited
+  if (count > maxRequests) {
+    const retryAfter = Math.ceil((resetAt - now) / 1000);
+    return {
+      rateLimited: true,
+      retryAfter,
+      message: `Rate limit exceeded. Try again in ${retryAfter}s`,
+    };
+  }
+
+  // Process request
+  return {
+    rateLimited: false,
+    requestsRemaining: maxRequests - count,
+  };
+});
+```
+
+#### Example 3: Using VersoriKVAdapter for Workflow State
+
+**Note**: VersoriKVAdapter doesn't have `mset()` or `mget()` methods. For batch operations, use native Versori KV or loop through individual operations.
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const workflowState = fn('workflow-state', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  // Set workflow states (individual operations with array-based keys)
+  await adapter.set(['state', 'workflow1'], { status: 'running', startedAt: Date.now() });
+  await adapter.set(['state', 'workflow2'], { status: 'pending', queuedAt: Date.now() });
+  await adapter.set(['state', 'workflow3'], { status: 'completed', finishedAt: Date.now() });
+
+  // Get workflow states (individual operations)
+  const workflow1 = await adapter.get(['state', 'workflow1']);
+  const workflow2 = await adapter.get(['state', 'workflow2']);
+  const workflow3 = await adapter.get(['state', 'workflow3']);
+
+  const states = [workflow1?.value, workflow2?.value, workflow3?.value];
+
+  ctx.log('info', 'Workflow states retrieved', {
+    retrieved: states.filter(v => v !== null && v !== undefined).length,
+  });
+
+  return { states };
+});
+```
+
+---
+
+## VersoriFileTracker - Duplicate Prevention
+
+The most common KV use case: tracking processed files to prevent duplicates.
+
+### VersoriFileTracker API Reference
+
+```typescript
+interface VersoriFileTracker {
+  // Check if file was processed
+  wasFileProcessed(fileName: string): Promise<boolean>;
+
+  // Mark file as processed with metadata
+  markFileProcessed(fileName: string, metadata?: { recordCount?: number }): Promise<void>;
+
+  // Incremental sync helpers
+  setLastProcessedFile(fileName: string): Promise<void>;
+  getLastProcessedFile(): Promise<string | null>;
+}
+```
+
+**Key Points**:
+
+- **Array-based keys internally**: Uses `prefix:processed-files:${fileName}` pattern
+- **Simple metadata**: Only stores `processedAt` timestamp and optional `recordCount`
+- **No list/clear methods**: For advanced queries, use native Versori KV with prefix patterns
+
+### Example 1: Basic File Tracking
+
+```typescript
+import { schedule } from '@versori/run';
+import { createClient, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Daily inventory sync with duplicate prevention
+ *
+ * Cron: 0 2 * * * (daily at 2 AM)
+ */
+export const dailySyncWithTracking = schedule(
+  'daily-sync',
+  '0 2 * * *',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const tracker = new VersoriFileTracker(kv, 'daily-inventory-sync');
+
+    // Generate file name based on date
+    const today = new Date().toISOString().split('T')[0];
+    const fileName = `inventory-${today}.csv`;
+
+    // Check if already processed
+    if (await tracker.wasFileProcessed(fileName)) {
+      ctx.log('info', 'File already processed today', { fileName });
+      return {
+        skipped: true,
+        reason: 'Already processed',
+        fileName,
+      };
+    }
+
+    // Process file
+    ctx.log('info', 'Processing new file', { fileName });
+    const records = await fetchAndParseInventoryFile(fileName);
+
+    // Send to Fluent
+    const client = await createClient(ctx);
+    const job = await client.createJob({ name: `Daily Sync ${fileName}` });
+    await client.sendBatch(job.id, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: records,
+    });
+
+    // Mark as processed with metadata
+    await tracker.markFileProcessed(fileName, {
+      recordCount: records.length,
+      jobId: job.id,
+      timestamp: Date.now(),
+    });
+
+    ctx.log('info', 'File processed successfully', {
+      fileName,
+      recordCount: records.length,
+      jobId: job.id,
+    });
+
+    return {
+      success: true,
+      fileName,
+      recordCount: records.length,
+      jobId: job.id,
+    };
+  }
+);
+```
+
+### Example 2: Incremental Processing
+
+```typescript
+export const incrementalSync = schedule(
+  'incremental-sync',
+  '0 * * * *',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const tracker = new VersoriFileTracker(kv, 'incremental-sync');
+
+    // Get last processed file
+    const lastFile = await tracker.getLastProcessedFile();
+    ctx.log('info', 'Last processed file', { lastFile });
+
+    // List new files since last run
+    const newFiles = await listFilesAfter(lastFile);
+
+    if (newFiles.length === 0) {
+      ctx.log('info', 'No new files to process');
+      return { skipped: true, reason: 'No new files' };
+    }
+
+    const client = await createClient(ctx);
+    let totalProcessed = 0;
+
+    for (const file of newFiles) {
+      // Skip if already processed (safety check)
+      if (await tracker.wasFileProcessed(file.name)) {
+        ctx.log('warn', 'File already processed (safety skip)', { file: file.name });
+        continue;
+      }
+
+      // Process file
+      const records = await processFile(file);
+
+      // Send to Fluent
+      const job = await client.createJob({ name: `Incremental ${file.name}` });
+      await client.sendBatch(job.id, {
+        action: 'UPSERT',
+        entityType: 'INVENTORY',
+        entities: records,
+      });
+
+      // Mark as processed
+      await tracker.markFileProcessed(file.name, {
+        recordCount: records.length,
+        jobId: job.id,
+      });
+
+      // Update last processed file
+      await tracker.setLastProcessedFile(file.name);
+
+      totalProcessed += records.length;
+
+      ctx.log('info', 'File processed', {
+        fileName: file.name,
+        recordCount: records.length,
+      });
+    }
+
+    return {
+      success: true,
+      filesProcessed: newFiles.length,
+      recordsProcessed: totalProcessed,
+    };
+  }
+);
+```
+
+### Example 3: Checking Last Processed File
+
+**Note**: VersoriFileTracker doesn't have `listProcessedFiles()` or `getFileProcessingInfo()` methods. Use `getLastProcessedFile()` to track incremental sync state.
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+export const checkProcessingState = fn('check-state', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const tracker = new VersoriFileTracker(kv, 'daily-inventory-sync');
+
+  // Get last processed file
+  const lastFile = await tracker.getLastProcessedFile();
+
+  // Check if specific files were processed
+  const today = new Date().toISOString().split('T')[0];
+  const todayFile = `inventory-${today}.csv`;
+  const yesterday = new Date(Date.now() - 86400000).toISOString().split('T')[0];
+  const yesterdayFile = `inventory-${yesterday}.csv`;
+
+  const todayProcessed = await tracker.wasFileProcessed(todayFile);
+  const yesterdayProcessed = await tracker.wasFileProcessed(yesterdayFile);
+
+  ctx.log('info', 'Processing state', {
+    lastFile,
+    todayProcessed,
+    yesterdayProcessed,
+  });
+
+  return {
+    lastFile,
+    todayFile: {
+      name: todayFile,
+      processed: todayProcessed,
+    },
+    yesterdayFile: {
+      name: yesterdayFile,
+      processed: yesterdayProcessed,
+    },
+  };
+});
+```
+
+**For viewing all processed files**, use native Versori KV with prefix listing:
+
+```typescript
+export const listAllProcessedFiles = fn('list-processed', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const prefix = 'fc-sdk:processed-files:';
+
+  // List all keys with prefix (native Versori KV)
+  const keys = await kv.list({ prefix });
+
+  const files = [];
+  for (const key of keys) {
+    const fileName = key.replace(prefix, '');
+    const metadata = await kv.get(key);
+    files.push({
+      fileName,
+      processedAt: metadata?.processedAt,
+      recordCount: metadata?.recordCount,
+    });
+  }
+
+  // Sort by date (newest first)
+  files.sort(
+    (a, b) => new Date(b.processedAt || 0).getTime() - new Date(a.processedAt || 0).getTime()
+  );
+
+  return { totalFiles: files.length, files };
+});
+```
+
+---
+
+## Distributed Locking
+
+Prevent concurrent execution of critical sections using distributed locks.
+
+### StateService with Locking
+
+```typescript
+import { schedule } from '@versori/run';
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Scheduled workflow with distributed locking
+ *
+ * Ensures only ONE instance runs at a time
+ */
+export const criticalSection = schedule(
+  'critical',
+  '*/5 * * * *',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const kvAdapter = new VersoriKVAdapter(kv);
+    const stateService = new StateService(logger);
+
+    const lockName = 'critical-section';
+    const timeoutMinutes = 1; // 1 minute timeout
+
+    // Try to acquire lock (returns boolean)
+    const acquired = await stateService.acquireLock(lockName, kvAdapter, timeoutMinutes);
+
+    if (!acquired) {
+      ctx.log('warn', 'Lock acquisition failed - another instance is running', {
+        lockName,
+      });
+      return {
+        skipped: true,
+        reason: 'Another instance is running',
+      };
+    }
+
+    ctx.log('info', 'Lock acquired, starting critical section', {
+      lockName,
+    });
+
+    try {
+      // Critical section - only ONE workflow instance executes this
+      await performCriticalOperation(ctx);
+
+      ctx.log('info', 'Critical section completed successfully');
+
+      return { success: true };
+    } finally {
+      // Always release lock
+      await stateService.releaseLock(lockName, kvAdapter);
+      ctx.log('info', 'Lock released', { lockName });
+    }
+  }
+);
+```
+
+### Advanced Locking Pattern
+
+```typescript
+export const advancedLocking = schedule(
+  'advanced-locking',
+  '*/10 * * * *',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const kv = ctx.openKv(':project:');
+    const kvAdapter = new VersoriKVAdapter(kv);
+    const stateService = new StateService(logger);
+
+    const lockName = 'inventory-sync';
+    const timeoutMinutes = 5; // 5 minutes timeout
+    const maxRetries = 3;
+    const retryDelay = 5000; // 5 seconds
+
+    let acquired = false;
+    let attempts = 0;
+
+    // Retry lock acquisition
+    while (attempts < maxRetries) {
+      acquired = await stateService.acquireLock(lockName, kvAdapter, timeoutMinutes);
+
+      if (acquired) {
+        break;
+      }
+
+      attempts++;
+      ctx.log('info', `Lock acquisition failed, retrying... (${attempts}/${maxRetries})`);
+      await new Promise(resolve => setTimeout(resolve, retryDelay));
+    }
+
+    if (!acquired) {
+      ctx.log('error', 'Failed to acquire lock after retries', {
+        attempts,
+      });
+      return {
+        success: false,
+        error: 'Failed to acquire lock',
+        attempts,
+      };
+    }
+
+    try {
+      // Long-running operation
+      const result = await performLongOperation(ctx);
+
+      // Note: StateService doesn't have extendLock() - acquire a new lock if needed
+      // If operation needs more time, acquire a new lock before releasing
+      if (result.needsMoreTime) {
+        // Release current lock and acquire new one
+        await stateService.releaseLock(lockName, kvAdapter);
+        const reacquired = await stateService.acquireLock(lockName, kvAdapter, timeoutMinutes);
+        if (reacquired) {
+          ctx.log('info', 'Lock reacquired for extended operation');
+        }
+      }
+
+      return { success: true, result };
+    } catch (error) {
+      ctx.log('error', 'Operation failed', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    } finally {
+      await stateService.releaseLock(lockName, kvAdapter);
+      ctx.log('info', 'Lock released');
+    }
+  }
+);
+```
+
+---
+
+## KV Namespace Patterns
+
+### Scoping Best Practices
+
+| Namespace        | Use Case                    | Scope               | Example Key                  |
+| ---------------- | --------------------------- | ------------------- | ---------------------------- |
+| `:project:`      | Global config, shared state | All workflows       | `config:retailerId`          |
+| `:workflow:name` | Workflow-specific state     | Single workflow     | `state:lastRun`              |
+| `cache:*`        | Cached data                 | Project-wide        | `cache:products:list`        |
+| `lock:*`         | Distributed locks           | Project-wide        | `lock:inventory-sync`        |
+| `files:*`        | File tracking               | Workflow or project | `files:processed:2025-01-15` |
+| `ratelimit:*`    | Rate limiting               | Per user/IP         | `ratelimit:user:123`         |
+
+### Namespace Examples
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const namespaceExamples = fn('namespace-examples', async ctx => {
+  // 1. Project-level configuration (native Versori KV)
+  const projectKV = ctx.openKv(':project:');
+  await projectKV.set('config:retailerId', '1');
+  await projectKV.set('config:environment', 'production');
+
+  // 2. Workflow-specific state (native Versori KV)
+  const workflowKV = ctx.openKv(':workflow:inventory-sync');
+  await workflowKV.set('state:lastRun', new Date().toISOString());
+  await workflowKV.set('state:lastCursor', 'cursor-value');
+
+  // 3. Custom namespace for caching (native Versori KV with TTL)
+  const cacheKV = ctx.openKv('cache:inventory');
+  await cacheKV.set('products', [], { ttl: 3600000 });
+
+  // 4. Custom namespace with VersoriKVAdapter (requires array-based keys)
+  const filesKV = ctx.openKv('files:daily-sync');
+  const adapter = new VersoriKVAdapter(filesKV);
+  // VersoriKVAdapter ALWAYS uses array syntax: ['processed', '2025-01-15']
+  await adapter.set(['processed', '2025-01-15'], { processedAt: Date.now() });
+
+  return { namespacesConfigured: 4 };
+});
+```
+
+---
+
+## Performance Optimization
+
+### 1. Minimize Individual KV Operations
+
+**Note**: VersoriKVAdapter doesn't have batch methods. Use native Versori KV for individual operations.
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+// ❌ Inefficient - N separate KV operations
+export const inefficientWrites = fn('inefficient', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  for (const item of items) {
+    await adapter.set(['item', item.id], item); // N operations
+  }
+});
+
+// ✅ Better - Use native Versori KV for multiple writes
+export const efficientWrites = fn('efficient', async ctx => {
+  const kv = ctx.openKv(':project:');
+
+  // Native KV operations are faster
+  for (const item of items) {
+    await kv.set(`item:${item.id}`, item);
+  }
+});
+
+// ✅ Best - Store as single aggregate if possible
+export const aggregateWrite = fn('aggregate', async ctx => {
+  const kv = ctx.openKv(':project:');
+
+  // Store all items in one key (if items are related)
+  await kv.set('items:batch', items); // 1 operation
+});
+```
+
+### 2. Set Appropriate TTLs
+
+```typescript
+// Cache duration guidelines:
+const TTL = {
+  VERY_SHORT: 60000, // 1 minute - volatile data
+  SHORT: 300000, // 5 minutes - frequently changing
+  MEDIUM: 1800000, // 30 minutes - semi-static
+  LONG: 3600000, // 1 hour - stable data
+  VERY_LONG: 86400000, // 24 hours - rarely changing
+  PERMANENT: undefined, // No TTL - manual cleanup
+};
+
+// Use based on data characteristics
+await adapter.set(['cache', 'products'], products, TTL.MEDIUM);
+await adapter.set(['cache', 'config'], config, TTL.VERY_LONG);
+await adapter.set(['session', 'user', '123'], session, TTL.SHORT);
+```
+
+### 3. Minimize KV Reads/Writes
+
+**Note**: VersoriKVAdapter doesn't have `increment()` method. Use read-modify-write pattern.
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+// ❌ Inefficient - read/write in loop
+export const inefficientCounter = fn('inefficient', async ctx => {
+  const kv = ctx.openKv(':project:');
+
+  for (let i = 0; i < 100; i++) {
+    const count = (await kv.get('counter')) || 0;
+    await kv.set('counter', count + 1); // 100 read + 100 write operations
+  }
+});
+
+// ✅ Better - Single read-modify-write
+export const efficientCounter = fn('efficient', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  // Get current count
+  const stored = await adapter.get(['counter']);
+  const currentCount = (stored?.value as number) || 0;
+
+  // Update once
+  await adapter.set(['counter'], currentCount + 100); // 1 read + 1 write
+
+  return { count: currentCount + 100 };
+});
+
+// ✅ Best - Use atomic operations if needed
+export const atomicCounter = fn('atomic', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const adapter = new VersoriKVAdapter(kv);
+
+  const atomic = adapter.atomic();
+  atomic.set(['counter'], 100);
+  const success = await atomic.commit();
+
+  return { success };
+});
+```
+
+### 4. Use Prefix-Based Cleanup
+
+**Note**: VersoriKVAdapter doesn't have `clear()` or `keys()` methods. Use **native Versori KV** for prefix-based operations.
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const cleanupCache = fn('cleanup-cache', async ctx => {
+  const kv = ctx.openKv(':project:');
+
+  // List all cache keys (native Versori KV)
+  const cacheKeys = await kv.list({ prefix: 'cache:' });
+
+  // Delete each cache entry
+  for (const key of cacheKeys) {
+    await kv.delete(key);
+  }
+
+  // Clear old sessions (older than 1 day)
+  const sessionKeys = await kv.list({ prefix: 'session:' });
+  const now = Date.now();
+  let deletedCount = 0;
+
+  for (const key of sessionKeys) {
+    const session = await kv.get(key);
+    if (session && now - session.createdAt > 86400000) {
+      await kv.delete(key);
+      deletedCount++;
+    }
+  }
+
+  ctx.log('info', 'Cleanup complete', {
+    cacheKeysDeleted: cacheKeys.length,
+    sessionsChecked: sessionKeys.length,
+    oldSessionsDeleted: deletedCount,
+  });
+
+  return {
+    cacheKeysDeleted: cacheKeys.length,
+    oldSessionsDeleted: deletedCount,
+  };
+});
+```
+
+---
+
+## Troubleshooting KV Storage
+
+### Common Issues & Solutions
+
+| Issue                       | Symptoms                        | Solution                                             |
+| --------------------------- | ------------------------------- | ---------------------------------------------------- |
+| **Data not persisting**     | Values disappear after workflow | Check TTL settings, ensure no accidental `clear()`   |
+| **Namespace conflicts**     | Unexpected data in keys         | Use unique namespaces per workflow/feature           |
+| **Performance degradation** | Slow KV operations              | Use batch operations, optimize key structure         |
+| **Lock deadlocks**          | Workflows stuck waiting         | Ensure locks are always released in `finally` blocks |
+| **Memory issues**           | Large values causing errors     | Split large objects, use pagination                  |
+
+### Debug KV State
+
+**Note**: Use **native Versori KV** for listing and debugging operations.
+
+```typescript
+import { fn } from '@versori/run';
+
+export const debugKV = fn('debug-kv', async ctx => {
+  const kv = ctx.openKv(':project:');
+
+  // List all keys (native Versori KV)
+  const allKeys = await kv.list();
+
+  // Group by prefix
+  const grouped: Record<string, string[]> = {};
+  for (const key of allKeys) {
+    const prefix = key.split(':')[0];
+    if (!grouped[prefix]) {
+      grouped[prefix] = [];
+    }
+    grouped[prefix].push(key);
+  }
+
+  // Sample some values
+  const samples: Record<string, unknown> = {};
+  for (const [prefix, keys] of Object.entries(grouped)) {
+    const sampleKey = keys[0];
+    samples[sampleKey] = await kv.get(sampleKey);
+  }
+
+  ctx.log('info', 'KV Debug Info', {
+    totalKeys: allKeys.length,
+    namespaces: Object.keys(grouped),
+    keysByNamespace: Object.fromEntries(Object.entries(grouped).map(([k, v]) => [k, v.length])),
+    samples,
+  });
+
+  return {
+    totalKeys: allKeys.length,
+    namespaces: grouped,
+    keysByNamespace: Object.fromEntries(Object.entries(grouped).map(([k, v]) => [k, v.length])),
+    samples,
+  };
+});
+```
+
+---
+
+## Key Takeaways
+
+- 🎯 **VersoriKVAdapter** provides array-based key interface matching SDK's KVStore (use `['key']` syntax)
+- 🎯 **Native Versori KV** recommended for TTL, increment, list, and prefix operations
+- 🎯 **VersoriFileTracker** prevents duplicate file processing with simple metadata (`wasFileProcessed`, `markFileProcessed`)
+- 🎯 **Distributed locking** via StateService ensures concurrent workflow safety
+- 🎯 **Namespace scoping** (`:project:`, `:workflow:`, custom) provides isolation
+- 🎯 **TTL optimization** reduces storage costs - use native Versori KV for TTL support
+- 🎯 **Minimize KV operations** - aggregate data when possible, avoid loops
+- 🎯 **Always release locks** in `finally` blocks to prevent deadlocks
+
+---
+
+## Practice Exercise
+
+Create a workflow that:
+
+1. Uses VersoriFileTracker to prevent duplicate processing
+2. Implements distributed locking for critical section
+3. Caches expensive API results with 30-minute TTL
+4. Tracks processing statistics using atomic counters
+5. Provides debug endpoint to view KV state
+
+**Hints**:
+
+- Combine VersoriFileTracker + StateService + VersoriKVAdapter
+- Use appropriate TTLs for cache vs state
+- Implement cleanup for old cache entries
+- Use atomic increment for statistics
+
+**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
+
+---
+
+## Next Steps
+
+Now that you've mastered KV storage, let's explore deployment patterns and monitoring.
+
+Continue to [Module 7: Deployment →](./platforms-versori-07-deployment.md) to learn about deploying connectors, CI/CD, monitoring, and production operations.
+
+---
+
+## Related Documentation
+
+- [Module 4: Workflows](./platforms-versori-04-workflows.md) - Using KV in workflows
+- [Module 7: Deployment](./platforms-versori-07-deployment.md) - Production deployment
+- [Module 8: Best Practices](./platforms-versori-08-best-practices.md) - Production patterns
+- [API Reference](../../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
+
+---
+
+[← Previous: Module 5](./platforms-versori-05-connections.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 7: Deployment →](./platforms-versori-07-deployment.md)