@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md

@@ -1,1882 +1,1882 @@
----
-template_id: tpl-ingest-multi-channel-inventory-sync
-canonical_filename: template-ingestion-multi-channel-inventory-sync.md
-sdk_version: latest
-runtime: versori
-direction: ingestion
-source: multi-channel-rest-s3
-destination: fluent-batch-api
-entity: inventory
-format: json-csv
-logging: versori
-status: stable
----
-
-# Template: Ingestion - Multi-Channel Inventory Sync (Scheduled)
-
-## STEP 1: Understand This Template
-
-**What This Template Does:**
-
-- Scheduled Versori workflow for multi-channel inventory aggregation and sync
-- Fetches inventory from multiple sources in parallel (REST API, S3 CSV, Fluent GraphQL)
-- Calculates channel-specific ATP (Available To Promise) with configurable buffers and caps
-- Performs delta detection using VersoriKVAdapter to sync only changed inventory records
-- Handles partial channel failures gracefully with Promise.allSettled
-- Rate-limits external REST API calls with exponential backoff retry logic
-- Sends consolidated inventory updates to Fluent Commerce Batch API with chunking
-- Tracks job lifecycle with JobTracker for operational monitoring
-- Supports scheduled (cron) and ad-hoc (webhook) triggers
-
-**Key SDK Components:**
-
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `S3DataSource` - S3 file operations with retry logic
-- `CSVParserService` - CSV parsing with validation
-- `UniversalMapper` - Field transformation with SDK resolvers
-- `StateService` + `VersoriKVAdapter` - Delta detection state management
-- `JobTracker` - Job lifecycle tracking - `FluentClient.createJob()` - Create Batch API job
-- `FluentClient.sendBatch()` - Send inventory chunks (fire-and-forget)
-- `FluentClient.graphql()` - Query current Fluent inventory state with auto-pagination
-- Native Versori `log` - Use `log` from context 
-**Entity Type:**
-
-- **InventoryQuantity** - Fluent entity for inventory positions and quantities
-- **EntityType: 'INVENTORY'** - Used in Batch API `sendBatch()` call
-- **Batch API Method** - Uses `createJob()` and `sendBatch()` (not Event API)
-
-**Critical Patterns:**
-
-- **Multi-source aggregation**: Use `Promise.allSettled()` for parallel channel fetching
-- **Graceful degradation**: Continue processing even if one channel fails
-- **Delta detection**: StateService tracks previous state to detect changes
-- **Progress Logging**: Enhanced logging with context (sample SKUs, locations)
-- **JobTracker Progress Updates**: Periodic progress updates during batch processing
-- **ATP calculation**: `ATP = (onHand - reserved) - buffer` with oversell protection
-- **Delta detection**: Use `StateService` + `VersoriKVAdapter` to track previous ATP values
-- **Rate limiting**: Enforce minimum interval between channel API requests
-- **Safe configuration**: External JSON mapping file (not inline TypeScript)
-- **BPP Configuration**: Use `'skip'` (delta detection already filters changes)
-- **Fire-and-forget batches**: Batch submission is asynchronous (no polling needed)
-
-**When to Use This Template:**
-
-- ✅ Multiple inventory sources (3+ channels) requiring aggregation
-- ✅ Channel-specific ATP calculations with buffers and caps
-- ✅ Delta detection needed (only sync changed records)
-- ✅ Partial channel failures shouldn't block entire sync
-- ✅ External APIs require rate limiting and retry logic
-- ✅ Scheduled batch processing (every 15 minutes, hourly, etc.)
-
-**When NOT to Use:**
-
-- ❌ Single inventory source (use simpler single-source templates)
-- ❌ Real-time sync required (this is designed for scheduled batch processing)
-- ❌ No ATP calculations needed (use direct field mapping)
-- ❌ Don't need delta detection (full snapshots every time)
-- ❌ Products, Locations, Customers (use Event API templates)
-
----
-
-## STEP 2: AI Prompt
-
-**Copy this prompt to generate the complete implementation:**
-
-```
-Create a Versori scheduled workflow for multi-channel inventory aggregation to Fluent Commerce Batch API.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (scheduled workflow)
-2. Sources: Multiple channels (REST API, S3 CSV, Fluent GraphQL)
-3. Destination: Fluent Commerce Batch API (InventoryQuantity entity)
-4. Entity: InventoryQuantity (EntityType: 'INVENTORY')
-
-KEY FEATURES:
-1. **Multi-channel fetching** (parallel):
-   - **Channel A**: REST API with rate limiting (120 RPM) and retry logic
-   - **Channel B**: S3 CSV file with CSVParserService
-   - **Fluent GraphQL**: Current inventory state via auto-pagination
-2. **ATP (Available To Promise) calculation**:
-   - Formula: `ATP = (onHand - reserved) - buffer`
-   - Channel-specific buffers (configurable per channel)
-   - Aggregate ATP across channels with deduplication by SKU + location
-   - Support oversell protection (ensure ATP ≥ 0)
-3. **Delta detection**:
-   - Use `StateService` + `VersoriKVAdapter` to track previous ATP values
-   - Only send changed records to Batch API
-   - Store state with 7-day TTL in Versori KV
-4. **Graceful degradation**:
-   - Use `Promise.allSettled()` for channel fetching
-   - Continue processing even if one channel fails
-   - Log channel failures but don't block entire sync
-5. **Batch API**:
-   - Entity: `InventoryQuantity`
-   - EntityType: `'INVENTORY'`
-   - Action: `'UPSERT'`
-   - BPP: `'skip'` (delta detection already filters)
-   - Batch size: 500 records per chunk
-   - Poll batches until complete with exponential backoff
-6. **Job tracking**:
-   - Use `JobTracker` with Versori KV storage
-   - Track status transitions: `fetching_channels` → `aggregating` → `delta_detection` → `creating_batch_job` → `sending_batches` → `polling_batches` → `updating_delta_state`
-7. **Modular architecture**:
-   - Separate service files (ATP calculator, channel connectors, batch dispatcher)
-   - External JSON mapping config
-   - Clean separation of concerns
-
-CRITICAL REQUIREMENTS:
-1. Modular architecture: Separate service files (ATP calculator, channel connectors, batch dispatcher)
-2. External JSON mapping config: Use `with { type: 'json' }` import syntax
-3. Native logging: Use log from context (LoggingService removed - use native log)
-4. Graceful degradation: Promise.allSettled for parallel channel fetching
-5. Delta detection: Track previous ATP values in Versori KV
-6. BPP: Set to 'skip' (delta already filters changes)
-7. Rate limiting: Enforce minimum interval between Channel A requests
-8. Job tracking: Use JobTracker for lifecycle management
-
-SDK METHODS TO USE:
-- createClient(ctx) - Pass entire Versori context, auto-detects platform
-- new S3DataSource(config, log) - S3 file operations
-- new CSVParserService() - Parse CSV files
-- await client.graphql({ query, variables, pagination }) - Fluent GraphQL extraction with auto-pagination
-- new VersoriKVAdapter(openKv(':project:')) - Versori KV storage adapter
-- new StateService(kvAdapter) - Delta state management (takes KV adapter, not logger)
-- new JobTracker(kv, log) - Job lifecycle tracking
-- await client.createJob({ name, retailerId, meta: { preprocessing: 'skip' } }) - Create Batch API job
-- await client.sendBatch(jobId, { action, entityType, source, event, entities }) - Send batch chunk (fire-and-forget)
-
-FORBIDDEN PATTERNS:
-- ❌ LoggingService (removed - use native log on Versori)
-- ❌ Don't use monolithic index.ts (extract services into separate files)
-- ❌ Don't use inline mapping config (use external JSON file)
-- ❌ Don't fail entire sync if one channel fails (use Promise.allSettled)
-- ❌ Don't send all records (use delta detection to filter unchanged)
-- ❌ Don't use BPP with deltas (set preprocessing: 'skip')
-- ❌ Don't forget rate limiting for external APIs
-- ❌ Don't forget to call dispose() on data sources in finally block
-
-GENERATE:
-1. package.json with dependencies
-2. index.ts (workflow entry point with scheduled/adhoc/status triggers)
-3. src/workflows/multi-channel-sync.workflow.ts (main orchestration logic)
-4. src/services/atp-calculator.service.ts (ATP calculation and aggregation)
-5. src/services/channel-a-connector.service.ts (REST API with rate limiting)
-6. src/services/channel-b-connector.service.ts (S3 CSV fetching)
-7. src/services/batch-processor.service.ts (Batch API submission)
-8. src/services/batch-logger.service.ts (SFTP log file writing)
-9. src/types/multi-channel.types.ts (TypeScript interfaces)
-10. config/multi-channel.mapping.json (mapping configuration - external JSON file)
-
-NOTE: Use external JSON files for mapping configuration (not TypeScript .config files)
-
-Ensure all code is production-ready with proper error handling, graceful degradation, and rate limiting. Use modular architecture with separate service files for each concern.
-```
-
----
-
-## What You'll Build
-
-### 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:**
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`workflow()`** → Durable workflows (advanced, rarely used)
-
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from schedule/webhook)
-- **`fn()`** → Internal processing (chained from schedule/webhook)
-
-### Recommended Project Structure
-
-```
-inventory-batch-sync/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-inventory-sync.ts   # Scheduled: Daily inventory sync
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-inventory-sync.ts   # Webhook: Manual trigger
-    │       └── job-status-check.ts       # Webhook: Status query
-    │
-    ├── services/
-    │   └── inventory-sync.service.ts     # Shared orchestration logic (reusable)
-    │
-    └── types/
-        └── inventory.types.ts            # Shared type definitions
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`scheduled/` vs `webhook/`)
-- ✅ 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
-
----
-
-## Workflow Files
-
-### 1. Scheduled Workflows (`src/workflows/scheduled/`)
-
-All time-based triggers that run automatically on cron schedules.
-
-#### `src/workflows/scheduled/daily-inventory-sync.ts`
-
-**Purpose**: Automatic Daily inventory sync
-**Trigger**: Cron schedule (`0 2 * * *`)
-**Exposed as Endpoint**: ❌ NO - Runs automatically
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { runIngestion } from '../../services/inventory-sync.service.ts';
-
-/**
- * Scheduled Workflow: Daily Inventory Sync
- *
- * Runs automatically daily at 2 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Uses shared service: inventory-sync.service.ts
- */
-export const daily_inventory_sync = schedule(
-  'inventory-batch-scheduled',
-  '0 2 * * *' // Daily at 2 AM UTC
-).then(
-  http('run-inventory-batch', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, openKv } = ctx;
-    const jobId = `inventory-batch-${Date.now()}`;
-    const tracker = new JobTracker(openKv(':project:'), log);
-
-    await tracker.createJob(jobId, { triggeredBy: 'schedule', stage: 'initialization' });
-    await tracker.updateJob(jobId, { status: 'processing' });
-
-    try {
-      // Reuse shared orchestration logic
-      const result = await runIngestion(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-      return { success: false, jobId, error: e?.message };
-    }
-  })
-);
-```
-
----
-
-### 2. Webhook Workflows (`src/workflows/webhook/`)
-
-All HTTP-based triggers that create webhook endpoints.
-
-#### `src/workflows/webhook/adhoc-inventory-sync.ts`
-
-**Purpose**: Manual inventory sync trigger (on-demand)
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/inventory-batch-adhoc`
-**Use Cases**: Testing, priority processing, ad-hoc runs
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { runIngestion } from '../../services/inventory-sync.service.ts';
-
-/**
- * Webhook: Manual Inventory Sync Trigger
- *
- * Endpoint: POST https://{workspace}.versori.run/inventory-batch-adhoc
- * Request body (optional): { filePattern: "urgent_*.xml", maxFiles: 5 }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: inventory-sync.service.ts
- */
-export const adhoc_inventory_sync = webhook('inventory-batch-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'inventory-batch-adhoc', // Versori validates API key
-}).then(
-  http('run-inventory-batch-adhoc', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, openKv, data } = ctx;
-    const jobId = `inventory-batch-adhoc-${Date.now()}`;
-    const tracker = new JobTracker(openKv(':project:'), log);
-
-    await tracker.createJob(jobId, {
-      triggeredBy: 'manual',
-      stage: 'initialization',
-      options: data // Optional: filePattern, maxFiles, etc.
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-
-    try {
-      // Same orchestration logic as scheduled workflow
-      const result = await runIngestion(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-      return { success: false, jobId, error: e?.message };
-    }
-  })
-);
-```
-
-#### `src/workflows/webhook/job-status-check.ts`
-
-**Purpose**: Query job status
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/inventory-batch-job-status`
-**Request body**: `{ jobId: "inventory-batch-1234567890" }`
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Webhook: Job Status Check
- *
- * Endpoint: POST https://{workspace}.versori.run/inventory-batch-job-status
- * Request body: { jobId: "inventory-batch-1234567890" }
- *
- * Pattern: webhook().then(fn()) - no external API needed, only KV storage
- * Lightweight: Only queries KV store, no Fluent API calls
- */
-export const jobStatusCheck = webhook('inventory-batch-job-status', {
-  response: { mode: 'sync' },
-  connection: 'inventory-batch-job-status',
-}).then(
-  fn('status', async ctx => {
-    const { data, log, openKv } = ctx;
-    const jobId = data?.jobId as string;
-
-    if (!jobId) {
-      return { success: false, error: 'jobId required' };
-    }
-
-    const tracker = new JobTracker(openKv(':project:'), log);
-    const status = await tracker.getJob(jobId);
-
-    return status
-      ? { success: true, jobId, ...status }
-      : { success: false, error: 'Job not found', jobId };
-  })
-);
-```
-
----
-
-### 3. Entry Point (`index.ts`)
-
-**Purpose**: Register all workflows with Versori platform
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/scheduled/ → Time-based triggers (cron)
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- */
-
-// Import scheduled workflows
-import { daily_inventory_sync } from './src/workflows/scheduled/daily-inventory-sync';
-
-// Import webhook workflows
-import { adhoc_inventory_sync } from './src/workflows/webhook/adhoc-inventory-sync';
-import { jobStatusCheck } from './src/workflows/webhook/job-status-check';
-
-// Register all workflows
-export {
-  // Scheduled (time-based triggers)
-  daily_inventory_sync,
-
-  // Webhooks (HTTP-based triggers)
-  adhoc_inventory_sync,
-  jobStatusCheck,
-};
-```
-
-**What Gets Exposed:**
-
-- ✅ `adhoc_inventory_sync` → `https://{workspace}.versori.run/inventory-batch-adhoc`
-- ✅ `jobStatusCheck` → `https://{workspace}.versori.run/inventory-batch-job-status`
-- ❌ `daily_inventory_sync` → NOT exposed (runs automatically on cron)
-
----
-
-### Adding New Workflows
-
-**To add a scheduled workflow:**
-1. Create file in `src/workflows/scheduled/` with descriptive name (e.g., `hourly-delta-sync.ts`)
-2. Export the workflow from the file
-3. Import and re-export in `index.ts`
-
-**To add a webhook workflow:**
-1. Create file in `src/workflows/webhook/` with descriptive name (e.g., `error-notification.ts`)
-2. Export the workflow from the file
-3. Import and re-export in `index.ts`
-
-**Example - Adding hourly delta sync:**
-
-```typescript
-// src/workflows/scheduled/hourly-delta-sync.ts
-export const hourlyDeltaSync = schedule(
-  'inventory-delta-hourly',
-  '0 * * * *' // Every hour
-).then(
-  http('run-delta-sync', { connection: 'fluent_commerce' }, async ctx => {
-    // Delta sync logic (skip BPP)
-    const result = await runIngestion(ctx, jobId, tracker, { bppEnabled: false });
-    return result;
-  })
-);
-
-// index.ts (add to imports and exports)
-import { hourlyDeltaSync } from './src/workflows/scheduled/hourly-delta-sync';
-export { daily_inventory_sync, hourlyDeltaSync, ... };
-```
-
----
-## Complete Modular Implementation
-
-### File: `package.json`
-
-```json
-{
-  "name": "multi-channel-inventory-sync",
-  "version": "1.0.0",
-  "description": "Multi-Channel Inventory Aggregation to Fluent Commerce Batch API",
-  "type": "module",
-  "versori": {
-    "workflows": "./index.ts"
-  },
-  "scripts": {
-    "lint": "eslint . --ext .ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
-```
-
----
-
-### File: `index.ts`
-
-```typescript
-import { schedule, webhook, http, fn } from '@versori/run';
-import { processMultiChannelSync } from './src/workflows/multi-channel-sync.workflow';
-
-/**
- * Scheduled workflow: Multi-channel inventory sync every 15 minutes
- *
- * Processing: Parallel channel fetching with graceful degradation
- * BPP: Disabled (preprocessing: 'skip') - delta detection already filters
- * State Management: VersoriKVAdapter + JobTracker prevent duplicates
- */
-export const scheduledMultiChannelSync = schedule(
-  'multi-channel-sync',
-  '*/15 * * * *' // Every 15 minutes
-).then(
-  http('run-sync', { connection: 'fluent_commerce' }, async ctx => {
-    // ctx contains: fetch, connections, log, activation, openKv
-    // Pass entire context to workflow
-    return await processMultiChannelSync(ctx);
-  })
-);
-
-/**
- * Manual trigger endpoint for testing and ad-hoc runs
- */
-export const adhocMultiChannelSync = webhook('multi-channel-sync-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'multi-channel-sync-adhoc',
-}).then(
-  http('run-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
-    return await processMultiChannelSync(ctx);
-  })
-);
-
-/**
- * Job status check endpoint
- */
-export const multiChannelSyncJobStatus = webhook('multi-channel-sync-job-status', {
-  response: { mode: 'sync' },
-  connection: 'multi-channel-sync-job-status',
-}).then(
-  fn('status', async ctx => {
-    const { data, log, openKv } = ctx;
-    const jobId = data?.jobId as string;
-    if (!jobId) return { success: false, error: 'jobId required' };
-    const { JobTracker } = await import('@fluentcommerce/fc-connect-sdk');
-    const tracker = new JobTracker(openKv(':project:'), log);
-    const status = await tracker.getJob(jobId);
-    return status
-      ? { success: true, jobId, ...status }
-      : { success: false, error: 'Job not found', jobId };
-  })
-);
-```
-
----
-
-### File: `src/types/multi-channel.types.ts`
-
-```typescript
-/**
- * Type definitions for multi-channel inventory sync
- */
-export interface ChannelInventoryRecord {
-  sku: string;
-  location: string;
-  channel: string;
-  onHand: number;
-  reserved: number;
-  buffer: number;
-  lastUpdated?: string;
-}
-
-export interface AggregatedInventory {
-  sku: string;
-  location: string;
-  totalOnHand: number;
-  totalReserved: number;
-  atp: number;
-  channels: {
-    [channel: string]: {
-      allocated: number;
-      buffer: number;
-      max?: number;
-    };
-  };
-}
-
-export interface SyncState {
-  [sku: string]: {
-    [location: string]: number; // ATP value
-  };
-}
-
-export interface SyncStats {
-  totalRecords: number;
-  channelARecords: number;
-  channelBRecords: number;
-  fluentRecords: number;
-  aggregatedSkus: number;
-  changedRecords: number;
-  batchesSent: number;
-  successCount: number;
-  errorCount: number;
-  duration: number;
-}
-
-export interface BatchDetail {
-  batchId: string;
-  recordCount: number;
-  timestamp: string;
-  status: 'SENT' | 'FAILED';
-  error?: string;
-}
-
-export interface BatchResult {
-  totalSent: number;
-  batchCount: number;
-  batches: BatchDetail[];
-  errors: Array<{ batchId: string; error: string }>;
-}
-```
-
----
-
-### File: `src/config/multi-channel.mapping.json`
-
-```json
-{
-  "name": "multi-channel-inventory",
-  "version": "1.0.0",
-  "description": "Normalize channel payloads to aggregation schema",
-  "fields": {
-    "locationRef": {
-      "source": "locationRef",
-      "required": true,
-      "resolver": "sdk.trim",
-      "comment": "Location reference"
-    },
-    "skuRef": {
-      "source": "skuRef",
-      "required": true,
-      "resolver": "sdk.trim",
-      "comment": "SKU reference"
-    },
-    "onHand": {
-      "source": "onHand",
-      "resolver": "sdk.number",
-      "comment": "On-hand quantity"
-    },
-    "reserved": {
-      "source": "reserved",
-      "resolver": "sdk.number",
-      "comment": "Reserved quantity"
-    },
-    "buffer": {
-      "source": "buffer",
-      "resolver": "sdk.number",
-      "comment": "Safety buffer"
-    },
-    "channel": {
-      "source": "channel",
-      "defaultValue": "UNKNOWN",
-      "comment": "Channel identifier"
-    }
-  }
-}
-```
-
-> **✅ PRODUCTION STANDARD:** Use external JSON files for mapping configuration (not TypeScript objects)
-
----
-
-### File: `src/services/atp-calculator.service.ts`
-
-```typescript
-import type { ChannelInventoryRecord, AggregatedInventory } from '../types/multi-channel.types';
-
-/**
- * Service for calculating ATP (Available To Promise) across channels
- */
-export class ATPCalculatorService {
-  private readonly oversellProtection: boolean;
-
-  constructor(
-    oversellProtection = true
-  ) {
-    this.oversellProtection = oversellProtection;
-  }
-
-  /**
-   * Calculate base ATP for a single record
-   * Formula: ATP = (onHand - reserved) - buffer
-   */
-  calculateBaseATP(onHand: number, reserved: number, buffer: number): number {
-    const available = Math.max(0, onHand - reserved);
-    const atp = available - buffer;
-    return this.oversellProtection ? Math.max(0, atp) : atp;
-  }
-
-  /**
-   * Aggregate inventory across channels
-   * Deduplicates by SKU + location and calculates consolidated ATP
-   */
-  aggregateChannelInventory(records: ChannelInventoryRecord[]): Map<string, AggregatedInventory> {
-    const aggregated = new Map<string, AggregatedInventory>();
-
-    for (const record of records) {
-      const key = `${record.sku}:${record.location}`;
-      const existing = aggregated.get(key);
-
-      if (existing) {
-        // Aggregate across channels
-        existing.totalOnHand += record.onHand;
-        existing.totalReserved += record.reserved;
-        existing.channels[record.channel] = {
-          allocated: record.onHand - record.reserved - record.buffer,
-          buffer: record.buffer,
-        };
-      } else {
-        // First record for this SKU+location
-        aggregated.set(key, {
-          sku: record.sku,
-          location: record.location,
-          totalOnHand: record.onHand,
-          totalReserved: record.reserved,
-          atp: 0,
-          channels: {
-            [record.channel]: {
-              allocated: record.onHand - record.reserved - record.buffer,
-              buffer: record.buffer,
-            },
-          },
-        });
-      }
-    }
-
-    // Calculate final ATP for each aggregated record
-    for (const [, agg] of aggregated) {
-      const totalBuffer = Math.max(...Object.values(agg.channels).map(c => c.buffer));
-      agg.atp = this.calculateBaseATP(agg.totalOnHand, agg.totalReserved, totalBuffer);
-    }
-
-
-    return aggregated;
-  }
-}
-```
-
----
-
-### File: `src/services/channel-a-connector.service.ts`
-
-```typescript
-
-/**
- * Service for fetching inventory from Channel A REST API
- * Includes rate limiting and exponential backoff retry logic
- */
-export class ChannelAConnectorService {
-  private readonly url: string;
-  private readonly apiKey: string;
-  private readonly rateLimitRpm: number;
-  private readonly logger; // ✅ Versori native log - TypeScript infers type
-  private lastRequest = 0;
-
-  constructor(url: string, apiKey: string, rateLimitRpm: number, logger) { // ✅ Versori native log - TypeScript infers type
-    this.url = url;
-    this.apiKey = apiKey;
-    this.rateLimitRpm = rateLimitRpm;
-    this.logger = logger;
-  }
-
-  /**
-   * Fetch inventory from Channel A with rate limiting
-   */
-  async fetchInventory(): Promise<any[]> {
-    await this.enforceRateLimit();
-
-    const response = await this.fetchWithRetry(this.url, {
-      method: 'GET',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-    });
-
-    if (!response.ok) {
-      throw new Error(`Channel A API error: ${response.status} ${response.statusText}`);
-    }
-
-    const data = await response.json();
-    return data.inventory || [];
-  }
-
-  /**
-   * Enforce rate limit (minimum interval between requests)
-   */
-  private async enforceRateLimit(): Promise<void> {
-    const minInterval = 60000 / this.rateLimitRpm;
-    const now = Date.now();
-    const elapsed = now - this.lastRequest;
-
-    if (elapsed < minInterval) {
-      const wait = minInterval - elapsed;
-      await new Promise(resolve => setTimeout(resolve, wait));
-    }
-
-    this.lastRequest = Date.now();
-  }
-
-  /**
-   * Fetch with exponential backoff retry
-   */
-  private async fetchWithRetry(
-    url: string,
-    options: RequestInit,
-    maxRetries = 3
-  ): Promise<Response> {
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-      try {
-        const response = await fetch(url, options);
-
-        if (response.status === 429 || response.status >= 500) {
-          if (attempt < maxRetries) {
-            const backoff = Math.pow(2, attempt) * 1000;
-              `[ChannelA] Error ${response.status}, retrying in ${backoff}ms (attempt ${attempt}/${maxRetries})`
-            );
-            await new Promise(resolve => setTimeout(resolve, backoff));
-            continue;
-          }
-        }
-
-        return response;
-      } catch (error) {
-        if (attempt === maxRetries) throw error;
-        const backoff = Math.pow(2, attempt) * 1000;
-          `[ChannelA] Fetch error, retrying in ${backoff}ms (attempt ${attempt}/${maxRetries}):`,
-          error
-        );
-        await new Promise(resolve => setTimeout(resolve, backoff));
-      }
-    }
-
-    throw new Error('Channel A: Max retries exceeded');
-  }
-}
-```
-
----
-
-### File: `src/services/channel-b-connector.service.ts`
-
-```typescript
-import { S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Service for fetching inventory from Channel B S3 CSV
- */
-export class ChannelBConnectorService {
-  private readonly s3: S3DataSource;
-  private readonly csv: CSVParserService;
-  private readonly bucket: string;
-  private readonly key: string;
-  private readonly logger; // ✅ Versori native log - TypeScript infers type
-
-  constructor(s3Config: any, bucket: string, key: string, logger) { // ✅ Versori native log - TypeScript infers type
-    this.s3 = new S3DataSource(s3Config, logger);
-    this.csv = new CSVParserService();
-    this.bucket = bucket;
-    this.key = key;
-  }
-
-  /**
-   * Fetch inventory from S3 CSV file
-   */
-  async fetchInventory(): Promise<any[]> {
-    try {
-      const csvContent = (await this.s3.downloadFile(`${this.bucket}/${this.key}`, {
-        encoding: 'utf8',
-      })) as string;
-
-      const records = await this.csv.parse(csvContent, {
-        columns: true,
-        skip_empty_lines: true,
-        trim: true,
-      });
-
-      return records || [];
-    } catch (error) {
-      throw error;
-    }
-    // Note: S3DataSource doesn't require explicit disposal (unlike SFTP)
-  }
-}
-```
-
----
-
-### File: `src/services/batch-processor.service.ts`
-
-```typescript
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { BatchResult, BatchDetail } from '../types/multi-channel.types';
-
-/**
- * Service for sending records to Fluent Batch API
- *
- * ✅ PRODUCTION ENHANCEMENT: Optional logger for detailed progress tracking
- */
-export class BatchProcessorService {
-  constructor(
-    private client: FluentClient,
-    private jobTracker: JobTracker,
-    private log?: any  // ✅ Optional logger for progress tracking
-  ) {}
-
-  /**
-   * Send inventory records to Batch API with chunking
-   */
-  async sendInventoryBatches(
-    jobId: string,
-    records: any[],
-    batchSize: number = 500
-  ): Promise<BatchResult> {
-    const result: BatchResult = {
-      totalSent: 0,
-      batchCount: 0,
-      batches: [],
-      errors: [],
-    };
-
-    // Chunk records into batches
-    const chunks: any[][] = [];
-    for (let i = 0; i < records.length; i += batchSize) {
-      chunks.push(records.slice(i, i + batchSize));
-    }
-
-    const totalBatches = chunks.length;
-
-    // ✅ PRODUCTION ENHANCEMENT: Log batch sending start
-    if (this.log) {
-      this.log.info('📤 Starting batch sending', {
-        jobId,
-        totalRecords: records.length,
-        batchSize,
-        totalBatches,
-        processingMode: 'sequential (one at a time)',
-      });
-    }
-
-    // Send each batch
-    for (let i = 0; i < chunks.length; i++) {
-      const batchNumber = i + 1;
-
-      // ✅ PRODUCTION ENHANCEMENT: Log progress every 10 batches
-      if (this.log && batchNumber % 10 === 0) {
-        this.log.info(`📤 Sending batch ${batchNumber}/${totalBatches}`, {
-          jobId,
-          batchNumber,
-          totalBatches,
-          recordsInBatch: chunks[i].length,
-          totalSentSoFar: result.totalSent,
-          progress: `${((batchNumber / totalBatches) * 100).toFixed(1)}%`,
-        });
-      }
-
-      try {
-        const batch = await this.client.sendBatch(jobId, {
-          action: 'UPSERT',
-          entityType: 'INVENTORY',
-          source: 'MULTI_CHANNEL',
-          event: 'MULTI_CHANNEL_SYNC',
-          entities: chunks[i],
-        });
-
-        result.totalSent += chunks[i].length;
-        result.batchCount++;
-        result.batches.push({
-          batchId: batch.id,
-          recordCount: chunks[i].length,
-          timestamp: new Date().toISOString(),
-          status: 'SENT',
-        });
-
-        // ✅ No logging here - workflow handles it
-
-        // Update job tracker
-        await this.jobTracker.updateJob(jobId, {
-          details: {
-            batchesSent: result.batchCount,
-            recordsProcessed: result.totalSent,
-          },
-        });
-      } catch (error: any) {
-        result.errors.push({
-          batchId: `batch-${batchNumber}`,
-          error: error.message,
-        });
-        result.batches.push({
-          batchId: `batch-${batchNumber}`,
-          recordCount: chunks[i].length,
-          timestamp: new Date().toISOString(),
-          status: 'FAILED',
-          error: error.message,
-        });
-      }
-    }
-
-    // ✅ PRODUCTION ENHANCEMENT: Log completion
-    if (this.log) {
-      this.log.info('✅ Sequential batch sending completed', {
-        jobId,
-        totalBatches,
-        batchesSent: result.batchCount,
-        batchesFailed: result.errors.length,
-        totalRecordsSent: result.totalSent,
-      });
-    }
-
-    return result;
-  }
-}
-```
-
----
-
-### File: `src/services/batch-logger.service.ts`
-
-```typescript
-import { Buffer } from 'node:buffer';
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Service for writing batch processing logs to S3
- */
-export class BatchLoggerService {
-  constructor(private s3: S3DataSource) {
-    // ✅ No logger - workflow handles logging with Versori native log
-  }
-
-  /**
-   * Write batch processing log to S3
-   */
-  async writeBatchLog(
-    logData: any,
-    bucket: string,
-    keyPrefix: string,
-    format: 'json' | 'text' = 'json'
-  ): Promise<void> {
-    try {
-      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-      const logFileName = `${keyPrefix}${timestamp}.${format === 'json' ? 'json' : 'log'}`;
-      const logKey = `${bucket}/${logFileName}`;
-
-      const logContent = this.formatLogContent(logData, format);
-
-      await this.s3.uploadFile(logKey, Buffer.from(logContent, 'utf8'), {
-        encoding: 'utf8',
-        contentType: format === 'json' ? 'application/json' : 'text/plain',
-      });
-
-      // ✅ No logging here - workflow handles it
-    } catch (error: any) {
-      // ✅ No logging here - workflow handles it
-      // Don't throw - logging failure shouldn't stop workflow
-    }
-  }
-
-  private formatLogContent(logData: any, format: 'json' | 'text'): string {
-    if (format === 'json') {
-      return JSON.stringify(logData, null, 2);
-    }
-
-    return `Multi-Channel Sync Log
-======================
-Timestamp: ${logData.timestamp}
-Job ID: ${logData.jobId}
-
-Channel Summary:
-  Channel A: ${logData.channels.channelA || 0} records
-  Channel B: ${logData.channels.channelB || 0} records
-  Fluent: ${logData.channels.fluent || 0} records
-
-Aggregation:
-  Total Records: ${logData.aggregated}
-  Changed Records: ${logData.changed}
-  Unchanged: ${logData.unchanged}
-
-Batches:
-${logData.batches
-  .map(
-    (b: any, i: number) =>
-      `  [${i + 1}] ${b.batchId} | ${b.recordCount} records | ${b.status}${b.error ? ` | Error: ${b.error}` : ''}`
-  )
-  .join('\n')}
-
-Summary:
-  Total Batches: ${logData.summary.totalBatches}
-  Successful: ${logData.summary.success}
-  Failed: ${logData.summary.failed}
-  Duration: ${logData.summary.duration}ms
-
-Status: ${logData.status}
-`;
-  }
-}
-```
-
----
-
-### File: `src/workflows/multi-channel-sync.workflow.ts`
-
-```typescript
-import { Buffer } from 'node:buffer';
-import {
-  createClient,
-  StateService,
-  VersoriKVAdapter,
-  JobTracker,
-} from '@fluentcommerce/fc-connect-sdk';
-import type { ChannelInventoryRecord, SyncStats } from '../types/multi-channel.types';
-import { ATPCalculatorService } from '../services/atp-calculator.service';
-import { ChannelAConnectorService } from '../services/channel-a-connector.service';
-import { ChannelBConnectorService } from '../services/channel-b-connector.service';
-import { BatchProcessorService } from '../services/batch-processor.service';
-import { BatchLoggerService } from '../services/batch-logger.service';
-
-const INVENTORY_QUERY = `
-  query GetInventory($retailerId: ID!, $first: Int!, $after: String) {
-    inventoryPositions(retailerId: $retailerId, first: $first, after: $after) {
-      edges {
-        node {
-          id
-          ref
-          productRef
-          locationRef
-          onHand
-          reservedQuantity
-          status
-          type
-        }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-        endCursor
-      }
-    }
-  }
-`;
-
-/**
- * Fetch current inventory state from Fluent GraphQL
- */
-async function fetchFluentInventory(
-  client: any,
-  retailerId: string,
-  pageSize: number,
-  maxRecords: number,
-  log: any
-): Promise<any[]> {
-  try {
-    const result = await client.graphql({
-      query: INVENTORY_QUERY,
-      variables: { retailerId, first: pageSize },
-      pagination: { maxRecords },
-    });
-
-    const edges = result.data?.inventoryPositions?.edges || [];
-    const records = edges.map((e: any) => ({
-      productRef: e.node.productRef,
-      locationRef: e.node.locationRef,
-      onHand: Number(e.node.onHand || 0),
-      reserved: Number(e.node.reservedQuantity || 0),
-    }));
-
-    log.info(`[Fluent] Fetched ${records.length} records from GraphQL`);
-    return records;
-  } catch (error) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorDetails = {
-      message: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-    };
-    log.error('[Fluent] GraphQL fetch error:', errorDetails);
-    throw error;
-  }
-}
-
-/**
- * Main multi-channel sync workflow orchestrator
- * Coordinates channel fetching, aggregation, delta detection, and batch submission
- *
- * @param ctx - Versori context object containing fetch, connections, log, activation, openKv
- */
-export async function processMultiChannelSync(ctx: any) {
-  const { log, openKv, activation } = ctx;
-  const startTime = Date.now();
-
-  log.info('[MultiChannelSync] Starting sync workflow');
-
-  try {
-    // ========================================
-    // CLIENT INITIALIZATION
-    // ========================================
-    const client = await createClient(ctx);
-
-    // ========================================
-    // CONFIGURATION
-    // ========================================
-    const config = {
-      retailerId: activation?.getVariable('retailerId'),
-      jobName: activation?.getVariable('jobName') || 'Multi-Channel Inventory Sync',
-      batchSize: parseInt(activation?.getVariable('batchSize') || '500', 10),
-      maxRecords: parseInt(activation?.getVariable('maxRecords') || '50000', 10),
-      defaultBuffer: parseInt(activation?.getVariable('defaultBuffer') || '5', 10),
-      oversellProtection: activation?.getVariable('oversellProtection') !== 'false',
-      useBpp: activation?.getVariable('useBpp') || 'skip',
-      enableDelta: activation?.getVariable('enableDelta') !== 'false',
-      deltaStateKey: activation?.getVariable('deltaStateKey') || 'sync:delta:state',
-      channelAEnabled: activation?.getVariable('channelAEnabled') === 'true',
-      channelAUrl: activation?.getVariable('channelAUrl'),
-      channelAKey: activation?.getVariable('channelAKey'),
-      channelABuffer: parseInt(activation?.getVariable('channelABuffer') || '5', 10),
-      channelARateLimitRpm: parseInt(activation?.getVariable('channelARateLimitRpm') || '120', 10),
-      channelBEnabled: activation?.getVariable('channelBEnabled') === 'true',
-      channelBBucket: activation?.getVariable('channelBBucket'),
-      channelBKey: activation?.getVariable('channelBKey'),
-      fluentEnabled: activation?.getVariable('fluentEnabled') === 'true',
-      fluentPageSize: parseInt(activation?.getVariable('fluentPageSize') || '200', 10),
-    };
-
-    // ========================================
-    // SERVICE INITIALIZATION
-    // ========================================
-    const kv = new VersoriKVAdapter(openKv(':project:'));
-    const jobTracker = new JobTracker(openKv(':project:'), log);
-    const stateService = new StateService(log);
-
-    const atpCalc = new ATPCalculatorService(config.oversellProtection);
-    // ✅ PRODUCTION ENHANCEMENT: Pass log to BatchProcessorService for detailed progress tracking
-    const batchProcessor = new BatchProcessorService(client, jobTracker, log);
-
-    const jobId = `multi-channel-sync-${Date.now()}`;
-    await jobTracker.createJob(jobId, {
-      triggeredBy: 'schedule',
-      stage: 'initialization',
-      details: { config },
-    });
-
-    const stats: SyncStats = {
-      totalRecords: 0,
-      channelARecords: 0,
-      channelBRecords: 0,
-      fluentRecords: 0,
-      aggregatedSkus: 0,
-      changedRecords: 0,
-      batchesSent: 0,
-      successCount: 0,
-      errorCount: 0,
-      duration: 0,
-    };
-
-    await jobTracker.updateJob(jobId, { status: 'fetching_channels' });
-
-    // ========================================
-    // CHANNEL FETCHING (PARALLEL WITH GRACEFUL DEGRADATION)
-    // ========================================
-    const allRecords: ChannelInventoryRecord[] = [];
-
-    // Fetch Channel A (REST API)
-    if (config.channelAEnabled && config.channelAUrl && config.channelAKey) {
-      log.info('[MultiChannelSync] Fetching from Channel A...');
-      const channelA = new ChannelAConnectorService(
-        config.channelAUrl,
-        config.channelAKey,
-        config.channelARateLimitRpm,
-        log
-      );
-
-      try {
-        const records = await channelA.fetchInventory();
-        const mapped = records.map(r => ({
-          sku: r.product_id,
-          location: r.warehouse_code,
-          channel: 'A',
-          onHand: r.quantity_available,
-          reserved: r.quantity_reserved,
-          buffer: config.channelABuffer,
-          lastUpdated: r.updated_at,
-        }));
-
-        allRecords.push(...mapped);
-        stats.channelARecords = mapped.length;
-        log.info(`[MultiChannelSync] Channel A: ${mapped.length} records`);
-      } catch (error) {
-        // ✅ Enhanced error logging: Extract all error details for visibility
-        const errorDetails = {
-          message: error instanceof Error ? error.message : String(error),
-          stack: error instanceof Error ? error.stack : undefined,
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-        };
-        log.error('[MultiChannelSync] Channel A fetch failed (continuing):', errorDetails);
-        stats.errorCount++;
-      }
-    }
-
-    // Fetch Channel B (S3 CSV)
-    if (config.channelBEnabled && config.channelBBucket && config.channelBKey) {
-      log.info('[MultiChannelSync] Fetching from Channel B...');
-      const s3Config = {
-        type: 'S3_CSV',
-        connectionId: 'channel-b-s3',
-        name: 'Channel B S3',
-        s3Config: {
-          bucket: config.channelBBucket,
-          region: activation?.getVariable('awsRegion') || 'us-east-1',
-          accessKeyId: activation?.getVariable('awsAccessKeyId'),
-          secretAccessKey: activation?.getVariable('awsSecretAccessKey'),
-        },
-      };
-
-      const channelB = new ChannelBConnectorService(
-        s3Config,
-        config.channelBBucket,
-        config.channelBKey,
-        log
-      );
-
-      try {
-        const records = await channelB.fetchInventory();
-        const mapped = records.map((r: any) => ({
-          sku: r.sku,
-          location: r.location,
-          channel: 'B',
-          onHand: parseInt(r.qty, 10),
-          reserved: parseInt(r.reserved, 10),
-          buffer: config.defaultBuffer,
-        }));
-
-        allRecords.push(...mapped);
-        stats.channelBRecords = mapped.length;
-        log.info(`[MultiChannelSync] Channel B: ${mapped.length} records`);
-      } catch (error) {
-        // ✅ Enhanced error logging: Extract all error details for visibility
-        const errorDetails = {
-          message: error instanceof Error ? error.message : String(error),
-          stack: error instanceof Error ? error.stack : undefined,
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-        };
-        log.error('[MultiChannelSync] Channel B fetch failed (continuing):', errorDetails);
-        stats.errorCount++;
-      }
-    }
-
-    // Fetch Fluent GraphQL (current state)
-    if (config.fluentEnabled) {
-      log.info('[MultiChannelSync] Fetching from Fluent GraphQL...');
-      try {
-        const records = await fetchFluentInventory(
-          client,
-          config.retailerId!,
-          config.fluentPageSize,
-          config.maxRecords,
-          log
-        );
-
-        const mapped = records.map(r => ({
-          sku: r.productRef,
-          location: r.locationRef,
-          channel: 'FLUENT',
-          onHand: r.onHand,
-          reserved: r.reserved,
-          buffer: 0,
-        }));
-
-        allRecords.push(...mapped);
-        stats.fluentRecords = mapped.length;
-        log.info(`[MultiChannelSync] Fluent: ${mapped.length} records`);
-      } catch (error) {
-        // ✅ Enhanced error logging: Extract all error details for visibility
-        const errorDetails = {
-          message: error instanceof Error ? error.message : String(error),
-          stack: error instanceof Error ? error.stack : undefined,
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-        };
-        log.error('[MultiChannelSync] Fluent fetch failed (continuing):', errorDetails);
-        stats.errorCount++;
-      }
-    }
-
-    stats.totalRecords = allRecords.length;
-
-    if (allRecords.length === 0) {
-      log.warn('[MultiChannelSync] No inventory records fetched from any channel');
-      await jobTracker.markCompleted(jobId, { message: 'No data', stats });
-      return { success: false, message: 'No data', stats };
-    }
-
-    // ========================================
-    // AGGREGATION
-    // ========================================
-    await jobTracker.updateJob(jobId, { status: 'aggregating' });
-
-    log.info('[MultiChannelSync] Aggregating inventory across channels...');
-    const aggregated = atpCalc.aggregateChannelInventory(allRecords);
-    stats.aggregatedSkus = aggregated.size;
-
-    const finalInventory = Array.from(aggregated.values()).map(agg => ({
-      skuRef: agg.sku,
-      locationRef: agg.location,
-      qty: agg.atp,
-      type: 'AVAILABLE',
-      status: 'ACTIVE',
-      expectedOn: new Date().toISOString().split('T')[0],
-    }));
-
-    log.info(`[MultiChannelSync] Aggregated ${stats.aggregatedSkus} unique SKU/location combinations`);
-
-    // ========================================
-    // DELTA DETECTION
-    // ========================================
-    let recordsToSend = finalInventory;
-
-    if (config.enableDelta) {
-      await jobTracker.updateJob(jobId, { status: 'delta_detection' });
-      log.info('[MultiChannelSync] Checking for changes (delta detection)...');
-
-      const prevState = ((await stateService.getState(config.deltaStateKey)) as any) || {};
-      const changedRecords = [];
-
-      for (const record of finalInventory) {
-        const prevQty = prevState[record.skuRef]?.[record.locationRef];
-        if (prevQty === undefined || prevQty !== record.qty) {
-          changedRecords.push(record);
-        }
-      }
-
-      recordsToSend = changedRecords;
-      stats.changedRecords = changedRecords.length;
-      log.info(
-        `[MultiChannelSync] Delta detection: ${changedRecords.length} changed records (${finalInventory.length} total)`
-      );
-    } else {
-      stats.changedRecords = finalInventory.length;
-    }
-
-    if (recordsToSend.length === 0) {
-      log.info('[MultiChannelSync] No changes detected, skipping batch send');
-      stats.duration = Date.now() - startTime;
-      await jobTracker.markCompleted(jobId, { message: 'No changes', stats });
-      return { success: true, message: 'No changes', stats };
-    }
-
-    // ========================================
-    // BATCH API SUBMISSION
-    // ========================================
-    await jobTracker.updateJob(jobId, { status: 'creating_batch_job' });
-
-    log.info('[MultiChannelSync] Creating Batch API job...');
-    const job = await client.createJob({
-      name: config.jobName,
-      retailerId: config.retailerId!,
-      meta: {
-        preprocessing: config.useBpp,
-      },
-    });
-
-    log.info(`[MultiChannelSync] Job created: ${job.id}`);
-
-    await jobTracker.updateJob(jobId, { status: 'sending_batches' });
-
-    // ? Enhanced: Extract context for progress logging
-    const uniqueLocations = [...new Set(recordsToSend.map((r: any) => r.locationRef))];
-    const sampleSKUs = recordsToSend.slice(0, 5).map((r: any) => r.skuRef);
-    const estimatedBatches = Math.ceil(recordsToSend.length / config.batchSize);
-
-    // ? Enhanced: Start logging with context
-    log.info(`[BatchProcessor] Sending batches for multi-channel sync`, {
-      totalRecords: recordsToSend.length,
-      estimatedBatches,
-      batchSize: config.batchSize,
-      locations: uniqueLocations.join(', '),
-      sampleSKUs: sampleSKUs.join(', '),
-      jobId: job.id
-    });
-
-    const batchResults = await batchProcessor.sendInventoryBatches(
-      job.id,
-      recordsToSend,
-      config.batchSize
-    );
-
-    // ✅ Logging handled in workflow with Versori native log
-    log.info(`[BatchProcessor] Sent ${batchResults.batchCount} batches`, {
-      jobId: job.id,
-      totalRecords: batchResults.totalSent,
-      successfulBatches: batchResults.batches.filter(b => b.status === 'SENT').length,
-      failedBatches: batchResults.batches.filter(b => b.status === 'FAILED').length,
-    });
-
-    // ? Enhanced: Completion logging with summary
-    log.info(`[BatchProcessor] Batch submission completed for multi-channel sync`, {
-      totalBatches: batchResults.batchCount,
-      totalRecords: batchResults.totalSent,
-      successfulBatches: batchResults.batches.filter(b => b.status === 'SENT').length,
-      failedBatches: batchResults.errors.length,
-      jobId: job.id
-    });
-
-    if (batchResults.errors.length > 0) {
-      log.warn(`[BatchProcessor] ${batchResults.errors.length} batches failed`, {
-        jobId: job.id,
-        errors: batchResults.errors.slice(0, 5), // Log first 5 errors
-      });
-    }
-
-    stats.batchesSent = batchResults.batchCount;
-    stats.successCount = batchResults.batches.filter(b => b.status === 'SENT').length;
-    stats.errorCount = batchResults.errors.length;
-
-    // ========================================
-    // DELTA STATE UPDATE
-    // ========================================
-    if (config.enableDelta) {
-      await jobTracker.updateJob(jobId, { status: 'updating_delta_state' });
-      log.info('[MultiChannelSync] Updating delta state...');
-
-      const newState: any = {};
-      for (const record of finalInventory) {
-        if (!newState[record.skuRef]) {
-          newState[record.skuRef] = {};
-        }
-        newState[record.skuRef][record.locationRef] = record.qty;
-      }
-
-      await stateService.setState(config.deltaStateKey, newState, {
-        ttlSeconds: 7 * 24 * 60 * 60, // 7 days
-      });
-
-      log.info('[MultiChannelSync] Delta state updated');
-    }
-
-    stats.duration = Date.now() - startTime;
-
-    log.info('[MultiChannelSync] Sync completed', { stats });
-
-    await jobTracker.markCompleted(jobId, {
-      stats,
-      jobId: job.id,
-    });
-
-    return {
-      success: stats.errorCount === 0,
-      jobId: job.id,
-      stats,
-    };
-  } catch (error: any) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorDetails = {
-      message: error?.message || 'Unknown error',
-      stack: error?.stack,
-      fileName: error?.fileName,
-      lineNumber: error?.lineNumber,
-      originalError: error?.context?.originalError?.message,
-      errorType: error?.name || 'Error',
-    };
-    log.error('[MultiChannelSync] Fatal error:', errorDetails);
-    return { success: false, error: error.message, duration: Date.now() - startTime };
-  }
-}
-```
-
----
-
-## Versori Activation Variables
-
-```bash
-# Required Variables
-retailerId=your-retailer-id
-
-# Sync Configuration
-jobName=Multi-Channel Inventory Sync
-batchSize=500
-maxRecords=50000
-defaultBuffer=5
-oversellProtection=true
-useBpp=skip
-
-# Delta Detection
-enableDelta=true
-deltaStateKey=sync:delta:state
-
-# Channel A (REST API)
-channelAEnabled=true
-channelAUrl=https://api.channel-a.example.com/inventory
-channelAKey=your-api-key
-channelABuffer=5
-channelARateLimitRpm=120
-
-# Channel B (S3 CSV)
-channelBEnabled=true
-channelBBucket=channel-b-inventory
-channelBKey=inventory/current.csv
-
-# AWS Credentials (for Channel B S3)
-awsRegion=us-east-1
-awsAccessKeyId=AKIAXXXXXXXXXXXX
-awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-
-# Fluent GraphQL (current state comparison)
-fluentEnabled=true
-fluentPageSize=200
-```
-
----
-
-## Sample Channel Data
-
-### Channel A (REST API Response)
-
-```json
-{
-  "inventory": [
-    {
-      "product_id": "SKU-12345",
-      "warehouse_code": "LOC001",
-      "quantity_available": 100,
-      "quantity_reserved": 20,
-      "updated_at": "2025-01-25T10:00:00Z"
-    }
-  ]
-}
-```
-
-### Channel B (S3 CSV)
-
-```csv
-sku,location,qty,reserved
-SKU-12345,LOC001,95,15
-SKU-67890,LOC002,75,5
-SKU-11111,LOC001,200,0
-```
-
-### ATP Calculation Example
-
-```typescript
-// Channel A: SKU-12345 at LOC001
-onHand = 100
-reserved = 20
-buffer = 5
-ATP = (100 - 20) - 5 = 75
-
-// Channel B: SKU-12345 at LOC001
-onHand = 95
-reserved = 15
-buffer = 5
-ATP = (95 - 15) - 5 = 75
-
-// Aggregated: SKU-12345 at LOC001
-totalOnHand = 100 + 95 = 195
-totalReserved = 20 + 15 = 35
-maxBuffer = max(5, 5) = 5
-finalATP = (195 - 35) - 5 = 155
-```
-
----
-
-## Deployment
-
-```bash
-# Install dependencies
-npm install
-
-# Validate configuration
-npm run lint
-
-# Deploy to Versori
-versori deploy
-
-# View logs
-versori logs multi-channel-inventory-sync
-
-# Trigger manual sync
-versori run adhocMultiChannelSync
-```
-
----
-
-## Testing
-
-### Test Scheduled Sync
-
-Upload test CSV files to S3/SFTP for each channel and wait for the scheduled run.
-
-**Check logs:**
-
-```
-[STEP 1/8] Initializing job tracking
-[STEP 2/8] Initializing Fluent Commerce client and data sources
-[STEP 3/8] Discovering files across channels
-[CHANNEL 1/3] Processing channel: CHANNEL_A
-[FILE 1/1] Processing file: channel-a-inventory_20250124.csv
-[STEP 4/8] Downloading and parsing: channel-a-inventory_20250124.csv
-[STEP 5/8] Transforming 5000 inventory records from channel-a-inventory_20250124.csv
-[STEP 6/8] Creating batch job and sending 5 batches to Fluent Commerce
-[STEP 7/8] Archiving file: channel-a-inventory_20250124.csv
-[STEP 8/8] Completing job and calculating totals
-```
-
-### Test Ad hoc Sync
-
-```bash
-# Sync all channels
-curl -X POST https://api.versori.com/webhooks/multi-channel-sync-adhoc \
-  -H "Content-Type: application/json" \
-  -d '{}'
-
-# Sync specific channel
-curl -X POST https://api.versori.com/webhooks/multi-channel-sync-adhoc \
-  -H "Content-Type: application/json" \
-  -d '{
-    "channelId": "CHANNEL_A"
-  }'
-
-# Sync with specific pattern
-curl -X POST https://api.versori.com/webhooks/multi-channel-sync-adhoc \
-  -H "Content-Type: application/json" \
-  -d '{
-    "filePattern": "urgent_*.csv",
-    "channelId": "CHANNEL_B"
-  }'
-```
-
-### Test Job Status Query
-
-```bash
-curl -X POST https://api.versori.com/webhooks/multi-channel-sync-job-status \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jobId": "ADHOC_MULTI_20251024_183045_abc123"
-  }'
-```
-
-### Verify Batch Jobs in Fluent
-
-After processing, check the Batch job status for each channel in Fluent Commerce:
-
-```bash
-# Query job status via GraphQL
-curl -X POST https://your-fluent-instance.com/graphql \
-  -H "Authorization: Bearer YOUR_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "query { job(id: \"job-123456\") { id status recordCount processedCount } }"
-  }'
-```
-
----
-
-## Monitoring
-
-### Success Response
-
-```json
-{
-  "success": true,
-  "channelsProcessed": 3,
-  "channelsFailed": 0,
-  "filesProcessed": 3,
-  "filesSkipped": 0,
-  "filesFailed": 0,
-  "results": [
-    {
-      "channel": "CHANNEL_A",
-      "file": "channel-a-inventory_2025-01-22.csv",
-      "success": true,
-      "recordCount": 5000,
-      "batchCount": 5,
-      "jobId": "job-123456",
-      "duration": 12345
-    },
-    {
-      "channel": "CHANNEL_B",
-      "file": "channel-b-inventory_2025-01-22.csv",
-      "success": true,
-      "recordCount": 3000,
-      "batchCount": 3,
-      "jobId": "job-123457",
-      "duration": 9876
-    },
-    {
-      "channel": "CHANNEL_C",
-      "file": "channel-c-inventory_2025-01-22.csv",
-      "success": true,
-      "recordCount": 2000,
-      "batchCount": 2,
-      "jobId": "job-123458",
-      "duration": 8765
-    }
-  ],
-  "duration": 13456
-}
-```
-
-### Partial Success Response
-
-```json
-{
-  "success": true,
-  "channelsProcessed": 2,
-  "channelsFailed": 1,
-  "filesProcessed": 2,
-  "filesSkipped": 0,
-  "filesFailed": 1,
-  "results": [
-    {
-      "channel": "CHANNEL_A",
-      "file": "channel-a-inventory_2025-01-22.csv",
-      "success": true,
-      "recordCount": 5000,
-      "batchCount": 5,
-      "jobId": "job-123456",
-      "duration": 12345
-    },
-    {
-      "channel": "CHANNEL_B",
-      "file": "channel-b-inventory_2025-01-22.csv",
-      "success": false,
-      "error": "CSV parse error: Invalid structure"
-    }
-  ],
-  "duration": 13456
-}
-```
-
-### Error Response
-
-```json
-{
-  "success": false,
-  "channelsProcessed": 0,
-  "channelsFailed": 3,
-  "filesProcessed": 0,
-  "filesFailed": 3,
-  "results": [
-    {
-      "channel": "CHANNEL_A",
-      "file": "channel-a-inventory_2025-01-22.csv",
-      "success": false,
-      "error": "Data source connection failed"
-    }
-  ],
-  "duration": 876
-}
-```
-
-### Monitoring Metrics
-
-Monitor these metrics via Versori logs filtered by `jobId` or `stage`:
-
-- **Channels Processed** - Total channels successfully processed
-- **Files Processed** - Total files successfully processed across all channels
-- **Batch Jobs Created** - Total Batch jobs created in Fluent Commerce (one per channel)
-- **Processing Duration** - Time taken for complete multi-channel sync
-- **Channel Failures** - Channels that failed (check individual channel errors)
-
-Use the status webhook for dashboards and automated monitoring.
-
----
-
-- 🎯 **TRUE modular architecture** - Separate service files with clear responsibilities
-- 🎯 **Graceful degradation** - Use `Promise.allSettled()` for partial channel failures
-- 🎯 **Delta detection** - Only sync changed records (reduces API load by 90%+)
-- 🎯 **External JSON mapping** - Use `with { type: 'json' }` import syntax
-- 🎯 **ATP calculation** - `ATP = (onHand - reserved) - buffer` with oversell protection
-- 🎯 **Rate limiting** - Enforce minimum interval between Channel A requests
-- 🎯 **Skip BPP** - Set `preprocessing: 'skip'` when using delta detection
-- 🎯 **Job tracking** - Use `JobTracker` for lifecycle management
-- 🎯 **Native logging** - Use `log` from context on Versori platform
-- 🎯 **EntityType: INVENTORY** - Correct entity type for inventory records
-- 🎯 **Error handling** - Log channel failures but don't block entire sync
-
----
-
-## Related Documentation
-
-- **Single-source batch ingestion**: [SFTP XML Inventory Batch Template](./template-ingestion-sftp-xml-inventory-batch.md) - Simpler pattern for single data sources (GOLD STANDARD)
-- [Batch API Guide](../../../../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-06-batch-api.md) - Complete Batch API patterns and BPP documentation
-- [State Management](../../../../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md) - VersoriKVAdapter and StateService usage
-- [Job Tracker](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-job-tracker.md) - Job lifecycle tracking
-- [Universal Mapping](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) - Field transformation guide
-- [Error Handling Patterns](../../../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Retry logic and exponential backoff
-- [File Operations](../../../../../03-PATTERN-GUIDES/file-operations/file-operations-readme.md) - KV state management patterns
-- [GraphQL Extraction](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) - Auto-pagination for Fluent inventory queries
-
----
-
-[→ Back to Versori Scheduled Workflows](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) | [Versori Platform Guide →](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+---
+template_id: tpl-ingest-multi-channel-inventory-sync
+canonical_filename: template-ingestion-multi-channel-inventory-sync.md
+sdk_version: latest
+runtime: versori
+direction: ingestion
+source: multi-channel-rest-s3
+destination: fluent-batch-api
+entity: inventory
+format: json-csv
+logging: versori
+status: stable
+---
+
+# Template: Ingestion - Multi-Channel Inventory Sync (Scheduled)
+
+## STEP 1: Understand This Template
+
+**What This Template Does:**
+
+- Scheduled Versori workflow for multi-channel inventory aggregation and sync
+- Fetches inventory from multiple sources in parallel (REST API, S3 CSV, Fluent GraphQL)
+- Calculates channel-specific ATP (Available To Promise) with configurable buffers and caps
+- Performs delta detection using VersoriKVAdapter to sync only changed inventory records
+- Handles partial channel failures gracefully with Promise.allSettled
+- Rate-limits external REST API calls with exponential backoff retry logic
+- Sends consolidated inventory updates to Fluent Commerce Batch API with chunking
+- Tracks job lifecycle with JobTracker for operational monitoring
+- Supports scheduled (cron) and ad-hoc (webhook) triggers
+
+**Key SDK Components:**
+
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `S3DataSource` - S3 file operations with retry logic
+- `CSVParserService` - CSV parsing with validation
+- `UniversalMapper` - Field transformation with SDK resolvers
+- `StateService` + `VersoriKVAdapter` - Delta detection state management
+- `JobTracker` - Job lifecycle tracking - `FluentClient.createJob()` - Create Batch API job
+- `FluentClient.sendBatch()` - Send inventory chunks (fire-and-forget)
+- `FluentClient.graphql()` - Query current Fluent inventory state with auto-pagination
+- Native Versori `log` - Use `log` from context 
+**Entity Type:**
+
+- **InventoryQuantity** - Fluent entity for inventory positions and quantities
+- **EntityType: 'INVENTORY'** - Used in Batch API `sendBatch()` call
+- **Batch API Method** - Uses `createJob()` and `sendBatch()` (not Event API)
+
+**Critical Patterns:**
+
+- **Multi-source aggregation**: Use `Promise.allSettled()` for parallel channel fetching
+- **Graceful degradation**: Continue processing even if one channel fails
+- **Delta detection**: StateService tracks previous state to detect changes
+- **Progress Logging**: Enhanced logging with context (sample SKUs, locations)
+- **JobTracker Progress Updates**: Periodic progress updates during batch processing
+- **ATP calculation**: `ATP = (onHand - reserved) - buffer` with oversell protection
+- **Delta detection**: Use `StateService` + `VersoriKVAdapter` to track previous ATP values
+- **Rate limiting**: Enforce minimum interval between channel API requests
+- **Safe configuration**: External JSON mapping file (not inline TypeScript)
+- **BPP Configuration**: Use `'skip'` (delta detection already filters changes)
+- **Fire-and-forget batches**: Batch submission is asynchronous (no polling needed)
+
+**When to Use This Template:**
+
+- ✅ Multiple inventory sources (3+ channels) requiring aggregation
+- ✅ Channel-specific ATP calculations with buffers and caps
+- ✅ Delta detection needed (only sync changed records)
+- ✅ Partial channel failures shouldn't block entire sync
+- ✅ External APIs require rate limiting and retry logic
+- ✅ Scheduled batch processing (every 15 minutes, hourly, etc.)
+
+**When NOT to Use:**
+
+- ❌ Single inventory source (use simpler single-source templates)
+- ❌ Real-time sync required (this is designed for scheduled batch processing)
+- ❌ No ATP calculations needed (use direct field mapping)
+- ❌ Don't need delta detection (full snapshots every time)
+- ❌ Products, Locations, Customers (use Event API templates)
+
+---
+
+## STEP 2: AI Prompt
+
+**Copy this prompt to generate the complete implementation:**
+
+```
+Create a Versori scheduled workflow for multi-channel inventory aggregation to Fluent Commerce Batch API.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (scheduled workflow)
+2. Sources: Multiple channels (REST API, S3 CSV, Fluent GraphQL)
+3. Destination: Fluent Commerce Batch API (InventoryQuantity entity)
+4. Entity: InventoryQuantity (EntityType: 'INVENTORY')
+
+KEY FEATURES:
+1. **Multi-channel fetching** (parallel):
+   - **Channel A**: REST API with rate limiting (120 RPM) and retry logic
+   - **Channel B**: S3 CSV file with CSVParserService
+   - **Fluent GraphQL**: Current inventory state via auto-pagination
+2. **ATP (Available To Promise) calculation**:
+   - Formula: `ATP = (onHand - reserved) - buffer`
+   - Channel-specific buffers (configurable per channel)
+   - Aggregate ATP across channels with deduplication by SKU + location
+   - Support oversell protection (ensure ATP ≥ 0)
+3. **Delta detection**:
+   - Use `StateService` + `VersoriKVAdapter` to track previous ATP values
+   - Only send changed records to Batch API
+   - Store state with 7-day TTL in Versori KV
+4. **Graceful degradation**:
+   - Use `Promise.allSettled()` for channel fetching
+   - Continue processing even if one channel fails
+   - Log channel failures but don't block entire sync
+5. **Batch API**:
+   - Entity: `InventoryQuantity`
+   - EntityType: `'INVENTORY'`
+   - Action: `'UPSERT'`
+   - BPP: `'skip'` (delta detection already filters)
+   - Batch size: 500 records per chunk
+   - Poll batches until complete with exponential backoff
+6. **Job tracking**:
+   - Use `JobTracker` with Versori KV storage
+   - Track status transitions: `fetching_channels` → `aggregating` → `delta_detection` → `creating_batch_job` → `sending_batches` → `polling_batches` → `updating_delta_state`
+7. **Modular architecture**:
+   - Separate service files (ATP calculator, channel connectors, batch dispatcher)
+   - External JSON mapping config
+   - Clean separation of concerns
+
+CRITICAL REQUIREMENTS:
+1. Modular architecture: Separate service files (ATP calculator, channel connectors, batch dispatcher)
+2. External JSON mapping config: Use `with { type: 'json' }` import syntax
+3. Native logging: Use log from context (LoggingService removed - use native log)
+4. Graceful degradation: Promise.allSettled for parallel channel fetching
+5. Delta detection: Track previous ATP values in Versori KV
+6. BPP: Set to 'skip' (delta already filters changes)
+7. Rate limiting: Enforce minimum interval between Channel A requests
+8. Job tracking: Use JobTracker for lifecycle management
+
+SDK METHODS TO USE:
+- createClient(ctx) - Pass entire Versori context, auto-detects platform
+- new S3DataSource(config, log) - S3 file operations
+- new CSVParserService() - Parse CSV files
+- await client.graphql({ query, variables, pagination }) - Fluent GraphQL extraction with auto-pagination
+- new VersoriKVAdapter(openKv(':project:')) - Versori KV storage adapter
+- new StateService(kvAdapter) - Delta state management (takes KV adapter, not logger)
+- new JobTracker(kv, log) - Job lifecycle tracking
+- await client.createJob({ name, retailerId, meta: { preprocessing: 'skip' } }) - Create Batch API job
+- await client.sendBatch(jobId, { action, entityType, source, event, entities }) - Send batch chunk (fire-and-forget)
+
+FORBIDDEN PATTERNS:
+- ❌ LoggingService (removed - use native log on Versori)
+- ❌ Don't use monolithic index.ts (extract services into separate files)
+- ❌ Don't use inline mapping config (use external JSON file)
+- ❌ Don't fail entire sync if one channel fails (use Promise.allSettled)
+- ❌ Don't send all records (use delta detection to filter unchanged)
+- ❌ Don't use BPP with deltas (set preprocessing: 'skip')
+- ❌ Don't forget rate limiting for external APIs
+- ❌ Don't forget to call dispose() on data sources in finally block
+
+GENERATE:
+1. package.json with dependencies
+2. index.ts (workflow entry point with scheduled/adhoc/status triggers)
+3. src/workflows/multi-channel-sync.workflow.ts (main orchestration logic)
+4. src/services/atp-calculator.service.ts (ATP calculation and aggregation)
+5. src/services/channel-a-connector.service.ts (REST API with rate limiting)
+6. src/services/channel-b-connector.service.ts (S3 CSV fetching)
+7. src/services/batch-processor.service.ts (Batch API submission)
+8. src/services/batch-logger.service.ts (SFTP log file writing)
+9. src/types/multi-channel.types.ts (TypeScript interfaces)
+10. config/multi-channel.mapping.json (mapping configuration - external JSON file)
+
+NOTE: Use external JSON files for mapping configuration (not TypeScript .config files)
+
+Ensure all code is production-ready with proper error handling, graceful degradation, and rate limiting. Use modular architecture with separate service files for each concern.
+```
+
+---
+
+## What You'll Build
+
+### 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:**
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`workflow()`** → Durable workflows (advanced, rarely used)
+
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from schedule/webhook)
+- **`fn()`** → Internal processing (chained from schedule/webhook)
+
+### Recommended Project Structure
+
+```
+inventory-batch-sync/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-inventory-sync.ts   # Scheduled: Daily inventory sync
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-inventory-sync.ts   # Webhook: Manual trigger
+    │       └── job-status-check.ts       # Webhook: Status query
+    │
+    ├── services/
+    │   └── inventory-sync.service.ts     # Shared orchestration logic (reusable)
+    │
+    └── types/
+        └── inventory.types.ts            # Shared type definitions
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`scheduled/` vs `webhook/`)
+- ✅ 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
+
+---
+
+## Workflow Files
+
+### 1. Scheduled Workflows (`src/workflows/scheduled/`)
+
+All time-based triggers that run automatically on cron schedules.
+
+#### `src/workflows/scheduled/daily-inventory-sync.ts`
+
+**Purpose**: Automatic Daily inventory sync
+**Trigger**: Cron schedule (`0 2 * * *`)
+**Exposed as Endpoint**: ❌ NO - Runs automatically
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { runIngestion } from '../../services/inventory-sync.service.ts';
+
+/**
+ * Scheduled Workflow: Daily Inventory Sync
+ *
+ * Runs automatically daily at 2 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Uses shared service: inventory-sync.service.ts
+ */
+export const daily_inventory_sync = schedule(
+  'inventory-batch-scheduled',
+  '0 2 * * *' // Daily at 2 AM UTC
+).then(
+  http('run-inventory-batch', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, openKv } = ctx;
+    const jobId = `inventory-batch-${Date.now()}`;
+    const tracker = new JobTracker(openKv(':project:'), log);
+
+    await tracker.createJob(jobId, { triggeredBy: 'schedule', stage: 'initialization' });
+    await tracker.updateJob(jobId, { status: 'processing' });
+
+    try {
+      // Reuse shared orchestration logic
+      const result = await runIngestion(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+      return { success: false, jobId, error: e?.message };
+    }
+  })
+);
+```
+
+---
+
+### 2. Webhook Workflows (`src/workflows/webhook/`)
+
+All HTTP-based triggers that create webhook endpoints.
+
+#### `src/workflows/webhook/adhoc-inventory-sync.ts`
+
+**Purpose**: Manual inventory sync trigger (on-demand)
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/inventory-batch-adhoc`
+**Use Cases**: Testing, priority processing, ad-hoc runs
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { runIngestion } from '../../services/inventory-sync.service.ts';
+
+/**
+ * Webhook: Manual Inventory Sync Trigger
+ *
+ * Endpoint: POST https://{workspace}.versori.run/inventory-batch-adhoc
+ * Request body (optional): { filePattern: "urgent_*.xml", maxFiles: 5 }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: inventory-sync.service.ts
+ */
+export const adhoc_inventory_sync = webhook('inventory-batch-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'inventory-batch-adhoc', // Versori validates API key
+}).then(
+  http('run-inventory-batch-adhoc', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, openKv, data } = ctx;
+    const jobId = `inventory-batch-adhoc-${Date.now()}`;
+    const tracker = new JobTracker(openKv(':project:'), log);
+
+    await tracker.createJob(jobId, {
+      triggeredBy: 'manual',
+      stage: 'initialization',
+      options: data // Optional: filePattern, maxFiles, etc.
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+
+    try {
+      // Same orchestration logic as scheduled workflow
+      const result = await runIngestion(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+      return { success: false, jobId, error: e?.message };
+    }
+  })
+);
+```
+
+#### `src/workflows/webhook/job-status-check.ts`
+
+**Purpose**: Query job status
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/inventory-batch-job-status`
+**Request body**: `{ jobId: "inventory-batch-1234567890" }`
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Webhook: Job Status Check
+ *
+ * Endpoint: POST https://{workspace}.versori.run/inventory-batch-job-status
+ * Request body: { jobId: "inventory-batch-1234567890" }
+ *
+ * Pattern: webhook().then(fn()) - no external API needed, only KV storage
+ * Lightweight: Only queries KV store, no Fluent API calls
+ */
+export const jobStatusCheck = webhook('inventory-batch-job-status', {
+  response: { mode: 'sync' },
+  connection: 'inventory-batch-job-status',
+}).then(
+  fn('status', async ctx => {
+    const { data, log, openKv } = ctx;
+    const jobId = data?.jobId as string;
+
+    if (!jobId) {
+      return { success: false, error: 'jobId required' };
+    }
+
+    const tracker = new JobTracker(openKv(':project:'), log);
+    const status = await tracker.getJob(jobId);
+
+    return status
+      ? { success: true, jobId, ...status }
+      : { success: false, error: 'Job not found', jobId };
+  })
+);
+```
+
+---
+
+### 3. Entry Point (`index.ts`)
+
+**Purpose**: Register all workflows with Versori platform
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/scheduled/ → Time-based triggers (cron)
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ */
+
+// Import scheduled workflows
+import { daily_inventory_sync } from './src/workflows/scheduled/daily-inventory-sync';
+
+// Import webhook workflows
+import { adhoc_inventory_sync } from './src/workflows/webhook/adhoc-inventory-sync';
+import { jobStatusCheck } from './src/workflows/webhook/job-status-check';
+
+// Register all workflows
+export {
+  // Scheduled (time-based triggers)
+  daily_inventory_sync,
+
+  // Webhooks (HTTP-based triggers)
+  adhoc_inventory_sync,
+  jobStatusCheck,
+};
+```
+
+**What Gets Exposed:**
+
+- ✅ `adhoc_inventory_sync` → `https://{workspace}.versori.run/inventory-batch-adhoc`
+- ✅ `jobStatusCheck` → `https://{workspace}.versori.run/inventory-batch-job-status`
+- ❌ `daily_inventory_sync` → NOT exposed (runs automatically on cron)
+
+---
+
+### Adding New Workflows
+
+**To add a scheduled workflow:**
+1. Create file in `src/workflows/scheduled/` with descriptive name (e.g., `hourly-delta-sync.ts`)
+2. Export the workflow from the file
+3. Import and re-export in `index.ts`
+
+**To add a webhook workflow:**
+1. Create file in `src/workflows/webhook/` with descriptive name (e.g., `error-notification.ts`)
+2. Export the workflow from the file
+3. Import and re-export in `index.ts`
+
+**Example - Adding hourly delta sync:**
+
+```typescript
+// src/workflows/scheduled/hourly-delta-sync.ts
+export const hourlyDeltaSync = schedule(
+  'inventory-delta-hourly',
+  '0 * * * *' // Every hour
+).then(
+  http('run-delta-sync', { connection: 'fluent_commerce' }, async ctx => {
+    // Delta sync logic (skip BPP)
+    const result = await runIngestion(ctx, jobId, tracker, { bppEnabled: false });
+    return result;
+  })
+);
+
+// index.ts (add to imports and exports)
+import { hourlyDeltaSync } from './src/workflows/scheduled/hourly-delta-sync';
+export { daily_inventory_sync, hourlyDeltaSync, ... };
+```
+
+---
+## Complete Modular Implementation
+
+### File: `package.json`
+
+```json
+{
+  "name": "multi-channel-inventory-sync",
+  "version": "1.0.0",
+  "description": "Multi-Channel Inventory Aggregation to Fluent Commerce Batch API",
+  "type": "module",
+  "versori": {
+    "workflows": "./index.ts"
+  },
+  "scripts": {
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+```
+
+---
+
+### File: `index.ts`
+
+```typescript
+import { schedule, webhook, http, fn } from '@versori/run';
+import { processMultiChannelSync } from './src/workflows/multi-channel-sync.workflow';
+
+/**
+ * Scheduled workflow: Multi-channel inventory sync every 15 minutes
+ *
+ * Processing: Parallel channel fetching with graceful degradation
+ * BPP: Disabled (preprocessing: 'skip') - delta detection already filters
+ * State Management: VersoriKVAdapter + JobTracker prevent duplicates
+ */
+export const scheduledMultiChannelSync = schedule(
+  'multi-channel-sync',
+  '*/15 * * * *' // Every 15 minutes
+).then(
+  http('run-sync', { connection: 'fluent_commerce' }, async ctx => {
+    // ctx contains: fetch, connections, log, activation, openKv
+    // Pass entire context to workflow
+    return await processMultiChannelSync(ctx);
+  })
+);
+
+/**
+ * Manual trigger endpoint for testing and ad-hoc runs
+ */
+export const adhocMultiChannelSync = webhook('multi-channel-sync-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'multi-channel-sync-adhoc',
+}).then(
+  http('run-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
+    return await processMultiChannelSync(ctx);
+  })
+);
+
+/**
+ * Job status check endpoint
+ */
+export const multiChannelSyncJobStatus = webhook('multi-channel-sync-job-status', {
+  response: { mode: 'sync' },
+  connection: 'multi-channel-sync-job-status',
+}).then(
+  fn('status', async ctx => {
+    const { data, log, openKv } = ctx;
+    const jobId = data?.jobId as string;
+    if (!jobId) return { success: false, error: 'jobId required' };
+    const { JobTracker } = await import('@fluentcommerce/fc-connect-sdk');
+    const tracker = new JobTracker(openKv(':project:'), log);
+    const status = await tracker.getJob(jobId);
+    return status
+      ? { success: true, jobId, ...status }
+      : { success: false, error: 'Job not found', jobId };
+  })
+);
+```
+
+---
+
+### File: `src/types/multi-channel.types.ts`
+
+```typescript
+/**
+ * Type definitions for multi-channel inventory sync
+ */
+export interface ChannelInventoryRecord {
+  sku: string;
+  location: string;
+  channel: string;
+  onHand: number;
+  reserved: number;
+  buffer: number;
+  lastUpdated?: string;
+}
+
+export interface AggregatedInventory {
+  sku: string;
+  location: string;
+  totalOnHand: number;
+  totalReserved: number;
+  atp: number;
+  channels: {
+    [channel: string]: {
+      allocated: number;
+      buffer: number;
+      max?: number;
+    };
+  };
+}
+
+export interface SyncState {
+  [sku: string]: {
+    [location: string]: number; // ATP value
+  };
+}
+
+export interface SyncStats {
+  totalRecords: number;
+  channelARecords: number;
+  channelBRecords: number;
+  fluentRecords: number;
+  aggregatedSkus: number;
+  changedRecords: number;
+  batchesSent: number;
+  successCount: number;
+  errorCount: number;
+  duration: number;
+}
+
+export interface BatchDetail {
+  batchId: string;
+  recordCount: number;
+  timestamp: string;
+  status: 'SENT' | 'FAILED';
+  error?: string;
+}
+
+export interface BatchResult {
+  totalSent: number;
+  batchCount: number;
+  batches: BatchDetail[];
+  errors: Array<{ batchId: string; error: string }>;
+}
+```
+
+---
+
+### File: `src/config/multi-channel.mapping.json`
+
+```json
+{
+  "name": "multi-channel-inventory",
+  "version": "1.0.0",
+  "description": "Normalize channel payloads to aggregation schema",
+  "fields": {
+    "locationRef": {
+      "source": "locationRef",
+      "required": true,
+      "resolver": "sdk.trim",
+      "comment": "Location reference"
+    },
+    "skuRef": {
+      "source": "skuRef",
+      "required": true,
+      "resolver": "sdk.trim",
+      "comment": "SKU reference"
+    },
+    "onHand": {
+      "source": "onHand",
+      "resolver": "sdk.number",
+      "comment": "On-hand quantity"
+    },
+    "reserved": {
+      "source": "reserved",
+      "resolver": "sdk.number",
+      "comment": "Reserved quantity"
+    },
+    "buffer": {
+      "source": "buffer",
+      "resolver": "sdk.number",
+      "comment": "Safety buffer"
+    },
+    "channel": {
+      "source": "channel",
+      "defaultValue": "UNKNOWN",
+      "comment": "Channel identifier"
+    }
+  }
+}
+```
+
+> **✅ PRODUCTION STANDARD:** Use external JSON files for mapping configuration (not TypeScript objects)
+
+---
+
+### File: `src/services/atp-calculator.service.ts`
+
+```typescript
+import type { ChannelInventoryRecord, AggregatedInventory } from '../types/multi-channel.types';
+
+/**
+ * Service for calculating ATP (Available To Promise) across channels
+ */
+export class ATPCalculatorService {
+  private readonly oversellProtection: boolean;
+
+  constructor(
+    oversellProtection = true
+  ) {
+    this.oversellProtection = oversellProtection;
+  }
+
+  /**
+   * Calculate base ATP for a single record
+   * Formula: ATP = (onHand - reserved) - buffer
+   */
+  calculateBaseATP(onHand: number, reserved: number, buffer: number): number {
+    const available = Math.max(0, onHand - reserved);
+    const atp = available - buffer;
+    return this.oversellProtection ? Math.max(0, atp) : atp;
+  }
+
+  /**
+   * Aggregate inventory across channels
+   * Deduplicates by SKU + location and calculates consolidated ATP
+   */
+  aggregateChannelInventory(records: ChannelInventoryRecord[]): Map<string, AggregatedInventory> {
+    const aggregated = new Map<string, AggregatedInventory>();
+
+    for (const record of records) {
+      const key = `${record.sku}:${record.location}`;
+      const existing = aggregated.get(key);
+
+      if (existing) {
+        // Aggregate across channels
+        existing.totalOnHand += record.onHand;
+        existing.totalReserved += record.reserved;
+        existing.channels[record.channel] = {
+          allocated: record.onHand - record.reserved - record.buffer,
+          buffer: record.buffer,
+        };
+      } else {
+        // First record for this SKU+location
+        aggregated.set(key, {
+          sku: record.sku,
+          location: record.location,
+          totalOnHand: record.onHand,
+          totalReserved: record.reserved,
+          atp: 0,
+          channels: {
+            [record.channel]: {
+              allocated: record.onHand - record.reserved - record.buffer,
+              buffer: record.buffer,
+            },
+          },
+        });
+      }
+    }
+
+    // Calculate final ATP for each aggregated record
+    for (const [, agg] of aggregated) {
+      const totalBuffer = Math.max(...Object.values(agg.channels).map(c => c.buffer));
+      agg.atp = this.calculateBaseATP(agg.totalOnHand, agg.totalReserved, totalBuffer);
+    }
+
+
+    return aggregated;
+  }
+}
+```
+
+---
+
+### File: `src/services/channel-a-connector.service.ts`
+
+```typescript
+
+/**
+ * Service for fetching inventory from Channel A REST API
+ * Includes rate limiting and exponential backoff retry logic
+ */
+export class ChannelAConnectorService {
+  private readonly url: string;
+  private readonly apiKey: string;
+  private readonly rateLimitRpm: number;
+  private readonly logger; // ✅ Versori native log - TypeScript infers type
+  private lastRequest = 0;
+
+  constructor(url: string, apiKey: string, rateLimitRpm: number, logger) { // ✅ Versori native log - TypeScript infers type
+    this.url = url;
+    this.apiKey = apiKey;
+    this.rateLimitRpm = rateLimitRpm;
+    this.logger = logger;
+  }
+
+  /**
+   * Fetch inventory from Channel A with rate limiting
+   */
+  async fetchInventory(): Promise<any[]> {
+    await this.enforceRateLimit();
+
+    const response = await this.fetchWithRetry(this.url, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Channel A API error: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    return data.inventory || [];
+  }
+
+  /**
+   * Enforce rate limit (minimum interval between requests)
+   */
+  private async enforceRateLimit(): Promise<void> {
+    const minInterval = 60000 / this.rateLimitRpm;
+    const now = Date.now();
+    const elapsed = now - this.lastRequest;
+
+    if (elapsed < minInterval) {
+      const wait = minInterval - elapsed;
+      await new Promise(resolve => setTimeout(resolve, wait));
+    }
+
+    this.lastRequest = Date.now();
+  }
+
+  /**
+   * Fetch with exponential backoff retry
+   */
+  private async fetchWithRetry(
+    url: string,
+    options: RequestInit,
+    maxRetries = 3
+  ): Promise<Response> {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await fetch(url, options);
+
+        if (response.status === 429 || response.status >= 500) {
+          if (attempt < maxRetries) {
+            const backoff = Math.pow(2, attempt) * 1000;
+              `[ChannelA] Error ${response.status}, retrying in ${backoff}ms (attempt ${attempt}/${maxRetries})`
+            );
+            await new Promise(resolve => setTimeout(resolve, backoff));
+            continue;
+          }
+        }
+
+        return response;
+      } catch (error) {
+        if (attempt === maxRetries) throw error;
+        const backoff = Math.pow(2, attempt) * 1000;
+          `[ChannelA] Fetch error, retrying in ${backoff}ms (attempt ${attempt}/${maxRetries}):`,
+          error
+        );
+        await new Promise(resolve => setTimeout(resolve, backoff));
+      }
+    }
+
+    throw new Error('Channel A: Max retries exceeded');
+  }
+}
+```
+
+---
+
+### File: `src/services/channel-b-connector.service.ts`
+
+```typescript
+import { S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Service for fetching inventory from Channel B S3 CSV
+ */
+export class ChannelBConnectorService {
+  private readonly s3: S3DataSource;
+  private readonly csv: CSVParserService;
+  private readonly bucket: string;
+  private readonly key: string;
+  private readonly logger; // ✅ Versori native log - TypeScript infers type
+
+  constructor(s3Config: any, bucket: string, key: string, logger) { // ✅ Versori native log - TypeScript infers type
+    this.s3 = new S3DataSource(s3Config, logger);
+    this.csv = new CSVParserService();
+    this.bucket = bucket;
+    this.key = key;
+  }
+
+  /**
+   * Fetch inventory from S3 CSV file
+   */
+  async fetchInventory(): Promise<any[]> {
+    try {
+      const csvContent = (await this.s3.downloadFile(`${this.bucket}/${this.key}`, {
+        encoding: 'utf8',
+      })) as string;
+
+      const records = await this.csv.parse(csvContent, {
+        columns: true,
+        skip_empty_lines: true,
+        trim: true,
+      });
+
+      return records || [];
+    } catch (error) {
+      throw error;
+    }
+    // Note: S3DataSource doesn't require explicit disposal (unlike SFTP)
+  }
+}
+```
+
+---
+
+### File: `src/services/batch-processor.service.ts`
+
+```typescript
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { BatchResult, BatchDetail } from '../types/multi-channel.types';
+
+/**
+ * Service for sending records to Fluent Batch API
+ *
+ * ✅ PRODUCTION ENHANCEMENT: Optional logger for detailed progress tracking
+ */
+export class BatchProcessorService {
+  constructor(
+    private client: FluentClient,
+    private jobTracker: JobTracker,
+    private log?: any  // ✅ Optional logger for progress tracking
+  ) {}
+
+  /**
+   * Send inventory records to Batch API with chunking
+   */
+  async sendInventoryBatches(
+    jobId: string,
+    records: any[],
+    batchSize: number = 500
+  ): Promise<BatchResult> {
+    const result: BatchResult = {
+      totalSent: 0,
+      batchCount: 0,
+      batches: [],
+      errors: [],
+    };
+
+    // Chunk records into batches
+    const chunks: any[][] = [];
+    for (let i = 0; i < records.length; i += batchSize) {
+      chunks.push(records.slice(i, i + batchSize));
+    }
+
+    const totalBatches = chunks.length;
+
+    // ✅ PRODUCTION ENHANCEMENT: Log batch sending start
+    if (this.log) {
+      this.log.info('📤 Starting batch sending', {
+        jobId,
+        totalRecords: records.length,
+        batchSize,
+        totalBatches,
+        processingMode: 'sequential (one at a time)',
+      });
+    }
+
+    // Send each batch
+    for (let i = 0; i < chunks.length; i++) {
+      const batchNumber = i + 1;
+
+      // ✅ PRODUCTION ENHANCEMENT: Log progress every 10 batches
+      if (this.log && batchNumber % 10 === 0) {
+        this.log.info(`📤 Sending batch ${batchNumber}/${totalBatches}`, {
+          jobId,
+          batchNumber,
+          totalBatches,
+          recordsInBatch: chunks[i].length,
+          totalSentSoFar: result.totalSent,
+          progress: `${((batchNumber / totalBatches) * 100).toFixed(1)}%`,
+        });
+      }
+
+      try {
+        const batch = await this.client.sendBatch(jobId, {
+          action: 'UPSERT',
+          entityType: 'INVENTORY',
+          source: 'MULTI_CHANNEL',
+          event: 'MULTI_CHANNEL_SYNC',
+          entities: chunks[i],
+        });
+
+        result.totalSent += chunks[i].length;
+        result.batchCount++;
+        result.batches.push({
+          batchId: batch.id,
+          recordCount: chunks[i].length,
+          timestamp: new Date().toISOString(),
+          status: 'SENT',
+        });
+
+        // ✅ No logging here - workflow handles it
+
+        // Update job tracker
+        await this.jobTracker.updateJob(jobId, {
+          details: {
+            batchesSent: result.batchCount,
+            recordsProcessed: result.totalSent,
+          },
+        });
+      } catch (error: any) {
+        result.errors.push({
+          batchId: `batch-${batchNumber}`,
+          error: error.message,
+        });
+        result.batches.push({
+          batchId: `batch-${batchNumber}`,
+          recordCount: chunks[i].length,
+          timestamp: new Date().toISOString(),
+          status: 'FAILED',
+          error: error.message,
+        });
+      }
+    }
+
+    // ✅ PRODUCTION ENHANCEMENT: Log completion
+    if (this.log) {
+      this.log.info('✅ Sequential batch sending completed', {
+        jobId,
+        totalBatches,
+        batchesSent: result.batchCount,
+        batchesFailed: result.errors.length,
+        totalRecordsSent: result.totalSent,
+      });
+    }
+
+    return result;
+  }
+}
+```
+
+---
+
+### File: `src/services/batch-logger.service.ts`
+
+```typescript
+import { Buffer } from 'node:buffer';
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Service for writing batch processing logs to S3
+ */
+export class BatchLoggerService {
+  constructor(private s3: S3DataSource) {
+    // ✅ No logger - workflow handles logging with Versori native log
+  }
+
+  /**
+   * Write batch processing log to S3
+   */
+  async writeBatchLog(
+    logData: any,
+    bucket: string,
+    keyPrefix: string,
+    format: 'json' | 'text' = 'json'
+  ): Promise<void> {
+    try {
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const logFileName = `${keyPrefix}${timestamp}.${format === 'json' ? 'json' : 'log'}`;
+      const logKey = `${bucket}/${logFileName}`;
+
+      const logContent = this.formatLogContent(logData, format);
+
+      await this.s3.uploadFile(logKey, Buffer.from(logContent, 'utf8'), {
+        encoding: 'utf8',
+        contentType: format === 'json' ? 'application/json' : 'text/plain',
+      });
+
+      // ✅ No logging here - workflow handles it
+    } catch (error: any) {
+      // ✅ No logging here - workflow handles it
+      // Don't throw - logging failure shouldn't stop workflow
+    }
+  }
+
+  private formatLogContent(logData: any, format: 'json' | 'text'): string {
+    if (format === 'json') {
+      return JSON.stringify(logData, null, 2);
+    }
+
+    return `Multi-Channel Sync Log
+======================
+Timestamp: ${logData.timestamp}
+Job ID: ${logData.jobId}
+
+Channel Summary:
+  Channel A: ${logData.channels.channelA || 0} records
+  Channel B: ${logData.channels.channelB || 0} records
+  Fluent: ${logData.channels.fluent || 0} records
+
+Aggregation:
+  Total Records: ${logData.aggregated}
+  Changed Records: ${logData.changed}
+  Unchanged: ${logData.unchanged}
+
+Batches:
+${logData.batches
+  .map(
+    (b: any, i: number) =>
+      `  [${i + 1}] ${b.batchId} | ${b.recordCount} records | ${b.status}${b.error ? ` | Error: ${b.error}` : ''}`
+  )
+  .join('\n')}
+
+Summary:
+  Total Batches: ${logData.summary.totalBatches}
+  Successful: ${logData.summary.success}
+  Failed: ${logData.summary.failed}
+  Duration: ${logData.summary.duration}ms
+
+Status: ${logData.status}
+`;
+  }
+}
+```
+
+---
+
+### File: `src/workflows/multi-channel-sync.workflow.ts`
+
+```typescript
+import { Buffer } from 'node:buffer';
+import {
+  createClient,
+  StateService,
+  VersoriKVAdapter,
+  JobTracker,
+} from '@fluentcommerce/fc-connect-sdk';
+import type { ChannelInventoryRecord, SyncStats } from '../types/multi-channel.types';
+import { ATPCalculatorService } from '../services/atp-calculator.service';
+import { ChannelAConnectorService } from '../services/channel-a-connector.service';
+import { ChannelBConnectorService } from '../services/channel-b-connector.service';
+import { BatchProcessorService } from '../services/batch-processor.service';
+import { BatchLoggerService } from '../services/batch-logger.service';
+
+const INVENTORY_QUERY = `
+  query GetInventory($retailerId: ID!, $first: Int!, $after: String) {
+    inventoryPositions(retailerId: $retailerId, first: $first, after: $after) {
+      edges {
+        node {
+          id
+          ref
+          productRef
+          locationRef
+          onHand
+          reservedQuantity
+          status
+          type
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+`;
+
+/**
+ * Fetch current inventory state from Fluent GraphQL
+ */
+async function fetchFluentInventory(
+  client: any,
+  retailerId: string,
+  pageSize: number,
+  maxRecords: number,
+  log: any
+): Promise<any[]> {
+  try {
+    const result = await client.graphql({
+      query: INVENTORY_QUERY,
+      variables: { retailerId, first: pageSize },
+      pagination: { maxRecords },
+    });
+
+    const edges = result.data?.inventoryPositions?.edges || [];
+    const records = edges.map((e: any) => ({
+      productRef: e.node.productRef,
+      locationRef: e.node.locationRef,
+      onHand: Number(e.node.onHand || 0),
+      reserved: Number(e.node.reservedQuantity || 0),
+    }));
+
+    log.info(`[Fluent] Fetched ${records.length} records from GraphQL`);
+    return records;
+  } catch (error) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorDetails = {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+    };
+    log.error('[Fluent] GraphQL fetch error:', errorDetails);
+    throw error;
+  }
+}
+
+/**
+ * Main multi-channel sync workflow orchestrator
+ * Coordinates channel fetching, aggregation, delta detection, and batch submission
+ *
+ * @param ctx - Versori context object containing fetch, connections, log, activation, openKv
+ */
+export async function processMultiChannelSync(ctx: any) {
+  const { log, openKv, activation } = ctx;
+  const startTime = Date.now();
+
+  log.info('[MultiChannelSync] Starting sync workflow');
+
+  try {
+    // ========================================
+    // CLIENT INITIALIZATION
+    // ========================================
+    const client = await createClient(ctx);
+
+    // ========================================
+    // CONFIGURATION
+    // ========================================
+    const config = {
+      retailerId: activation?.getVariable('retailerId'),
+      jobName: activation?.getVariable('jobName') || 'Multi-Channel Inventory Sync',
+      batchSize: parseInt(activation?.getVariable('batchSize') || '500', 10),
+      maxRecords: parseInt(activation?.getVariable('maxRecords') || '50000', 10),
+      defaultBuffer: parseInt(activation?.getVariable('defaultBuffer') || '5', 10),
+      oversellProtection: activation?.getVariable('oversellProtection') !== 'false',
+      useBpp: activation?.getVariable('useBpp') || 'skip',
+      enableDelta: activation?.getVariable('enableDelta') !== 'false',
+      deltaStateKey: activation?.getVariable('deltaStateKey') || 'sync:delta:state',
+      channelAEnabled: activation?.getVariable('channelAEnabled') === 'true',
+      channelAUrl: activation?.getVariable('channelAUrl'),
+      channelAKey: activation?.getVariable('channelAKey'),
+      channelABuffer: parseInt(activation?.getVariable('channelABuffer') || '5', 10),
+      channelARateLimitRpm: parseInt(activation?.getVariable('channelARateLimitRpm') || '120', 10),
+      channelBEnabled: activation?.getVariable('channelBEnabled') === 'true',
+      channelBBucket: activation?.getVariable('channelBBucket'),
+      channelBKey: activation?.getVariable('channelBKey'),
+      fluentEnabled: activation?.getVariable('fluentEnabled') === 'true',
+      fluentPageSize: parseInt(activation?.getVariable('fluentPageSize') || '200', 10),
+    };
+
+    // ========================================
+    // SERVICE INITIALIZATION
+    // ========================================
+    const kv = new VersoriKVAdapter(openKv(':project:'));
+    const jobTracker = new JobTracker(openKv(':project:'), log);
+    const stateService = new StateService(log);
+
+    const atpCalc = new ATPCalculatorService(config.oversellProtection);
+    // ✅ PRODUCTION ENHANCEMENT: Pass log to BatchProcessorService for detailed progress tracking
+    const batchProcessor = new BatchProcessorService(client, jobTracker, log);
+
+    const jobId = `multi-channel-sync-${Date.now()}`;
+    await jobTracker.createJob(jobId, {
+      triggeredBy: 'schedule',
+      stage: 'initialization',
+      details: { config },
+    });
+
+    const stats: SyncStats = {
+      totalRecords: 0,
+      channelARecords: 0,
+      channelBRecords: 0,
+      fluentRecords: 0,
+      aggregatedSkus: 0,
+      changedRecords: 0,
+      batchesSent: 0,
+      successCount: 0,
+      errorCount: 0,
+      duration: 0,
+    };
+
+    await jobTracker.updateJob(jobId, { status: 'fetching_channels' });
+
+    // ========================================
+    // CHANNEL FETCHING (PARALLEL WITH GRACEFUL DEGRADATION)
+    // ========================================
+    const allRecords: ChannelInventoryRecord[] = [];
+
+    // Fetch Channel A (REST API)
+    if (config.channelAEnabled && config.channelAUrl && config.channelAKey) {
+      log.info('[MultiChannelSync] Fetching from Channel A...');
+      const channelA = new ChannelAConnectorService(
+        config.channelAUrl,
+        config.channelAKey,
+        config.channelARateLimitRpm,
+        log
+      );
+
+      try {
+        const records = await channelA.fetchInventory();
+        const mapped = records.map(r => ({
+          sku: r.product_id,
+          location: r.warehouse_code,
+          channel: 'A',
+          onHand: r.quantity_available,
+          reserved: r.quantity_reserved,
+          buffer: config.channelABuffer,
+          lastUpdated: r.updated_at,
+        }));
+
+        allRecords.push(...mapped);
+        stats.channelARecords = mapped.length;
+        log.info(`[MultiChannelSync] Channel A: ${mapped.length} records`);
+      } catch (error) {
+        // ✅ Enhanced error logging: Extract all error details for visibility
+        const errorDetails = {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+        };
+        log.error('[MultiChannelSync] Channel A fetch failed (continuing):', errorDetails);
+        stats.errorCount++;
+      }
+    }
+
+    // Fetch Channel B (S3 CSV)
+    if (config.channelBEnabled && config.channelBBucket && config.channelBKey) {
+      log.info('[MultiChannelSync] Fetching from Channel B...');
+      const s3Config = {
+        type: 'S3_CSV',
+        connectionId: 'channel-b-s3',
+        name: 'Channel B S3',
+        s3Config: {
+          bucket: config.channelBBucket,
+          region: activation?.getVariable('awsRegion') || 'us-east-1',
+          accessKeyId: activation?.getVariable('awsAccessKeyId'),
+          secretAccessKey: activation?.getVariable('awsSecretAccessKey'),
+        },
+      };
+
+      const channelB = new ChannelBConnectorService(
+        s3Config,
+        config.channelBBucket,
+        config.channelBKey,
+        log
+      );
+
+      try {
+        const records = await channelB.fetchInventory();
+        const mapped = records.map((r: any) => ({
+          sku: r.sku,
+          location: r.location,
+          channel: 'B',
+          onHand: parseInt(r.qty, 10),
+          reserved: parseInt(r.reserved, 10),
+          buffer: config.defaultBuffer,
+        }));
+
+        allRecords.push(...mapped);
+        stats.channelBRecords = mapped.length;
+        log.info(`[MultiChannelSync] Channel B: ${mapped.length} records`);
+      } catch (error) {
+        // ✅ Enhanced error logging: Extract all error details for visibility
+        const errorDetails = {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+        };
+        log.error('[MultiChannelSync] Channel B fetch failed (continuing):', errorDetails);
+        stats.errorCount++;
+      }
+    }
+
+    // Fetch Fluent GraphQL (current state)
+    if (config.fluentEnabled) {
+      log.info('[MultiChannelSync] Fetching from Fluent GraphQL...');
+      try {
+        const records = await fetchFluentInventory(
+          client,
+          config.retailerId!,
+          config.fluentPageSize,
+          config.maxRecords,
+          log
+        );
+
+        const mapped = records.map(r => ({
+          sku: r.productRef,
+          location: r.locationRef,
+          channel: 'FLUENT',
+          onHand: r.onHand,
+          reserved: r.reserved,
+          buffer: 0,
+        }));
+
+        allRecords.push(...mapped);
+        stats.fluentRecords = mapped.length;
+        log.info(`[MultiChannelSync] Fluent: ${mapped.length} records`);
+      } catch (error) {
+        // ✅ Enhanced error logging: Extract all error details for visibility
+        const errorDetails = {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+        };
+        log.error('[MultiChannelSync] Fluent fetch failed (continuing):', errorDetails);
+        stats.errorCount++;
+      }
+    }
+
+    stats.totalRecords = allRecords.length;
+
+    if (allRecords.length === 0) {
+      log.warn('[MultiChannelSync] No inventory records fetched from any channel');
+      await jobTracker.markCompleted(jobId, { message: 'No data', stats });
+      return { success: false, message: 'No data', stats };
+    }
+
+    // ========================================
+    // AGGREGATION
+    // ========================================
+    await jobTracker.updateJob(jobId, { status: 'aggregating' });
+
+    log.info('[MultiChannelSync] Aggregating inventory across channels...');
+    const aggregated = atpCalc.aggregateChannelInventory(allRecords);
+    stats.aggregatedSkus = aggregated.size;
+
+    const finalInventory = Array.from(aggregated.values()).map(agg => ({
+      skuRef: agg.sku,
+      locationRef: agg.location,
+      qty: agg.atp,
+      type: 'AVAILABLE',
+      status: 'ACTIVE',
+      expectedOn: new Date().toISOString().split('T')[0],
+    }));
+
+    log.info(`[MultiChannelSync] Aggregated ${stats.aggregatedSkus} unique SKU/location combinations`);
+
+    // ========================================
+    // DELTA DETECTION
+    // ========================================
+    let recordsToSend = finalInventory;
+
+    if (config.enableDelta) {
+      await jobTracker.updateJob(jobId, { status: 'delta_detection' });
+      log.info('[MultiChannelSync] Checking for changes (delta detection)...');
+
+      const prevState = ((await stateService.getState(config.deltaStateKey)) as any) || {};
+      const changedRecords = [];
+
+      for (const record of finalInventory) {
+        const prevQty = prevState[record.skuRef]?.[record.locationRef];
+        if (prevQty === undefined || prevQty !== record.qty) {
+          changedRecords.push(record);
+        }
+      }
+
+      recordsToSend = changedRecords;
+      stats.changedRecords = changedRecords.length;
+      log.info(
+        `[MultiChannelSync] Delta detection: ${changedRecords.length} changed records (${finalInventory.length} total)`
+      );
+    } else {
+      stats.changedRecords = finalInventory.length;
+    }
+
+    if (recordsToSend.length === 0) {
+      log.info('[MultiChannelSync] No changes detected, skipping batch send');
+      stats.duration = Date.now() - startTime;
+      await jobTracker.markCompleted(jobId, { message: 'No changes', stats });
+      return { success: true, message: 'No changes', stats };
+    }
+
+    // ========================================
+    // BATCH API SUBMISSION
+    // ========================================
+    await jobTracker.updateJob(jobId, { status: 'creating_batch_job' });
+
+    log.info('[MultiChannelSync] Creating Batch API job...');
+    const job = await client.createJob({
+      name: config.jobName,
+      retailerId: config.retailerId!,
+      meta: {
+        preprocessing: config.useBpp,
+      },
+    });
+
+    log.info(`[MultiChannelSync] Job created: ${job.id}`);
+
+    await jobTracker.updateJob(jobId, { status: 'sending_batches' });
+
+    // ? Enhanced: Extract context for progress logging
+    const uniqueLocations = [...new Set(recordsToSend.map((r: any) => r.locationRef))];
+    const sampleSKUs = recordsToSend.slice(0, 5).map((r: any) => r.skuRef);
+    const estimatedBatches = Math.ceil(recordsToSend.length / config.batchSize);
+
+    // ? Enhanced: Start logging with context
+    log.info(`[BatchProcessor] Sending batches for multi-channel sync`, {
+      totalRecords: recordsToSend.length,
+      estimatedBatches,
+      batchSize: config.batchSize,
+      locations: uniqueLocations.join(', '),
+      sampleSKUs: sampleSKUs.join(', '),
+      jobId: job.id
+    });
+
+    const batchResults = await batchProcessor.sendInventoryBatches(
+      job.id,
+      recordsToSend,
+      config.batchSize
+    );
+
+    // ✅ Logging handled in workflow with Versori native log
+    log.info(`[BatchProcessor] Sent ${batchResults.batchCount} batches`, {
+      jobId: job.id,
+      totalRecords: batchResults.totalSent,
+      successfulBatches: batchResults.batches.filter(b => b.status === 'SENT').length,
+      failedBatches: batchResults.batches.filter(b => b.status === 'FAILED').length,
+    });
+
+    // ? Enhanced: Completion logging with summary
+    log.info(`[BatchProcessor] Batch submission completed for multi-channel sync`, {
+      totalBatches: batchResults.batchCount,
+      totalRecords: batchResults.totalSent,
+      successfulBatches: batchResults.batches.filter(b => b.status === 'SENT').length,
+      failedBatches: batchResults.errors.length,
+      jobId: job.id
+    });
+
+    if (batchResults.errors.length > 0) {
+      log.warn(`[BatchProcessor] ${batchResults.errors.length} batches failed`, {
+        jobId: job.id,
+        errors: batchResults.errors.slice(0, 5), // Log first 5 errors
+      });
+    }
+
+    stats.batchesSent = batchResults.batchCount;
+    stats.successCount = batchResults.batches.filter(b => b.status === 'SENT').length;
+    stats.errorCount = batchResults.errors.length;
+
+    // ========================================
+    // DELTA STATE UPDATE
+    // ========================================
+    if (config.enableDelta) {
+      await jobTracker.updateJob(jobId, { status: 'updating_delta_state' });
+      log.info('[MultiChannelSync] Updating delta state...');
+
+      const newState: any = {};
+      for (const record of finalInventory) {
+        if (!newState[record.skuRef]) {
+          newState[record.skuRef] = {};
+        }
+        newState[record.skuRef][record.locationRef] = record.qty;
+      }
+
+      await stateService.setState(config.deltaStateKey, newState, {
+        ttlSeconds: 7 * 24 * 60 * 60, // 7 days
+      });
+
+      log.info('[MultiChannelSync] Delta state updated');
+    }
+
+    stats.duration = Date.now() - startTime;
+
+    log.info('[MultiChannelSync] Sync completed', { stats });
+
+    await jobTracker.markCompleted(jobId, {
+      stats,
+      jobId: job.id,
+    });
+
+    return {
+      success: stats.errorCount === 0,
+      jobId: job.id,
+      stats,
+    };
+  } catch (error: any) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorDetails = {
+      message: error?.message || 'Unknown error',
+      stack: error?.stack,
+      fileName: error?.fileName,
+      lineNumber: error?.lineNumber,
+      originalError: error?.context?.originalError?.message,
+      errorType: error?.name || 'Error',
+    };
+    log.error('[MultiChannelSync] Fatal error:', errorDetails);
+    return { success: false, error: error.message, duration: Date.now() - startTime };
+  }
+}
+```
+
+---
+
+## Versori Activation Variables
+
+```bash
+# Required Variables
+retailerId=your-retailer-id
+
+# Sync Configuration
+jobName=Multi-Channel Inventory Sync
+batchSize=500
+maxRecords=50000
+defaultBuffer=5
+oversellProtection=true
+useBpp=skip
+
+# Delta Detection
+enableDelta=true
+deltaStateKey=sync:delta:state
+
+# Channel A (REST API)
+channelAEnabled=true
+channelAUrl=https://api.channel-a.example.com/inventory
+channelAKey=your-api-key
+channelABuffer=5
+channelARateLimitRpm=120
+
+# Channel B (S3 CSV)
+channelBEnabled=true
+channelBBucket=channel-b-inventory
+channelBKey=inventory/current.csv
+
+# AWS Credentials (for Channel B S3)
+awsRegion=us-east-1
+awsAccessKeyId=AKIAXXXXXXXXXXXX
+awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Fluent GraphQL (current state comparison)
+fluentEnabled=true
+fluentPageSize=200
+```
+
+---
+
+## Sample Channel Data
+
+### Channel A (REST API Response)
+
+```json
+{
+  "inventory": [
+    {
+      "product_id": "SKU-12345",
+      "warehouse_code": "LOC001",
+      "quantity_available": 100,
+      "quantity_reserved": 20,
+      "updated_at": "2025-01-25T10:00:00Z"
+    }
+  ]
+}
+```
+
+### Channel B (S3 CSV)
+
+```csv
+sku,location,qty,reserved
+SKU-12345,LOC001,95,15
+SKU-67890,LOC002,75,5
+SKU-11111,LOC001,200,0
+```
+
+### ATP Calculation Example
+
+```typescript
+// Channel A: SKU-12345 at LOC001
+onHand = 100
+reserved = 20
+buffer = 5
+ATP = (100 - 20) - 5 = 75
+
+// Channel B: SKU-12345 at LOC001
+onHand = 95
+reserved = 15
+buffer = 5
+ATP = (95 - 15) - 5 = 75
+
+// Aggregated: SKU-12345 at LOC001
+totalOnHand = 100 + 95 = 195
+totalReserved = 20 + 15 = 35
+maxBuffer = max(5, 5) = 5
+finalATP = (195 - 35) - 5 = 155
+```
+
+---
+
+## Deployment
+
+```bash
+# Install dependencies
+npm install
+
+# Validate configuration
+npm run lint
+
+# Deploy to Versori
+versori deploy
+
+# View logs
+versori logs multi-channel-inventory-sync
+
+# Trigger manual sync
+versori run adhocMultiChannelSync
+```
+
+---
+
+## Testing
+
+### Test Scheduled Sync
+
+Upload test CSV files to S3/SFTP for each channel and wait for the scheduled run.
+
+**Check logs:**
+
+```
+[STEP 1/8] Initializing job tracking
+[STEP 2/8] Initializing Fluent Commerce client and data sources
+[STEP 3/8] Discovering files across channels
+[CHANNEL 1/3] Processing channel: CHANNEL_A
+[FILE 1/1] Processing file: channel-a-inventory_20250124.csv
+[STEP 4/8] Downloading and parsing: channel-a-inventory_20250124.csv
+[STEP 5/8] Transforming 5000 inventory records from channel-a-inventory_20250124.csv
+[STEP 6/8] Creating batch job and sending 5 batches to Fluent Commerce
+[STEP 7/8] Archiving file: channel-a-inventory_20250124.csv
+[STEP 8/8] Completing job and calculating totals
+```
+
+### Test Ad hoc Sync
+
+```bash
+# Sync all channels
+curl -X POST https://api.versori.com/webhooks/multi-channel-sync-adhoc \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Sync specific channel
+curl -X POST https://api.versori.com/webhooks/multi-channel-sync-adhoc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channelId": "CHANNEL_A"
+  }'
+
+# Sync with specific pattern
+curl -X POST https://api.versori.com/webhooks/multi-channel-sync-adhoc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filePattern": "urgent_*.csv",
+    "channelId": "CHANNEL_B"
+  }'
+```
+
+### Test Job Status Query
+
+```bash
+curl -X POST https://api.versori.com/webhooks/multi-channel-sync-job-status \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jobId": "ADHOC_MULTI_20251024_183045_abc123"
+  }'
+```
+
+### Verify Batch Jobs in Fluent
+
+After processing, check the Batch job status for each channel in Fluent Commerce:
+
+```bash
+# Query job status via GraphQL
+curl -X POST https://your-fluent-instance.com/graphql \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "query { job(id: \"job-123456\") { id status recordCount processedCount } }"
+  }'
+```
+
+---
+
+## Monitoring
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "channelsProcessed": 3,
+  "channelsFailed": 0,
+  "filesProcessed": 3,
+  "filesSkipped": 0,
+  "filesFailed": 0,
+  "results": [
+    {
+      "channel": "CHANNEL_A",
+      "file": "channel-a-inventory_2025-01-22.csv",
+      "success": true,
+      "recordCount": 5000,
+      "batchCount": 5,
+      "jobId": "job-123456",
+      "duration": 12345
+    },
+    {
+      "channel": "CHANNEL_B",
+      "file": "channel-b-inventory_2025-01-22.csv",
+      "success": true,
+      "recordCount": 3000,
+      "batchCount": 3,
+      "jobId": "job-123457",
+      "duration": 9876
+    },
+    {
+      "channel": "CHANNEL_C",
+      "file": "channel-c-inventory_2025-01-22.csv",
+      "success": true,
+      "recordCount": 2000,
+      "batchCount": 2,
+      "jobId": "job-123458",
+      "duration": 8765
+    }
+  ],
+  "duration": 13456
+}
+```
+
+### Partial Success Response
+
+```json
+{
+  "success": true,
+  "channelsProcessed": 2,
+  "channelsFailed": 1,
+  "filesProcessed": 2,
+  "filesSkipped": 0,
+  "filesFailed": 1,
+  "results": [
+    {
+      "channel": "CHANNEL_A",
+      "file": "channel-a-inventory_2025-01-22.csv",
+      "success": true,
+      "recordCount": 5000,
+      "batchCount": 5,
+      "jobId": "job-123456",
+      "duration": 12345
+    },
+    {
+      "channel": "CHANNEL_B",
+      "file": "channel-b-inventory_2025-01-22.csv",
+      "success": false,
+      "error": "CSV parse error: Invalid structure"
+    }
+  ],
+  "duration": 13456
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "channelsProcessed": 0,
+  "channelsFailed": 3,
+  "filesProcessed": 0,
+  "filesFailed": 3,
+  "results": [
+    {
+      "channel": "CHANNEL_A",
+      "file": "channel-a-inventory_2025-01-22.csv",
+      "success": false,
+      "error": "Data source connection failed"
+    }
+  ],
+  "duration": 876
+}
+```
+
+### Monitoring Metrics
+
+Monitor these metrics via Versori logs filtered by `jobId` or `stage`:
+
+- **Channels Processed** - Total channels successfully processed
+- **Files Processed** - Total files successfully processed across all channels
+- **Batch Jobs Created** - Total Batch jobs created in Fluent Commerce (one per channel)
+- **Processing Duration** - Time taken for complete multi-channel sync
+- **Channel Failures** - Channels that failed (check individual channel errors)
+
+Use the status webhook for dashboards and automated monitoring.
+
+---
+
+- 🎯 **TRUE modular architecture** - Separate service files with clear responsibilities
+- 🎯 **Graceful degradation** - Use `Promise.allSettled()` for partial channel failures
+- 🎯 **Delta detection** - Only sync changed records (reduces API load by 90%+)
+- 🎯 **External JSON mapping** - Use `with { type: 'json' }` import syntax
+- 🎯 **ATP calculation** - `ATP = (onHand - reserved) - buffer` with oversell protection
+- 🎯 **Rate limiting** - Enforce minimum interval between Channel A requests
+- 🎯 **Skip BPP** - Set `preprocessing: 'skip'` when using delta detection
+- 🎯 **Job tracking** - Use `JobTracker` for lifecycle management
+- 🎯 **Native logging** - Use `log` from context on Versori platform
+- 🎯 **EntityType: INVENTORY** - Correct entity type for inventory records
+- 🎯 **Error handling** - Log channel failures but don't block entire sync
+
+---
+
+## Related Documentation
+
+- **Single-source batch ingestion**: [SFTP XML Inventory Batch Template](./template-ingestion-sftp-xml-inventory-batch.md) - Simpler pattern for single data sources (GOLD STANDARD)
+- [Batch API Guide](../../../../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-06-batch-api.md) - Complete Batch API patterns and BPP documentation
+- [State Management](../../../../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md) - VersoriKVAdapter and StateService usage
+- [Job Tracker](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-job-tracker.md) - Job lifecycle tracking
+- [Universal Mapping](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) - Field transformation guide
+- [Error Handling Patterns](../../../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Retry logic and exponential backoff
+- [File Operations](../../../../../03-PATTERN-GUIDES/file-operations/file-operations-readme.md) - KV state management patterns
+- [GraphQL Extraction](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) - Auto-pagination for Fluent inventory queries
+
+---
+
+[→ Back to Versori Scheduled Workflows](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) | [Versori Platform Guide →](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)