@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md

@@ -1,2619 +1,2619 @@
----
-template_id: tpl-ingest-s3-csv-to-price-graphql
-canonical_filename: template-ingestion-s3-csv-price-graphql.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: s3-csv
-destination: fluent-graphql
-entity: price
-format: csv
-logging: versori
-status: stable
-features:
-  - graphql-mutation-mapper
-  - memory-management
-  - enhanced-logging
-  - attribute-transformation
-compliance: gold-standard
----
-
-# Template: Ingestion - S3 CSV to Price GraphQL
-n**Template Version:** 2.0.0
-**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
-**Last Updated:** 2025-01-24
-
-**🆕 Version 2.0.0 Enhancements:**
-- ✅ **GraphQL Mutation Mapper** - Direct field mapping to mutation variables
-- ✅ **Memory Management** - Clear large arrays after processing batches
-- ✅ **Enhanced Logging** - Track mutation execution with emoji indicators
-- ✅ **Attribute Transformation** - Handle complex nested data structures
-
-## STEP 1: What This Template Does
-
-This template provides a **scheduled Versori workflow** that:
-
-1. **Discovers CSV files** from S3 bucket with price data
-2. **Parses CSV** using `CSVParserService` with validation
-3. **Validates products exist** in Fluent Commerce before updating prices
-4. **Maps fields** using `GraphQLMutationMapper` with custom price validation resolvers
-5. **Updates prices** via direct GraphQL mutations (`updateProduct`)
-6. **Tracks price changes** for audit trail
-7. **Archives processed files** to prevent duplicates
-8. **Uses JobTracker** for job lifecycle management
-
-**Key Features:**
-- ✅ Direct GraphQL mutations (NOT Batch API)
-- ✅ Product existence validation before price updates
-- ✅ Price range validation (min/max checks)
-- ✅ Multi-tier pricing support (DEFAULT, SALE, CLEARANCE, BULK)
-- ✅ Configurable concurrency control (sequential or parallel)
-- ✅ Optional GraphQL alias batching for high-volume scenarios
-- ✅ Price change tracking and reporting
-- ✅ Versori KV state management (duplicate prevention)
-- ✅ File archival with error handling
-
-**Use Cases:**
-- Daily product price synchronization
-- Promotional price updates
-- Multi-currency pricing management
-- Quantity-based pricing tiers
-
-## STEP 2: Understanding This Template (AI Agent Guide)
-
-**🎯 Template Purpose:** Scheduled price synchronization from S3 CSV files to Fluent Commerce using direct GraphQL mutations.
-
-### Architecture Pattern
-
-```
-S3 CSV Files → CSVParserService → GraphQLMutationMapper → Product Validation → GraphQL Mutations → Archive
-   ↓       ↓          ↓         ↓          ↓       ↓
-File Discovery  Parsing     Field Mapping   Existence Check   updateProduct    Processed/
-Price Data   Validation    Price Validation  Active Status    Concurrency Ctrl   Error Dirs
-```
-
-### SDK Services Used
-
-| Service | Purpose | Key Methods |
-|---------|---------|-------------|
-| `createClient(ctx)` | Fluent API client | `client.graphql()` |
-| `S3DataSource` | S3 operations | `listFiles()`, `downloadFile()`, `moveFile()` |
-| `CSVParserService` | CSV parsing | `parse()` |
-| `GraphQLMutationMapper` | Field transformation | `map()` with custom resolvers |
-| `VersoriKVAdapter` | State management | `get()`, `set()`, `list()` |
-| `JobTracker` | Job lifecycle | `createJob()`, `updateJob()`, `markCompleted()`, `markFailed()`, `getJob()` |
-
-### Price Entity Structure
-
-**Fluent Commerce Price Schema:**
-```typescript
-{
- productRef: string;   // SKU reference (required)
- type: string;      // DEFAULT, SALE, CLEARANCE, BULK (required)
- value: number;      // Price amount (required, validated)
- currency: string;    // ISO 4217 code (USD, EUR, GBP)
- effectiveFrom?: string; // ISO 8601 date
- effectiveTo?: string;  // ISO 8601 date
- minQuantity?: number;  // Min qty for tier pricing
- maxQuantity?: number;  // Max qty for tier pricing
-}
-```
-
-### GraphQL Mutation Pattern
-
-**Mutation Used:** `updateProduct` (NOT Batch API)
-
-```graphql
-mutation UpdateProductPrice($input: UpdateProductInput!) {
- updateProduct(input: $input) {
-  id
-  ref
-  prices {
-   type
-   value
-   currency
-   effectiveFrom
-   effectiveTo
-   minQuantity
-   maxQuantity
-  }
- }
-}
-```
-
-**Why Direct Mutations?**
-- ✅ Immediate price updates (no batch processing delay)
-- ✅ Product validation before update
-- ✅ Price change tracking
-- ✅ Suitable for low-volume price updates (<1000/day)
-
-**NO BPP (Batch Pre-Processing):** Direct GraphQL mutations bypass batch workflows entirely.
-
-### Custom Resolvers
-
-**Three price-specific resolvers:**
-
-1. **`custom.validatePriceRange`** - Ensures price within min/max bounds
-2. **`custom.normalizePriceType`** - Validates price tier types
-3. **`custom.normalizeQuantity`** - Validates quantity ranges for BULK pricing
-
-### Product Validation Pattern
-
-**Critical Step:** Validate product exists and is ACTIVE before price update:
-
-```typescript
-async function validateProductExists(client, productRef, retailerId, log) {
- const query = `
-  query GetProduct($ref: String!, $retailerId: ID!) {
-   products(first: 1, ref: [$ref], retailerId: $retailerId) {
-    edges {
-     node { id ref status }
-    }
-   }
-  }
- `;
- const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
- const product = result?.data?.products?.edges?.[0]?.node;
- return product && product.status === 'ACTIVE';
-}
-```
-
-**Why?** Prevents GraphQL errors for non-existent products.
-
-### Concurrency Control & Performance
-
-**Mutation execution** supports two performance modes:
-
-**Mode 1: Concurrency Control (default)**
-```typescript
-// Configuration: Control concurrent mutations
-const mutationBatchSize = parseInt(
- activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
- 10
-);
-
-// Execute with bounded concurrency
-await executeMutations(
- client,
- mapper,
- priceRecords,
- retailerId,
- validateProducts,
- mutationBatchSize, // 1=sequential, 3-10=parallel
- undefined,     // No alias batching
- log
-);
-```
-
-**Mode 2: GraphQL Alias Batching (optional, high-volume)**
-```typescript
-// Configuration: Group mutations into aliased requests
-const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
- ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
- : undefined; // Default: undefined (disabled)
-
-// Execute with alias batching (reduces network overhead by ~80%)
-await executeMutations(
- client,
- mapper,
- priceRecords,
- retailerId,
- validateProducts,
- mutationBatchSize,      // Concurrency control
- mutationsPerAliasBatch,   // Alias batching (e.g., 5)
- log
-);
-```
-
-**Activation Variables:**
-- `mutationBatchSize=1` - Default: sequential (safe)
-- `mutationBatchSize=3-5` - Balanced throughput
-- `mutationBatchSize=10` - High-volume (100+ locations)
-- `mutationsPerAliasBatch` - Optional: Group mutations (e.g., 5 per request)
-
-### State Management
-
-**VersoriKVAdapter** prevents duplicate file processing:
-
-```typescript
-const stateKey = ['processed-files', 's3-price-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) {
- log.info('Skipping already processed file', { fileName });
- continue;
-}
-// After success:
-await kv.set(stateKey, { successful, failed, processedAt: new Date().toISOString() });
-```
-
-### JobTracker Integration
-
-**Job lifecycle tracking:**
-
-```typescript
-const tracker = new JobTracker(openKv(':project:'), log);
-await tracker.startJob(jobId, { mode: 'scheduled' });
-try {
- const result = await runPriceCsvWorkflow(ctx, jobId, tracker);
- await tracker.completeJob(jobId, { result });
-} catch (e) {
- await tracker.failJob(jobId, { error: e.message });
-}
-```
-
-### Price Change Tracking
-
-**Audit trail for price updates:**
-
-```typescript
-const currentPrice = await getCurrentPrice(client, productRef, priceType, currency, retailerId);
-// ... after update ...
-if (currentPrice !== undefined && currentPrice !== priceData.value) {
- results.priceChanges.push({
-  sku: priceData.productRef,
-  type: priceData.type,
-  oldPrice: currentPrice,
-  newPrice: priceData.value,
- });
-}
-// Log changes at end:
-log.info('Price changes detected', { count: results.priceChanges.length, changes });
-```
-
-### Schema Validation (CLI Commands)
-
-**Before deployment, validate GraphQL schema:**
-
-```bash
-# 1. Introspect Fluent schema
-fc-connect introspect-schema \
- --url https://api.fluentcommerce.com/graphql \
- --client-id CLIENT_ID \
- --client-secret CLIENT_SECRET \
- --output fluent-schema.json
-
-# 2. Create mutation file
-cat > price-mutation.graphql << 'EOF'
-mutation UpdateProductPrice($input: UpdateProductInput!) {
- updateProduct(input: $input) {
-  id
-  ref
-  prices { type value currency }
- }
-}
-EOF
-
-# 3. Generate mapping from mutation
-fc-connect generate-mutation-mapping \
- --file price-mutation.graphql \
- --output price-mapping.json
-
-# 4. Validate mapping against schema
-fc-connect validate-schema \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-
-# 5. Analyze field coverage
-fc-connect analyze-coverage \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-```
-
-### Configuration File Structure
-
-**Mapping Config:** `config/price-mapping.json`
-
-**✅ PRODUCTION STANDARD:** External JSON file with GraphQLMutationMapper structure
-
-```json
-{
- "mutation": "updateProduct",
- "sourceFormat": "csv",
- "version": "1.0.0",
- "arguments": {
-  "input": {
-   "ref": {
-    "source": "sku",
-    "required": true,
-    "resolver": "trim"
-   },
-   "prices": {
-    "type": {
-     "source": "priceType",
-     "required": true,
-     "resolver": "normalizePriceType"
-    },
-    "value": {
-     "source": "amount",
-     "required": true,
-     "resolver": "validatePriceRange"
-    },
-    "currency": {
-     "source": "currency",
-     "required": true,
-     "resolver": "toUpperCase"
-    },
-    "effectiveFrom": {
-     "source": "effectiveDate",
-     "resolver": "formatDate"
-    },
-    "effectiveTo": {
-     "source": "expiryDate",
-     "resolver": "formatDate"
-    },
-    "minQuantity": {
-     "source": "minQuantity",
-     "resolver": "normalizeQuantity"
-    },
-    "maxQuantity": {
-     "source": "maxQuantity",
-     "resolver": "normalizeQuantity"
-    }
-   }
-  }
- }
-}
-```
-
-**Key Differences from UniversalMapper:**
-- ✅ `mutation` property (not `mutationName`)
-- ✅ `arguments.input` structure (matches GraphQL schema)
-- ✅ Nested `prices` object (not flat productRef/type/value)
-- ✅ Resolver names without `sdk.` or `custom.` prefix (`trim`, `toUpperCase`, `formatDate`)
-- ✅ Used with `GraphQLMutationMapper.map()` method (not `UniversalMapper.map()`)
-
-### Activation Variables Required
-
-**Minimum Required:**
-- `s3BucketName` - S3 bucket with price CSV files
-- `awsAccessKeyId` - AWS credentials
-- `awsSecretAccessKey` - AWS credentials
-
-**Optional (with defaults):**
-- `awsRegion=us-east-1`
-- `s3Prefix=prices/`
-- `archivePrefix=processed/`
-- `errorPrefix=errors/`
-- `logPrefix=logs/` - Where to write mutation logs
-- `maxFilesToProcess=10`
-- `mutationBatchSize=1` - Number of concurrent mutations (1=sequential, 3-10=parallel)
-- `mutationsPerAliasBatch` - Optional: Number of mutations per aliased request (default: undefined = disabled)
-- `minPrice=0.01`
-- `maxPrice=999999.99`
-- `validateProducts=true`
-- `validateConnection=true` - Validate S3 connection at startup
-- `enableFileTracking=true` - Enable file tracking via VersoriFileTracker
-- `fluentRetailerId` - Optional: Only if mutation schema requires retailerId in input (most Price mutations don't need it)
-
-### Error Handling Patterns
-
-**Three-level error handling:**
-
-1. **Mapping errors** - Invalid price data (validation failures)
-2. **GraphQL errors** - Mutation failures (product not found, invalid fields)
-3. **File processing errors** - S3 access issues, CSV parsing failures
-
-**Error state tracking with exponential backoff:**
-```typescript
-const errorKey = ['error-state', fileName];
-const attempts = (prev?.attemptCount || 0) + 1;
-const backoffMinutes = Math.min(Math.pow(2, attempts) * 5, 24 * 60);
-const nextRetryAt = new Date(Date.now() + backoffMinutes * 60000).toISOString();
-```
-
-### Common Pitfalls
-
-**❌ WRONG Patterns:**
-- Using Batch API for price updates (overhead, delay)
-- Using `UniversalMapper` instead of `GraphQLMutationMapper`
-- Calling `client.setRetailerId()` for GraphQL mutations (only needed for Job/Event API)
-- Skipping product validation (causes GraphQL errors)
-- No concurrency control (API throttling)
-- Hardcoded price validation rules (not configurable)
-- Missing price change tracking (no audit trail)
-
-**✅ CORRECT Patterns:**
-- Direct GraphQL mutations for immediate updates
-- `GraphQLMutationMapper` with nested mapping structure
-- NO `setRetailerId()` call (pass in mutation input if schema requires it)
-- Product existence validation before updates
-- Configurable concurrency control (mutationBatchSize)
-- Optional alias batching for high-volume scenarios
-- Custom resolvers for price validation
-- Price change tracking for audit
-- VersoriKVAdapter for state management
-- JobTracker for job lifecycle
-
-### Testing Checklist
-
-**Before deployment:**
-- [ ] S3 credentials validated (IAM permissions: ListBucket, GetObject, PutObject, DeleteObject)
-- [ ] GraphQL schema validated using CLI tools
-- [ ] Mapping configuration uses GraphQLMutationMapper structure (nested objects, not flat fields)
-- [ ] Mapping configuration tested with sample CSV
-- [ ] Product validation working (queries products endpoint)
-- [ ] Price validation rules configured (min/max bounds)
-- [ ] Concurrency control configured (mutationBatchSize)
-- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
-- [ ] NO setRetailerId() call present (only for Job/Event API)
-- [ ] File duplicate prevention working (KV state)
-- [ ] Price change tracking verified (logs price changes)
-- [ ] Error handling tested (malformed CSV, invalid products)
-- [ ] File archival working (processed/ and errors/ directories)
-
-### Related Documentation
-
-- **Core Guides:** `docs/02-CORE-GUIDES/ingestion/modules/`
-- **Universal Mapping:** `docs/02-CORE-GUIDES/mapping/modules/`
-- **CLI Tools:** `fc-connect-sdk/bin/readme.md`
-- **State Management:** `docs/03-PATTERN-GUIDES/file-operations/`
-- **Error Handling:** `docs/03-PATTERN-GUIDES/error-handling/`
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Scheduled Versori workflow that reads product price CSV files from S3 and creates/updates Fluent Commerce product prices via GraphQL mutations
-
-**Complexity**: Medium-High
-
-**Runtime**: Versori Platform (Scheduled)
-
-**Estimated Lines**: ~700 lines
-
-## What You'll Build
-
-- Versori scheduled workflow (cron trigger)
-- S3 file listing and download with retry logic
-- CSV parsing with validation
-- UniversalMapper for price field transformations
-- Product existence validation before price updates
-- GraphQL mutations for price upserts with rate limiting
-- Versori KV state management (duplicate prevention)
-- Price change tracking and reporting
-- File archival after processing
-
-## 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
-
-```
-s3-csv-price-graphql/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-price-sync.ts       # Scheduled: Daily price sync
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-price-sync.ts       # Webhook: Manual trigger
-    │       └── job-status-check.ts       # Webhook: Status query
-    │
-    ├── services/
-    │   └── price-sync.service.ts         # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── price-mapping.json            # GraphQL mapping config
-```
-
----
-
-## Workflow Files
-
-### 1. Scheduled Workflows (`src/workflows/scheduled/`)
-
-All time-based triggers that run automatically on cron schedules.
-
-#### `src/workflows/scheduled/daily-price-sync.ts`
-
-**Purpose**: Automatic daily price 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 { executePriceSync } from '../../services/price-sync.service';
-
-/**
- * Scheduled Workflow: Daily Price Sync
- *
- * Runs automatically daily at 2 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Uses shared service: price-sync.service.ts
- */
-export const dailyPriceSync = schedule(
-  'price-sync-scheduled',
-  '0 2 * * *' // Daily at 2 AM UTC
-).then(
-  http('run-price-sync', { connection: 'fluent_commerce' }, async (ctx: any) => {
-    const { log, openKv } = ctx;
-    const jobId = `price-sync-${Date.now()}`;
-    const executionStartTime = Date.now();
-    const tracker = new JobTracker(openKv(':project:'), log);
-
-    log.info('🔄 [WORKFLOW] Starting price sync', { jobId });
-
-    await tracker.createJob(jobId, {
-      triggeredBy: 'schedule',
-      stage: 'initialization',
-      startTime: executionStartTime,
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-
-    try {
-      const result = await executePriceSync(ctx, jobId, tracker);
-
-      if (result.success) {
-        await tracker.markCompleted(jobId, result);
-        log.info('✅ [WORKFLOW] Price sync completed', {
-          jobId,
-          filesProcessed: result.filesProcessed,
-          duration: result.duration,
-        });
-      } else {
-        await tracker.markFailed(jobId, result.error || 'Unknown error');
-        log.error('❌ [WORKFLOW] Price sync failed', { jobId, error: result.error });
-      }
-
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      const errorMessage = e instanceof Error ? e.message : String(e);
-      await tracker.markFailed(jobId, errorMessage);
-      log.error('❌ [WORKFLOW] Price sync failed with exception', {
-        jobId,
-        error: errorMessage,
-        stack: e instanceof Error ? e.stack : undefined,
-      });
-      return { success: false, jobId, error: errorMessage };
-    }
-  })
-);
-```
-
----
-
-### 2. Webhook Workflows (`src/workflows/webhook/`)
-
-All HTTP-based triggers that create webhook endpoints.
-
-#### `src/workflows/webhook/adhoc-price-sync.ts`
-
-**Purpose**: Manual price sync trigger (on-demand)
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/price-sync-adhoc`
-**Use Cases**: Testing, priority processing, ad-hoc runs
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { executePriceSync } from '../../services/price-sync.service';
-
-/**
- * Webhook: Manual Price Sync Trigger
- *
- * Endpoint: POST https://{workspace}.versori.run/price-sync-adhoc
- * Request body (optional): { filePattern: "urgent_*.csv", maxFiles: 5 }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: price-sync.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const adhocPriceSync = webhook('price-sync-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'price-sync-adhoc', // Versori validates API key
-}).then(
-  http('run-price-sync-adhoc', { connection: 'fluent_commerce' }, async (ctx: any) => {
-    const { log, openKv, data } = ctx;
-    const jobId = `price-sync-adhoc-${Date.now()}`;
-    const executionStartTime = Date.now();
-    const tracker = new JobTracker(openKv(':project:'), log);
-
-    log.info('🔄 [WEBHOOK] Starting adhoc price sync', { jobId });
-
-    await tracker.createJob(jobId, {
-      triggeredBy: 'manual',
-      stage: 'initialization',
-      startTime: executionStartTime,
-      options: data // Optional: filePattern, maxFiles, etc.
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-
-    try {
-      const result = await executePriceSync(ctx, jobId, tracker);
-
-      if (result.success) {
-        await tracker.markCompleted(jobId, result);
-        log.info('✅ [WEBHOOK] Adhoc price sync completed', {
-          jobId,
-          filesProcessed: result.filesProcessed,
-          duration: result.duration,
-        });
-      } else {
-        await tracker.markFailed(jobId, result.error || 'Unknown error');
-        log.error('❌ [WEBHOOK] Adhoc price sync failed', { jobId, error: result.error });
-      }
-
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      const errorMessage = e instanceof Error ? e.message : String(e);
-      await tracker.markFailed(jobId, errorMessage);
-      log.error('❌ [WEBHOOK] Adhoc price sync failed with exception', {
-        jobId,
-        error: errorMessage,
-        stack: e instanceof Error ? e.stack : undefined,
-      });
-      return { success: false, jobId, error: errorMessage };
-    }
-  })
-);
-```
-
----
-
-#### `src/workflows/webhook/job-status-check.ts`
-
-**Purpose**: Query job status
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/price-sync-job-status`
-**Request body**: `{ "jobId": "price-sync-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/price-sync-job-status
- * Request body: { "jobId": "price-sync-1234567890" }
- *
- * Pattern: webhook().then(fn()) - no external API needed, only KV storage
- * Lightweight: Only queries KV store, no Fluent API calls
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const priceSyncJobStatus = webhook('price-sync-job-status', {
-  response: { mode: 'sync' },
-  connection: 'price-sync-job-status',
-}).then(
-  fn('status', async (ctx: any) => {
-    const { data, log, openKv } = ctx;
-    const jobId = data?.jobId as string;
-
-    log.info('🔍 [STATUS] Checking job status', { jobId });
-
-    if (!jobId) {
-      log.warn('❌ [STATUS] Missing jobId in request');
-      return { success: false, error: 'jobId required' };
-    }
-
-    const tracker = new JobTracker(openKv(':project:'), log);
-    const status = await tracker.getJob(jobId);
-
-    if (status) {
-      log.info('✅ [STATUS] Job found', { jobId, status: status.status });
-      return { success: true, jobId, ...status };
-    } else {
-      log.warn('❌ [STATUS] Job not found', { jobId });
-      return { 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 { dailyPriceSync } from './workflows/scheduled/daily-price-sync';
-
-// Import webhook workflows
-import { adhocPriceSync } from './workflows/webhook/adhoc-price-sync';
-import { priceSyncJobStatus } from './workflows/webhook/job-status-check';
-
-// Register all workflows
-export {
-  // Scheduled (time-based triggers)
-  dailyPriceSync,
-
-  // Webhooks (HTTP-based triggers)
-  adhocPriceSync,
-  priceSyncJobStatus,
-};
-```
-
-**What Gets Exposed:**
-- ✅ `adhocPriceSync` → `https://{workspace}.versori.run/price-sync-adhoc`
-- ✅ `priceSyncJobStatus` → `https://{workspace}.versori.run/price-sync-job-status`
-- ❌ `dailyPriceSync` → NOT exposed (runs automatically on cron)
-
----
-
-## SDK Methods Used
-
-**Core Services:**
-- `createClient(ctx)` - Create Fluent client (auto-detects Versori context)
-- `S3DataSource(config, log)` - S3 operations (list, download, upload, move)
-- `CSVParserService()` - CSV parsing with validation
-- `GraphQLMutationMapper(mappingConfig, log, { fluentClient: client })` - Field mapping with schema validation
-- `VersoriKVAdapter(openKv(':project:'))` - KV state management for duplicate prevention
-
-**Key Methods:**
-- `s3.listFiles({ prefix, maxKeys })` - List S3 files
-- `s3.downloadFile(path, options)` - Download file content
-- `s3.uploadFile(path, content)` - Upload file (accepts string or Buffer)
-- `s3.moveFile(source, dest)` - Archive or move file
-- `parser.parse(content, options)` - Parse CSV to records
-- `mapper.map(record)` - Transform single record
-- `client.graphql({ query, variables })` - Execute GraphQL mutations/queries
-- `kv.get(key)` / `kv.set(key, value)` - State management
-
-**Critical Imports:**
-- `Buffer` - **Required for Versori/Deno runtime** (S3 upload operations)
- ```typescript
- import { Buffer } from 'node:buffer';
- ```
- **Why:** Deno runtime (used by Versori) does not have `Buffer` as a global. However, `uploadFile()` accepts string or Buffer, so you can use strings directly without Buffer conversion.
-
-**Service Functions (User-Defined):**
-- `processFile()` - S3 download + CSV parsing + field mapping
-- `executeMutations()` - GraphQL price updates with validation + rate limiting
-- `writeMutationLog()` - Write execution log to S3 (uses Buffer)
-
-## Sample CSV Input Data
-
-**File**: `product-prices-20250122-001.csv`
-
-```csv
-sku,priceType,amount,currency,effectiveDate,expiryDate,minQuantity,maxQuantity
-PROD-001,DEFAULT,29.99,USD,2025-01-22T00:00:00Z,,1,
-PROD-002,SALE,19.99,USD,2025-01-22T00:00:00Z,2025-02-15T23:59:59Z,1,
-PROD-003,CLEARANCE,9.99,USD,2025-01-22T00:00:00Z,2025-01-31T23:59:59Z,1,
-PROD-004,DEFAULT,149.99,USD,2025-01-22T00:00:00Z,,1,
-PROD-004,BULK,129.99,USD,2025-01-22T00:00:00Z,,10,99
-PROD-004,BULK,119.99,USD,2025-01-22T00:00:00Z,,100,
-```
-
-**Note**: Products can have multiple price tiers. Same SKU with different `priceType` or quantity ranges = multiple rows.
-
-**Field Mapping**:
-
-- `sku` → Product reference (required) - must exist in Fluent
-- `priceType` → Price tier (DEFAULT, SALE, CLEARANCE, BULK, etc.) (required)
-- `amount` → Price value (required, must be > 0)
-- `currency` → Currency code (USD, EUR, GBP, etc.) (required)
-- `effectiveDate` → When price becomes active (ISO 8601 format)
-- `expiryDate` → When price expires (optional, ISO 8601 format)
-- `minQuantity` → Minimum quantity for this price tier (optional, default: 1)
-- `maxQuantity` → Maximum quantity for this price tier (optional)
-
-**Price Tier Logic**:
-
-- **DEFAULT**: Standard retail price (most products)
-- **SALE**: Temporary promotional price
-- **CLEARANCE**: Final markdown price
-- **BULK**: Quantity-based pricing (requires minQuantity/maxQuantity)
-
-## Project Setup
-
-```bash
-mkdir versori-s3-csv-price-sync && cd $_
-npm init -y
-npm install @fluentcommerce/fc-connect-sdk@latest @versori/run
-mkdir -p src
-```
-
-### Package Configuration (package.json)
-
-```json
-{
- "name": "versori-s3-csv-price-sync",
- "version": "1.0.0",
- "description": "Versori workflow: S3 CSV price sync to Fluent GraphQL",
- "versori": {
-  "workflows": "./src/index.ts"
- },
- "type": "module",
- "scripts": {
-  "deploy": "versori deploy",
-  "logs": "versori logs"
- },
- "dependencies": {
-  "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-  "@versori/run": "latest"
- },
- "devDependencies": {
-  "typescript": "^5.0.0",
-  "@types/node": "^20.0.0"
- }
-}
-```
-
-### Activation Variables (Versori)
-
-```bash
-# Required Variables
-s3BucketName=my-price-bucket
-awsAccessKeyId=AKIAXXXXXXXXXXXX
-awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-retailerId=your-retailer-id
-
-# Optional Variables (with defaults shown)
-awsRegion=us-east-1
-s3Prefix=prices/
-archivePrefix=processed/
-errorPrefix=errors/
-logPrefix=logs/       # Where to write mutation logs
-maxFilesToProcess=10
-filePattern=.csv
-enableArchival=true
-mutationRateLimit=10
-
-# Price Validation Rules
-minPrice=0.01       # Minimum allowed price
-maxPrice=999999.99     # Maximum allowed price
-validateProducts=true   # Validate products exist before updating prices
-```
-
-## Complete Workflow (src/index.ts)
-
-```typescript
-import { schedule, webhook, http, fn } from '@versori/run';
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
-import {
- createClient,
- S3DataSource,
- CSVParserService,
- GraphQLMutationMapper,
- VersoriFileTracker,
- JobTracker,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// ============================================================================
-// Type Definitions
-// ============================================================================
-
-interface FileProcessingResult {
- fileName: string;
- successful: number;
- failed: number;
- validationFailed: number;
- priceChanges: Array<{
-  sku: string;
-  type: string;
-  oldPrice?: number;
-  newPrice: number;
- }>;
- errors: string[];
-}
-
-interface MutationResult {
- successful: number;
- failed: number;
- priceChanges: Array<{
-  sku: string;
-  type: string;
-  oldPrice?: number;
-  newPrice: number;
- }>;
-}
-
-interface MappedPriceData {
- productRef: string;
- type: string;
- value: number;
- currency: string;
- effectiveFrom?: string;
- effectiveTo?: string;
- minQuantity?: number;
- maxQuantity?: number;
-}
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-/**
- * Retry utility with exponential backoff
- * (User-defined - not part of SDK public API)
- */
-async function retryWithBackoff<T>(
- operation: () => Promise<T>,
- maxRetries = 3,
- baseDelayMs = 1000
-): Promise<T> {
- let lastError: any;
- for (let attempt = 0; attempt < maxRetries; attempt++) {
-  try {
-   return await operation();
-  } catch (error) {
-   lastError = error;
-   if (attempt < maxRetries - 1) {
-    const delay = baseDelayMs * Math.pow(2, attempt) + Math.floor(Math.random() * 200);
-    await new Promise(resolve => setTimeout(resolve, delay));
-   }
-  }
- }
- throw lastError;
-}
-
-/**
- * Validate product exists in Fluent Commerce
- */
-async function validateProductExists(
- client: any,
- productRef: string,
- retailerId: string,
- log: any
-): Promise<boolean> {
- const query = `
-  query GetProduct($ref: String!, $retailerId: ID!) {
-   products(first: 1, ref: [$ref], retailerId: $retailerId) {
-    edges {
-     node {
-      id
-      ref
-      status
-     }
-    }
-   }
-  }
- `;
-
- try {
-  const result = await client.graphql({
-   query,
-   variables: { ref: productRef, retailerId },
-  });
-
-  const product = result?.data?.products?.edges?.[0]?.node;
-  if (!product) {
-   log.warn(`Product not found: ${productRef}`);
-   return false;
-  }
-
-  if (product.status !== 'ACTIVE') {
-   log.warn(`Product not active: ${productRef} (status: ${product.status})`);
-   return false;
-  }
-
-  return true;
- } catch (error: unknown) {
-  // ✅ Enhanced error logging: Extract all error details for visibility
-  const errorMsg = error instanceof Error ? error.message : String(error);
-  const errorDetails = {
-   message: errorMsg,
-   stack: error instanceof Error ? error.stack : undefined,
-   errorType: error instanceof Error ? error.constructor.name : 'Error',
-  };
-  log.error(`Failed to validate product: ${productRef}`, errorDetails);
-  return false;
- }
-}
-
-/**
- * Get current product price for change tracking
- */
-async function getCurrentPrice(
- client: any,
- productRef: string,
- priceType: string,
- currency: string,
- retailerId: string
-): Promise<number | undefined> {
- try {
-  const query = `
-   query GetProductPrice($ref: String!, $retailerId: ID!) {
-    products(first: 1, ref: [$ref], retailerId: $retailerId) {
-     edges {
-      node {
-       id
-       ref
-       prices {
-        type
-        value
-        currency
-       }
-      }
-     }
-    }
-   }
-  `;
-
-  const result = await client.graphql({
-   query,
-   variables: { ref: productRef, retailerId },
-  });
-
-  const product = result?.data?.products?.edges?.[0]?.node;
-  if (product?.prices) {
-   const existingPrice = product.prices.find(
-    (p: any) => p.type === priceType && p.currency === currency
-   );
-   if (existingPrice) {
-    return existingPrice.value;
-   }
-  }
- } catch (err) {
-  // Ignore - price change tracking is optional
- }
- return undefined;
-}
-
-// ============================================================================
-// Service Function 1: Process File (S3 + CSV + Mapper)
-// ============================================================================
-
-/**
- * Process single CSV file: Download from S3, parse CSV, map fields to Price schema
- *
- * @param s3 - S3DataSource instance
- * @param parser - CSVParserService instance
- * @param mapper - UniversalMapper instance (with custom price resolvers)
- * @param filePath - S3 file path
- * @param fileName - File name
- * @param log - Logger instance
- * @returns FileProcessingResult with parsed and mapped price data
- */
-async function processFile(
- s3: S3DataSource,
- parser: CSVParserService,
- mapper: GraphQLMutationMapper,
- filePath: string,
- fileName: string,
- log: any
-): Promise<{ records: Array<{ query: string; variables: any; input: any }>; errors: string[] }> {
- log.info('Processing file', { fileName });
-
- // Download CSV from S3 with retry
- const content = await retryWithBackoff(
-  () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
- );
-
- // Parse CSV
- const rawRecords = await parser.parse(content, {
-  columns: true,
-  skip_empty_lines: true,
-  trim: true,
- });
-
- if (!rawRecords.length) {
-  log.warn('Empty CSV file', { fileName });
-  return { records: [], errors: [] };
- }
-
- log.info('CSV parsed', { fileName, recordCount: rawRecords.length });
-
- // Map CSV records to Price schema
-  const mappedRecords: Array<{ query: string; variables: any; input: any }> = [];
-  const errors: string[] = [];
-
-  // ✅ PRODUCTION ENHANCEMENT: Log transformation start
-  log.info('Transforming records to GraphQL mutations', {
-   fileName,
-   totalRecords: rawRecords.length,
-  });
-
-  for (let i = 0; i < rawRecords.length; i++) {
-   const rec = rawRecords[i];
-   const recordNumber = i + 1;
-
-   // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 records
-   if (recordNumber % 50 === 0) {
-    log.info(`📤 Transforming record ${recordNumber}/${rawRecords.length}`, {
-     fileName,
-     recordNumber,
-     totalRecords: rawRecords.length,
-     validSoFar: mappedRecords.length,
-     errorsSoFar: errors.length,
-     progress: `${((recordNumber / rawRecords.length) * 100).toFixed(1)}%`,
-    });
-   }
-
-   try {
-    // GraphQLMutationMapper returns { query, variables } directly
-    const mapped = await mapper.map(rec);
-    
-    mappedRecords.push({
-     query: mapped.query,
-     variables: mapped.variables,
-     input: mapped.variables.input || mapped.variables,
-    });
-   } catch (error: unknown) {
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    errors.push(`Row ${recordNumber}: ${errorMsg}`);
-   }
-  }
-
- log.info('Mapping completed', {
-  fileName,
-  successful: mappedRecords.length,
-  failed: errors.length,
-  totalRecords: rawRecords.length,
-  successRate: `${((mappedRecords.length / rawRecords.length) * 100).toFixed(1)}%`,
- });
-
- return { records: mappedRecords, errors };
-}
-
-// ============================================================================
-// Service Function 2: Execute Mutations (GraphQL Price Updates)
-// ============================================================================
-
-/**
- * Execute GraphQL mutations for price updates with validation and rate limiting
- * ✅ Supports alias batching for improved performance
- *
- * @param client - FluentClient instance
- * @param mapper - GraphQLMutationMapper instance
- * @param priceRecords - Mapped price data with query and variables
- * @param retailerId - Fluent retailer ID
- * @param validateProducts - Whether to validate product existence
- * @param batchSize - Number of concurrent requests (concurrency control)
- * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (alias batching)
- * @param log - Logger instance
- * @returns MutationResult with success/failure counts and price changes
- */
-async function executeMutations(
- client: any,
- mapper: GraphQLMutationMapper,
- priceRecords: Array<{ query: string; variables: any; input: any }>,
- retailerId: string,
- validateProducts: boolean,
- batchSize: number = 1, // ✅ Default: 1 (sequential)
- mutationsPerAliasBatch?: number, // ✅ NEW: Alias batching parameter (default: undefined = disabled)
- log: any
-): Promise<MutationResult> {
- let successful = 0;
- let failed = 0;
- const priceChanges: Array<{
-  sku: string;
-  type: string;
-  oldPrice?: number;
-  newPrice: number;
- }> = [];
-
- // ✅ Use alias batching if enabled
- const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
-
- if (useAliases) {
-  // Process with alias batching
-  const results = await executeMutationsWithAliases(
-   priceRecords,
-   client,
-   mapper,
-   log,
-   retailerId,
-   batchSize,
-   mutationsPerAliasBatch,
-   'updateProduct'
-  );
-  successful = results.executed;
-  failed = results.failed;
-  // Note: Price changes tracking would need to be done separately if needed
- } else {
-  // Process individually with validation
-  for (const priceData of priceRecords) {
-   try {
-    // Validate product exists (if enabled)
-    if (validateProducts) {
-     const productExists = await validateProductExists(
-      client,
-      priceData.input.productRef,
-      retailerId,
-      log
-     );
-
-     if (!productExists) {
-      log.warn(`Skipping price update for non-existent product: ${priceData.input.productRef}`);
-      failed++;
-      continue;
-     }
-    }
-
-    // Get current price for change tracking
-    const currentPrice = await getCurrentPrice(
-     client,
-     priceData.input.productRef,
-     priceData.input.type,
-     priceData.input.currency,
-     retailerId
-    );
-
-    // Execute mutation using pre-generated query and variables
-    await retryWithBackoff(() =>
-     client.graphql({
-      query: priceData.query,
-      variables: priceData.variables,
-     })
-    );
-
-    successful++;
-
-    // Track price change
-    if (currentPrice !== undefined && currentPrice !== priceData.input.value) {
-     priceChanges.push({
-      sku: priceData.input.productRef,
-      type: priceData.input.type,
-      oldPrice: currentPrice,
-      newPrice: priceData.input.value,
-     });
-    }
-
-    log.info('Price updated', {
-     ref: priceData.input.productRef,
-     type: priceData.input.type,
-     oldPrice: currentPrice,
-     newPrice: priceData.input.value,
-     currency: priceData.input.currency,
-    });
-   } catch (error: unknown) {
-    failed++;
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    const errorDetails = {
-     message: errorMsg,
-     stack: error instanceof Error ? error.stack : undefined,
-     errorType: error instanceof Error ? error.constructor.name : 'Error',
-    };
-    log.error('Failed to update price', errorDetails, {
-     ref: priceData.input?.productRef,
-     type: priceData.input?.type,
-    });
-   }
-  }
- }
-
- return { successful, failed, priceChanges };
-}
-
-/**
- * ✅ NEW: Execute mutations with GraphQL alias batching
- */
-async function executeMutationsWithAliases(
- priceRecords: Array<{ query: string; variables: any; input: any }>,
- client: any,
- mapper: GraphQLMutationMapper,
- log: any,
- retailerId: string,
- maxParallel: number,
- mutationsPerAliasBatch: number,
- mutationName: string
-): Promise<{ executed: number; failed: number; errors: string[] }> {
- const results = { executed: 0, failed: 0, errors: [] as string[] };
- 
- const aliasBatches: Array<Array<typeof priceRecords[0]>> = [];
- for (let i = 0; i < priceRecords.length; i += mutationsPerAliasBatch) {
-  aliasBatches.push(priceRecords.slice(i, i + mutationsPerAliasBatch));
- }
- 
- log.info(`Processing ${aliasBatches.length} alias batches`, {
-  totalPrices: priceRecords.length,
-  maxParallel,
- });
- 
- for (let i = 0; i < aliasBatches.length; i += maxParallel) {
-  const concurrentBatches = aliasBatches.slice(i, i + maxParallel);
-  
-  const batchResults = await Promise.allSettled(
-   concurrentBatches.map(async (batch) => {
-    const { query, variables } = buildAliasedBatch(batch, mutationName, retailerId);
-    const response = await retryWithBackoff(() => client.graphql({ query, variables }), log);
-    return parseAliasResponse(response, batch, mutationName);
-   })
-  );
-  
-  batchResults.forEach((result, idx) => {
-   if (result.status === 'fulfilled') {
-    const batchResult = result.value;
-    results.executed += batchResult.executed;
-    results.failed += batchResult.failed;
-    results.errors.push(...batchResult.errors);
-   } else {
-    const batch = concurrentBatches[idx];
-    const errorMsg = result.reason instanceof Error ? result.reason.message : String(result.reason);
-    batch.forEach(price => {
-     results.failed++;
-     const productRef = price.input?.productRef || 'unknown';
-     results.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
-    });
-   }
-  });
-  
-  if (i + maxParallel < aliasBatches.length) {
-   await new Promise(resolve => setTimeout(resolve, 500));
-  }
- }
- 
- return results;
-}
-
-/**
- * ✅ NEW: Build aliased batch query and variables
- */
-function buildAliasedBatch(
- batch: Array<{ query: string; variables: any; input: any }>,
- mutationName: string,
- retailerId: string
-): { query: string; variables: Record<string, any> } {
- const batchSize = batch.length;
- const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
- 
- const variables = Array.from({ length: batchSize }, (_, i) => 
-  `$input${i + 1}: ${inputTypeName}!`
- ).join(', ');
- 
- const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
-  const alias = `${mutationName}${i + 1}`;
-  return ` ${alias}: ${mutationName}(input: $input${i + 1}) { id ref }`;
- }).join('\n');
- 
- const operationName = `Batch${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}s`;
- const query = `mutation ${operationName}(${variables}) {\n${aliasedMutations}\n}`;
- 
- const variablesObj: Record<string, any> = {};
- batch.forEach((price, index) => {
-  const input = price.variables.input || price.variables;
-  variablesObj[`input${index + 1}`] = input;
- });
- 
- return { query, variables: variablesObj };
-}
-
-/**
- * ✅ NEW: Parse aliased GraphQL response
- */
-function parseAliasResponse(
- response: any,
- batch: Array<{ query: string; variables: any; input: any }>,
- mutationName: string
-): { executed: number; failed: number; errors: string[] } {
- const result = { executed: 0, failed: 0, errors: [] as string[] };
- 
- const data = response.data || {};
- const errors = response.errors || [];
- 
- batch.forEach((price, index) => {
-  const alias = `${mutationName}${index + 1}`;
-  const aliasData = data[alias];
-  const aliasErrors = errors.filter((e: unknown) => 
-   e && typeof e === 'object' && 'path' in e && Array.isArray((e as any).path) && (e as any).path.includes(alias)
-  );
-  
-  if (aliasData && !aliasErrors.length) {
-   result.executed++;
-  } else {
-   result.failed++;
-   const errorMsg = aliasErrors[0] && typeof aliasErrors[0] === 'object' && 'message' in aliasErrors[0]
-    ? String((aliasErrors[0] as any).message)
-    : 'Mutation failed';
-   const productRef = price.input?.productRef || 'unknown';
-   result.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
-  }
- });
- 
- return result;
-}
-
-// ============================================================================
-// Service Function 3: Write Mutation Log (S3 Upload)
-// ============================================================================
-
-/**
- * Write mutation execution log to S3
- *
- * @param s3 - S3DataSource instance
- * @param fileName - Original CSV file name
- * @param result - FileProcessingResult
- * @param logPrefix - S3 prefix for logs
- * @param log - Logger instance
- */
-async function writeMutationLog(
- s3: S3DataSource,
- fileName: string,
- result: FileProcessingResult,
- logPrefix: string,
- log: any
-): Promise<void> {
- const logFileName = `${fileName.replace('.csv', '')}-log.json`;
- const logPath = `${logPrefix}${logFileName}`;
-
- const logData = {
-  fileName,
-  timestamp: new Date().toISOString(),
-  summary: {
-   successful: result.successful,
-   failed: result.failed,
-   validationFailed: result.validationFailed,
-   priceChanges: result.priceChanges.length,
-  },
-  priceChanges: result.priceChanges,
-  errors: result.errors,
- };
-
- const logContent = JSON.stringify(logData, null, 2);
-
-// Upload log to S3 (uploadFile accepts string or Buffer)
-await s3.uploadFile(logPath, logContent);
-
- log.info('Mutation log written', { logPath });
-}
-
-// ============================================================================
-// Main Workflow Function (Per-File Processing)
-// ============================================================================
-
-async function executePriceSync(ctx: any, jobId: string, tracker: any) {
- const { log, activation, openKv } = ctx;
- const startTime = Date.now();
-
- log.info('🔄 [PriceSync] Starting scheduled price sync from S3');
-
- // ✅ CRITICAL: Declare S3 outside try block for safe disposal
- let s3: S3DataSource | undefined;
-
- try {
-  // ========================================
-  // STEP 1: CONFIGURATION & VALIDATION
-  // ========================================
-
-  // Read activation variables
-  const s3Bucket = activation?.getVariable('s3BucketName');
-  const s3Region = activation?.getVariable('awsRegion') || 'us-east-1';
-  const s3AccessKeyId = activation?.getVariable('awsAccessKeyId');
-  const s3SecretAccessKey = activation?.getVariable('awsSecretAccessKey');
-  const s3Prefix = activation?.getVariable('s3Prefix') || 'prices/';
-  const retailerId = activation?.getVariable('retailerId');
-  const maxFiles = parseInt(activation?.getVariable('maxFilesToProcess') || '10', 10);
-  const filePattern = (activation?.getVariable('filePattern') || '.csv').toLowerCase();
-  const enableArchival = activation?.getVariable('enableArchival') !== 'false';
-  const archivePrefix = activation?.getVariable('archivePrefix') || 'processed/';
-  const errorPrefix = activation?.getVariable('errorPrefix') || 'errors/';
-  const logPrefix = activation?.getVariable('logPrefix') || 'logs/';
-
-  // Configuration with defaults
-  const mutationBatchSize = parseInt(
-   activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
-   10
-  );
-
-  const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
-   ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
-   : undefined; // Default: undefined (disabled)
-
-  const minPrice = parseFloat(activation?.getVariable('minPrice') || '0.01');
-  const maxPrice = parseFloat(activation?.getVariable('maxPrice') || '999999.99');
-  const validateProducts = activation?.getVariable('validateProducts') !== 'false';
-  const validateConnection = activation?.getVariable('validateConnection') !== 'false';
-  const enableFileTracking = activation?.getVariable('enableFileTracking') !== 'false';
-
-  // Validate required variables
-  const missingVars: string[] = [];
-  if (!s3Bucket) missingVars.push('s3BucketName');
-  if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
-  if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
-  if (!retailerId) missingVars.push('retailerId');
-
-  if (missingVars.length > 0) {
-   const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
-   log.error('❌ [PriceSync] Configuration error', { error: errorMsg });
-   return {
-    success: false,
-    error: errorMsg,
-    recommendation: `Please configure these activation variables: ${missingVars.join(', ')}`,
-    processed: 0,
-    duration: Date.now() - startTime,
-   };
-  }
-
-  // ========================================
-  // STEP 2: CLIENT INITIALIZATION
-  // ========================================
-
-  const client = await createClient(ctx);
-  if (!client) {
-   throw new Error('Failed to create Fluent Commerce client');
-  }
-
-  // ✅ CORRECT: GraphQL mutations don't need setRetailerId()
-  // Check your GraphQL schema to determine retailerId handling:
-  // - Mandatory retailerId → Must pass it in mutation input
-  // - Optional retailerId → Can pass it if needed
-  // - No retailerId field → Don't pass it
-  // See: fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md
-
-  log.info('✅ [PriceSync] Fluent client initialized');
-
-  // ========================================
-  // STEP 3: SERVICE INITIALIZATION
-  // ========================================
-
-  s3 = new S3DataSource(
-   {
-    type: 'S3_CSV',
-    connectionId: 's3-price-sync',
-    name: 'Source S3',
-    s3Config: {
-     bucket: s3Bucket,
-     region: s3Region,
-     accessKeyId: s3AccessKeyId,
-     secretAccessKey: s3SecretAccessKey,
-    },
-   },
-   log
-  );
-
-  // Validate S3 connection if enabled
-  if (validateConnection) {
-   try {
-    await s3.listFiles({ prefix: s3Prefix, maxKeys: 1 });
-    log.info('✅ [PriceSync] S3 connection validated');
-   } catch (error: any) {
-    log.error('❌ [PriceSync] S3 connection validation failed', {
-     error: error instanceof Error ? error.message : String(error),
-    });
-    return {
-     success: false,
-     error: 'S3 connection validation failed',
-     details: error?.message,
-     recommendation: 'Please verify S3 credentials and bucket access permissions',
-     duration: Date.now() - startTime,
-    };
-   }
-  }
-
-  const parser = new CSVParserService();
-  const kv = openKv(':project:');
-  const fileTracker = enableFileTracking
-   ? new VersoriFileTracker(kv, 's3-csv-price-sync')
-   : null;
-
- // Create custom resolvers for price validation
- const customResolvers = {
-  'custom.validatePriceRange': (value: any) => {
-   const price = parseFloat(value);
-   if (isNaN(price)) {
-    throw new Error(`Invalid price: ${value}`);
-   }
-   if (price < minPrice) {
-    throw new Error(`Price ${price} below minimum ${minPrice}`);
-   }
-   if (price > maxPrice) {
-    throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
-   }
-   return price;
-  },
-
-  'custom.normalizePriceType': (value: any) => {
-   const type = String(value || 'DEFAULT').toUpperCase().trim();
-   const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
-   if (!validTypes.includes(type)) {
-    throw new Error(`Invalid price type: ${type}`);
-   }
-   return type;
-  },
-
-  'custom.normalizeQuantity': (value: any) => {
-   if (!value || value === '') return undefined;
-   const qty = parseInt(value, 10);
-   if (isNaN(qty) || qty < 0) {
-    throw new Error(`Invalid quantity: ${value}`);
-   }
-   return qty;
-  },
- };
-
- // ✅ CRITICAL: Load mapping config from external JSON file
- // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
- // File: src/config/price-mapping.json
- const mappingConfigJson = await import('../config/price-mapping.json', { assert: { type: 'json' } });
- const mappingConfig = mappingConfigJson.default;
- 
- // Initialize GraphQLMutationMapper with client for schema introspection
- const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-
-  // ========================================
-  // STEP 4: FILE DISCOVERY
-  // ========================================
-
-  try {
-   // List files (pattern filtering handled by listFiles)
-   const files = await s3.listFiles({
-    prefix: s3Prefix,
-    pattern: filePattern,
-    maxKeys: 1000,
-   });
-
-   const csvFiles = files
-    .sort((a, b) => {
-     const dateA = a.lastModified ? new Date(a.lastModified).getTime() : 0;
-     const dateB = b.lastModified ? new Date(b.lastModified).getTime() : 0;
-     return dateA - dateB;
-    })
-    .slice(0, maxFiles);
-
-   log.info('📂 [PriceSync] Files discovered', {
-    total: files.length,
-    toProcess: csvFiles.length,
-    maxFiles,
-   });
-
-  const results = {
-   processed: 0,
-   skipped: 0,
-   failed: 0,
-   totalRecords: 0,
-   pricesUpdated: 0,
-   pricesSkipped: 0,
-   validationErrors: 0,
-   priceChanges: [] as Array<{
-    sku: string;
-    type: string;
-    oldPrice?: number;
-    newPrice: number;
-   }>,
-   errors: [] as string[],
-  };
-
-   // ========================================
-   // STEP 5: FILE PROCESSING LOOP
-   // ========================================
-
-   // Process each file using service functions
-   for (const file of csvFiles) {
-    const filePath = file.path;
-    const fileName = file.name;
-    const fileStartTime = Date.now();
-
-    log.info('📄 [PriceSync] Processing file', { fileName });
-
-    // Duplicate prevention via file tracker
-    if (fileTracker && (await fileTracker.wasFileProcessed(fileName))) {
-     log.info('⏭️ [PriceSync] Skipping already processed file', { fileName });
-     results.skipped++;
-     continue;
-    }
-
-    try {
-    // SERVICE FUNCTION 1: Process file (S3 + CSV + Mapper)
-    const { records: mappedRecords, errors: mappingErrors } = await processFile(
-     s3,
-     parser,
-     mapper,
-     filePath,
-     fileName,
-     log
-    );
-
-    if (!mappedRecords.length) {
-     log.warn('No valid records after mapping, archiving', { fileName });
-     if (enableArchival) {
-      await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-     }
-     results.skipped++;
-     continue;
-    }
-
-    // SERVICE FUNCTION 2: Execute mutations
-    // ✅ Configuration with defaults
-    const mutationBatchSize = parseInt(
-     ctx.activation?.getVariable('mutationBatchSize') || '1', // ✅ Default: 1 (sequential)
-     10
-    );
-    
-    const mutationsPerAliasBatch = ctx.activation?.getVariable('mutationsPerAliasBatch') 
-     ? parseInt(ctx.activation?.getVariable('mutationsPerAliasBatch') || '1', 10) 
-     : undefined; // ✅ Default: undefined (disabled, use separate requests)
-    
-    // ? Enhanced: Extract context for progress logging
-    const sampleProductRefs = mappedRecords.slice(0, 5).map((r: any) => r.input?.skuRef || r.input?.productRef || 'unknown');
-    const mutationType = mapper?.mutationName || 'updatePrice';
-
-    // ? Enhanced: Start logging with context
-    log.info(`[GraphQLMutations] Sending price mutations for file "${fileName}"`, {
-     totalMutations: mappedRecords.length,
-     mutationType,
-     batchSize: mutationBatchSize,
-     batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
-     sampleProductRefs: sampleProductRefs.join(', '),
-     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled',
-     validateProducts
-    });
-    
-    const mutationResult = await executeMutations(
-     client,
-     mapper,
-     mappedRecords,
-     retailerId,
-     validateProducts,
-     mutationBatchSize, // Concurrency control (default: 1)
-     mutationsPerAliasBatch, // ✅ NEW: Alias batching (default: undefined)
-     log
-    );
-
-    // ? Enhanced: Completion logging with summary
-    log.info(`[GraphQLMutations] Price mutation submission completed for file "${fileName}"`, {
-     totalMutations: mappedRecords.length,
-     successful: mutationResult.successful,
-     failed: mutationResult.failed,
-     successRate: mappedRecords.length > 0 ? `${Math.round((mutationResult.successful / mappedRecords.length) * 100)}%` : '0%',
-     mutationType,
-     priceChanges: mutationResult.priceChanges?.length || 0
-    });
-
-    // Aggregate results
-    results.processed++;
-    results.totalRecords += mappedRecords.length;
-    results.pricesUpdated += mutationResult.successful;
-    results.validationErrors += mappingErrors.length;
-    results.priceChanges.push(...mutationResult.priceChanges);
-
-    // Build file processing result for logging
-    const fileResult: FileProcessingResult = {
-     fileName,
-     successful: mutationResult.successful,
-     failed: mutationResult.failed,
-     validationFailed: mappingErrors.length,
-     priceChanges: mutationResult.priceChanges,
-     errors: mappingErrors,
-    };
-
-    // SERVICE FUNCTION 3: Write mutation log to S3
-    await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
-
-    // Mark processed with file tracker
-    if (fileTracker) {
-     await fileTracker.markFileProcessed(fileName, {
-      successful: mutationResult.successful,
-      failed: mutationResult.failed,
-      validationFailed: mappingErrors.length,
-      recordCount: mappedRecords.length,
-      duration: Date.now() - fileStartTime,
-     });
-    }
-
-    if (enableArchival) {
-     await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-    }
-
-    const fileDuration = Date.now() - fileStartTime;
-    log.info('✅ [PriceSync] File processed successfully', {
-     fileName,
-     recordCount: mappedRecords.length,
-     successful: mutationResult.successful,
-     failed: mutationResult.failed,
-     duration: `${fileDuration}ms`,
-    });
-
-    if (mappingErrors.length > 0) {
-     results.errors.push(`${fileName}: ${mappingErrors.length} mapping errors`);
-    }
-   } catch (error: unknown) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    const errorDetails = {
-     message: errorMsg,
-     stack: error instanceof Error ? error.stack : undefined,
-     errorType: error instanceof Error ? error.constructor.name : 'Error',
-    };
-    log.error('❌ [PriceSync] File processing failed', {
-     fileName,
-     ...errorDetails,
-    });
-    results.failed++;
-    results.errors.push(`${fileName}: ${errorMsg}`);
-
-    // Attempt to move to error directory
-    try {
-     await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
-     log.info('📁 [PriceSync] Moved failed file to error directory', { fileName });
-    } catch (moveError) {
-     log.error('❌ [PriceSync] Failed to move error file', {
-      fileName,
-      error: moveError instanceof Error ? moveError.message : String(moveError),
-     });
-    }
-   }
-  }
-
-   // ========================================
-   // STEP 6: SUMMARY & COMPLETION
-   // ========================================
-
-   const totalDuration = Date.now() - startTime;
-   const summary = {
-    success: true,
-    processed: results.processed,
-    skipped: results.skipped,
-    failed: results.failed,
-    totalRecords: results.totalRecords,
-    pricesUpdated: results.pricesUpdated,
-    pricesSkipped: results.pricesSkipped,
-    validationErrors: results.validationErrors,
-    priceChanges: results.priceChanges.length,
-    errors: results.errors.length > 0 ? results.errors : undefined,
-    duration: totalDuration,
-    timestamp: new Date().toISOString(),
-   };
-
-   log.info('🎉 [PriceSync] Price sync completed', {
-    ...summary,
-    duration: `${totalDuration}ms`,
-   });
-
-   // Log significant price changes
-   if (results.priceChanges.length > 0) {
-    log.info('💰 [PriceSync] Price changes detected', {
-     count: results.priceChanges.length,
-     changes: results.priceChanges.slice(0, 10),
-    });
-   }
-
-   return summary;
-  } catch (error: unknown) {
-   // ✅ Enhanced error logging: Extract all error details for visibility
-   const errorMsg = error instanceof Error ? error.message : String(error);
-   const errorDetails = {
-    message: errorMsg,
-    stack: error instanceof Error ? error.stack : undefined,
-    errorType: error instanceof Error ? error.constructor.name : 'Error',
-   };
-   log.error('❌ [PriceSync] Fatal error', errorDetails);
-   return {
-    success: false,
-    error: errorMsg,
-    recommendation: 'Check error logs for details and verify configuration',
-    processed: 0,
-    duration: Date.now() - startTime,
-    timestamp: new Date().toISOString(),
-   };
-  }
- } catch (error: unknown) {
-  const errorMsg = error instanceof Error ? error.message : String(error);
-  log.error('❌ [PriceSync] Initialization failed', {
-   error: errorMsg,
-   stack: error instanceof Error ? error.stack : undefined,
-  });
-  return {
-   success: false,
-   error: errorMsg,
-   recommendation: 'Check configuration and service initialization',
-   duration: Date.now() - startTime,
-  };
- } finally {
-  // ✅ CRITICAL: Always dispose S3 connection to prevent connection pool exhaustion
-  if (s3) {
-   try {
-    await s3.dispose();
-    log.info('✅ [PriceSync] S3 connection disposed successfully');
-   } catch (disposeError: any) {
-    log.error('⚠️ [PriceSync] Failed to dispose S3 connection', {
-     error: disposeError instanceof Error ? disposeError.message : String(disposeError),
-     stack: disposeError instanceof Error ? disposeError.stack : undefined,
-    });
-    // Don't throw - disposal failure shouldn't prevent workflow completion
-   }
-  }
- }
-}
-```
-
-**Note:** The `runPriceSync` function above should be renamed to `executePriceSync` and moved to `src/services/price-sync.service.ts` to match the new workflow structure.
-
-## Key Patterns Explained
-
-### Pattern 1: Service Function Architecture
-
-**Three modular service functions for clean separation of concerns:**
-
-```typescript
-// SERVICE FUNCTION 1: processFile()
-// Handles: S3 download + CSV parsing + field mapping
-const { records: mappedRecords, errors: mappingErrors } = await processFile(
- s3,
- parser,
- mapper,
- filePath,
- fileName,
- log
-);
-
-// SERVICE FUNCTION 2: executeMutations()
-// Handles: GraphQL mutations + product validation + concurrency control + price change tracking
-const mutationResult = await executeMutations(
- client,
- mapper,
- mappedRecords,
- retailerId,
- validateProducts,
- mutationBatchSize,    // Concurrency control (default: 1)
- mutationsPerAliasBatch,  // Alias batching (default: undefined)
- log
-);
-
-// SERVICE FUNCTION 3: writeMutationLog()
-// Handles: Write execution log to S3 (with Buffer for Versori/Deno)
-await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
-```
-
-**Why this pattern?**
-- ✅ **Testability**: Each function can be unit tested independently
-- ✅ **Reusability**: Functions can be reused in different workflows
-- ✅ **Clarity**: Clear responsibilities for each step
-- ✅ **Error handling**: Isolated error boundaries per function
-- ✅ **Maintainability**: Easy to modify single concerns without affecting others
-
-### Pattern 2: Buffer Import for S3 Upload (Versori/Deno)
-
-**CRITICAL for Versori/Deno runtime:**
-
-```typescript
-// MUST import Buffer explicitly (not global like Node.js)
-import { Buffer } from 'node:buffer';
-
-// writeMutationLog() function
-async function writeMutationLog(s3, fileName, result, logPrefix, log) {
- const logContent = JSON.stringify(logData, null, 2);
-
- // ✅ CORRECT: Use Buffer.from() for S3 upload
- await s3.uploadFile(logPath, logContent);
-
- // ✅ CORRECT: uploadFile accepts string directly (no Buffer needed)
- // await s3.uploadFile(logPath, logContent);
-}
-```
-
-**Why?** Deno runtime requires explicit `Buffer` import from `node:buffer`. Without it, you'll get `Buffer is not defined` errors.
-
-### Pattern 3: Direct KV State Management
-
-```typescript
-const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-// Check if file already processed
-const stateKey = ['processed-files', 's3-price-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) {
- log.info('Skipping already processed file', { fileName });
- continue;
-}
-
-// Mark as processed after success
-await kv.set(stateKey, {
- successful,
- failed,
- validationFailed,
- processedAt: new Date().toISOString(),
-});
-```
-
-### Pattern 4: Custom Price Validation Resolvers
-
-```typescript
-const customResolvers = {
- 'custom.validatePriceRange': (value: any) => {
-  const price = parseFloat(value);
-  if (isNaN(price)) {
-   throw new Error(`Invalid price: ${value}`);
-  }
-  if (price < minPrice) {
-   throw new Error(`Price ${price} below minimum ${minPrice}`);
-  }
-  if (price > maxPrice) {
-   throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
-  }
-  return price;
- },
-
- 'custom.normalizePriceType': (value: any) => {
-  const type = String(value || 'DEFAULT').toUpperCase().trim();
-  const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
-  if (!validTypes.includes(type)) {
-   throw new Error(`Invalid price type: ${type}`);
-  }
-  return type;
- },
-};
-```
-
-**Why this matters**: Price data requires strict validation to prevent:
-
-- Negative prices
-- Prices outside business rules (too low/high)
-- Invalid price tiers
-- Data entry errors
-
-### Pattern 5: Product Existence Validation
-
-```typescript
-async function validateProductExists(
- client: any,
- productRef: string,
- retailerId: string,
- log: any
-): Promise<boolean> {
- const query = `
-  query GetProduct($ref: String!, $retailerId: ID!) {
-   products(first: 1, ref: [$ref], retailerId: $retailerId) {
-    edges {
-     node {
-      id
-      ref
-      status
-     }
-    }
-   }
-  }
- `;
-
- const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
- const product = result?.data?.products?.edges?.[0]?.node;
-
- if (!product || product.status !== 'ACTIVE') {
-  return false;
- }
-
- return true;
-}
-```
-
-**Why this matters**: Prevents price updates for non-existent products, which would fail at GraphQL level.
-
-### Pattern 6: Price Change Tracking
-
-```typescript
-// Get current price before update
-const currentPrice = await getCurrentPrice(
- client,
- priceData.productRef,
- priceData.type,
- priceData.currency,
- retailerId
-);
-
-// Track change after update
-if (currentPrice !== undefined && currentPrice !== priceData.value) {
- results.priceChanges.push({
-  sku: priceData.productRef,
-  type: priceData.type,
-  oldPrice: currentPrice,
-  newPrice: priceData.value,
- });
-}
-
-// Log changes at end
-if (results.priceChanges.length > 0) {
- log.info('Price changes detected', {
-  count: results.priceChanges.length,
-  changes: results.priceChanges.slice(0, 10),
- });
-}
-```
-
-**Why this matters**: Provides audit trail and monitoring for price changes.
-
-### Pattern 7: Concurrency Control & Alias Batching
-
-```typescript
-// ✅ Configuration with defaults
-const mutationBatchSize = parseInt(
- activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
- 10
-);
-
-const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
- ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
- : undefined; // Default: undefined (disabled)
-
-// Execute with bounded concurrency + optional alias batching
-const mutationResult = await executeMutations(
- client,
- mapper,
- priceRecords,
- retailerId,
- validateProducts,
- mutationBatchSize,    // 1=sequential, 3-10=parallel
- mutationsPerAliasBatch,  // Optional: Group mutations (e.g., 5)
- log
-);
-```
-
-**Performance Modes:**
-- `mutationBatchSize: 1` → Sequential (safe default, ~1 mutation/sec)
-- `mutationBatchSize: 3-5` → Balanced (~3-5 mutations/sec)
-- `mutationBatchSize: 10` → High-volume (~10 mutations/sec)
-- `mutationsPerAliasBatch: 5` → Alias batching (reduces network overhead by ~80%)
-
-## Advanced: Multi-Currency Price Management
-
-### External Mapping File for Multi-Currency
-
-**File**: `config/price-mapping.json`
-
-```json
-{
- "version": "1.0.0",
- "description": "Multi-currency price mapping",
- "fields": {
-  "productRef": {
-   "source": "sku",
-   "required": true,
-   "resolver": "sdk.trim"
-  },
-  "type": {
-   "source": "price_type",
-   "required": true,
-   "resolver": "custom.normalizePriceType"
-  },
-  "value": {
-   "source": "amount",
-   "required": true,
-   "resolver": "custom.validatePriceRange"
-  },
-  "currency": {
-   "source": "currency_code",
-   "required": true,
-   "resolver": "custom.normalizeCurrency"
-  },
-  "effectiveFrom": {
-   "source": "start_date",
-   "resolver": "sdk.formatDate"
-  },
-  "effectiveTo": {
-   "source": "end_date",
-   "resolver": "sdk.formatDate"
-  }
- }
-}
-```
-
-### Custom Resolvers for Multi-Currency
-
-```typescript
-const customResolvers = {
- 'custom.normalizeCurrency': (value: string) => {
-  // Normalize currency codes to ISO 4217
-  const currencyMap: Record<string, string> = {
-   usd: 'USD',
-   us: 'USD',
-   dollar: 'USD',
-   eur: 'EUR',
-   euro: 'EUR',
-   gbp: 'GBP',
-   pound: 'GBP',
-   cad: 'CAD',
-   aud: 'AUD',
-  };
-
-  const normalized = currencyMap[value.toLowerCase()] || value.toUpperCase();
-
-  // Validate against known currencies
-  const validCurrencies = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY', 'CNY'];
-  if (!validCurrencies.includes(normalized)) {
-   throw new Error(`Invalid currency code: ${value}`);
-  }
-
-  return normalized;
- },
-
- 'custom.convertToBaseCurrency': (value: any, sourceRecord: any) => {
-  // Convert foreign currency to base currency
-  const amount = parseFloat(value);
-  const currency = sourceRecord.currency_code;
-
-  // Exchange rates (in production, fetch from API)
-  const exchangeRates: Record<string, number> = {
-   USD: 1.0,
-   EUR: 0.85,
-   GBP: 0.73,
-   CAD: 1.35,
-   AUD: 1.45,
-  };
-
-  const rate = exchangeRates[currency?.toUpperCase()] || 1.0;
-  return amount * rate;
- },
-
- 'custom.buildPriceAttributes': (_: any, sourceRecord: any) => {
-  // Build price attributes array
-  const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-  if (sourceRecord.cost_basis) {
-   attributes.push({
-    name: 'costBasis',
-    type: 'Float',
-    value: parseFloat(sourceRecord.cost_basis),
-   });
-  }
-
-  if (sourceRecord.margin_percent) {
-   attributes.push({
-    name: 'marginPercent',
-    type: 'Float',
-    value: parseFloat(sourceRecord.margin_percent),
-   });
-  }
-
-  if (sourceRecord.competitor_price) {
-   attributes.push({
-    name: 'competitorPrice',
-    type: 'Float',
-    value: parseFloat(sourceRecord.competitor_price),
-   });
-  }
-
-  if (sourceRecord.price_source) {
-   attributes.push({
-    name: 'priceSource',
-    type: 'String',
-    value: sourceRecord.price_source,
-   });
-  }
-
-  return attributes;
- },
-};
-```
-
-## Schema Validation (Before Deployment)
-
-Use SDK CLI tools to validate your GraphQL schema and mapping configuration:
-
-```bash
-# Install SDK globally (or use npx)
-npm install -g @fluentcommerce/fc-connect-sdk
-
-# 1. Introspect Fluent GraphQL schema
-fc-connect introspect-schema \
- --url https://api.fluentcommerce.com/graphql \
- --client-id YOUR_CLIENT_ID \
- --client-secret YOUR_CLIENT_SECRET \
- --output fluent-schema.json
-
-# 2. Create mutation file (price-mutation.graphql)
-cat > price-mutation.graphql << 'EOF'
-mutation UpdateProductPrice($input: UpdateProductInput!) {
- updateProduct(input: $input) {
-  id
-  ref
-  prices {
-   type
-   value
-   currency
-  }
- }
-}
-EOF
-
-# 3. Generate mapping from mutation (validates structure)
-fc-connect generate-mutation-mapping \
- --file price-mutation.graphql \
- --output price-mapping.json
-
-# 4. Validate mapping against schema
-fc-connect validate-schema \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-
-# 5. Analyze field coverage
-fc-connect analyze-coverage \
- --mapping price-mapping.json \
- --schema fluent-schema.json
-```
-
-**Output Example**:
-
-```bash
-✓ Schema validation passed
-✓ All required fields present: ref, retailerId, prices[].type, prices[].value, prices[].currency
-✓ Mutation structure matches GraphQL schema
-⚠ Optional fields not mapped: prices[].taxType, prices[].taxRate
-```
-
-## Testing the Workflow
-
-### 1. Upload Test CSV to S3
-
-```bash
-# Using AWS CLI
-aws s3 cp product-prices-test.csv s3://my-price-bucket/prices/
-
-# Or using S3 Console
-# Navigate to bucket → prices/ → Upload
-```
-
-### 2. Deploy to Versori
-
-```bash
-npm run deploy
-```
-
-### 3. Manual Testing via Webhook
-
-```bash
-curl -X POST https://your-workspace.versori.run/sync-prices-now \
- -H "Content-Type: application/json"
-```
-
-### 4. Check Status
-
-```bash
-curl https://your-workspace.versori.run/check-status
-```
-
-### 5. Monitor Logs
-
-```bash
-npm run logs
-# Or via Versori dashboard
-```
-
----
-
-## Monitoring
-
-### Success Response
-
-```json
-{
- "success": true,
- "filesProcessed": 1,
- "filesSkipped": 0,
- "filesFailed": 0,
- "totalRecords": 100,
- "mutationsExecuted": 100,
- "mutationsFailed": 0,
- "results": [
-  {
-   "file": "prices_2025-01-22.csv",
-   "success": true,
-   "recordsProcessed": 100,
-   "mutationsExecuted": 100,
-   "mutationsFailed": 0
-  }
- ],
- "duration": 12345
-}
-```
-
-### Partial Success Response
-
-```json
-{
- "success": true,
- "filesProcessed": 1,
- "filesSkipped": 0,
- "filesFailed": 0,
- "totalRecords": 100,
- "mutationsExecuted": 95,
- "mutationsFailed": 5,
- "results": [
-  {
-   "file": "prices_2025-01-22.csv",
-   "success": true,
-   "recordsProcessed": 100,
-   "mutationsExecuted": 95,
-   "mutationsFailed": 5,
-   "errors": ["PRICE-001: Invalid price value", "PRICE-002: Missing currency"]
-  }
- ],
- "duration": 12345
-}
-```
-
-### Error Response
-
-```json
-{
- "success": false,
- "filesProcessed": 0,
- "filesFailed": 1,
- "totalRecords": 0,
- "mutationsExecuted": 0,
- "mutationsFailed": 0,
- "results": [
-  {
-   "file": "prices_2025-01-22.csv",
-   "success": false,
-   "error": "CSV parse error: Invalid structure"
-  }
- ],
- "duration": 876
-}
-```
-
-### Monitoring Metrics
-
-Monitor these metrics via Versori logs filtered by `jobId` or `stage`:
-
-- **Files Processed** - Total files successfully processed
-- **Mutations Executed** - Total GraphQL mutations executed successfully
-- **Mutations Failed** - Mutations that failed (check error logs)
-- **Processing Duration** - Time taken for complete workflow
-- **Rate Limiting** - Watch for 429 errors indicating GraphQL throttling
-
-Use the status webhook for dashboards and automated monitoring.
-
----
-
-### Issue 1: Product Not Found
-
-**Error**: `Skipping price update for non-existent product: PROD-XYZ`
-
-**Solution**:
-
-- Verify product exists in Fluent Commerce
-- Check SKU matches exactly (case-sensitive)
-- Ensure product status is `ACTIVE`
-- Disable validation temporarily for testing: `validateProducts=false`
-
-### Issue 2: Price Validation Failures
-
-**Error**: `Price 0.00 below minimum 0.01`
-
-**Solution**:
-
-```bash
-# Adjust validation rules in activation variables
-minPrice=0.00 # Allow zero prices
-maxPrice=9999999.99 # Increase max
-```
-
-Or fix source data:
-
-```csv
-# ❌ WRONG
-PROD-001,DEFAULT,0,USD
-
-# ✅ CORRECT
-PROD-001,DEFAULT,0.01,USD
-```
-
-### Issue 3: Invalid Price Type
-
-**Error**: `Invalid price type: PROMO`
-
-**Solution**: Update custom resolver to include new type:
-
-```typescript
-'custom.normalizePriceType': (value: any) => {
- const type = String(value || 'DEFAULT').toUpperCase().trim();
- const validTypes = [
-  'DEFAULT',
-  'SALE',
-  'CLEARANCE',
-  'BULK',
-  'PROMOTIONAL',
-  'MEMBER',
-  'PROMO', // Add new type
- ];
- if (!validTypes.includes(type)) {
-  throw new Error(`Invalid price type: ${type}`);
- }
- return type;
-};
-```
-
-### Issue 4: Duplicate Price Updates
-
-**Symptom**: Same file processed multiple times
-
-**Solution**: VersoriKVAdapter already prevents this:
-
-```typescript
-const stateKey = ['processed-files', 's3-price-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) {
- log.info('Skipping already processed file', { fileName });
- continue;
-}
-```
-
-Verify KV storage is working:
-
-```bash
-# Check Versori logs for:
-[INFO] Skipping already processed file: product-prices-20250122-001.csv
-```
-
-### Issue 5: S3 Access Denied
-
-Required IAM Permissions:
-
-```json
-{
- "Version": "2012-10-17",
- "Statement": [
-  {
-   "Effect": "Allow",
-   "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
-   "Resource": [
-    "arn:aws:s3:::my-price-bucket",
-    "arn:aws:s3:::my-price-bucket/*"
-   ]
-  }
- ]
-}
-```
-
-### Issue 6: GraphQL Mutation Failures
-
-**Common Causes**:
-
-- Invalid price type (check Fluent schema for valid types)
-- Missing required fields (ref, retailerId, prices)
-- Invalid currency code (must be ISO 4217: USD, EUR, GBP)
-- Product not found or inactive
-
-**Debugging**:
-
-```typescript
-// Log mutation input before execution
-log.info('GraphQL mutation input', { input });
-
-// Validate required fields
-if (!priceData.productRef || !priceData.type || !priceData.value) {
- log.error('Missing required fields', { priceData });
- continue;
-}
-```
-
-## Production Checklist
-
-- [ ] S3 credentials validated with correct IAM permissions
-- [ ] Activation secrets stored securely (not in code)
-- [ ] GraphQL schema validated using CLI tools
-- [ ] Mapping configuration uses GraphQLMutationMapper structure (NOT UniversalMapper)
-- [ ] Mapping configuration tested with sample data
-- [ ] NO setRetailerId() call in code (only for Job/Event API)
-- [ ] Price validation rules configured per business policy
-- [ ] Product existence validation enabled (`validateProducts=true`)
-- [ ] File duplicate prevention working via KV state
-- [ ] Concurrency control configured (mutationBatchSize)
-- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
-- [ ] Error handling tested with malformed CSV
-- [ ] Retry logic tested with transient failures
-- [ ] File archival working (processed and error directories)
-- [ ] Price change tracking verified in logs
-- [ ] Monitoring/alerting configured for price update failures
-- [ ] Clear runbook for error recovery
-
-## Related Guides
-
-- **GraphQL Mutation Mapping**: `docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
-- **GraphQL Alias Batching**: `docs/02-CORE-GUIDES/mapping/graphql-alias-batching-guide.md`
-- **retailerId Configuration**: `docs/00-START-HERE/retailerid-configuration.md`
-- **CLI Tools**: `fc-connect-sdk/bin/readme.md`
-- **State & KV patterns**: `docs/03-PATTERN-GUIDES/file-operations/`
-- **Error handling**: `docs/03-PATTERN-GUIDES/error-handling/`
+---
+template_id: tpl-ingest-s3-csv-to-price-graphql
+canonical_filename: template-ingestion-s3-csv-price-graphql.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: s3-csv
+destination: fluent-graphql
+entity: price
+format: csv
+logging: versori
+status: stable
+features:
+  - graphql-mutation-mapper
+  - memory-management
+  - enhanced-logging
+  - attribute-transformation
+compliance: gold-standard
+---
+
+# Template: Ingestion - S3 CSV to Price GraphQL
+n**Template Version:** 2.0.0
+**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
+**Last Updated:** 2025-01-24
+
+**🆕 Version 2.0.0 Enhancements:**
+- ✅ **GraphQL Mutation Mapper** - Direct field mapping to mutation variables
+- ✅ **Memory Management** - Clear large arrays after processing batches
+- ✅ **Enhanced Logging** - Track mutation execution with emoji indicators
+- ✅ **Attribute Transformation** - Handle complex nested data structures
+
+## STEP 1: What This Template Does
+
+This template provides a **scheduled Versori workflow** that:
+
+1. **Discovers CSV files** from S3 bucket with price data
+2. **Parses CSV** using `CSVParserService` with validation
+3. **Validates products exist** in Fluent Commerce before updating prices
+4. **Maps fields** using `GraphQLMutationMapper` with custom price validation resolvers
+5. **Updates prices** via direct GraphQL mutations (`updateProduct`)
+6. **Tracks price changes** for audit trail
+7. **Archives processed files** to prevent duplicates
+8. **Uses JobTracker** for job lifecycle management
+
+**Key Features:**
+- ✅ Direct GraphQL mutations (NOT Batch API)
+- ✅ Product existence validation before price updates
+- ✅ Price range validation (min/max checks)
+- ✅ Multi-tier pricing support (DEFAULT, SALE, CLEARANCE, BULK)
+- ✅ Configurable concurrency control (sequential or parallel)
+- ✅ Optional GraphQL alias batching for high-volume scenarios
+- ✅ Price change tracking and reporting
+- ✅ Versori KV state management (duplicate prevention)
+- ✅ File archival with error handling
+
+**Use Cases:**
+- Daily product price synchronization
+- Promotional price updates
+- Multi-currency pricing management
+- Quantity-based pricing tiers
+
+## STEP 2: Understanding This Template (AI Agent Guide)
+
+**🎯 Template Purpose:** Scheduled price synchronization from S3 CSV files to Fluent Commerce using direct GraphQL mutations.
+
+### Architecture Pattern
+
+```
+S3 CSV Files → CSVParserService → GraphQLMutationMapper → Product Validation → GraphQL Mutations → Archive
+   ↓       ↓          ↓         ↓          ↓       ↓
+File Discovery  Parsing     Field Mapping   Existence Check   updateProduct    Processed/
+Price Data   Validation    Price Validation  Active Status    Concurrency Ctrl   Error Dirs
+```
+
+### SDK Services Used
+
+| Service | Purpose | Key Methods |
+|---------|---------|-------------|
+| `createClient(ctx)` | Fluent API client | `client.graphql()` |
+| `S3DataSource` | S3 operations | `listFiles()`, `downloadFile()`, `moveFile()` |
+| `CSVParserService` | CSV parsing | `parse()` |
+| `GraphQLMutationMapper` | Field transformation | `map()` with custom resolvers |
+| `VersoriKVAdapter` | State management | `get()`, `set()`, `list()` |
+| `JobTracker` | Job lifecycle | `createJob()`, `updateJob()`, `markCompleted()`, `markFailed()`, `getJob()` |
+
+### Price Entity Structure
+
+**Fluent Commerce Price Schema:**
+```typescript
+{
+ productRef: string;   // SKU reference (required)
+ type: string;      // DEFAULT, SALE, CLEARANCE, BULK (required)
+ value: number;      // Price amount (required, validated)
+ currency: string;    // ISO 4217 code (USD, EUR, GBP)
+ effectiveFrom?: string; // ISO 8601 date
+ effectiveTo?: string;  // ISO 8601 date
+ minQuantity?: number;  // Min qty for tier pricing
+ maxQuantity?: number;  // Max qty for tier pricing
+}
+```
+
+### GraphQL Mutation Pattern
+
+**Mutation Used:** `updateProduct` (NOT Batch API)
+
+```graphql
+mutation UpdateProductPrice($input: UpdateProductInput!) {
+ updateProduct(input: $input) {
+  id
+  ref
+  prices {
+   type
+   value
+   currency
+   effectiveFrom
+   effectiveTo
+   minQuantity
+   maxQuantity
+  }
+ }
+}
+```
+
+**Why Direct Mutations?**
+- ✅ Immediate price updates (no batch processing delay)
+- ✅ Product validation before update
+- ✅ Price change tracking
+- ✅ Suitable for low-volume price updates (<1000/day)
+
+**NO BPP (Batch Pre-Processing):** Direct GraphQL mutations bypass batch workflows entirely.
+
+### Custom Resolvers
+
+**Three price-specific resolvers:**
+
+1. **`custom.validatePriceRange`** - Ensures price within min/max bounds
+2. **`custom.normalizePriceType`** - Validates price tier types
+3. **`custom.normalizeQuantity`** - Validates quantity ranges for BULK pricing
+
+### Product Validation Pattern
+
+**Critical Step:** Validate product exists and is ACTIVE before price update:
+
+```typescript
+async function validateProductExists(client, productRef, retailerId, log) {
+ const query = `
+  query GetProduct($ref: String!, $retailerId: ID!) {
+   products(first: 1, ref: [$ref], retailerId: $retailerId) {
+    edges {
+     node { id ref status }
+    }
+   }
+  }
+ `;
+ const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
+ const product = result?.data?.products?.edges?.[0]?.node;
+ return product && product.status === 'ACTIVE';
+}
+```
+
+**Why?** Prevents GraphQL errors for non-existent products.
+
+### Concurrency Control & Performance
+
+**Mutation execution** supports two performance modes:
+
+**Mode 1: Concurrency Control (default)**
+```typescript
+// Configuration: Control concurrent mutations
+const mutationBatchSize = parseInt(
+ activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
+ 10
+);
+
+// Execute with bounded concurrency
+await executeMutations(
+ client,
+ mapper,
+ priceRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize, // 1=sequential, 3-10=parallel
+ undefined,     // No alias batching
+ log
+);
+```
+
+**Mode 2: GraphQL Alias Batching (optional, high-volume)**
+```typescript
+// Configuration: Group mutations into aliased requests
+const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+ ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+ : undefined; // Default: undefined (disabled)
+
+// Execute with alias batching (reduces network overhead by ~80%)
+await executeMutations(
+ client,
+ mapper,
+ priceRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize,      // Concurrency control
+ mutationsPerAliasBatch,   // Alias batching (e.g., 5)
+ log
+);
+```
+
+**Activation Variables:**
+- `mutationBatchSize=1` - Default: sequential (safe)
+- `mutationBatchSize=3-5` - Balanced throughput
+- `mutationBatchSize=10` - High-volume (100+ locations)
+- `mutationsPerAliasBatch` - Optional: Group mutations (e.g., 5 per request)
+
+### State Management
+
+**VersoriKVAdapter** prevents duplicate file processing:
+
+```typescript
+const stateKey = ['processed-files', 's3-price-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) {
+ log.info('Skipping already processed file', { fileName });
+ continue;
+}
+// After success:
+await kv.set(stateKey, { successful, failed, processedAt: new Date().toISOString() });
+```
+
+### JobTracker Integration
+
+**Job lifecycle tracking:**
+
+```typescript
+const tracker = new JobTracker(openKv(':project:'), log);
+await tracker.startJob(jobId, { mode: 'scheduled' });
+try {
+ const result = await runPriceCsvWorkflow(ctx, jobId, tracker);
+ await tracker.completeJob(jobId, { result });
+} catch (e) {
+ await tracker.failJob(jobId, { error: e.message });
+}
+```
+
+### Price Change Tracking
+
+**Audit trail for price updates:**
+
+```typescript
+const currentPrice = await getCurrentPrice(client, productRef, priceType, currency, retailerId);
+// ... after update ...
+if (currentPrice !== undefined && currentPrice !== priceData.value) {
+ results.priceChanges.push({
+  sku: priceData.productRef,
+  type: priceData.type,
+  oldPrice: currentPrice,
+  newPrice: priceData.value,
+ });
+}
+// Log changes at end:
+log.info('Price changes detected', { count: results.priceChanges.length, changes });
+```
+
+### Schema Validation (CLI Commands)
+
+**Before deployment, validate GraphQL schema:**
+
+```bash
+# 1. Introspect Fluent schema
+fc-connect introspect-schema \
+ --url https://api.fluentcommerce.com/graphql \
+ --client-id CLIENT_ID \
+ --client-secret CLIENT_SECRET \
+ --output fluent-schema.json
+
+# 2. Create mutation file
+cat > price-mutation.graphql << 'EOF'
+mutation UpdateProductPrice($input: UpdateProductInput!) {
+ updateProduct(input: $input) {
+  id
+  ref
+  prices { type value currency }
+ }
+}
+EOF
+
+# 3. Generate mapping from mutation
+fc-connect generate-mutation-mapping \
+ --file price-mutation.graphql \
+ --output price-mapping.json
+
+# 4. Validate mapping against schema
+fc-connect validate-schema \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+
+# 5. Analyze field coverage
+fc-connect analyze-coverage \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+```
+
+### Configuration File Structure
+
+**Mapping Config:** `config/price-mapping.json`
+
+**✅ PRODUCTION STANDARD:** External JSON file with GraphQLMutationMapper structure
+
+```json
+{
+ "mutation": "updateProduct",
+ "sourceFormat": "csv",
+ "version": "1.0.0",
+ "arguments": {
+  "input": {
+   "ref": {
+    "source": "sku",
+    "required": true,
+    "resolver": "trim"
+   },
+   "prices": {
+    "type": {
+     "source": "priceType",
+     "required": true,
+     "resolver": "normalizePriceType"
+    },
+    "value": {
+     "source": "amount",
+     "required": true,
+     "resolver": "validatePriceRange"
+    },
+    "currency": {
+     "source": "currency",
+     "required": true,
+     "resolver": "toUpperCase"
+    },
+    "effectiveFrom": {
+     "source": "effectiveDate",
+     "resolver": "formatDate"
+    },
+    "effectiveTo": {
+     "source": "expiryDate",
+     "resolver": "formatDate"
+    },
+    "minQuantity": {
+     "source": "minQuantity",
+     "resolver": "normalizeQuantity"
+    },
+    "maxQuantity": {
+     "source": "maxQuantity",
+     "resolver": "normalizeQuantity"
+    }
+   }
+  }
+ }
+}
+```
+
+**Key Differences from UniversalMapper:**
+- ✅ `mutation` property (not `mutationName`)
+- ✅ `arguments.input` structure (matches GraphQL schema)
+- ✅ Nested `prices` object (not flat productRef/type/value)
+- ✅ Resolver names without `sdk.` or `custom.` prefix (`trim`, `toUpperCase`, `formatDate`)
+- ✅ Used with `GraphQLMutationMapper.map()` method (not `UniversalMapper.map()`)
+
+### Activation Variables Required
+
+**Minimum Required:**
+- `s3BucketName` - S3 bucket with price CSV files
+- `awsAccessKeyId` - AWS credentials
+- `awsSecretAccessKey` - AWS credentials
+
+**Optional (with defaults):**
+- `awsRegion=us-east-1`
+- `s3Prefix=prices/`
+- `archivePrefix=processed/`
+- `errorPrefix=errors/`
+- `logPrefix=logs/` - Where to write mutation logs
+- `maxFilesToProcess=10`
+- `mutationBatchSize=1` - Number of concurrent mutations (1=sequential, 3-10=parallel)
+- `mutationsPerAliasBatch` - Optional: Number of mutations per aliased request (default: undefined = disabled)
+- `minPrice=0.01`
+- `maxPrice=999999.99`
+- `validateProducts=true`
+- `validateConnection=true` - Validate S3 connection at startup
+- `enableFileTracking=true` - Enable file tracking via VersoriFileTracker
+- `fluentRetailerId` - Optional: Only if mutation schema requires retailerId in input (most Price mutations don't need it)
+
+### Error Handling Patterns
+
+**Three-level error handling:**
+
+1. **Mapping errors** - Invalid price data (validation failures)
+2. **GraphQL errors** - Mutation failures (product not found, invalid fields)
+3. **File processing errors** - S3 access issues, CSV parsing failures
+
+**Error state tracking with exponential backoff:**
+```typescript
+const errorKey = ['error-state', fileName];
+const attempts = (prev?.attemptCount || 0) + 1;
+const backoffMinutes = Math.min(Math.pow(2, attempts) * 5, 24 * 60);
+const nextRetryAt = new Date(Date.now() + backoffMinutes * 60000).toISOString();
+```
+
+### Common Pitfalls
+
+**❌ WRONG Patterns:**
+- Using Batch API for price updates (overhead, delay)
+- Using `UniversalMapper` instead of `GraphQLMutationMapper`
+- Calling `client.setRetailerId()` for GraphQL mutations (only needed for Job/Event API)
+- Skipping product validation (causes GraphQL errors)
+- No concurrency control (API throttling)
+- Hardcoded price validation rules (not configurable)
+- Missing price change tracking (no audit trail)
+
+**✅ CORRECT Patterns:**
+- Direct GraphQL mutations for immediate updates
+- `GraphQLMutationMapper` with nested mapping structure
+- NO `setRetailerId()` call (pass in mutation input if schema requires it)
+- Product existence validation before updates
+- Configurable concurrency control (mutationBatchSize)
+- Optional alias batching for high-volume scenarios
+- Custom resolvers for price validation
+- Price change tracking for audit
+- VersoriKVAdapter for state management
+- JobTracker for job lifecycle
+
+### Testing Checklist
+
+**Before deployment:**
+- [ ] S3 credentials validated (IAM permissions: ListBucket, GetObject, PutObject, DeleteObject)
+- [ ] GraphQL schema validated using CLI tools
+- [ ] Mapping configuration uses GraphQLMutationMapper structure (nested objects, not flat fields)
+- [ ] Mapping configuration tested with sample CSV
+- [ ] Product validation working (queries products endpoint)
+- [ ] Price validation rules configured (min/max bounds)
+- [ ] Concurrency control configured (mutationBatchSize)
+- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
+- [ ] NO setRetailerId() call present (only for Job/Event API)
+- [ ] File duplicate prevention working (KV state)
+- [ ] Price change tracking verified (logs price changes)
+- [ ] Error handling tested (malformed CSV, invalid products)
+- [ ] File archival working (processed/ and errors/ directories)
+
+### Related Documentation
+
+- **Core Guides:** `docs/02-CORE-GUIDES/ingestion/modules/`
+- **Universal Mapping:** `docs/02-CORE-GUIDES/mapping/modules/`
+- **CLI Tools:** `fc-connect-sdk/bin/readme.md`
+- **State Management:** `docs/03-PATTERN-GUIDES/file-operations/`
+- **Error Handling:** `docs/03-PATTERN-GUIDES/error-handling/`
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Scheduled Versori workflow that reads product price CSV files from S3 and creates/updates Fluent Commerce product prices via GraphQL mutations
+
+**Complexity**: Medium-High
+
+**Runtime**: Versori Platform (Scheduled)
+
+**Estimated Lines**: ~700 lines
+
+## What You'll Build
+
+- Versori scheduled workflow (cron trigger)
+- S3 file listing and download with retry logic
+- CSV parsing with validation
+- UniversalMapper for price field transformations
+- Product existence validation before price updates
+- GraphQL mutations for price upserts with rate limiting
+- Versori KV state management (duplicate prevention)
+- Price change tracking and reporting
+- File archival after processing
+
+## 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
+
+```
+s3-csv-price-graphql/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-price-sync.ts       # Scheduled: Daily price sync
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-price-sync.ts       # Webhook: Manual trigger
+    │       └── job-status-check.ts       # Webhook: Status query
+    │
+    ├── services/
+    │   └── price-sync.service.ts         # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── price-mapping.json            # GraphQL mapping config
+```
+
+---
+
+## Workflow Files
+
+### 1. Scheduled Workflows (`src/workflows/scheduled/`)
+
+All time-based triggers that run automatically on cron schedules.
+
+#### `src/workflows/scheduled/daily-price-sync.ts`
+
+**Purpose**: Automatic daily price 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 { executePriceSync } from '../../services/price-sync.service';
+
+/**
+ * Scheduled Workflow: Daily Price Sync
+ *
+ * Runs automatically daily at 2 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Uses shared service: price-sync.service.ts
+ */
+export const dailyPriceSync = schedule(
+  'price-sync-scheduled',
+  '0 2 * * *' // Daily at 2 AM UTC
+).then(
+  http('run-price-sync', { connection: 'fluent_commerce' }, async (ctx: any) => {
+    const { log, openKv } = ctx;
+    const jobId = `price-sync-${Date.now()}`;
+    const executionStartTime = Date.now();
+    const tracker = new JobTracker(openKv(':project:'), log);
+
+    log.info('🔄 [WORKFLOW] Starting price sync', { jobId });
+
+    await tracker.createJob(jobId, {
+      triggeredBy: 'schedule',
+      stage: 'initialization',
+      startTime: executionStartTime,
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+
+    try {
+      const result = await executePriceSync(ctx, jobId, tracker);
+
+      if (result.success) {
+        await tracker.markCompleted(jobId, result);
+        log.info('✅ [WORKFLOW] Price sync completed', {
+          jobId,
+          filesProcessed: result.filesProcessed,
+          duration: result.duration,
+        });
+      } else {
+        await tracker.markFailed(jobId, result.error || 'Unknown error');
+        log.error('❌ [WORKFLOW] Price sync failed', { jobId, error: result.error });
+      }
+
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      const errorMessage = e instanceof Error ? e.message : String(e);
+      await tracker.markFailed(jobId, errorMessage);
+      log.error('❌ [WORKFLOW] Price sync failed with exception', {
+        jobId,
+        error: errorMessage,
+        stack: e instanceof Error ? e.stack : undefined,
+      });
+      return { success: false, jobId, error: errorMessage };
+    }
+  })
+);
+```
+
+---
+
+### 2. Webhook Workflows (`src/workflows/webhook/`)
+
+All HTTP-based triggers that create webhook endpoints.
+
+#### `src/workflows/webhook/adhoc-price-sync.ts`
+
+**Purpose**: Manual price sync trigger (on-demand)
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/price-sync-adhoc`
+**Use Cases**: Testing, priority processing, ad-hoc runs
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { executePriceSync } from '../../services/price-sync.service';
+
+/**
+ * Webhook: Manual Price Sync Trigger
+ *
+ * Endpoint: POST https://{workspace}.versori.run/price-sync-adhoc
+ * Request body (optional): { filePattern: "urgent_*.csv", maxFiles: 5 }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: price-sync.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const adhocPriceSync = webhook('price-sync-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'price-sync-adhoc', // Versori validates API key
+}).then(
+  http('run-price-sync-adhoc', { connection: 'fluent_commerce' }, async (ctx: any) => {
+    const { log, openKv, data } = ctx;
+    const jobId = `price-sync-adhoc-${Date.now()}`;
+    const executionStartTime = Date.now();
+    const tracker = new JobTracker(openKv(':project:'), log);
+
+    log.info('🔄 [WEBHOOK] Starting adhoc price sync', { jobId });
+
+    await tracker.createJob(jobId, {
+      triggeredBy: 'manual',
+      stage: 'initialization',
+      startTime: executionStartTime,
+      options: data // Optional: filePattern, maxFiles, etc.
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+
+    try {
+      const result = await executePriceSync(ctx, jobId, tracker);
+
+      if (result.success) {
+        await tracker.markCompleted(jobId, result);
+        log.info('✅ [WEBHOOK] Adhoc price sync completed', {
+          jobId,
+          filesProcessed: result.filesProcessed,
+          duration: result.duration,
+        });
+      } else {
+        await tracker.markFailed(jobId, result.error || 'Unknown error');
+        log.error('❌ [WEBHOOK] Adhoc price sync failed', { jobId, error: result.error });
+      }
+
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      const errorMessage = e instanceof Error ? e.message : String(e);
+      await tracker.markFailed(jobId, errorMessage);
+      log.error('❌ [WEBHOOK] Adhoc price sync failed with exception', {
+        jobId,
+        error: errorMessage,
+        stack: e instanceof Error ? e.stack : undefined,
+      });
+      return { success: false, jobId, error: errorMessage };
+    }
+  })
+);
+```
+
+---
+
+#### `src/workflows/webhook/job-status-check.ts`
+
+**Purpose**: Query job status
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/price-sync-job-status`
+**Request body**: `{ "jobId": "price-sync-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/price-sync-job-status
+ * Request body: { "jobId": "price-sync-1234567890" }
+ *
+ * Pattern: webhook().then(fn()) - no external API needed, only KV storage
+ * Lightweight: Only queries KV store, no Fluent API calls
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const priceSyncJobStatus = webhook('price-sync-job-status', {
+  response: { mode: 'sync' },
+  connection: 'price-sync-job-status',
+}).then(
+  fn('status', async (ctx: any) => {
+    const { data, log, openKv } = ctx;
+    const jobId = data?.jobId as string;
+
+    log.info('🔍 [STATUS] Checking job status', { jobId });
+
+    if (!jobId) {
+      log.warn('❌ [STATUS] Missing jobId in request');
+      return { success: false, error: 'jobId required' };
+    }
+
+    const tracker = new JobTracker(openKv(':project:'), log);
+    const status = await tracker.getJob(jobId);
+
+    if (status) {
+      log.info('✅ [STATUS] Job found', { jobId, status: status.status });
+      return { success: true, jobId, ...status };
+    } else {
+      log.warn('❌ [STATUS] Job not found', { jobId });
+      return { 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 { dailyPriceSync } from './workflows/scheduled/daily-price-sync';
+
+// Import webhook workflows
+import { adhocPriceSync } from './workflows/webhook/adhoc-price-sync';
+import { priceSyncJobStatus } from './workflows/webhook/job-status-check';
+
+// Register all workflows
+export {
+  // Scheduled (time-based triggers)
+  dailyPriceSync,
+
+  // Webhooks (HTTP-based triggers)
+  adhocPriceSync,
+  priceSyncJobStatus,
+};
+```
+
+**What Gets Exposed:**
+- ✅ `adhocPriceSync` → `https://{workspace}.versori.run/price-sync-adhoc`
+- ✅ `priceSyncJobStatus` → `https://{workspace}.versori.run/price-sync-job-status`
+- ❌ `dailyPriceSync` → NOT exposed (runs automatically on cron)
+
+---
+
+## SDK Methods Used
+
+**Core Services:**
+- `createClient(ctx)` - Create Fluent client (auto-detects Versori context)
+- `S3DataSource(config, log)` - S3 operations (list, download, upload, move)
+- `CSVParserService()` - CSV parsing with validation
+- `GraphQLMutationMapper(mappingConfig, log, { fluentClient: client })` - Field mapping with schema validation
+- `VersoriKVAdapter(openKv(':project:'))` - KV state management for duplicate prevention
+
+**Key Methods:**
+- `s3.listFiles({ prefix, maxKeys })` - List S3 files
+- `s3.downloadFile(path, options)` - Download file content
+- `s3.uploadFile(path, content)` - Upload file (accepts string or Buffer)
+- `s3.moveFile(source, dest)` - Archive or move file
+- `parser.parse(content, options)` - Parse CSV to records
+- `mapper.map(record)` - Transform single record
+- `client.graphql({ query, variables })` - Execute GraphQL mutations/queries
+- `kv.get(key)` / `kv.set(key, value)` - State management
+
+**Critical Imports:**
+- `Buffer` - **Required for Versori/Deno runtime** (S3 upload operations)
+ ```typescript
+ import { Buffer } from 'node:buffer';
+ ```
+ **Why:** Deno runtime (used by Versori) does not have `Buffer` as a global. However, `uploadFile()` accepts string or Buffer, so you can use strings directly without Buffer conversion.
+
+**Service Functions (User-Defined):**
+- `processFile()` - S3 download + CSV parsing + field mapping
+- `executeMutations()` - GraphQL price updates with validation + rate limiting
+- `writeMutationLog()` - Write execution log to S3 (uses Buffer)
+
+## Sample CSV Input Data
+
+**File**: `product-prices-20250122-001.csv`
+
+```csv
+sku,priceType,amount,currency,effectiveDate,expiryDate,minQuantity,maxQuantity
+PROD-001,DEFAULT,29.99,USD,2025-01-22T00:00:00Z,,1,
+PROD-002,SALE,19.99,USD,2025-01-22T00:00:00Z,2025-02-15T23:59:59Z,1,
+PROD-003,CLEARANCE,9.99,USD,2025-01-22T00:00:00Z,2025-01-31T23:59:59Z,1,
+PROD-004,DEFAULT,149.99,USD,2025-01-22T00:00:00Z,,1,
+PROD-004,BULK,129.99,USD,2025-01-22T00:00:00Z,,10,99
+PROD-004,BULK,119.99,USD,2025-01-22T00:00:00Z,,100,
+```
+
+**Note**: Products can have multiple price tiers. Same SKU with different `priceType` or quantity ranges = multiple rows.
+
+**Field Mapping**:
+
+- `sku` → Product reference (required) - must exist in Fluent
+- `priceType` → Price tier (DEFAULT, SALE, CLEARANCE, BULK, etc.) (required)
+- `amount` → Price value (required, must be > 0)
+- `currency` → Currency code (USD, EUR, GBP, etc.) (required)
+- `effectiveDate` → When price becomes active (ISO 8601 format)
+- `expiryDate` → When price expires (optional, ISO 8601 format)
+- `minQuantity` → Minimum quantity for this price tier (optional, default: 1)
+- `maxQuantity` → Maximum quantity for this price tier (optional)
+
+**Price Tier Logic**:
+
+- **DEFAULT**: Standard retail price (most products)
+- **SALE**: Temporary promotional price
+- **CLEARANCE**: Final markdown price
+- **BULK**: Quantity-based pricing (requires minQuantity/maxQuantity)
+
+## Project Setup
+
+```bash
+mkdir versori-s3-csv-price-sync && cd $_
+npm init -y
+npm install @fluentcommerce/fc-connect-sdk@latest @versori/run
+mkdir -p src
+```
+
+### Package Configuration (package.json)
+
+```json
+{
+ "name": "versori-s3-csv-price-sync",
+ "version": "1.0.0",
+ "description": "Versori workflow: S3 CSV price sync to Fluent GraphQL",
+ "versori": {
+  "workflows": "./src/index.ts"
+ },
+ "type": "module",
+ "scripts": {
+  "deploy": "versori deploy",
+  "logs": "versori logs"
+ },
+ "dependencies": {
+  "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+  "@versori/run": "latest"
+ },
+ "devDependencies": {
+  "typescript": "^5.0.0",
+  "@types/node": "^20.0.0"
+ }
+}
+```
+
+### Activation Variables (Versori)
+
+```bash
+# Required Variables
+s3BucketName=my-price-bucket
+awsAccessKeyId=AKIAXXXXXXXXXXXX
+awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+retailerId=your-retailer-id
+
+# Optional Variables (with defaults shown)
+awsRegion=us-east-1
+s3Prefix=prices/
+archivePrefix=processed/
+errorPrefix=errors/
+logPrefix=logs/       # Where to write mutation logs
+maxFilesToProcess=10
+filePattern=.csv
+enableArchival=true
+mutationRateLimit=10
+
+# Price Validation Rules
+minPrice=0.01       # Minimum allowed price
+maxPrice=999999.99     # Maximum allowed price
+validateProducts=true   # Validate products exist before updating prices
+```
+
+## Complete Workflow (src/index.ts)
+
+```typescript
+import { schedule, webhook, http, fn } from '@versori/run';
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
+import {
+ createClient,
+ S3DataSource,
+ CSVParserService,
+ GraphQLMutationMapper,
+ VersoriFileTracker,
+ JobTracker,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+interface FileProcessingResult {
+ fileName: string;
+ successful: number;
+ failed: number;
+ validationFailed: number;
+ priceChanges: Array<{
+  sku: string;
+  type: string;
+  oldPrice?: number;
+  newPrice: number;
+ }>;
+ errors: string[];
+}
+
+interface MutationResult {
+ successful: number;
+ failed: number;
+ priceChanges: Array<{
+  sku: string;
+  type: string;
+  oldPrice?: number;
+  newPrice: number;
+ }>;
+}
+
+interface MappedPriceData {
+ productRef: string;
+ type: string;
+ value: number;
+ currency: string;
+ effectiveFrom?: string;
+ effectiveTo?: string;
+ minQuantity?: number;
+ maxQuantity?: number;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Retry utility with exponential backoff
+ * (User-defined - not part of SDK public API)
+ */
+async function retryWithBackoff<T>(
+ operation: () => Promise<T>,
+ maxRetries = 3,
+ baseDelayMs = 1000
+): Promise<T> {
+ let lastError: any;
+ for (let attempt = 0; attempt < maxRetries; attempt++) {
+  try {
+   return await operation();
+  } catch (error) {
+   lastError = error;
+   if (attempt < maxRetries - 1) {
+    const delay = baseDelayMs * Math.pow(2, attempt) + Math.floor(Math.random() * 200);
+    await new Promise(resolve => setTimeout(resolve, delay));
+   }
+  }
+ }
+ throw lastError;
+}
+
+/**
+ * Validate product exists in Fluent Commerce
+ */
+async function validateProductExists(
+ client: any,
+ productRef: string,
+ retailerId: string,
+ log: any
+): Promise<boolean> {
+ const query = `
+  query GetProduct($ref: String!, $retailerId: ID!) {
+   products(first: 1, ref: [$ref], retailerId: $retailerId) {
+    edges {
+     node {
+      id
+      ref
+      status
+     }
+    }
+   }
+  }
+ `;
+
+ try {
+  const result = await client.graphql({
+   query,
+   variables: { ref: productRef, retailerId },
+  });
+
+  const product = result?.data?.products?.edges?.[0]?.node;
+  if (!product) {
+   log.warn(`Product not found: ${productRef}`);
+   return false;
+  }
+
+  if (product.status !== 'ACTIVE') {
+   log.warn(`Product not active: ${productRef} (status: ${product.status})`);
+   return false;
+  }
+
+  return true;
+ } catch (error: unknown) {
+  // ✅ Enhanced error logging: Extract all error details for visibility
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  const errorDetails = {
+   message: errorMsg,
+   stack: error instanceof Error ? error.stack : undefined,
+   errorType: error instanceof Error ? error.constructor.name : 'Error',
+  };
+  log.error(`Failed to validate product: ${productRef}`, errorDetails);
+  return false;
+ }
+}
+
+/**
+ * Get current product price for change tracking
+ */
+async function getCurrentPrice(
+ client: any,
+ productRef: string,
+ priceType: string,
+ currency: string,
+ retailerId: string
+): Promise<number | undefined> {
+ try {
+  const query = `
+   query GetProductPrice($ref: String!, $retailerId: ID!) {
+    products(first: 1, ref: [$ref], retailerId: $retailerId) {
+     edges {
+      node {
+       id
+       ref
+       prices {
+        type
+        value
+        currency
+       }
+      }
+     }
+    }
+   }
+  `;
+
+  const result = await client.graphql({
+   query,
+   variables: { ref: productRef, retailerId },
+  });
+
+  const product = result?.data?.products?.edges?.[0]?.node;
+  if (product?.prices) {
+   const existingPrice = product.prices.find(
+    (p: any) => p.type === priceType && p.currency === currency
+   );
+   if (existingPrice) {
+    return existingPrice.value;
+   }
+  }
+ } catch (err) {
+  // Ignore - price change tracking is optional
+ }
+ return undefined;
+}
+
+// ============================================================================
+// Service Function 1: Process File (S3 + CSV + Mapper)
+// ============================================================================
+
+/**
+ * Process single CSV file: Download from S3, parse CSV, map fields to Price schema
+ *
+ * @param s3 - S3DataSource instance
+ * @param parser - CSVParserService instance
+ * @param mapper - UniversalMapper instance (with custom price resolvers)
+ * @param filePath - S3 file path
+ * @param fileName - File name
+ * @param log - Logger instance
+ * @returns FileProcessingResult with parsed and mapped price data
+ */
+async function processFile(
+ s3: S3DataSource,
+ parser: CSVParserService,
+ mapper: GraphQLMutationMapper,
+ filePath: string,
+ fileName: string,
+ log: any
+): Promise<{ records: Array<{ query: string; variables: any; input: any }>; errors: string[] }> {
+ log.info('Processing file', { fileName });
+
+ // Download CSV from S3 with retry
+ const content = await retryWithBackoff(
+  () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
+ );
+
+ // Parse CSV
+ const rawRecords = await parser.parse(content, {
+  columns: true,
+  skip_empty_lines: true,
+  trim: true,
+ });
+
+ if (!rawRecords.length) {
+  log.warn('Empty CSV file', { fileName });
+  return { records: [], errors: [] };
+ }
+
+ log.info('CSV parsed', { fileName, recordCount: rawRecords.length });
+
+ // Map CSV records to Price schema
+  const mappedRecords: Array<{ query: string; variables: any; input: any }> = [];
+  const errors: string[] = [];
+
+  // ✅ PRODUCTION ENHANCEMENT: Log transformation start
+  log.info('Transforming records to GraphQL mutations', {
+   fileName,
+   totalRecords: rawRecords.length,
+  });
+
+  for (let i = 0; i < rawRecords.length; i++) {
+   const rec = rawRecords[i];
+   const recordNumber = i + 1;
+
+   // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 records
+   if (recordNumber % 50 === 0) {
+    log.info(`📤 Transforming record ${recordNumber}/${rawRecords.length}`, {
+     fileName,
+     recordNumber,
+     totalRecords: rawRecords.length,
+     validSoFar: mappedRecords.length,
+     errorsSoFar: errors.length,
+     progress: `${((recordNumber / rawRecords.length) * 100).toFixed(1)}%`,
+    });
+   }
+
+   try {
+    // GraphQLMutationMapper returns { query, variables } directly
+    const mapped = await mapper.map(rec);
+    
+    mappedRecords.push({
+     query: mapped.query,
+     variables: mapped.variables,
+     input: mapped.variables.input || mapped.variables,
+    });
+   } catch (error: unknown) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    errors.push(`Row ${recordNumber}: ${errorMsg}`);
+   }
+  }
+
+ log.info('Mapping completed', {
+  fileName,
+  successful: mappedRecords.length,
+  failed: errors.length,
+  totalRecords: rawRecords.length,
+  successRate: `${((mappedRecords.length / rawRecords.length) * 100).toFixed(1)}%`,
+ });
+
+ return { records: mappedRecords, errors };
+}
+
+// ============================================================================
+// Service Function 2: Execute Mutations (GraphQL Price Updates)
+// ============================================================================
+
+/**
+ * Execute GraphQL mutations for price updates with validation and rate limiting
+ * ✅ Supports alias batching for improved performance
+ *
+ * @param client - FluentClient instance
+ * @param mapper - GraphQLMutationMapper instance
+ * @param priceRecords - Mapped price data with query and variables
+ * @param retailerId - Fluent retailer ID
+ * @param validateProducts - Whether to validate product existence
+ * @param batchSize - Number of concurrent requests (concurrency control)
+ * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (alias batching)
+ * @param log - Logger instance
+ * @returns MutationResult with success/failure counts and price changes
+ */
+async function executeMutations(
+ client: any,
+ mapper: GraphQLMutationMapper,
+ priceRecords: Array<{ query: string; variables: any; input: any }>,
+ retailerId: string,
+ validateProducts: boolean,
+ batchSize: number = 1, // ✅ Default: 1 (sequential)
+ mutationsPerAliasBatch?: number, // ✅ NEW: Alias batching parameter (default: undefined = disabled)
+ log: any
+): Promise<MutationResult> {
+ let successful = 0;
+ let failed = 0;
+ const priceChanges: Array<{
+  sku: string;
+  type: string;
+  oldPrice?: number;
+  newPrice: number;
+ }> = [];
+
+ // ✅ Use alias batching if enabled
+ const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
+
+ if (useAliases) {
+  // Process with alias batching
+  const results = await executeMutationsWithAliases(
+   priceRecords,
+   client,
+   mapper,
+   log,
+   retailerId,
+   batchSize,
+   mutationsPerAliasBatch,
+   'updateProduct'
+  );
+  successful = results.executed;
+  failed = results.failed;
+  // Note: Price changes tracking would need to be done separately if needed
+ } else {
+  // Process individually with validation
+  for (const priceData of priceRecords) {
+   try {
+    // Validate product exists (if enabled)
+    if (validateProducts) {
+     const productExists = await validateProductExists(
+      client,
+      priceData.input.productRef,
+      retailerId,
+      log
+     );
+
+     if (!productExists) {
+      log.warn(`Skipping price update for non-existent product: ${priceData.input.productRef}`);
+      failed++;
+      continue;
+     }
+    }
+
+    // Get current price for change tracking
+    const currentPrice = await getCurrentPrice(
+     client,
+     priceData.input.productRef,
+     priceData.input.type,
+     priceData.input.currency,
+     retailerId
+    );
+
+    // Execute mutation using pre-generated query and variables
+    await retryWithBackoff(() =>
+     client.graphql({
+      query: priceData.query,
+      variables: priceData.variables,
+     })
+    );
+
+    successful++;
+
+    // Track price change
+    if (currentPrice !== undefined && currentPrice !== priceData.input.value) {
+     priceChanges.push({
+      sku: priceData.input.productRef,
+      type: priceData.input.type,
+      oldPrice: currentPrice,
+      newPrice: priceData.input.value,
+     });
+    }
+
+    log.info('Price updated', {
+     ref: priceData.input.productRef,
+     type: priceData.input.type,
+     oldPrice: currentPrice,
+     newPrice: priceData.input.value,
+     currency: priceData.input.currency,
+    });
+   } catch (error: unknown) {
+    failed++;
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    const errorDetails = {
+     message: errorMsg,
+     stack: error instanceof Error ? error.stack : undefined,
+     errorType: error instanceof Error ? error.constructor.name : 'Error',
+    };
+    log.error('Failed to update price', errorDetails, {
+     ref: priceData.input?.productRef,
+     type: priceData.input?.type,
+    });
+   }
+  }
+ }
+
+ return { successful, failed, priceChanges };
+}
+
+/**
+ * ✅ NEW: Execute mutations with GraphQL alias batching
+ */
+async function executeMutationsWithAliases(
+ priceRecords: Array<{ query: string; variables: any; input: any }>,
+ client: any,
+ mapper: GraphQLMutationMapper,
+ log: any,
+ retailerId: string,
+ maxParallel: number,
+ mutationsPerAliasBatch: number,
+ mutationName: string
+): Promise<{ executed: number; failed: number; errors: string[] }> {
+ const results = { executed: 0, failed: 0, errors: [] as string[] };
+ 
+ const aliasBatches: Array<Array<typeof priceRecords[0]>> = [];
+ for (let i = 0; i < priceRecords.length; i += mutationsPerAliasBatch) {
+  aliasBatches.push(priceRecords.slice(i, i + mutationsPerAliasBatch));
+ }
+ 
+ log.info(`Processing ${aliasBatches.length} alias batches`, {
+  totalPrices: priceRecords.length,
+  maxParallel,
+ });
+ 
+ for (let i = 0; i < aliasBatches.length; i += maxParallel) {
+  const concurrentBatches = aliasBatches.slice(i, i + maxParallel);
+  
+  const batchResults = await Promise.allSettled(
+   concurrentBatches.map(async (batch) => {
+    const { query, variables } = buildAliasedBatch(batch, mutationName, retailerId);
+    const response = await retryWithBackoff(() => client.graphql({ query, variables }), log);
+    return parseAliasResponse(response, batch, mutationName);
+   })
+  );
+  
+  batchResults.forEach((result, idx) => {
+   if (result.status === 'fulfilled') {
+    const batchResult = result.value;
+    results.executed += batchResult.executed;
+    results.failed += batchResult.failed;
+    results.errors.push(...batchResult.errors);
+   } else {
+    const batch = concurrentBatches[idx];
+    const errorMsg = result.reason instanceof Error ? result.reason.message : String(result.reason);
+    batch.forEach(price => {
+     results.failed++;
+     const productRef = price.input?.productRef || 'unknown';
+     results.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
+    });
+   }
+  });
+  
+  if (i + maxParallel < aliasBatches.length) {
+   await new Promise(resolve => setTimeout(resolve, 500));
+  }
+ }
+ 
+ return results;
+}
+
+/**
+ * ✅ NEW: Build aliased batch query and variables
+ */
+function buildAliasedBatch(
+ batch: Array<{ query: string; variables: any; input: any }>,
+ mutationName: string,
+ retailerId: string
+): { query: string; variables: Record<string, any> } {
+ const batchSize = batch.length;
+ const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
+ 
+ const variables = Array.from({ length: batchSize }, (_, i) => 
+  `$input${i + 1}: ${inputTypeName}!`
+ ).join(', ');
+ 
+ const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
+  const alias = `${mutationName}${i + 1}`;
+  return ` ${alias}: ${mutationName}(input: $input${i + 1}) { id ref }`;
+ }).join('\n');
+ 
+ const operationName = `Batch${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}s`;
+ const query = `mutation ${operationName}(${variables}) {\n${aliasedMutations}\n}`;
+ 
+ const variablesObj: Record<string, any> = {};
+ batch.forEach((price, index) => {
+  const input = price.variables.input || price.variables;
+  variablesObj[`input${index + 1}`] = input;
+ });
+ 
+ return { query, variables: variablesObj };
+}
+
+/**
+ * ✅ NEW: Parse aliased GraphQL response
+ */
+function parseAliasResponse(
+ response: any,
+ batch: Array<{ query: string; variables: any; input: any }>,
+ mutationName: string
+): { executed: number; failed: number; errors: string[] } {
+ const result = { executed: 0, failed: 0, errors: [] as string[] };
+ 
+ const data = response.data || {};
+ const errors = response.errors || [];
+ 
+ batch.forEach((price, index) => {
+  const alias = `${mutationName}${index + 1}`;
+  const aliasData = data[alias];
+  const aliasErrors = errors.filter((e: unknown) => 
+   e && typeof e === 'object' && 'path' in e && Array.isArray((e as any).path) && (e as any).path.includes(alias)
+  );
+  
+  if (aliasData && !aliasErrors.length) {
+   result.executed++;
+  } else {
+   result.failed++;
+   const errorMsg = aliasErrors[0] && typeof aliasErrors[0] === 'object' && 'message' in aliasErrors[0]
+    ? String((aliasErrors[0] as any).message)
+    : 'Mutation failed';
+   const productRef = price.input?.productRef || 'unknown';
+   result.errors.push(`Failed to update price for ${productRef}: ${errorMsg}`);
+  }
+ });
+ 
+ return result;
+}
+
+// ============================================================================
+// Service Function 3: Write Mutation Log (S3 Upload)
+// ============================================================================
+
+/**
+ * Write mutation execution log to S3
+ *
+ * @param s3 - S3DataSource instance
+ * @param fileName - Original CSV file name
+ * @param result - FileProcessingResult
+ * @param logPrefix - S3 prefix for logs
+ * @param log - Logger instance
+ */
+async function writeMutationLog(
+ s3: S3DataSource,
+ fileName: string,
+ result: FileProcessingResult,
+ logPrefix: string,
+ log: any
+): Promise<void> {
+ const logFileName = `${fileName.replace('.csv', '')}-log.json`;
+ const logPath = `${logPrefix}${logFileName}`;
+
+ const logData = {
+  fileName,
+  timestamp: new Date().toISOString(),
+  summary: {
+   successful: result.successful,
+   failed: result.failed,
+   validationFailed: result.validationFailed,
+   priceChanges: result.priceChanges.length,
+  },
+  priceChanges: result.priceChanges,
+  errors: result.errors,
+ };
+
+ const logContent = JSON.stringify(logData, null, 2);
+
+// Upload log to S3 (uploadFile accepts string or Buffer)
+await s3.uploadFile(logPath, logContent);
+
+ log.info('Mutation log written', { logPath });
+}
+
+// ============================================================================
+// Main Workflow Function (Per-File Processing)
+// ============================================================================
+
+async function executePriceSync(ctx: any, jobId: string, tracker: any) {
+ const { log, activation, openKv } = ctx;
+ const startTime = Date.now();
+
+ log.info('🔄 [PriceSync] Starting scheduled price sync from S3');
+
+ // ✅ CRITICAL: Declare S3 outside try block for safe disposal
+ let s3: S3DataSource | undefined;
+
+ try {
+  // ========================================
+  // STEP 1: CONFIGURATION & VALIDATION
+  // ========================================
+
+  // Read activation variables
+  const s3Bucket = activation?.getVariable('s3BucketName');
+  const s3Region = activation?.getVariable('awsRegion') || 'us-east-1';
+  const s3AccessKeyId = activation?.getVariable('awsAccessKeyId');
+  const s3SecretAccessKey = activation?.getVariable('awsSecretAccessKey');
+  const s3Prefix = activation?.getVariable('s3Prefix') || 'prices/';
+  const retailerId = activation?.getVariable('retailerId');
+  const maxFiles = parseInt(activation?.getVariable('maxFilesToProcess') || '10', 10);
+  const filePattern = (activation?.getVariable('filePattern') || '.csv').toLowerCase();
+  const enableArchival = activation?.getVariable('enableArchival') !== 'false';
+  const archivePrefix = activation?.getVariable('archivePrefix') || 'processed/';
+  const errorPrefix = activation?.getVariable('errorPrefix') || 'errors/';
+  const logPrefix = activation?.getVariable('logPrefix') || 'logs/';
+
+  // Configuration with defaults
+  const mutationBatchSize = parseInt(
+   activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
+   10
+  );
+
+  const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+   ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+   : undefined; // Default: undefined (disabled)
+
+  const minPrice = parseFloat(activation?.getVariable('minPrice') || '0.01');
+  const maxPrice = parseFloat(activation?.getVariable('maxPrice') || '999999.99');
+  const validateProducts = activation?.getVariable('validateProducts') !== 'false';
+  const validateConnection = activation?.getVariable('validateConnection') !== 'false';
+  const enableFileTracking = activation?.getVariable('enableFileTracking') !== 'false';
+
+  // Validate required variables
+  const missingVars: string[] = [];
+  if (!s3Bucket) missingVars.push('s3BucketName');
+  if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
+  if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
+  if (!retailerId) missingVars.push('retailerId');
+
+  if (missingVars.length > 0) {
+   const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
+   log.error('❌ [PriceSync] Configuration error', { error: errorMsg });
+   return {
+    success: false,
+    error: errorMsg,
+    recommendation: `Please configure these activation variables: ${missingVars.join(', ')}`,
+    processed: 0,
+    duration: Date.now() - startTime,
+   };
+  }
+
+  // ========================================
+  // STEP 2: CLIENT INITIALIZATION
+  // ========================================
+
+  const client = await createClient(ctx);
+  if (!client) {
+   throw new Error('Failed to create Fluent Commerce client');
+  }
+
+  // ✅ CORRECT: GraphQL mutations don't need setRetailerId()
+  // Check your GraphQL schema to determine retailerId handling:
+  // - Mandatory retailerId → Must pass it in mutation input
+  // - Optional retailerId → Can pass it if needed
+  // - No retailerId field → Don't pass it
+  // See: fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md
+
+  log.info('✅ [PriceSync] Fluent client initialized');
+
+  // ========================================
+  // STEP 3: SERVICE INITIALIZATION
+  // ========================================
+
+  s3 = new S3DataSource(
+   {
+    type: 'S3_CSV',
+    connectionId: 's3-price-sync',
+    name: 'Source S3',
+    s3Config: {
+     bucket: s3Bucket,
+     region: s3Region,
+     accessKeyId: s3AccessKeyId,
+     secretAccessKey: s3SecretAccessKey,
+    },
+   },
+   log
+  );
+
+  // Validate S3 connection if enabled
+  if (validateConnection) {
+   try {
+    await s3.listFiles({ prefix: s3Prefix, maxKeys: 1 });
+    log.info('✅ [PriceSync] S3 connection validated');
+   } catch (error: any) {
+    log.error('❌ [PriceSync] S3 connection validation failed', {
+     error: error instanceof Error ? error.message : String(error),
+    });
+    return {
+     success: false,
+     error: 'S3 connection validation failed',
+     details: error?.message,
+     recommendation: 'Please verify S3 credentials and bucket access permissions',
+     duration: Date.now() - startTime,
+    };
+   }
+  }
+
+  const parser = new CSVParserService();
+  const kv = openKv(':project:');
+  const fileTracker = enableFileTracking
+   ? new VersoriFileTracker(kv, 's3-csv-price-sync')
+   : null;
+
+ // Create custom resolvers for price validation
+ const customResolvers = {
+  'custom.validatePriceRange': (value: any) => {
+   const price = parseFloat(value);
+   if (isNaN(price)) {
+    throw new Error(`Invalid price: ${value}`);
+   }
+   if (price < minPrice) {
+    throw new Error(`Price ${price} below minimum ${minPrice}`);
+   }
+   if (price > maxPrice) {
+    throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
+   }
+   return price;
+  },
+
+  'custom.normalizePriceType': (value: any) => {
+   const type = String(value || 'DEFAULT').toUpperCase().trim();
+   const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
+   if (!validTypes.includes(type)) {
+    throw new Error(`Invalid price type: ${type}`);
+   }
+   return type;
+  },
+
+  'custom.normalizeQuantity': (value: any) => {
+   if (!value || value === '') return undefined;
+   const qty = parseInt(value, 10);
+   if (isNaN(qty) || qty < 0) {
+    throw new Error(`Invalid quantity: ${value}`);
+   }
+   return qty;
+  },
+ };
+
+ // ✅ CRITICAL: Load mapping config from external JSON file
+ // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
+ // File: src/config/price-mapping.json
+ const mappingConfigJson = await import('../config/price-mapping.json', { assert: { type: 'json' } });
+ const mappingConfig = mappingConfigJson.default;
+ 
+ // Initialize GraphQLMutationMapper with client for schema introspection
+ const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+
+  // ========================================
+  // STEP 4: FILE DISCOVERY
+  // ========================================
+
+  try {
+   // List files (pattern filtering handled by listFiles)
+   const files = await s3.listFiles({
+    prefix: s3Prefix,
+    pattern: filePattern,
+    maxKeys: 1000,
+   });
+
+   const csvFiles = files
+    .sort((a, b) => {
+     const dateA = a.lastModified ? new Date(a.lastModified).getTime() : 0;
+     const dateB = b.lastModified ? new Date(b.lastModified).getTime() : 0;
+     return dateA - dateB;
+    })
+    .slice(0, maxFiles);
+
+   log.info('📂 [PriceSync] Files discovered', {
+    total: files.length,
+    toProcess: csvFiles.length,
+    maxFiles,
+   });
+
+  const results = {
+   processed: 0,
+   skipped: 0,
+   failed: 0,
+   totalRecords: 0,
+   pricesUpdated: 0,
+   pricesSkipped: 0,
+   validationErrors: 0,
+   priceChanges: [] as Array<{
+    sku: string;
+    type: string;
+    oldPrice?: number;
+    newPrice: number;
+   }>,
+   errors: [] as string[],
+  };
+
+   // ========================================
+   // STEP 5: FILE PROCESSING LOOP
+   // ========================================
+
+   // Process each file using service functions
+   for (const file of csvFiles) {
+    const filePath = file.path;
+    const fileName = file.name;
+    const fileStartTime = Date.now();
+
+    log.info('📄 [PriceSync] Processing file', { fileName });
+
+    // Duplicate prevention via file tracker
+    if (fileTracker && (await fileTracker.wasFileProcessed(fileName))) {
+     log.info('⏭️ [PriceSync] Skipping already processed file', { fileName });
+     results.skipped++;
+     continue;
+    }
+
+    try {
+    // SERVICE FUNCTION 1: Process file (S3 + CSV + Mapper)
+    const { records: mappedRecords, errors: mappingErrors } = await processFile(
+     s3,
+     parser,
+     mapper,
+     filePath,
+     fileName,
+     log
+    );
+
+    if (!mappedRecords.length) {
+     log.warn('No valid records after mapping, archiving', { fileName });
+     if (enableArchival) {
+      await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+     }
+     results.skipped++;
+     continue;
+    }
+
+    // SERVICE FUNCTION 2: Execute mutations
+    // ✅ Configuration with defaults
+    const mutationBatchSize = parseInt(
+     ctx.activation?.getVariable('mutationBatchSize') || '1', // ✅ Default: 1 (sequential)
+     10
+    );
+    
+    const mutationsPerAliasBatch = ctx.activation?.getVariable('mutationsPerAliasBatch') 
+     ? parseInt(ctx.activation?.getVariable('mutationsPerAliasBatch') || '1', 10) 
+     : undefined; // ✅ Default: undefined (disabled, use separate requests)
+    
+    // ? Enhanced: Extract context for progress logging
+    const sampleProductRefs = mappedRecords.slice(0, 5).map((r: any) => r.input?.skuRef || r.input?.productRef || 'unknown');
+    const mutationType = mapper?.mutationName || 'updatePrice';
+
+    // ? Enhanced: Start logging with context
+    log.info(`[GraphQLMutations] Sending price mutations for file "${fileName}"`, {
+     totalMutations: mappedRecords.length,
+     mutationType,
+     batchSize: mutationBatchSize,
+     batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
+     sampleProductRefs: sampleProductRefs.join(', '),
+     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled',
+     validateProducts
+    });
+    
+    const mutationResult = await executeMutations(
+     client,
+     mapper,
+     mappedRecords,
+     retailerId,
+     validateProducts,
+     mutationBatchSize, // Concurrency control (default: 1)
+     mutationsPerAliasBatch, // ✅ NEW: Alias batching (default: undefined)
+     log
+    );
+
+    // ? Enhanced: Completion logging with summary
+    log.info(`[GraphQLMutations] Price mutation submission completed for file "${fileName}"`, {
+     totalMutations: mappedRecords.length,
+     successful: mutationResult.successful,
+     failed: mutationResult.failed,
+     successRate: mappedRecords.length > 0 ? `${Math.round((mutationResult.successful / mappedRecords.length) * 100)}%` : '0%',
+     mutationType,
+     priceChanges: mutationResult.priceChanges?.length || 0
+    });
+
+    // Aggregate results
+    results.processed++;
+    results.totalRecords += mappedRecords.length;
+    results.pricesUpdated += mutationResult.successful;
+    results.validationErrors += mappingErrors.length;
+    results.priceChanges.push(...mutationResult.priceChanges);
+
+    // Build file processing result for logging
+    const fileResult: FileProcessingResult = {
+     fileName,
+     successful: mutationResult.successful,
+     failed: mutationResult.failed,
+     validationFailed: mappingErrors.length,
+     priceChanges: mutationResult.priceChanges,
+     errors: mappingErrors,
+    };
+
+    // SERVICE FUNCTION 3: Write mutation log to S3
+    await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
+
+    // Mark processed with file tracker
+    if (fileTracker) {
+     await fileTracker.markFileProcessed(fileName, {
+      successful: mutationResult.successful,
+      failed: mutationResult.failed,
+      validationFailed: mappingErrors.length,
+      recordCount: mappedRecords.length,
+      duration: Date.now() - fileStartTime,
+     });
+    }
+
+    if (enableArchival) {
+     await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+    }
+
+    const fileDuration = Date.now() - fileStartTime;
+    log.info('✅ [PriceSync] File processed successfully', {
+     fileName,
+     recordCount: mappedRecords.length,
+     successful: mutationResult.successful,
+     failed: mutationResult.failed,
+     duration: `${fileDuration}ms`,
+    });
+
+    if (mappingErrors.length > 0) {
+     results.errors.push(`${fileName}: ${mappingErrors.length} mapping errors`);
+    }
+   } catch (error: unknown) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    const errorDetails = {
+     message: errorMsg,
+     stack: error instanceof Error ? error.stack : undefined,
+     errorType: error instanceof Error ? error.constructor.name : 'Error',
+    };
+    log.error('❌ [PriceSync] File processing failed', {
+     fileName,
+     ...errorDetails,
+    });
+    results.failed++;
+    results.errors.push(`${fileName}: ${errorMsg}`);
+
+    // Attempt to move to error directory
+    try {
+     await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
+     log.info('📁 [PriceSync] Moved failed file to error directory', { fileName });
+    } catch (moveError) {
+     log.error('❌ [PriceSync] Failed to move error file', {
+      fileName,
+      error: moveError instanceof Error ? moveError.message : String(moveError),
+     });
+    }
+   }
+  }
+
+   // ========================================
+   // STEP 6: SUMMARY & COMPLETION
+   // ========================================
+
+   const totalDuration = Date.now() - startTime;
+   const summary = {
+    success: true,
+    processed: results.processed,
+    skipped: results.skipped,
+    failed: results.failed,
+    totalRecords: results.totalRecords,
+    pricesUpdated: results.pricesUpdated,
+    pricesSkipped: results.pricesSkipped,
+    validationErrors: results.validationErrors,
+    priceChanges: results.priceChanges.length,
+    errors: results.errors.length > 0 ? results.errors : undefined,
+    duration: totalDuration,
+    timestamp: new Date().toISOString(),
+   };
+
+   log.info('🎉 [PriceSync] Price sync completed', {
+    ...summary,
+    duration: `${totalDuration}ms`,
+   });
+
+   // Log significant price changes
+   if (results.priceChanges.length > 0) {
+    log.info('💰 [PriceSync] Price changes detected', {
+     count: results.priceChanges.length,
+     changes: results.priceChanges.slice(0, 10),
+    });
+   }
+
+   return summary;
+  } catch (error: unknown) {
+   // ✅ Enhanced error logging: Extract all error details for visibility
+   const errorMsg = error instanceof Error ? error.message : String(error);
+   const errorDetails = {
+    message: errorMsg,
+    stack: error instanceof Error ? error.stack : undefined,
+    errorType: error instanceof Error ? error.constructor.name : 'Error',
+   };
+   log.error('❌ [PriceSync] Fatal error', errorDetails);
+   return {
+    success: false,
+    error: errorMsg,
+    recommendation: 'Check error logs for details and verify configuration',
+    processed: 0,
+    duration: Date.now() - startTime,
+    timestamp: new Date().toISOString(),
+   };
+  }
+ } catch (error: unknown) {
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  log.error('❌ [PriceSync] Initialization failed', {
+   error: errorMsg,
+   stack: error instanceof Error ? error.stack : undefined,
+  });
+  return {
+   success: false,
+   error: errorMsg,
+   recommendation: 'Check configuration and service initialization',
+   duration: Date.now() - startTime,
+  };
+ } finally {
+  // ✅ CRITICAL: Always dispose S3 connection to prevent connection pool exhaustion
+  if (s3) {
+   try {
+    await s3.dispose();
+    log.info('✅ [PriceSync] S3 connection disposed successfully');
+   } catch (disposeError: any) {
+    log.error('⚠️ [PriceSync] Failed to dispose S3 connection', {
+     error: disposeError instanceof Error ? disposeError.message : String(disposeError),
+     stack: disposeError instanceof Error ? disposeError.stack : undefined,
+    });
+    // Don't throw - disposal failure shouldn't prevent workflow completion
+   }
+  }
+ }
+}
+```
+
+**Note:** The `runPriceSync` function above should be renamed to `executePriceSync` and moved to `src/services/price-sync.service.ts` to match the new workflow structure.
+
+## Key Patterns Explained
+
+### Pattern 1: Service Function Architecture
+
+**Three modular service functions for clean separation of concerns:**
+
+```typescript
+// SERVICE FUNCTION 1: processFile()
+// Handles: S3 download + CSV parsing + field mapping
+const { records: mappedRecords, errors: mappingErrors } = await processFile(
+ s3,
+ parser,
+ mapper,
+ filePath,
+ fileName,
+ log
+);
+
+// SERVICE FUNCTION 2: executeMutations()
+// Handles: GraphQL mutations + product validation + concurrency control + price change tracking
+const mutationResult = await executeMutations(
+ client,
+ mapper,
+ mappedRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize,    // Concurrency control (default: 1)
+ mutationsPerAliasBatch,  // Alias batching (default: undefined)
+ log
+);
+
+// SERVICE FUNCTION 3: writeMutationLog()
+// Handles: Write execution log to S3 (with Buffer for Versori/Deno)
+await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
+```
+
+**Why this pattern?**
+- ✅ **Testability**: Each function can be unit tested independently
+- ✅ **Reusability**: Functions can be reused in different workflows
+- ✅ **Clarity**: Clear responsibilities for each step
+- ✅ **Error handling**: Isolated error boundaries per function
+- ✅ **Maintainability**: Easy to modify single concerns without affecting others
+
+### Pattern 2: Buffer Import for S3 Upload (Versori/Deno)
+
+**CRITICAL for Versori/Deno runtime:**
+
+```typescript
+// MUST import Buffer explicitly (not global like Node.js)
+import { Buffer } from 'node:buffer';
+
+// writeMutationLog() function
+async function writeMutationLog(s3, fileName, result, logPrefix, log) {
+ const logContent = JSON.stringify(logData, null, 2);
+
+ // ✅ CORRECT: Use Buffer.from() for S3 upload
+ await s3.uploadFile(logPath, logContent);
+
+ // ✅ CORRECT: uploadFile accepts string directly (no Buffer needed)
+ // await s3.uploadFile(logPath, logContent);
+}
+```
+
+**Why?** Deno runtime requires explicit `Buffer` import from `node:buffer`. Without it, you'll get `Buffer is not defined` errors.
+
+### Pattern 3: Direct KV State Management
+
+```typescript
+const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+// Check if file already processed
+const stateKey = ['processed-files', 's3-price-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) {
+ log.info('Skipping already processed file', { fileName });
+ continue;
+}
+
+// Mark as processed after success
+await kv.set(stateKey, {
+ successful,
+ failed,
+ validationFailed,
+ processedAt: new Date().toISOString(),
+});
+```
+
+### Pattern 4: Custom Price Validation Resolvers
+
+```typescript
+const customResolvers = {
+ 'custom.validatePriceRange': (value: any) => {
+  const price = parseFloat(value);
+  if (isNaN(price)) {
+   throw new Error(`Invalid price: ${value}`);
+  }
+  if (price < minPrice) {
+   throw new Error(`Price ${price} below minimum ${minPrice}`);
+  }
+  if (price > maxPrice) {
+   throw new Error(`Price ${price} exceeds maximum ${maxPrice}`);
+  }
+  return price;
+ },
+
+ 'custom.normalizePriceType': (value: any) => {
+  const type = String(value || 'DEFAULT').toUpperCase().trim();
+  const validTypes = ['DEFAULT', 'SALE', 'CLEARANCE', 'BULK', 'PROMOTIONAL', 'MEMBER'];
+  if (!validTypes.includes(type)) {
+   throw new Error(`Invalid price type: ${type}`);
+  }
+  return type;
+ },
+};
+```
+
+**Why this matters**: Price data requires strict validation to prevent:
+
+- Negative prices
+- Prices outside business rules (too low/high)
+- Invalid price tiers
+- Data entry errors
+
+### Pattern 5: Product Existence Validation
+
+```typescript
+async function validateProductExists(
+ client: any,
+ productRef: string,
+ retailerId: string,
+ log: any
+): Promise<boolean> {
+ const query = `
+  query GetProduct($ref: String!, $retailerId: ID!) {
+   products(first: 1, ref: [$ref], retailerId: $retailerId) {
+    edges {
+     node {
+      id
+      ref
+      status
+     }
+    }
+   }
+  }
+ `;
+
+ const result = await client.graphql({ query, variables: { ref: productRef, retailerId } });
+ const product = result?.data?.products?.edges?.[0]?.node;
+
+ if (!product || product.status !== 'ACTIVE') {
+  return false;
+ }
+
+ return true;
+}
+```
+
+**Why this matters**: Prevents price updates for non-existent products, which would fail at GraphQL level.
+
+### Pattern 6: Price Change Tracking
+
+```typescript
+// Get current price before update
+const currentPrice = await getCurrentPrice(
+ client,
+ priceData.productRef,
+ priceData.type,
+ priceData.currency,
+ retailerId
+);
+
+// Track change after update
+if (currentPrice !== undefined && currentPrice !== priceData.value) {
+ results.priceChanges.push({
+  sku: priceData.productRef,
+  type: priceData.type,
+  oldPrice: currentPrice,
+  newPrice: priceData.value,
+ });
+}
+
+// Log changes at end
+if (results.priceChanges.length > 0) {
+ log.info('Price changes detected', {
+  count: results.priceChanges.length,
+  changes: results.priceChanges.slice(0, 10),
+ });
+}
+```
+
+**Why this matters**: Provides audit trail and monitoring for price changes.
+
+### Pattern 7: Concurrency Control & Alias Batching
+
+```typescript
+// ✅ Configuration with defaults
+const mutationBatchSize = parseInt(
+ activation?.getVariable('mutationBatchSize') || '1', // Default: 1 (sequential)
+ 10
+);
+
+const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+ ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+ : undefined; // Default: undefined (disabled)
+
+// Execute with bounded concurrency + optional alias batching
+const mutationResult = await executeMutations(
+ client,
+ mapper,
+ priceRecords,
+ retailerId,
+ validateProducts,
+ mutationBatchSize,    // 1=sequential, 3-10=parallel
+ mutationsPerAliasBatch,  // Optional: Group mutations (e.g., 5)
+ log
+);
+```
+
+**Performance Modes:**
+- `mutationBatchSize: 1` → Sequential (safe default, ~1 mutation/sec)
+- `mutationBatchSize: 3-5` → Balanced (~3-5 mutations/sec)
+- `mutationBatchSize: 10` → High-volume (~10 mutations/sec)
+- `mutationsPerAliasBatch: 5` → Alias batching (reduces network overhead by ~80%)
+
+## Advanced: Multi-Currency Price Management
+
+### External Mapping File for Multi-Currency
+
+**File**: `config/price-mapping.json`
+
+```json
+{
+ "version": "1.0.0",
+ "description": "Multi-currency price mapping",
+ "fields": {
+  "productRef": {
+   "source": "sku",
+   "required": true,
+   "resolver": "sdk.trim"
+  },
+  "type": {
+   "source": "price_type",
+   "required": true,
+   "resolver": "custom.normalizePriceType"
+  },
+  "value": {
+   "source": "amount",
+   "required": true,
+   "resolver": "custom.validatePriceRange"
+  },
+  "currency": {
+   "source": "currency_code",
+   "required": true,
+   "resolver": "custom.normalizeCurrency"
+  },
+  "effectiveFrom": {
+   "source": "start_date",
+   "resolver": "sdk.formatDate"
+  },
+  "effectiveTo": {
+   "source": "end_date",
+   "resolver": "sdk.formatDate"
+  }
+ }
+}
+```
+
+### Custom Resolvers for Multi-Currency
+
+```typescript
+const customResolvers = {
+ 'custom.normalizeCurrency': (value: string) => {
+  // Normalize currency codes to ISO 4217
+  const currencyMap: Record<string, string> = {
+   usd: 'USD',
+   us: 'USD',
+   dollar: 'USD',
+   eur: 'EUR',
+   euro: 'EUR',
+   gbp: 'GBP',
+   pound: 'GBP',
+   cad: 'CAD',
+   aud: 'AUD',
+  };
+
+  const normalized = currencyMap[value.toLowerCase()] || value.toUpperCase();
+
+  // Validate against known currencies
+  const validCurrencies = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY', 'CNY'];
+  if (!validCurrencies.includes(normalized)) {
+   throw new Error(`Invalid currency code: ${value}`);
+  }
+
+  return normalized;
+ },
+
+ 'custom.convertToBaseCurrency': (value: any, sourceRecord: any) => {
+  // Convert foreign currency to base currency
+  const amount = parseFloat(value);
+  const currency = sourceRecord.currency_code;
+
+  // Exchange rates (in production, fetch from API)
+  const exchangeRates: Record<string, number> = {
+   USD: 1.0,
+   EUR: 0.85,
+   GBP: 0.73,
+   CAD: 1.35,
+   AUD: 1.45,
+  };
+
+  const rate = exchangeRates[currency?.toUpperCase()] || 1.0;
+  return amount * rate;
+ },
+
+ 'custom.buildPriceAttributes': (_: any, sourceRecord: any) => {
+  // Build price attributes array
+  const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+  if (sourceRecord.cost_basis) {
+   attributes.push({
+    name: 'costBasis',
+    type: 'Float',
+    value: parseFloat(sourceRecord.cost_basis),
+   });
+  }
+
+  if (sourceRecord.margin_percent) {
+   attributes.push({
+    name: 'marginPercent',
+    type: 'Float',
+    value: parseFloat(sourceRecord.margin_percent),
+   });
+  }
+
+  if (sourceRecord.competitor_price) {
+   attributes.push({
+    name: 'competitorPrice',
+    type: 'Float',
+    value: parseFloat(sourceRecord.competitor_price),
+   });
+  }
+
+  if (sourceRecord.price_source) {
+   attributes.push({
+    name: 'priceSource',
+    type: 'String',
+    value: sourceRecord.price_source,
+   });
+  }
+
+  return attributes;
+ },
+};
+```
+
+## Schema Validation (Before Deployment)
+
+Use SDK CLI tools to validate your GraphQL schema and mapping configuration:
+
+```bash
+# Install SDK globally (or use npx)
+npm install -g @fluentcommerce/fc-connect-sdk
+
+# 1. Introspect Fluent GraphQL schema
+fc-connect introspect-schema \
+ --url https://api.fluentcommerce.com/graphql \
+ --client-id YOUR_CLIENT_ID \
+ --client-secret YOUR_CLIENT_SECRET \
+ --output fluent-schema.json
+
+# 2. Create mutation file (price-mutation.graphql)
+cat > price-mutation.graphql << 'EOF'
+mutation UpdateProductPrice($input: UpdateProductInput!) {
+ updateProduct(input: $input) {
+  id
+  ref
+  prices {
+   type
+   value
+   currency
+  }
+ }
+}
+EOF
+
+# 3. Generate mapping from mutation (validates structure)
+fc-connect generate-mutation-mapping \
+ --file price-mutation.graphql \
+ --output price-mapping.json
+
+# 4. Validate mapping against schema
+fc-connect validate-schema \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+
+# 5. Analyze field coverage
+fc-connect analyze-coverage \
+ --mapping price-mapping.json \
+ --schema fluent-schema.json
+```
+
+**Output Example**:
+
+```bash
+✓ Schema validation passed
+✓ All required fields present: ref, retailerId, prices[].type, prices[].value, prices[].currency
+✓ Mutation structure matches GraphQL schema
+⚠ Optional fields not mapped: prices[].taxType, prices[].taxRate
+```
+
+## Testing the Workflow
+
+### 1. Upload Test CSV to S3
+
+```bash
+# Using AWS CLI
+aws s3 cp product-prices-test.csv s3://my-price-bucket/prices/
+
+# Or using S3 Console
+# Navigate to bucket → prices/ → Upload
+```
+
+### 2. Deploy to Versori
+
+```bash
+npm run deploy
+```
+
+### 3. Manual Testing via Webhook
+
+```bash
+curl -X POST https://your-workspace.versori.run/sync-prices-now \
+ -H "Content-Type: application/json"
+```
+
+### 4. Check Status
+
+```bash
+curl https://your-workspace.versori.run/check-status
+```
+
+### 5. Monitor Logs
+
+```bash
+npm run logs
+# Or via Versori dashboard
+```
+
+---
+
+## Monitoring
+
+### Success Response
+
+```json
+{
+ "success": true,
+ "filesProcessed": 1,
+ "filesSkipped": 0,
+ "filesFailed": 0,
+ "totalRecords": 100,
+ "mutationsExecuted": 100,
+ "mutationsFailed": 0,
+ "results": [
+  {
+   "file": "prices_2025-01-22.csv",
+   "success": true,
+   "recordsProcessed": 100,
+   "mutationsExecuted": 100,
+   "mutationsFailed": 0
+  }
+ ],
+ "duration": 12345
+}
+```
+
+### Partial Success Response
+
+```json
+{
+ "success": true,
+ "filesProcessed": 1,
+ "filesSkipped": 0,
+ "filesFailed": 0,
+ "totalRecords": 100,
+ "mutationsExecuted": 95,
+ "mutationsFailed": 5,
+ "results": [
+  {
+   "file": "prices_2025-01-22.csv",
+   "success": true,
+   "recordsProcessed": 100,
+   "mutationsExecuted": 95,
+   "mutationsFailed": 5,
+   "errors": ["PRICE-001: Invalid price value", "PRICE-002: Missing currency"]
+  }
+ ],
+ "duration": 12345
+}
+```
+
+### Error Response
+
+```json
+{
+ "success": false,
+ "filesProcessed": 0,
+ "filesFailed": 1,
+ "totalRecords": 0,
+ "mutationsExecuted": 0,
+ "mutationsFailed": 0,
+ "results": [
+  {
+   "file": "prices_2025-01-22.csv",
+   "success": false,
+   "error": "CSV parse error: Invalid structure"
+  }
+ ],
+ "duration": 876
+}
+```
+
+### Monitoring Metrics
+
+Monitor these metrics via Versori logs filtered by `jobId` or `stage`:
+
+- **Files Processed** - Total files successfully processed
+- **Mutations Executed** - Total GraphQL mutations executed successfully
+- **Mutations Failed** - Mutations that failed (check error logs)
+- **Processing Duration** - Time taken for complete workflow
+- **Rate Limiting** - Watch for 429 errors indicating GraphQL throttling
+
+Use the status webhook for dashboards and automated monitoring.
+
+---
+
+### Issue 1: Product Not Found
+
+**Error**: `Skipping price update for non-existent product: PROD-XYZ`
+
+**Solution**:
+
+- Verify product exists in Fluent Commerce
+- Check SKU matches exactly (case-sensitive)
+- Ensure product status is `ACTIVE`
+- Disable validation temporarily for testing: `validateProducts=false`
+
+### Issue 2: Price Validation Failures
+
+**Error**: `Price 0.00 below minimum 0.01`
+
+**Solution**:
+
+```bash
+# Adjust validation rules in activation variables
+minPrice=0.00 # Allow zero prices
+maxPrice=9999999.99 # Increase max
+```
+
+Or fix source data:
+
+```csv
+# ❌ WRONG
+PROD-001,DEFAULT,0,USD
+
+# ✅ CORRECT
+PROD-001,DEFAULT,0.01,USD
+```
+
+### Issue 3: Invalid Price Type
+
+**Error**: `Invalid price type: PROMO`
+
+**Solution**: Update custom resolver to include new type:
+
+```typescript
+'custom.normalizePriceType': (value: any) => {
+ const type = String(value || 'DEFAULT').toUpperCase().trim();
+ const validTypes = [
+  'DEFAULT',
+  'SALE',
+  'CLEARANCE',
+  'BULK',
+  'PROMOTIONAL',
+  'MEMBER',
+  'PROMO', // Add new type
+ ];
+ if (!validTypes.includes(type)) {
+  throw new Error(`Invalid price type: ${type}`);
+ }
+ return type;
+};
+```
+
+### Issue 4: Duplicate Price Updates
+
+**Symptom**: Same file processed multiple times
+
+**Solution**: VersoriKVAdapter already prevents this:
+
+```typescript
+const stateKey = ['processed-files', 's3-price-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) {
+ log.info('Skipping already processed file', { fileName });
+ continue;
+}
+```
+
+Verify KV storage is working:
+
+```bash
+# Check Versori logs for:
+[INFO] Skipping already processed file: product-prices-20250122-001.csv
+```
+
+### Issue 5: S3 Access Denied
+
+Required IAM Permissions:
+
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+  {
+   "Effect": "Allow",
+   "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+   "Resource": [
+    "arn:aws:s3:::my-price-bucket",
+    "arn:aws:s3:::my-price-bucket/*"
+   ]
+  }
+ ]
+}
+```
+
+### Issue 6: GraphQL Mutation Failures
+
+**Common Causes**:
+
+- Invalid price type (check Fluent schema for valid types)
+- Missing required fields (ref, retailerId, prices)
+- Invalid currency code (must be ISO 4217: USD, EUR, GBP)
+- Product not found or inactive
+
+**Debugging**:
+
+```typescript
+// Log mutation input before execution
+log.info('GraphQL mutation input', { input });
+
+// Validate required fields
+if (!priceData.productRef || !priceData.type || !priceData.value) {
+ log.error('Missing required fields', { priceData });
+ continue;
+}
+```
+
+## Production Checklist
+
+- [ ] S3 credentials validated with correct IAM permissions
+- [ ] Activation secrets stored securely (not in code)
+- [ ] GraphQL schema validated using CLI tools
+- [ ] Mapping configuration uses GraphQLMutationMapper structure (NOT UniversalMapper)
+- [ ] Mapping configuration tested with sample data
+- [ ] NO setRetailerId() call in code (only for Job/Event API)
+- [ ] Price validation rules configured per business policy
+- [ ] Product existence validation enabled (`validateProducts=true`)
+- [ ] File duplicate prevention working via KV state
+- [ ] Concurrency control configured (mutationBatchSize)
+- [ ] Optional alias batching tested if enabled (mutationsPerAliasBatch)
+- [ ] Error handling tested with malformed CSV
+- [ ] Retry logic tested with transient failures
+- [ ] File archival working (processed and error directories)
+- [ ] Price change tracking verified in logs
+- [ ] Monitoring/alerting configured for price update failures
+- [ ] Clear runbook for error recovery
+
+## Related Guides
+
+- **GraphQL Mutation Mapping**: `docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/`
+- **GraphQL Alias Batching**: `docs/02-CORE-GUIDES/mapping/graphql-alias-batching-guide.md`
+- **retailerId Configuration**: `docs/00-START-HERE/retailerid-configuration.md`
+- **CLI Tools**: `fc-connect-sdk/bin/readme.md`
+- **State & KV patterns**: `docs/03-PATTERN-GUIDES/file-operations/`
+- **Error handling**: `docs/03-PATTERN-GUIDES/error-handling/`