@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

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

@@ -1,2417 +1,2417 @@
----
-template_id: tpl-ingest-s3-csv-to-control-graphql
-canonical_filename: template-ingestion-s3-csv-control-graphql.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: s3-csv
-destination: fluent-graphql
-entity: control
-format: csv
-logging: versori
-status: stable
-compliance: gold-standard
-features:
-  - graphql-mutation-mapper
-  - memory-management
-  - enhanced-logging
-  - attribute-transformation
----
-
-# Template: Ingestion - S3 CSV to Control GraphQL
-
-**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: Read This Template As-Is (Do Not Execute Yet)
-
-**IMPORTANT:** This is a template that requires customization before use.
-
-**Purpose:** This template shows you how to build a scheduled Versori workflow that:
-- Reads Control CSV files from S3
-- Parses CSV records and validates them
-- Creates/updates Fluent Commerce controls via GraphQL mutations (createControl, updateControl)
-- Archives processed files and prevents duplicates via KV state
-- Handles rate limiting and retries
-- Tracks job status via JobTracker webhook
-
-**What You'll Learn:**
-- S3 file discovery with prefix filtering and archiving
-- CSV parsing with CSVParserService
-- Control entity structure (EXCLUSION vs QUANTITY_BUFFER types)
-- Direct GraphQL mutations (NOT Batch API)
-- Rate limiting (25-50 mutations at a time to prevent API throttling)
-- Custom control ref building (catalog + type + entity combinations)
-- Schema validation using CLI commands
-- Error handling and partial failure recovery
-- Versori KV state management for duplicate prevention
-- JobTracker integration with job-status webhook
-
-**Before You Begin:**
-1. Read through the entire template to understand the workflow
-2. Identify which parts need customization (marked with activation variables)
-3. Have your Fluent API credentials ready
-4. Have your S3 bucket details ready
-5. Understand Control entity structure in Fluent (see Sample CSV section)
-6. Review schema validation CLI commands (see Schema Validation section)
-
-## STEP 2: AI Agent Customization Instructions
-
-**If you are an AI agent helping a developer customize this template, follow these steps:**
-
-### 1. Gather Requirements
-
-Ask the developer:
-- **S3 Configuration:**
- - Bucket name and region
- - Access credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
- - Prefix for control files (e.g., `controls/` or `incoming/controls/`)
- - Archive prefix (e.g., `processed/` or `archive/`)
- - Error prefix (e.g., `errors/` or `failed/`)
-
-- **CSV Structure:**
- - Does CSV have pre-built control refs OR component fields?
- - Which control types are used? (EXCLUSION, QUANTITY_BUFFER, THRESHOLD, EXPIRY)
- - CSV column names and sample data
- - Any custom validation rules beyond schema requirements
-
-- **Processing Rules:**
- - Cron schedule (e.g., `0 2 * * *` = daily at 2 AM)
- - Max files to process per run (default: 10)
- - Rate limiting (mutations per second, default: 10)
- - File naming pattern (default: `.csv`)
- - Enable archival? (default: true)
- - Enable file tracking? (default: true) - prevents duplicate processing
- - Validate S3 connection on startup? (default: true)
-
-- **Fluent Configuration:**
- - GraphQL endpoint URL (usually `https://api.fluentcommerce.com/graphql`)
- - OAuth2 client credentials (will be in Versori connection)
- - ⚠️ NOTE: retailerId is NOT needed for GraphQL mutations (only for Job/Event API)
-
-### 2. Schema Validation (CRITICAL - Run First!)
-
-**Before customizing any code, validate the Control schema:**
-
-```bash
-# 1. Introspect current Fluent GraphQL schema
-npx @fluentcommerce/fc-connect-sdk introspect-schema \
- --url https://api.fluentcommerce.com/graphql \
- --client-id YOUR_CLIENT_ID \
- --client-secret YOUR_CLIENT_SECRET \
- --output fluent-schema.json
-
-# 2. Create test mutation file for Control
-cat > control-test-mutation.graphql << 'EOF'
-mutation CreateControl(
- $controlRef: String!
- $catalogRef: String!
- $controlType: String!
- $executionOrder: Int!
- $value: Json!
-) {
- createControl(input: {
-  type: $controlType
-  ref: $controlRef
-  name: $controlRef
-  values: { name: "CONTROL_VALUE", type: "INTEGER", value: $value }
-  controlGroup: { ref: $catalogRef }
-  executionOrder: $executionOrder
- }) {
-  ref
-  type
-  status
- }
-}
-EOF
-
-# 3. Validate mutation against schema
-npx @fluentcommerce/fc-connect-sdk validate-schema \
- --mapping control-test-mutation.graphql \
- --schema fluent-schema.json
-
-# 4. Analyze field coverage
-npx @fluentcommerce/fc-connect-sdk analyze-coverage \
- --mapping control-test-mutation.graphql \
- --schema fluent-schema.json
-```
-
-**Verify these Control fields exist in schema:**
-- `ref` (String!, required) - Unique control reference
-- `type` (String!, required) - Control type: EXCLUSION, QUANTITY_BUFFER, THRESHOLD, EXPIRY
-- `executionOrder` (Int!, required) - Priority: 1-999 (lower = higher priority)
-- `values` (Json!, required) - Control value object with name, type, value
-- `status` (String) - ACTIVE or INACTIVE
-- `controlGroup` (reference) - For EXCLUSION controls (uses catalogRef)
-- `virtualCatalogue` (reference) - For QUANTITY_BUFFER controls (uses catalogRef)
-
-### 3. Customize CSV Mapping
-
-**Update the `mappingConfig` in the template:**
-
-```typescript
-// ✅ CORRECT: GraphQLMutationMapper configuration structure
-// File: src/config/control-mapping.json
-{
- "mutation": "createControl",
- "arguments": {
-  "input": {
-   "type": { "source": "controlType", "required": true, "resolver": "uppercase" },
-   "ref": { "resolver": "custom.buildOrUseControlRef", "required": true },
-   "name": { "resolver": "custom.buildOrUseControlRef" },
-   "values": {
-    "value": [
-     {
-      "name": { "value": "CONTROL_VALUE" },
-      "type": { "value": "INTEGER" },
-      "value": { "source": "value", "required": true, "resolver": "parseInt" }
-     }
-    ]
-   },
-   "executionOrder": { "source": "executionOrder", "required": true, "resolver": "parseInt" },
-   "controlGroup": {
-    "ref": { "resolver": "custom.resolveCatalogRef", "required": true }
-   }
-  }
- }
-}
-
-**Save mapping to config file:**
-```bash
-mkdir -p config
-cat > config/control.import.csv.json << 'EOF'
-{
- "version": "2.0.0",
- "description": "CSV control to Fluent Commerce GraphQL mapping",
- "fields": {
-  "controlRef": { "resolver": "custom.buildOrUseControlRef", "required": true },
-  "catalogRef": { "resolver": "custom.resolveCatalogRef", "required": true },
-  "controlType": { "source": "controlType", "required": true, "resolver": "sdk.uppercase" },
-  "executionOrder": { "source": "executionOrder", "required": true, "resolver": "sdk.parseInt" },
-  "value": { "source": "value", "required": true, "resolver": "sdk.parseInt" },
-  "status": { "source": "status", "resolver": "sdk.uppercase" }
- }
-}
-EOF
-```
-
-### 4. Control Ref Building Rules
-
-**EXCLUSION controls (catalog + type + product/category):**
-```typescript
-// Pattern: {controlGroupRef}:EXCLUSION:{productRef|categoryRef}
-// Examples:
-CG-RETAIL:EXCLUSION:CAT-SEASONAL   // Category exclusion
-CG-RETAIL:EXCLUSION:PROD-12345    // Product exclusion
-```
-
-**QUANTITY_BUFFER controls (catalog + type + product/category/location):**
-```typescript
-// Pattern: {virtualCatalogueRef}:QUANTITY_BUFFER:{productRef}[:{locationRef}]
-// Examples:
-VC-RETAIL:QUANTITY_BUFFER:PROD-98765:LOC-001 // Product at location
-VC-RETAIL:QUANTITY_BUFFER:PROD-11111     // Product (all locations)
-VC-RETAIL:QUANTITY_BUFFER:CAT-ELECTRONICS   // Category
-VC-RETAIL:QUANTITY_BUFFER:LOC-002       // Location (all products)
-```
-
-**Validation rules:**
-- EXCLUSION must have `controlGroupRef` + (`productRef` OR `categoryRef`)
-- EXCLUSION must have `value=0` (always zero)
-- QUANTITY_BUFFER must have `virtualCatalogueRef` + (`productRef` OR `categoryRef` OR `locationRef`)
-- QUANTITY_BUFFER must have `value >= 0`
-- `executionOrder` must be 1-999 (lower = higher priority)
-- `status` must be ACTIVE or INACTIVE (defaults to ACTIVE if not provided)
-
-### 5. Rate Limiting Configuration
-
-**Why rate limiting is critical:**
-- Fluent GraphQL API has rate limits
-- Direct mutations (NOT Batch API) hit GraphQL endpoint directly
-- Recommended: 10-25 mutations per second
-- Higher rates may cause 429 (Too Many Requests) errors
-
-**Configure in activation variables:**
-```bash
-# Conservative (10 mutations/sec = 100ms delay between mutations)
-mutationRateLimit=10
-
-# Aggressive (25 mutations/sec = 40ms delay)
-mutationRateLimit=25
-
-# Very aggressive (50 mutations/sec = 20ms delay) - use with caution
-mutationRateLimit=50
-```
-
-**Implementation in template:**
-```typescript
-const rateLimit = parseInt(ctx.activation?.getVariable('mutationRateLimit') || '10', 10);
-const delayMs = rateLimit > 0 ? Math.floor(1000 / rateLimit) : 0;
-
-// Apply delay after each mutation
-await rateLimitedMutation(
- () => client.graphql({ query: createMutation, variables }),
- delayMs
-);
-```
-
-### 6. NO Batch API Guidance
-
-**This template uses DIRECT GraphQL mutations, NOT the Batch API:**
-
-**Why Direct Mutations:**
-- Controls are typically small volume (100s, not 1000s)
-- Need immediate feedback on create/update success
-- Simpler error handling (per-control vs per-batch)
-- No BPP (Batch Pre-Processing) needed
-
-**What This Means:**
-- Each control = 1 GraphQL mutation (createControl or updateControl)
-- Rate limiting is CRITICAL to prevent API throttling
-- No job/batch polling - mutations succeed or fail immediately
-- Errors are handled per-control, not per-batch
-
-**DO NOT use Batch API methods:**
-```typescript
-// ❌ WRONG - Don't use these for controls
-await client.createJob({ ... });
-await client.sendBatch(jobId, { ... });
-await client.getBatchStatus(jobId, batchId);
-```
-
-**✅ CORRECT - Use direct mutations:**
-```typescript
-// Check if exists
-const checkResult = await client.graphql({
- query: checkQuery,
- variables: { ref: control.controlRef }
-});
-
-// Create or update
-if (exists) {
- await client.graphql({ query: updateMutation, variables });
-} else {
- await client.graphql({ query: createMutation, variables });
-}
-```
-
-### 7. JobTracker Integration
-
-**This template includes JobTracker with job-status webhook:**
-
-```typescript
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-
-// Start job
-const tracker = new JobTracker(openKv(':project:'), log);
-await tracker.startJob(jobId, { mode: 'scheduled' });
-
-// Update progress (optional)
-await tracker.updateJob(jobId, {
- processed: results.processed,
- controlsCreated: results.controlsCreated
-});
-
-// Complete or fail
-if (success) {
- await tracker.completeJob(jobId, { result });
-} else {
- await tracker.failJob(jobId, { error: e?.message });
-}
-```
-
-**Query job status via webhook:**
-```bash
-curl -X POST https://your-workspace.versori.run/control-csv-job-status \
- -H "x-api-key: YOUR_WEBHOOK_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"jobId": "control-csv-1234567890"}'
-```
-
-### 8. Testing Checklist
-
-Before deploying to production:
-
-- [ ] Schema validation passed (introspect-schema, validate-schema)
-- [ ] CSV mapping tested with sample data
-- [ ] Control ref building logic verified (EXCLUSION vs QUANTITY_BUFFER)
-- [ ] Rate limiting configured appropriately
-- [ ] S3 credentials validated
-- [ ] Activation variables configured in Versori
-- [ ] Test file uploaded to S3
-- [ ] Manual webhook trigger tested
-- [ ] File archival working (processed and error directories)
-- [ ] JobTracker status webhook tested
-- [ ] Error handling tested with malformed CSV
-- [ ] Duplicate prevention working via KV state
-
-### 9. Common Customizations
-
-**Change cron schedule:**
-```typescript
-// Daily at 2 AM
-export const scheduledControlSync = schedule('control-csv-scheduled', '0 2 * * *')
-
-// Every 6 hours
-export const scheduledControlSync = schedule('control-csv-scheduled', '0 */6 * * *')
-
-// Hourly
-export const scheduledControlSync = schedule('control-csv-scheduled', '0 * * * *')
-```
-
-**Add custom validation:**
-```typescript
-// In ControlSchemaValidator class
-validateCustomRules(control: any): { valid: boolean; errors: string[] } {
- const errors: string[] = [];
-
- // Example: Require description for all controls
- if (!control.description?.trim()) {
-  errors.push('description is required');
- }
-
- // Example: Value range validation for QUANTITY_BUFFER
- if (control.controlType === 'QUANTITY_BUFFER' && control.value > 1000) {
-  errors.push('QUANTITY_BUFFER value cannot exceed 1000');
- }
-
- return { valid: errors.length === 0, errors };
-}
-```
-
-**Change file pattern:**
-```typescript
-// Only process files starting with "control-"
-const filePattern = 'control-.csv';
-
-// Process multiple extensions
-const filePattern = '.csv|.txt';
-```
-
-### 10. Deployment Steps
-
-```bash
-# 1. Install dependencies
-npm install @fluentcommerce/fc-connect-sdk@^0.1.39 @versori/run
-
-# 2. Configure activation variables in Versori
-# (See Activation Variables section in template)
-
-# 3. Deploy
-npm run deploy
-
-# 4. Test manual trigger
-curl -X POST https://your-workspace.versori.run/control-csv-adhoc \
- -H "x-api-key: YOUR_WEBHOOK_API_KEY"
-
-# 5. Monitor logs
-npm run logs
-
-# 6. Check job status
-curl -X POST https://your-workspace.versori.run/control-csv-job-status \
- -H "x-api-key: YOUR_WEBHOOK_API_KEY" \
- -d '{"jobId": "control-csv-1234567890"}'
-```
-
----
-
-# Template: Ingestion - S3 CSV to Control GraphQL
-
-**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@^0.1.39`
-
-**Context**: Scheduled Versori workflow that reads control CSV files from S3 and creates/updates Fluent Commerce controls 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 with custom control ref building
-- GraphQL mutations for control upserts with rate limiting
-- Versori KV state management (duplicate prevention)
-- File archival after processing
-- Schema validation for control-specific rules
-
-## 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-control-graphql/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-control-sync.ts    # Scheduled: Daily control sync
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-control-sync.ts    # Webhook: Manual trigger
-    │       └── job-status-check.ts     # Webhook: Status query
-    │
-    ├── services/
-    │   └── control-sync.service.ts      # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── control-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-control-sync.ts`
-
-**Purpose**: Automatic daily control 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 { executeControlSync } from '../../services/control-sync.service';
-
-/**
- * Scheduled Workflow: Daily Control Sync
- *
- * Runs automatically daily at 2 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Uses shared service: control-sync.service.ts
- */
-export const dailyControlSync = schedule(
-  'control-sync-scheduled',
-  '0 2 * * *' // Daily at 2 AM UTC
-).then(
-  http('run-control-sync', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, openKv } = ctx;
-    const executionStartTime = Date.now();
-    const jobId = `control-sync-${executionStartTime}`;
-    const tracker = new JobTracker(openKv(':project:'), log);
-
-    await tracker.createJob(jobId, {
-      triggeredBy: 'schedule',
-      stage: 'initialization',
-      startTime: executionStartTime,
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-
-    try {
-      const result = await executeControlSync(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-      return { success: false, jobId, error: e?.message };
-    }
-  })
-);
-```
-
----
-
-### 2. Webhook Workflows (`src/workflows/webhook/`)
-
-All HTTP-based triggers that create webhook endpoints.
-
-#### `src/workflows/webhook/adhoc-control-sync.ts`
-
-**Purpose**: Manual control sync trigger (on-demand)
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/control-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 { executeControlSync } from '../../services/control-sync.service';
-
-/**
- * Webhook: Manual Control Sync Trigger
- *
- * Endpoint: POST https://{workspace}.versori.run/control-sync-adhoc
- * Request body (optional): { filePattern: "urgent_*.csv", maxFiles: 5 }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: control-sync.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const adhocControlSync = webhook('control-sync-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'control-sync-adhoc', // Versori validates API key
-}).then(
-  http('run-control-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, openKv, data } = ctx;
-    const executionStartTime = Date.now();
-    const jobId = `control-sync-adhoc-${executionStartTime}`;
-    const tracker = new JobTracker(openKv(':project:'), log);
-
-    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 executeControlSync(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-      return { success: true, jobId, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-      return { success: false, jobId, error: e?.message };
-    }
-  })
-);
-```
-
----
-
-#### `src/workflows/webhook/job-status-check.ts`
-
-**Purpose**: Query job status
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/control-sync-job-status`
-**Request body**: `{ "jobId": "control-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/control-sync-job-status
- * Request body: { "jobId": "control-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 controlSyncJobStatus = webhook('control-sync-job-status', {
-  response: { mode: 'sync' },
-  connection: 'control-sync-job-status',
-}).then(
-  fn('status', async ctx => {
-    const { data, log, openKv } = ctx;
-    const jobId = data?.jobId as string;
-
-    if (!jobId) {
-      return { success: false, error: 'jobId required' };
-    }
-
-    const tracker = new JobTracker(openKv(':project:'), log);
-    const status = await tracker.getJob(jobId);
-
-    return status
-      ? { success: true, jobId, ...status }
-      : { success: false, error: 'Job not found', jobId };
-  })
-);
-```
-
----
-
-### 3. Entry Point (`index.ts`)
-
-**Purpose**: Register all workflows with Versori platform
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/scheduled/ → Time-based triggers (cron)
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- */
-
-// Import scheduled workflows
-export { dailyControlSync } from './src/workflows/scheduled/daily-control-sync';
-
-// Import webhook workflows
-export { adhocControlSync } from './src/workflows/webhook/adhoc-control-sync';
-export { controlSyncJobStatus } from './src/workflows/webhook/job-status-check';
-```
-
-**What Gets Exposed:**
-- ✅ `adhocControlSync` → `https://{workspace}.versori.run/control-sync-adhoc`
-- ✅ `controlSyncJobStatus` → `https://{workspace}.versori.run/control-sync-job-status`
-- ❌ `dailyControlSync` → NOT exposed (runs automatically on cron)
-
----
-
-## SDK Methods Used
-
-- `createClient(ctx)` - Create Fluent client (auto-detects Versori context)
-- `S3DataSource(config, log)` - S3 operations
-- `CSVParserService()` - CSV parsing
-- `GraphQLMutationMapper(mappingConfig, log, { fluentClient: client })` - Field mapping with schema validation
-- `mapper.map(record)` - Transform single record
-- `client.graphql({ query, variables })` - Execute GraphQL mutation
-- `VersoriKVAdapter` - Direct KV access for state management
-
-## Service Functions Architecture
-
-This template uses **three dedicated service functions** for clean separation of concerns:
-
-### 1. processFile()
-**Purpose:** Download, parse, map, and validate CSV file
-**Inputs:** S3DataSource, CSVParserService, GraphQLMutationMapper, ControlSchemaValidator, filePath, fileName, log
-**Returns:** FileProcessingResult with valid records ready for mutation
-**Responsibilities:**
-- Download file from S3 with retry
-- Parse CSV records
-- Map each record using GraphQLMutationMapper
-- Validate control schema
-- Return validated records for mutation
-
-### 2. executeMutations()
-**Purpose:** Execute GraphQL mutations for control records
-**Inputs:** FluentClient, ControlRecord[], delayMs (rate limit), log
-**Returns:** MutationResult[] with success/failure per control
-**Responsibilities:**
-- Check if control exists (query)
-- Create or update control (mutation)
-- Apply rate limiting between mutations
-- Track success/failure per control
-
-### 3. writeMutationLog()
-**Purpose:** Write detailed mutation results log to S3
-**Inputs:** S3DataSource, fileName, FileProcessingResult, logPrefix, log
-**Returns:** boolean (upload success)
-**Responsibilities:**
-- Create JSON log with processing summary
-- Include mutation results (created, updated, failed)
-- Upload to S3 logs directory using Buffer
-- Handle upload errors gracefully
-
-### Workflow Flow
-```
-Main Workflow (runControlSync)
- ↓
-List S3 files → Filter CSV files
- ↓
-For each file:
- ↓
- 1. processFile() → Download, parse, map, validate
- ↓
- 2. executeMutations() → Create/update controls with rate limiting
- ↓
- 3. writeMutationLog() → Write detailed logs to S3
- ↓
- Archive file → Update KV state
- ↓
-Return summary
-```
-
-## Sample CSV Input Data
-
-### Option 1: Component-Based (Recommended)
-
-**File**: `controls-20250122-001.csv`
-
-```csv
-controlGroupRef,virtualCatalogueRef,controlType,productRef,categoryRef,locationRef,executionOrder,value,status,description
-CG-RETAIL,,EXCLUSION,,CAT-SEASONAL,,1,0,ACTIVE,Seasonal items - in-store only
-CG-RETAIL,,EXCLUSION,PROD-12345,,,2,0,ACTIVE,Product recall active
-,VC-RETAIL,QUANTITY_BUFFER,PROD-98765,,LOC-001,3,10,ACTIVE,NYC flagship - high foot traffic
-,VC-RETAIL,QUANTITY_BUFFER,PROD-11111,,,4,5,ACTIVE,Fast-moving product safety stock
-,VC-RETAIL,QUANTITY_BUFFER,,CAT-ELECTRONICS,,5,20,ACTIVE,All electronics buffer
-,VC-RETAIL,QUANTITY_BUFFER,,,LOC-002,6,100,ACTIVE,Flagship store large buffer
-```
-
-**Note**: Use `controlGroupRef` for EXCLUSION controls, `virtualCatalogueRef` for QUANTITY_BUFFER controls.
-
-### Option 2: Pre-Built Refs (Simple)
-
-```csv
-controlRef,catalogRef,controlType,executionOrder,value,status
-CG-RETAIL:EXCLUSION:CAT-SEASONAL,CG-RETAIL,EXCLUSION,1,0,ACTIVE
-CG-RETAIL:EXCLUSION:PROD-12345,CG-RETAIL,EXCLUSION,2,0,ACTIVE
-VC-RETAIL:QUANTITY_BUFFER:PROD-98765:LOC-001,VC-RETAIL,QUANTITY_BUFFER,3,10,ACTIVE
-VC-RETAIL:QUANTITY_BUFFER:PROD-11111,VC-RETAIL,QUANTITY_BUFFER,4,5,ACTIVE
-```
-
-**Field Mapping**:
-
-- `controlRef` → Unique control reference (auto-built from components or pre-built)
-- `controlGroupRef` → Control Group reference (for EXCLUSION controls)
-- `virtualCatalogueRef` → Virtual Catalogue reference (for QUANTITY_BUFFER controls)
-- `catalogRef` → Generic catalog reference (for pre-built format)
-- `controlType` → Control type: EXCLUSION or QUANTITY_BUFFER (required)
-- `productRef` → Product reference (optional, used in ref building)
-- `categoryRef` → Category reference (optional, used in ref building)
-- `locationRef` → Location reference (optional, used in ref building)
-- `executionOrder` → Execution priority: 1-999 (lower = higher priority) (required)
-- `value` → Control value: 0 for EXCLUSION, ≥0 for QUANTITY_BUFFER (required)
-- `status` → Control status: ACTIVE or INACTIVE (defaults to ACTIVE)
-
-## Project Setup
-
-```bash
-mkdir versori-s3-csv-control-sync && cd $_
-npm init -y
-npm install @fluentcommerce/fc-connect-sdk@^0.1.39 @versori/run
-mkdir -p src
-```
-
-### Package Configuration (package.json)
-
-```json
-{
- "name": "versori-s3-csv-control-sync",
- "version": "1.0.0",
- "description": "Versori workflow: S3 CSV control 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-controls-bucket
-awsAccessKeyId=AKIAXXXXXXXXXXXX
-awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-
-# Optional Variables (with defaults shown)
-awsRegion=us-east-1
-s3Prefix=controls/
-archivePrefix=processed/
-errorPrefix=errors/
-logPrefix=logs/
-maxFilesToProcess=10
-filePattern=.csv
-enableArchival=true
-enableFileTracking=true
-validateConnection=true
-mutationRateLimit=10
-mutationBatchSize=1
-# mutationsPerAliasBatch=5 # Optional: Enable alias batching for high-volume scenarios
-
-# ⚠️ NOTE: 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
-# Standard createControl/updateControl do not have retailerId field - only use if your custom schema requires it
-```
-
-## Complete Workflow (src/index.ts)
-
-```typescript
-import { Buffer } from 'node:buffer'; // Required for Deno/Versori runtime
-import { schedule, webhook, http, fn } from '@versori/run';
-import {
- createClient,
- S3DataSource,
- CSVParserService,
- GraphQLMutationMapper,
- VersoriKVAdapter,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// ============================================================================
-// TYPES
-// ============================================================================
-
-interface FileProcessingResult {
- success: boolean;
- fileName: string;
- recordsProcessed: number;
- recordsSuccessful: number;
- recordsFailed: number;
- mutations: MutationResult[];
- errors: string[];
-}
-
-interface MutationResult {
- success: boolean;
- controlRef: string;
- operation: 'create' | 'update';
- error?: string;
-}
-
-interface ControlRecord {
- controlRef: string;
- catalogRef: string;
- controlType: string;
- executionOrder: number;
- value: number;
- status?: string;
-}
-
-// ============================================================================
-// UTILITY FUNCTIONS
-// ============================================================================
-
-/**
- * Retry utility with exponential backoff
- */
-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;
-}
-
-/**
- * Rate limiter with delay after operation
- */
-async function rateLimitedMutation(operation: () => Promise<any>, delayMs: number): Promise<any> {
- const result = await operation();
- if (delayMs > 0) {
-  await new Promise(resolve => setTimeout(resolve, delayMs));
- }
- return result;
-}
-
-/**
- * Build control ref from components
- */
-function buildControlRef(data: {
- controlGroupRef?: string;
- virtualCatalogueRef?: string;
- controlType: string;
- productRef?: string;
- categoryRef?: string;
- locationRef?: string;
-}): string {
- const { controlGroupRef, virtualCatalogueRef, controlType, productRef, categoryRef, locationRef } =
-  data;
-
- if (controlType === 'EXCLUSION') {
-  if (!controlGroupRef) throw new Error('EXCLUSION requires controlGroupRef');
-  if (categoryRef) return `${controlGroupRef}:EXCLUSION:${categoryRef}`;
-  else if (productRef) return `${controlGroupRef}:EXCLUSION:${productRef}`;
-  throw new Error('EXCLUSION requires either categoryRef or productRef');
- } else if (controlType === 'QUANTITY_BUFFER') {
-  if (!virtualCatalogueRef) throw new Error('QUANTITY_BUFFER requires virtualCatalogueRef');
-  if (productRef && locationRef)
-   return `${virtualCatalogueRef}:QUANTITY_BUFFER:${productRef}:${locationRef}`;
-  else if (productRef) return `${virtualCatalogueRef}:QUANTITY_BUFFER:${productRef}`;
-  else if (categoryRef) return `${virtualCatalogueRef}:QUANTITY_BUFFER:${categoryRef}`;
-  else if (locationRef) return `${virtualCatalogueRef}:QUANTITY_BUFFER:${locationRef}`;
-  throw new Error('QUANTITY_BUFFER requires productRef, categoryRef, or locationRef');
- }
- throw new Error(`Unknown control type: ${controlType}`);
-}
-
-/**
- * Schema validator for Control entities
- */
-class ControlSchemaValidator {
- private readonly VALID_CONTROL_TYPES = ['QUANTITY_BUFFER', 'EXCLUSION'];
- private readonly VALID_STATUSES = ['ACTIVE', 'INACTIVE'];
- private readonly MIN_EXECUTION_ORDER = 1;
- private readonly MAX_EXECUTION_ORDER = 999;
-
- validateForCreate(control: any): { valid: boolean; errors: string[] } {
-  const errors: string[] = [];
-
-  if (!control.controlRef?.trim()) errors.push('controlRef is required');
-  if (!control.catalogRef?.trim()) errors.push('catalogRef is required');
-
-  if (!control.controlType?.trim()) {
-   errors.push('controlType is required');
-  } else if (!this.VALID_CONTROL_TYPES.includes(control.controlType)) {
-   errors.push(`Invalid controlType: ${control.controlType}`);
-  }
-
-  if (control.executionOrder === undefined || control.executionOrder === null) {
-   errors.push('executionOrder is required');
-  } else {
-   const order = parseInt(control.executionOrder, 10);
-   if (isNaN(order) || order < this.MIN_EXECUTION_ORDER || order > this.MAX_EXECUTION_ORDER) {
-    errors.push(`executionOrder must be ${this.MIN_EXECUTION_ORDER}-${this.MAX_EXECUTION_ORDER}`);
-   }
-  }
-
-  if (control.value === undefined || control.value === null) {
-   errors.push('value is required');
-  } else {
-   const value = parseInt(control.value, 10);
-   if (isNaN(value)) errors.push('value must be integer');
-   if (control.controlType === 'EXCLUSION' && value !== 0) {
-    errors.push('EXCLUSION must have value=0');
-   }
-   if (control.controlType === 'QUANTITY_BUFFER' && value < 0) {
-    errors.push('QUANTITY_BUFFER value cannot be negative');
-   }
-  }
-
-  if (control.status && !this.VALID_STATUSES.includes(control.status)) {
-   errors.push(`Invalid status: ${control.status}`);
-  }
-
-  const ref = control.controlRef || '';
-  const type = control.controlType || '';
-
-  if (type === 'EXCLUSION' && !ref.includes(':EXCLUSION:')) {
-   errors.push('EXCLUSION ref must contain ":EXCLUSION:"');
-  }
-  if (type === 'QUANTITY_BUFFER' && !ref.includes(':QUANTITY_BUFFER:')) {
-   errors.push('QUANTITY_BUFFER ref must contain ":QUANTITY_BUFFER:"');
-  }
-
-  return { valid: errors.length === 0, errors };
- }
-}
-
-// ============================================================================
-// SERVICE FUNCTIONS
-// ============================================================================
-
-/**
- * SERVICE 1: Process a single CSV file
- * - Downloads file from S3
- * - Parses CSV records
- * - Maps records using UniversalMapper
- * - Validates control schema
- * - Returns processed records ready for mutation
- */
-async function processFile(
- s3: S3DataSource,
- parser: CSVParserService,
- mapper: GraphQLMutationMapper,
- validator: ControlSchemaValidator,
- filePath: string,
- fileName: string,
- log: any
-): Promise<FileProcessingResult> {
- const result: FileProcessingResult = {
-  success: false,
-  fileName,
-  recordsProcessed: 0,
-  recordsSuccessful: 0,
-  recordsFailed: 0,
-  mutations: [],
-  errors: [],
- };
-
- try {
-  log.info('[processFile] Downloading file', { fileName, filePath });
-
-  // Download file with retry
-  const content = await retryWithBackoff(
-   () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
-  );
-
-  // Parse CSV
-  const records = await parser.parse(content, {
-   columns: true,
-   skip_empty_lines: true,
-   trim: true,
-  });
-
-  log.info('[processFile] CSV parsed', { fileName, recordCount: records.length });
-
-  if (records.length === 0) {
-   result.success = true;
-   result.errors.push('Empty CSV file');
-   return result;
-  }
-
-  result.recordsProcessed = records.length;
-
-  // Map and validate each record using GraphQLMutationMapper
-  const validRecords: Array<{ query: string; variables: any; input: any }> = [];
-
-  // ✅ PRODUCTION ENHANCEMENT: Log transformation start
-  log.info('[processFile] Transforming records to GraphQL mutations', {
-   fileName,
-   totalRecords: records.length,
-  });
-
-  for (let i = 0; i < records.length; i++) {
-   const rec = records[i];
-   const recordNumber = i + 1;
-
-   // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 records
-   if (recordNumber % 50 === 0) {
-    log.info(`📤 Transforming record ${recordNumber}/${records.length}`, {
-     fileName,
-     recordNumber,
-     totalRecords: records.length,
-     validSoFar: validRecords.length,
-     failedSoFar: result.recordsFailed,
-     progress: `${((recordNumber / records.length) * 100).toFixed(1)}%`,
-    });
-   }
-
-   try {
-    // GraphQLMutationMapper returns { query, variables } directly
-    const mapped = await mapper.map(rec);
-    
-    const control = {
-     query: mapped.query,
-     variables: mapped.variables,
-     input: mapped.variables.input || mapped.variables,
-    };
-
-    // Validate schema using input
-    const validation = validator.validateForCreate(control.input);
-    if (!validation.valid) {
-     log.warn('[processFile] Validation error', { row: recordNumber, errors: validation.errors });
-     result.recordsFailed++;
-     result.errors.push(`Row ${recordNumber}: Validation failed - ${validation.errors.join(', ')}`);
-     continue;
-    }
-
-    validRecords.push(control);
-    result.recordsSuccessful++;
-   } catch (error: unknown) {
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    log.warn('[processFile] Mapping error', { row: recordNumber, error: errorMsg });
-    result.recordsFailed++;
-    result.errors.push(`Row ${recordNumber}: Mapping failed - ${errorMsg}`);
-   }
-  }
-
-  log.info('[processFile] Processing complete', {
-   fileName,
-   total: result.recordsProcessed,
-   valid: result.recordsSuccessful,
-   invalid: result.recordsFailed,
-   successRate: `${((result.recordsSuccessful / result.recordsProcessed) * 100).toFixed(1)}%`,
-  });
-
-  result.success = true;
-
-  // Store valid records in result for executeMutations
-  (result as any).validRecords = validRecords;
-
-  return result;
- } catch (error: unknown) {
-  // ✅ Enhanced error logging: Extract all error details for visibility
-  const errorDetails = {
-   message: error instanceof Error ? error.message : String(error),
-   stack: error instanceof Error ? error.stack : undefined,
-   errorType: error instanceof Error ? error.constructor.name : 'Error',
-  };
-  log.error('[processFile] Failed to process file', errorDetails, { fileName });
-  const errorMsg = error instanceof Error ? error.message : String(error);
-  result.errors.push(`File processing error: ${errorMsg}`);
-  return result;
- }
-}
-
-/**
- * ✅ NEW: Fetch all existing controls with pagination
- * Returns Map for O(1) lookups during upsert logic
- */
-async function fetchExistingControls(
- client: any,
- catalogRef: string,
- log: any
-): Promise<Map<string, any>> {
- const controlsMap = new Map();
- let hasMore = true;
- let cursor: string | null = null;
- const MAX_PAGES = 50; // Safety limit
-
- const query = `
-  query GetControls($catalogRef: String!, $first: Int!, $after: String) {
-   controlGroup(ref: $catalogRef) {
-    controls(first: $first, after: $after) {
-     edges {
-      node {
-       ref
-       type
-       status
-       executionOrder
-      }
-      cursor
-     }
-     pageInfo {
-      hasNextPage
-      endCursor
-     }
-    }
-   }
-  }
- `;
-
- let pageCount = 0;
- while (hasMore && pageCount < MAX_PAGES) {
-  try {
-   const result = await client.graphql({
-    query,
-    variables: { catalogRef, first: 100, after: cursor },
-   });
-
-   const edges = result?.data?.controlGroup?.controls?.edges || [];
-   edges.forEach((edge: any) => {
-    if (edge?.node?.ref) {
-     controlsMap.set(edge.node.ref, edge.node);
-    }
-   });
-
-   const pageInfo = result?.data?.controlGroup?.controls?.pageInfo;
-   hasMore = pageInfo?.hasNextPage || false;
-   cursor = pageInfo?.endCursor || null;
-   pageCount++;
-
-   log.info(`Fetched page ${pageCount} of existing controls`, {
-    pageCount,
-    totalFound: controlsMap.size,
-   });
-  } catch (error: unknown) {
-   const errorMsg = error instanceof Error ? error.message : String(error);
-   log.error('Failed to fetch existing controls', {
-    message: errorMsg,
-    pageCount,
-   });
-   break;
-  }
- }
-
- log.info(`Bulk query complete: ${controlsMap.size} existing controls found`);
- return controlsMap;
-}
-
-/**
- * SERVICE 2: Execute GraphQL mutations for control records
- * - Separates creates from updates
- * - Supports alias batching for creates
- * - Processes updates individually
- * - Returns mutation results
- */
-async function executeMutations(
- controls: Array<{ query: string; variables: any; input: any }>,
- existingControlsMap: Map<string, any>,
- client: any,
- mapper: GraphQLMutationMapper,
- log: any,
- batchSize: number = 1, // ✅ Default: 1 (sequential)
- mutationsPerAliasBatch?: number // ✅ NEW: Alias batching parameter (default: undefined = disabled)
-): Promise<MutationResult[]> {
- const results: MutationResult[] = [];
-
- log.info('[executeMutations] Starting mutations', { 
-  controlCount: controls.length, 
-  batchSize,
-  mutationsPerAliasBatch,
- });
-
- // Separate creates from updates
- const toCreate: Array<{ query: string; variables: any; input: any }> = [];
- const toUpdate: Array<{ query: string; variables: any; input: any }> = [];
-
- controls.forEach(control => {
-  const exists = existingControlsMap.has(control.input.controlRef);
-  if (exists) {
-   toUpdate.push(control);
-  } else {
-   toCreate.push(control);
-  }
- });
-
- log.info(`Mutation breakdown: ${toCreate.length} creates, ${toUpdate.length} updates`);
-
- // ✅ Process creates with alias batching if enabled
- if (toCreate.length > 0) {
-  const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
-  
-  if (useAliases) {
-   const createResults = await executeMutationsWithAliases(
-    toCreate,
-    client,
-    mapper,
-    log,
-    batchSize,
-    mutationsPerAliasBatch,
-    'createControl'
-   );
-   
-   // Convert to MutationResult format
-   toCreate.forEach((control, idx) => {
-    if (idx < createResults.executed) {
-     results.push({
-      success: true,
-      controlRef: control.input.controlRef,
-      operation: 'create',
-     });
-    } else {
-     results.push({
-      success: false,
-      controlRef: control.input.controlRef,
-      operation: 'create',
-      error: createResults.errors[idx - createResults.executed] || 'Unknown error',
-     });
-    }
-   });
-  } else {
-   // Process creates individually
-   for (const control of toCreate) {
-    try {
-     await retryWithBackoff(() =>
-      client.graphql({
-       query: control.query,
-       variables: control.variables,
-      })
-     );
-     results.push({
-      success: true,
-      controlRef: control.input.controlRef,
-      operation: 'create',
-     });
-    } catch (error: unknown) {
-     const errorMsg = error instanceof Error ? error.message : String(error);
-     results.push({
-      success: false,
-      controlRef: control.input.controlRef,
-      operation: 'create',
-      error: errorMsg,
-     });
-    }
-   }
-  }
- }
-
- // ✅ Process updates individually (conditional logic requires individual handling)
- for (const control of toUpdate) {
-  const mutationResult: MutationResult = {
-   success: false,
-   controlRef: control.input.controlRef,
-   operation: 'update',
-  };
-
-  try {
-   await retryWithBackoff(() =>
-    client.graphql({
-     query: control.query,
-     variables: control.variables,
-    })
-   );
-   mutationResult.success = true;
-  } catch (error: unknown) {
-   const errorMsg = error instanceof Error ? error.message : String(error);
-   mutationResult.error = errorMsg;
-   const errorDetails = {
-    message: errorMsg,
-    stack: error instanceof Error ? error.stack : undefined,
-    errorType: error instanceof Error ? error.constructor.name : 'Error',
-   };
-   log.error('[executeMutations] Mutation failed', errorDetails, { ref: control.input.controlRef });
-  }
-
-  results.push(mutationResult);
- }
-
- log.info('[executeMutations] Mutations complete', {
-  total: results.length,
-  successful: results.filter(r => r.success).length,
-  failed: results.filter(r => !r.success).length,
- });
-
- return results;
-}
-
-/**
- * ✅ NEW: Execute mutations with GraphQL alias batching
- */
-async function executeMutationsWithAliases(
- controls: Array<{ query: string; variables: any; input: any }>,
- client: any,
- mapper: GraphQLMutationMapper,
- log: any,
- 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 controls[0]>> = [];
- for (let i = 0; i < controls.length; i += mutationsPerAliasBatch) {
-  aliasBatches.push(controls.slice(i, i + mutationsPerAliasBatch));
- }
- 
- log.info(`Processing ${aliasBatches.length} alias batches`, {
-  totalControls: controls.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);
-    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(control => {
-     results.failed++;
-     const controlRef = control.input?.controlRef || 'unknown';
-     results.errors.push(`Failed to ${mutationName} ${controlRef}: ${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
-): { 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}) { ref type }`;
- }).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((control, index) => {
-  const input = control.variables.input || control.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((control, 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 controlRef = control.input?.controlRef || 'unknown';
-   result.errors.push(`Failed to ${mutationName} ${controlRef}: ${errorMsg}`);
-  }
- });
- 
- return result;
-}
-
-/**
- * SERVICE 3: Write mutation results log to S3
- * - Creates detailed JSON log with processing results
- * - Uploads to S3 logs directory with Buffer
- * - Returns upload success/failure
- */
-async function writeMutationLog(
- s3: S3DataSource,
- fileName: string,
- fileResult: FileProcessingResult,
- logPrefix: string,
- log: any
-): Promise<boolean> {
- try {
-  const logFileName = `${fileName.replace('.csv', '')}-log-${Date.now()}.json`;
-  const logPath = `${logPrefix}${logFileName}`;
-
-  const logData = {
-   fileName,
-   timestamp: new Date().toISOString(),
-   summary: {
-    totalRecords: fileResult.recordsProcessed,
-    successful: fileResult.recordsSuccessful,
-    failed: fileResult.recordsFailed,
-    mutations: {
-     total: fileResult.mutations.length,
-     created: fileResult.mutations.filter(m => m.operation === 'create' && m.success).length,
-     updated: fileResult.mutations.filter(m => m.operation === 'update' && m.success).length,
-     failed: fileResult.mutations.filter(m => !m.success).length,
-    },
-   },
-   errors: fileResult.errors,
-   mutations: fileResult.mutations,
-  };
-
-  const logContent = JSON.stringify(logData, null, 2);
-
-  log.info('[writeMutationLog] Writing log to S3', { logPath, size: logContent.length });
-
-  // Upload log to S3 (uploadFile accepts string or Buffer)
-  await s3.uploadFile(logPath, logContent);
-
-  log.info('[writeMutationLog] Log written successfully', { logPath });
-  return true;
- } catch (error: unknown) {
-  // ✅ Enhanced error logging: Extract all error details for visibility
-  const errorDetails = {
-   message: error instanceof Error ? error.message : String(error),
-   stack: error instanceof Error ? error.stack : undefined,
-   errorType: error instanceof Error ? error.constructor.name : 'Error',
-  };
-  log.error('[writeMutationLog] Failed to write log', errorDetails, { fileName });
-  return false;
- }
-}
-
-// ============================================================================
-// MAIN WORKFLOW FUNCTION
-// ============================================================================
-
-/**
- * Main workflow: Control CSV sync from S3
- * Per-file processing with three service functions:
- * 1. processFile() - Download, parse, map, validate
- * 2. executeMutations() - Create/update controls via GraphQL
- * 3. writeMutationLog() - Write detailed logs to S3
- */
-async function runControlSync(ctx: any) {
- const log = ctx.log;
- const executionStartTime = Date.now();
- log.info('🚀 [WORKFLOW] Starting control sync from S3');
-
- // Read activation variables
- const s3Bucket = ctx.activation?.getVariable('s3BucketName');
- const s3Region = ctx.activation?.getVariable('awsRegion') || 'us-east-1';
- const s3AccessKeyId = ctx.activation?.getVariable('awsAccessKeyId');
- const s3SecretAccessKey = ctx.activation?.getVariable('awsSecretAccessKey');
- const s3Prefix = ctx.activation?.getVariable('s3Prefix') || 'controls/';
- const maxFiles = parseInt(ctx.activation?.getVariable('maxFilesToProcess') || '10', 10);
- const filePattern = (ctx.activation?.getVariable('filePattern') || '.csv').toLowerCase();
- const enableArchival = ctx.activation?.getVariable('enableArchival') !== 'false';
- const enableFileTracking = ctx.activation?.getVariable('enableFileTracking') !== 'false';
- const validateConnection = ctx.activation?.getVariable('validateConnection') !== 'false';
- const archivePrefix = ctx.activation?.getVariable('archivePrefix') || 'processed/';
- const errorPrefix = ctx.activation?.getVariable('errorPrefix') || 'errors/';
- const logPrefix = ctx.activation?.getVariable('logPrefix') || 'logs/';
- const rateLimit = parseInt(ctx.activation?.getVariable('mutationRateLimit') || '10', 10);
- 
- // ✅ 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)
-
- // Validate required variables
- const missingVars: string[] = [];
- if (!s3Bucket) missingVars.push('s3BucketName');
- if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
- if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
-
- if (missingVars.length > 0) {
-  const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
-  log.error('❌ ' + errorMsg);
-  return {
-   success: false,
-   error: errorMsg,
-   processed: 0,
-   recommendation: 'Please configure the missing activation variables in Versori settings',
-  };
- }
-
- log.info('⚙️ [WORKFLOW] Configuration loaded', {
-  bucket: s3Bucket,
-  region: s3Region,
-  prefix: s3Prefix,
-  maxFiles,
-  rateLimit,
-  enableArchival,
-  enableFileTracking,
-  validateConnection,
- });
-
- // Initialize services
- log.info('🔌 [WORKFLOW] Initializing Fluent Commerce client');
- const client = await createClient(ctx);
- if (!client) {
-  log.error('❌ Failed to create Fluent Commerce client');
-  return {
-   success: false,
-   error: 'Failed to create Fluent Commerce client',
-   recommendation: 'Check Fluent Commerce connection configuration in Versori',
-  };
- }
- log.info('✅ [WORKFLOW] Fluent Commerce client initialized');
-
- // ✅ CORRECT: GraphQL mutations don't need client.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('☁️ [WORKFLOW] Initializing S3 data source');
- const s3 = new S3DataSource(
-  {
-   type: 'S3_CSV',
-   connectionId: 's3-control-sync',
-   name: 'Source S3',
-   s3Config: {
-    bucket: s3Bucket,
-    region: s3Region,
-    accessKeyId: s3AccessKeyId,
-    secretAccessKey: s3SecretAccessKey,
-   },
-  },
-  log
- );
-
- if (validateConnection) {
-  try {
-   log.info('🔍 [WORKFLOW] Validating S3 connection');
-   await s3.validateConnection();
-   log.info('✅ [WORKFLOW] S3 connection validated successfully');
-  } catch (error: any) {
-   log.error('❌ [WORKFLOW] S3 connection validation failed', {
-    message: error instanceof Error ? error.message : String(error),
-   });
-   return {
-    success: false,
-    error: 'S3 connection validation failed',
-    details: error instanceof Error ? error.message : String(error),
-    recommendation: 'Check S3 credentials and bucket permissions',
-   };
-  }
- }
-
- const parser = new CSVParserService();
- const { openKv } = ctx;
- const kv = new VersoriKVAdapter(openKv(':project:'));
- const validator = new ControlSchemaValidator();
-
- // Custom resolvers for control ref building
- const customResolvers = {
-  'custom.buildOrUseControlRef': (_: any, sourceData: any) => {
-   if (sourceData.controlRef && sourceData.controlRef.trim()) {
-    return sourceData.controlRef.trim();
-   }
-   return buildControlRef({
-    controlGroupRef: sourceData.controlGroupRef,
-    virtualCatalogueRef: sourceData.virtualCatalogueRef,
-    controlType: sourceData.controlType,
-    productRef: sourceData.productRef,
-    categoryRef: sourceData.categoryRef,
-    locationRef: sourceData.locationRef,
-   });
-  },
-  'custom.resolveCatalogRef': (_: any, sourceData: any) => {
-   if (sourceData.catalogRef && sourceData.catalogRef.trim()) {
-    return sourceData.catalogRef.trim();
-   }
-   if (sourceData.controlType === 'EXCLUSION') {
-    return sourceData.controlGroupRef?.trim() || '';
-   } else if (sourceData.controlType === 'QUANTITY_BUFFER') {
-    return sourceData.virtualCatalogueRef?.trim() || '';
-   }
-   return '';
-  },
- };
-
- // ✅ CRITICAL: Load mapping config from external JSON file
- // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
- // File: src/config/control-mapping.json
- const mappingConfigJson = await import('../config/control-mapping.json', { assert: { type: 'json' } });
- const mappingConfig = mappingConfigJson.default;
- 
- // Initialize GraphQLMutationMapper with client for schema introspection
- const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-
- try {
-  // List files from S3 (pattern filtering handled by listFiles)
-  log.info('📂 [WORKFLOW] Listing files from S3', { prefix: s3Prefix, filePattern });
-  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('📋 [WORKFLOW] Files discovered', { total: files.length, toProcess: csvFiles.length });
-
-  // ✅ BULK QUERY: Fetch all existing controls once for efficient upsert detection
-  const catalogRef = ctx.activation?.getVariable('catalogRef');
-  const existingControlsMap = catalogRef 
-   ? await fetchExistingControls(client, catalogRef, log)
-   : new Map<string, any>();
-
-  const workflowResults = {
-   processed: 0,
-   skipped: 0,
-   failed: 0,
-   totalRecords: 0,
-   controlsCreated: 0,
-   controlsUpdated: 0,
-   errors: [] as string[],
-  };
-
-  // Process each file using service functions
-  for (const file of csvFiles) {
-   const fileStartTime = Date.now();
-   const filePath = file.path;
-   const fileName = file.name;
-
-   log.info('📄 [WORKFLOW] Processing file', { fileName, filePath });
-
-   // Check duplicate via KV state
-   if (enableFileTracking) {
-    const stateKey = ['processed-files', 's3-control-sync', fileName];
-    const existing = await kv.get(stateKey);
-    if (existing) {
-     log.info('⏭️ [WORKFLOW] Skipping already processed file', { fileName });
-     workflowResults.skipped++;
-     continue;
-    }
-   }
-
-   try {
-    // SERVICE 1: Process file (download, parse, map, validate)
-    const fileResult = await processFile(
-     s3,
-     parser,
-     mapper,
-     validator,
-     filePath,
-     fileName,
-     log
-    );
-
-    if (!fileResult.success) {
-     log.error('❌ [WORKFLOW] File processing failed', { fileName, errors: fileResult.errors });
-     workflowResults.failed++;
-     workflowResults.errors.push(...fileResult.errors);
-
-     // Move to error directory
-     if (enableArchival) {
-      try {
-       await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
-       log.info('🗂️ [WORKFLOW] Moved failed file to error directory', { fileName });
-      } catch (moveError: any) {
-       log.error('⚠️ [WORKFLOW] Failed to move error file', {
-        fileName,
-        error: moveError instanceof Error ? moveError.message : String(moveError),
-       });
-      }
-     }
-     continue;
-    }
-
-    workflowResults.totalRecords += fileResult.recordsProcessed;
-
-    // Get valid records from result
-    const validRecords = (fileResult as any).validRecords as ControlRecord[];
-
-    if (validRecords.length === 0) {
-     log.warn('⚠️ [WORKFLOW] No valid records to process', { fileName });
-     if (enableArchival) {
-      try {
-       await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-       log.info('📦 [WORKFLOW] Archived empty file', { fileName });
-      } catch (moveError: any) {
-       log.error('⚠️ [WORKFLOW] Failed to archive empty file', {
-        fileName,
-        error: moveError instanceof Error ? moveError.message : String(moveError),
-       });
-      }
-     }
-     workflowResults.skipped++;
-     continue;
-    }
-
-    // SERVICE 2: Execute mutations (create/update controls)
-    // ✅ 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)
-
-    log.info('🔄 [WORKFLOW] Executing mutations', {
-     fileName,
-     controlCount: validRecords.length,
-     batchSize: mutationBatchSize,
-     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch})` : 'disabled',
-    });
-
-    // ? Enhanced: Extract context for progress logging
-    const sampleControlRefs = validRecords.slice(0, 5).map((r: any) => r.input?.controlRef || 'unknown');
-    const mutationType = mapper?.mutationName || 'createControl';
-
-    // ? Enhanced: Start logging with context
-    log.info(`[GraphQLMutations] Sending mutations for file "${fileName}"`, {
-     totalMutations: validRecords.length,
-     mutationType,
-     batchSize: mutationBatchSize,
-     batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
-     sampleControlRefs: sampleControlRefs.join(', '),
-     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled'
-    });
-
-    const mutationResults = await executeMutations(
-     validRecords,
-     existingControlsMap,
-     client,
-     mapper,
-     log,
-     mutationBatchSize, // Concurrency control (default: 1)
-     mutationsPerAliasBatch // ✅ NEW: Alias batching (default: undefined)
-    );
-
-    // Update workflow results
-    const created = mutationResults.filter(m => m.operation === 'create' && m.success).length;
-    const updated = mutationResults.filter(m => m.operation === 'update' && m.success).length;
-    const failed = mutationResults.filter(m => !m.success).length;
-
-    // ? Enhanced: Completion logging with summary
-    const successRate = validRecords.length > 0 ? Math.round(((created + updated) / validRecords.length) * 100) : 0;
-    log.info(`✅ [GraphQLMutations] Mutation submission completed for file "${fileName}"`, {
-     totalMutations: validRecords.length,
-     created,
-     updated,
-     failed,
-     successRate: `${successRate}%`,
-     mutationType,
-    });
-
-    workflowResults.controlsCreated += created;
-    workflowResults.controlsUpdated += updated;
-
-    // Store mutation results in fileResult for logging
-    fileResult.mutations = mutationResults;
-
-    const fileDuration = Date.now() - fileStartTime;
-    log.info('✅ [WORKFLOW] Mutations complete', {
-     fileName,
-     created,
-     updated,
-     failed,
-     duration: `${fileDuration}ms`,
-    });
-
-    // SERVICE 3: Write mutation log to S3
-    await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
-
-    // Mark file as processed in KV state
-    if (enableFileTracking) {
-     const stateKey = ['processed-files', 's3-control-sync', fileName];
-     await kv.set(stateKey, {
-      processedAt: new Date().toISOString(),
-      recordsProcessed: fileResult.recordsProcessed,
-      recordsSuccessful: fileResult.recordsSuccessful,
-      recordsFailed: fileResult.recordsFailed,
-      controlsCreated: created,
-      controlsUpdated: updated,
-      duration: fileDuration,
-     });
-    }
-
-    // Archive processed file
-    if (enableArchival) {
-     try {
-      await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-      log.info('📦 [WORKFLOW] File archived', { fileName, destination: archivePrefix });
-     } catch (moveError: any) {
-      log.error('⚠️ [WORKFLOW] Failed to archive file', {
-       fileName,
-       error: moveError instanceof Error ? moveError.message : String(moveError),
-      });
-     }
-    }
-
-    workflowResults.processed++;
-    log.info('✅ [WORKFLOW] File complete', { fileName, duration: `${fileDuration}ms` });
-   } catch (error: any) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorDetails = {
-     message: error?.message || 'Unknown error',
-     stack: error?.stack,
-     fileName: error?.fileName,
-     lineNumber: error?.lineNumber,
-     originalError: error?.context?.originalError?.message,
-     errorType: error?.name || 'Error',
-    };
-    log.error('❌ [WORKFLOW] File processing error', errorDetails, { fileName });
-    workflowResults.failed++;
-    workflowResults.errors.push({
-     file: fileName,
-     error: error.message,
-     recommendation: getErrorRecommendation(error),
-    });
-
-    // Move to error directory
-    if (enableArchival) {
-     try {
-      await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
-      log.info('🗂️ [WORKFLOW] Moved failed file to error directory', { fileName });
-     } catch (moveError: any) {
-      log.error('⚠️ [WORKFLOW] Failed to move error file', {
-       fileName,
-       error: moveError instanceof Error ? moveError.message : String(moveError),
-      });
-     }
-    }
-
-    // Track error state with exponential backoff
-    const errorKey = ['error-state', fileName];
-    const prev = (await kv.get(errorKey))?.value as any;
-    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();
-
-    await kv.set(errorKey, {
-     fileName,
-     attemptCount: attempts,
-     lastError: error?.message || 'unknown',
-     lastAttemptAt: new Date().toISOString(),
-     firstFailedAt: prev?.firstFailedAt || new Date().toISOString(),
-     nextRetryAt,
-    });
-   }
-  }
-
-  // Final summary
-  const executionDuration = Date.now() - executionStartTime;
-  const summary = {
-   success: true,
-   processed: workflowResults.processed,
-   skipped: workflowResults.skipped,
-   failed: workflowResults.failed,
-   totalRecords: workflowResults.totalRecords,
-   controlsCreated: workflowResults.controlsCreated,
-   controlsUpdated: workflowResults.controlsUpdated,
-   errors: workflowResults.errors.length > 0 ? workflowResults.errors : undefined,
-   duration: executionDuration,
-   durationFormatted: `${(executionDuration / 1000).toFixed(2)}s`,
-   timestamp: new Date().toISOString(),
-  };
-
-  log.info('🎉 [WORKFLOW] Control sync completed', summary);
-  return summary;
- } catch (error: unknown) {
-  // ✅ Enhanced error logging: Extract all error details for visibility
-  const errorDetails = {
-   message: error instanceof Error ? error.message : String(error),
-   stack: error instanceof Error ? error.stack : undefined,
-   errorType: error instanceof Error ? error.constructor.name : 'Error',
-  };
-  log.error('❌ [WORKFLOW] Sync failed', errorDetails);
-  const errorMsg = error instanceof Error ? error.message : String(error);
-  const executionDuration = Date.now() - executionStartTime;
-  return {
-   success: false,
-   error: errorMsg,
-   recommendation: getErrorRecommendation(error),
-   processed: 0,
-   duration: executionDuration,
-   durationFormatted: `${(executionDuration / 1000).toFixed(2)}s`,
-   timestamp: new Date().toISOString(),
-  };
- }
-}
-
-/**
- * Get error recommendation based on error type
- */
-function getErrorRecommendation(error: any): string {
- const errorMsg = (error?.message || '').toLowerCase();
-
- if (errorMsg.includes('credentials') || errorMsg.includes('access denied')) {
-  return 'Check AWS credentials and S3 bucket permissions';
- }
- if (errorMsg.includes('bucket') || errorMsg.includes('not found')) {
-  return 'Verify S3 bucket name and region configuration';
- }
- if (errorMsg.includes('connection') || errorMsg.includes('network')) {
-  return 'Check network connectivity and firewall settings';
- }
- if (errorMsg.includes('parse') || errorMsg.includes('invalid csv')) {
-  return 'Verify CSV file format and structure';
- }
- if (errorMsg.includes('validation') || errorMsg.includes('required field')) {
-  return 'Review control data validation rules and required fields';
- }
- if (errorMsg.includes('graphql') || errorMsg.includes('mutation')) {
-  return 'Check GraphQL schema and mutation configuration';
- }
- if (errorMsg.includes('rate limit') || errorMsg.includes('throttl')) {
-  return 'Reduce mutationRateLimit or mutationBatchSize in activation variables';
- }
-
- return 'Review error logs and activation variables configuration';
-}
-
-// Scheduled daily run
-export const scheduledControlSync = schedule('s3-control-daily', '0 2 * * *').then(
- http('sync-controls', { connection: 'fluent_commerce' }, async ctx => {
-  return await runControlSync(ctx);
- })
-);
-
-// Manual trigger
-export const syncNow = webhook('sync-controls-now').then(
- http('sync-controls-manual', { connection: 'fluent_commerce' }, async ctx => {
-  return await runControlSync(ctx);
- })
-);
-
-// Status check
-export const checkStatus = webhook('check-status').then(
- fn('get-status', async (ctx: any) => {
-  const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
-  const processedKeys = await kv.list({ prefix: ['processed-files', 's3-control-sync'] });
-  return {
-   success: true,
-   recentFiles: processedKeys.slice(0, 10),
-   timestamp: new Date().toISOString(),
-  };
- })
-);
-```
-
-## Key Patterns Explained
-
-### Pattern 1: Direct KV State Management
-
-```typescript
-const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
-
-// Check if file already processed
-const stateKey = ['processed-files', 's3-control-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,
- processedAt: new Date().toISOString(),
-});
-```
-
-### Pattern 2: Rate-Limited GraphQL Mutations
-
-```typescript
-async function rateLimitedMutation(operation: () => Promise<any>, delayMs: number) {
- const result = await operation();
- if (delayMs > 0) {
-  await new Promise(resolve => setTimeout(resolve, delayMs));
- }
- return result;
-}
-
-// Configure rate limit (10 mutations/sec = 100ms delay)
-const rateLimit = 10;
-const delayMs = Math.floor(1000 / rateLimit);
-```
-
-### Pattern 3: S3 File Operations with Retry
-
-```typescript
-// List files with prefix filtering
-const files = await s3.listFiles({ prefix: 'controls/', maxKeys: 1000 });
-
-// Download with retry
-const content = await retryWithBackoff(
- () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
-);
-
-// Move file (archive or error)
-await s3.moveFile('controls/file.csv', 'processed/file.csv');
-```
-
-### Pattern 4: Control Ref Building with Custom Resolvers
-
-```typescript
-const customResolvers = {
- 'custom.buildOrUseControlRef': (_: any, sourceData: any) => {
-  // If pre-built ref exists, use it
-  if (sourceData.controlRef?.trim()) return sourceData.controlRef.trim();
-
-  // Otherwise build from components
-  return buildControlRef({ ...sourceData });
- },
-};
-```
-
-### Pattern 5: UniversalMapper with Custom Resolvers
-
-Available SDK Resolvers:
-
-- **String**: `sdk.trim`, `sdk.uppercase`, `sdk.lowercase`, `sdk.toString`
-- **Number**: `sdk.parseInt`, `sdk.parseFloat`, `sdk.number`
-- **Date**: `sdk.formatDate`, `sdk.formatDateShort`, `sdk.parseDate`
-- **Type**: `sdk.boolean`, `sdk.parseJson`, `sdk.toJson`
-- **Utility**: `sdk.identity`, `sdk.coalesce`
-
-## Schema Validation (Before Deployment)
-
-Use SDK CLI tools to validate your GraphQL schema:
-
-```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
-cat > control-mutation.graphql << 'EOF'
-mutation CreateControl(
- $controlRef: String!
- $catalogRef: String!
- $controlType: String!
- $executionOrder: Int!
- $value: Json!
-) {
- createControl(input: {
-  type: $controlType
-  ref: $controlRef
-  name: $controlRef
-  values: { name: "CONTROL_VALUE", type: "INTEGER", value: $value }
-  controlGroup: { ref: $catalogRef }
-  executionOrder: $executionOrder
- }) {
-  ref
- }
-}
-EOF
-
-# 3. Generate mapping from mutation
-fc-connect generate-mutation-mapping \
- --file control-mutation.graphql \
- --output control-mapping.json
-
-# 4. Validate mapping against schema
-fc-connect validate-schema \
- --mapping control-mapping.json \
- --schema fluent-schema.json
-
-# 5. Analyze field coverage
-fc-connect analyze-coverage \
- --mapping control-mapping.json \
- --schema fluent-schema.json
-```
-
-**Output Example**:
-
-```bash
-✓ Schema validation passed
-✓ All required fields present: ref, type, executionOrder, values
-✓ Mutation structure matches GraphQL schema
-⚠ Optional fields not mapped: status, description
-```
-
-## Testing the Workflow
-
-### 1. Upload Test CSV to S3
-
-```bash
-aws s3 cp controls-test.csv s3://my-controls-bucket/controls/
-```
-
-### 2. Deploy to Versori
-
-```bash
-npm run deploy
-```
-
-### 3. Manual Testing via Webhook
-
-```bash
-curl -X POST https://your-workspace.versori.run/sync-controls-now
-```
-
-### 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": 50,
- "mutationsExecuted": 50,
- "mutationsFailed": 0,
- "results": [
-  {
-   "file": "controls_2025-01-22.csv",
-   "success": true,
-   "recordsProcessed": 50,
-   "mutationsExecuted": 50,
-   "mutationsFailed": 0
-  }
- ],
- "duration": 12345
-}
-```
-
-### Partial Success Response
-
-```json
-{
- "success": true,
- "filesProcessed": 1,
- "filesSkipped": 0,
- "filesFailed": 0,
- "totalRecords": 50,
- "mutationsExecuted": 45,
- "mutationsFailed": 5,
- "results": [
-  {
-   "file": "controls_2025-01-22.csv",
-   "success": true,
-   "recordsProcessed": 50,
-   "mutationsExecuted": 45,
-   "mutationsFailed": 5,
-   "errors": ["CTRL-001: Invalid control ref", "CTRL-002: Missing required field"]
-  }
- ],
- "duration": 12345
-}
-```
-
-### Error Response
-
-```json
-{
- "success": false,
- "filesProcessed": 0,
- "filesFailed": 1,
- "totalRecords": 0,
- "mutationsExecuted": 0,
- "mutationsFailed": 0,
- "results": [
-  {
-   "file": "controls_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: Duplicate File Processing
-
-**Solution**:
-
-```typescript
-const stateKey = ['processed-files', 's3-control-sync', fileName];
-const existing = await kv.get(stateKey);
-if (existing) continue;
-await kv.set(stateKey, { processedAt: new Date().toISOString() });
-```
-
-### Issue 2: "EXCLUSION must have value=0"
-
-**Solution**: Update CSV - EXCLUSION controls must always have value=0
-
-### Issue 3: "controlRef pattern mismatch"
-
-**Solution**: Verify required fields are populated:
-
-- EXCLUSION: `controlGroupRef` + (`productRef` OR `categoryRef`)
-- QUANTITY_BUFFER: `virtualCatalogueRef` + (`productRef` OR `categoryRef` OR `locationRef`)
-
-### Issue 4: 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-controls-bucket",
-    "arn:aws:s3:::my-controls-bucket/*"
-   ]
-  }
- ]
-}
-```
-
-### Issue 5: Rate Limiting
-
-**Solution**:
-
-```typescript
-// Adjust rate limit in activation variables
-mutationRateLimit = 5; // Reduce to 5 mutations/sec
-```
-
-## Production Checklist
-
-- [ ] S3 credentials validated with correct IAM permissions
-- [ ] Activation secrets stored securely
-- [ ] GraphQL schema validated using CLI tools
-- [ ] Mapping configuration tested with sample data
-- [ ] File duplicate prevention working via KV state
-- [ ] Rate limiting configured appropriately
-- [ ] Control validation rules tested
-- [ ] Error handling tested with malformed CSV
-- [ ] Retry logic tested with transient failures
-- [ ] File archival working (processed and error directories)
-- [ ] Monitoring/alerting configured for failures
-- [ ] Clear runbook for error recovery
-
-## Related Guides
-
-- **SFTP Version**: [sftp-csv-control-to-graphql.md](template-ingestion-sftp-csv-control-graphql.md)
-- **Universal Mapping**: `docs/02-CORE-GUIDES/mapping/modules/`
-- **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-control-graphql
+canonical_filename: template-ingestion-s3-csv-control-graphql.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: s3-csv
+destination: fluent-graphql
+entity: control
+format: csv
+logging: versori
+status: stable
+compliance: gold-standard
+features:
+  - graphql-mutation-mapper
+  - memory-management
+  - enhanced-logging
+  - attribute-transformation
+---
+
+# Template: Ingestion - S3 CSV to Control GraphQL
+
+**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: Read This Template As-Is (Do Not Execute Yet)
+
+**IMPORTANT:** This is a template that requires customization before use.
+
+**Purpose:** This template shows you how to build a scheduled Versori workflow that:
+- Reads Control CSV files from S3
+- Parses CSV records and validates them
+- Creates/updates Fluent Commerce controls via GraphQL mutations (createControl, updateControl)
+- Archives processed files and prevents duplicates via KV state
+- Handles rate limiting and retries
+- Tracks job status via JobTracker webhook
+
+**What You'll Learn:**
+- S3 file discovery with prefix filtering and archiving
+- CSV parsing with CSVParserService
+- Control entity structure (EXCLUSION vs QUANTITY_BUFFER types)
+- Direct GraphQL mutations (NOT Batch API)
+- Rate limiting (25-50 mutations at a time to prevent API throttling)
+- Custom control ref building (catalog + type + entity combinations)
+- Schema validation using CLI commands
+- Error handling and partial failure recovery
+- Versori KV state management for duplicate prevention
+- JobTracker integration with job-status webhook
+
+**Before You Begin:**
+1. Read through the entire template to understand the workflow
+2. Identify which parts need customization (marked with activation variables)
+3. Have your Fluent API credentials ready
+4. Have your S3 bucket details ready
+5. Understand Control entity structure in Fluent (see Sample CSV section)
+6. Review schema validation CLI commands (see Schema Validation section)
+
+## STEP 2: AI Agent Customization Instructions
+
+**If you are an AI agent helping a developer customize this template, follow these steps:**
+
+### 1. Gather Requirements
+
+Ask the developer:
+- **S3 Configuration:**
+ - Bucket name and region
+ - Access credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ - Prefix for control files (e.g., `controls/` or `incoming/controls/`)
+ - Archive prefix (e.g., `processed/` or `archive/`)
+ - Error prefix (e.g., `errors/` or `failed/`)
+
+- **CSV Structure:**
+ - Does CSV have pre-built control refs OR component fields?
+ - Which control types are used? (EXCLUSION, QUANTITY_BUFFER, THRESHOLD, EXPIRY)
+ - CSV column names and sample data
+ - Any custom validation rules beyond schema requirements
+
+- **Processing Rules:**
+ - Cron schedule (e.g., `0 2 * * *` = daily at 2 AM)
+ - Max files to process per run (default: 10)
+ - Rate limiting (mutations per second, default: 10)
+ - File naming pattern (default: `.csv`)
+ - Enable archival? (default: true)
+ - Enable file tracking? (default: true) - prevents duplicate processing
+ - Validate S3 connection on startup? (default: true)
+
+- **Fluent Configuration:**
+ - GraphQL endpoint URL (usually `https://api.fluentcommerce.com/graphql`)
+ - OAuth2 client credentials (will be in Versori connection)
+ - ⚠️ NOTE: retailerId is NOT needed for GraphQL mutations (only for Job/Event API)
+
+### 2. Schema Validation (CRITICAL - Run First!)
+
+**Before customizing any code, validate the Control schema:**
+
+```bash
+# 1. Introspect current Fluent GraphQL schema
+npx @fluentcommerce/fc-connect-sdk introspect-schema \
+ --url https://api.fluentcommerce.com/graphql \
+ --client-id YOUR_CLIENT_ID \
+ --client-secret YOUR_CLIENT_SECRET \
+ --output fluent-schema.json
+
+# 2. Create test mutation file for Control
+cat > control-test-mutation.graphql << 'EOF'
+mutation CreateControl(
+ $controlRef: String!
+ $catalogRef: String!
+ $controlType: String!
+ $executionOrder: Int!
+ $value: Json!
+) {
+ createControl(input: {
+  type: $controlType
+  ref: $controlRef
+  name: $controlRef
+  values: { name: "CONTROL_VALUE", type: "INTEGER", value: $value }
+  controlGroup: { ref: $catalogRef }
+  executionOrder: $executionOrder
+ }) {
+  ref
+  type
+  status
+ }
+}
+EOF
+
+# 3. Validate mutation against schema
+npx @fluentcommerce/fc-connect-sdk validate-schema \
+ --mapping control-test-mutation.graphql \
+ --schema fluent-schema.json
+
+# 4. Analyze field coverage
+npx @fluentcommerce/fc-connect-sdk analyze-coverage \
+ --mapping control-test-mutation.graphql \
+ --schema fluent-schema.json
+```
+
+**Verify these Control fields exist in schema:**
+- `ref` (String!, required) - Unique control reference
+- `type` (String!, required) - Control type: EXCLUSION, QUANTITY_BUFFER, THRESHOLD, EXPIRY
+- `executionOrder` (Int!, required) - Priority: 1-999 (lower = higher priority)
+- `values` (Json!, required) - Control value object with name, type, value
+- `status` (String) - ACTIVE or INACTIVE
+- `controlGroup` (reference) - For EXCLUSION controls (uses catalogRef)
+- `virtualCatalogue` (reference) - For QUANTITY_BUFFER controls (uses catalogRef)
+
+### 3. Customize CSV Mapping
+
+**Update the `mappingConfig` in the template:**
+
+```typescript
+// ✅ CORRECT: GraphQLMutationMapper configuration structure
+// File: src/config/control-mapping.json
+{
+ "mutation": "createControl",
+ "arguments": {
+  "input": {
+   "type": { "source": "controlType", "required": true, "resolver": "uppercase" },
+   "ref": { "resolver": "custom.buildOrUseControlRef", "required": true },
+   "name": { "resolver": "custom.buildOrUseControlRef" },
+   "values": {
+    "value": [
+     {
+      "name": { "value": "CONTROL_VALUE" },
+      "type": { "value": "INTEGER" },
+      "value": { "source": "value", "required": true, "resolver": "parseInt" }
+     }
+    ]
+   },
+   "executionOrder": { "source": "executionOrder", "required": true, "resolver": "parseInt" },
+   "controlGroup": {
+    "ref": { "resolver": "custom.resolveCatalogRef", "required": true }
+   }
+  }
+ }
+}
+
+**Save mapping to config file:**
+```bash
+mkdir -p config
+cat > config/control.import.csv.json << 'EOF'
+{
+ "version": "2.0.0",
+ "description": "CSV control to Fluent Commerce GraphQL mapping",
+ "fields": {
+  "controlRef": { "resolver": "custom.buildOrUseControlRef", "required": true },
+  "catalogRef": { "resolver": "custom.resolveCatalogRef", "required": true },
+  "controlType": { "source": "controlType", "required": true, "resolver": "sdk.uppercase" },
+  "executionOrder": { "source": "executionOrder", "required": true, "resolver": "sdk.parseInt" },
+  "value": { "source": "value", "required": true, "resolver": "sdk.parseInt" },
+  "status": { "source": "status", "resolver": "sdk.uppercase" }
+ }
+}
+EOF
+```
+
+### 4. Control Ref Building Rules
+
+**EXCLUSION controls (catalog + type + product/category):**
+```typescript
+// Pattern: {controlGroupRef}:EXCLUSION:{productRef|categoryRef}
+// Examples:
+CG-RETAIL:EXCLUSION:CAT-SEASONAL   // Category exclusion
+CG-RETAIL:EXCLUSION:PROD-12345    // Product exclusion
+```
+
+**QUANTITY_BUFFER controls (catalog + type + product/category/location):**
+```typescript
+// Pattern: {virtualCatalogueRef}:QUANTITY_BUFFER:{productRef}[:{locationRef}]
+// Examples:
+VC-RETAIL:QUANTITY_BUFFER:PROD-98765:LOC-001 // Product at location
+VC-RETAIL:QUANTITY_BUFFER:PROD-11111     // Product (all locations)
+VC-RETAIL:QUANTITY_BUFFER:CAT-ELECTRONICS   // Category
+VC-RETAIL:QUANTITY_BUFFER:LOC-002       // Location (all products)
+```
+
+**Validation rules:**
+- EXCLUSION must have `controlGroupRef` + (`productRef` OR `categoryRef`)
+- EXCLUSION must have `value=0` (always zero)
+- QUANTITY_BUFFER must have `virtualCatalogueRef` + (`productRef` OR `categoryRef` OR `locationRef`)
+- QUANTITY_BUFFER must have `value >= 0`
+- `executionOrder` must be 1-999 (lower = higher priority)
+- `status` must be ACTIVE or INACTIVE (defaults to ACTIVE if not provided)
+
+### 5. Rate Limiting Configuration
+
+**Why rate limiting is critical:**
+- Fluent GraphQL API has rate limits
+- Direct mutations (NOT Batch API) hit GraphQL endpoint directly
+- Recommended: 10-25 mutations per second
+- Higher rates may cause 429 (Too Many Requests) errors
+
+**Configure in activation variables:**
+```bash
+# Conservative (10 mutations/sec = 100ms delay between mutations)
+mutationRateLimit=10
+
+# Aggressive (25 mutations/sec = 40ms delay)
+mutationRateLimit=25
+
+# Very aggressive (50 mutations/sec = 20ms delay) - use with caution
+mutationRateLimit=50
+```
+
+**Implementation in template:**
+```typescript
+const rateLimit = parseInt(ctx.activation?.getVariable('mutationRateLimit') || '10', 10);
+const delayMs = rateLimit > 0 ? Math.floor(1000 / rateLimit) : 0;
+
+// Apply delay after each mutation
+await rateLimitedMutation(
+ () => client.graphql({ query: createMutation, variables }),
+ delayMs
+);
+```
+
+### 6. NO Batch API Guidance
+
+**This template uses DIRECT GraphQL mutations, NOT the Batch API:**
+
+**Why Direct Mutations:**
+- Controls are typically small volume (100s, not 1000s)
+- Need immediate feedback on create/update success
+- Simpler error handling (per-control vs per-batch)
+- No BPP (Batch Pre-Processing) needed
+
+**What This Means:**
+- Each control = 1 GraphQL mutation (createControl or updateControl)
+- Rate limiting is CRITICAL to prevent API throttling
+- No job/batch polling - mutations succeed or fail immediately
+- Errors are handled per-control, not per-batch
+
+**DO NOT use Batch API methods:**
+```typescript
+// ❌ WRONG - Don't use these for controls
+await client.createJob({ ... });
+await client.sendBatch(jobId, { ... });
+await client.getBatchStatus(jobId, batchId);
+```
+
+**✅ CORRECT - Use direct mutations:**
+```typescript
+// Check if exists
+const checkResult = await client.graphql({
+ query: checkQuery,
+ variables: { ref: control.controlRef }
+});
+
+// Create or update
+if (exists) {
+ await client.graphql({ query: updateMutation, variables });
+} else {
+ await client.graphql({ query: createMutation, variables });
+}
+```
+
+### 7. JobTracker Integration
+
+**This template includes JobTracker with job-status webhook:**
+
+```typescript
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+
+// Start job
+const tracker = new JobTracker(openKv(':project:'), log);
+await tracker.startJob(jobId, { mode: 'scheduled' });
+
+// Update progress (optional)
+await tracker.updateJob(jobId, {
+ processed: results.processed,
+ controlsCreated: results.controlsCreated
+});
+
+// Complete or fail
+if (success) {
+ await tracker.completeJob(jobId, { result });
+} else {
+ await tracker.failJob(jobId, { error: e?.message });
+}
+```
+
+**Query job status via webhook:**
+```bash
+curl -X POST https://your-workspace.versori.run/control-csv-job-status \
+ -H "x-api-key: YOUR_WEBHOOK_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"jobId": "control-csv-1234567890"}'
+```
+
+### 8. Testing Checklist
+
+Before deploying to production:
+
+- [ ] Schema validation passed (introspect-schema, validate-schema)
+- [ ] CSV mapping tested with sample data
+- [ ] Control ref building logic verified (EXCLUSION vs QUANTITY_BUFFER)
+- [ ] Rate limiting configured appropriately
+- [ ] S3 credentials validated
+- [ ] Activation variables configured in Versori
+- [ ] Test file uploaded to S3
+- [ ] Manual webhook trigger tested
+- [ ] File archival working (processed and error directories)
+- [ ] JobTracker status webhook tested
+- [ ] Error handling tested with malformed CSV
+- [ ] Duplicate prevention working via KV state
+
+### 9. Common Customizations
+
+**Change cron schedule:**
+```typescript
+// Daily at 2 AM
+export const scheduledControlSync = schedule('control-csv-scheduled', '0 2 * * *')
+
+// Every 6 hours
+export const scheduledControlSync = schedule('control-csv-scheduled', '0 */6 * * *')
+
+// Hourly
+export const scheduledControlSync = schedule('control-csv-scheduled', '0 * * * *')
+```
+
+**Add custom validation:**
+```typescript
+// In ControlSchemaValidator class
+validateCustomRules(control: any): { valid: boolean; errors: string[] } {
+ const errors: string[] = [];
+
+ // Example: Require description for all controls
+ if (!control.description?.trim()) {
+  errors.push('description is required');
+ }
+
+ // Example: Value range validation for QUANTITY_BUFFER
+ if (control.controlType === 'QUANTITY_BUFFER' && control.value > 1000) {
+  errors.push('QUANTITY_BUFFER value cannot exceed 1000');
+ }
+
+ return { valid: errors.length === 0, errors };
+}
+```
+
+**Change file pattern:**
+```typescript
+// Only process files starting with "control-"
+const filePattern = 'control-.csv';
+
+// Process multiple extensions
+const filePattern = '.csv|.txt';
+```
+
+### 10. Deployment Steps
+
+```bash
+# 1. Install dependencies
+npm install @fluentcommerce/fc-connect-sdk@^0.1.39 @versori/run
+
+# 2. Configure activation variables in Versori
+# (See Activation Variables section in template)
+
+# 3. Deploy
+npm run deploy
+
+# 4. Test manual trigger
+curl -X POST https://your-workspace.versori.run/control-csv-adhoc \
+ -H "x-api-key: YOUR_WEBHOOK_API_KEY"
+
+# 5. Monitor logs
+npm run logs
+
+# 6. Check job status
+curl -X POST https://your-workspace.versori.run/control-csv-job-status \
+ -H "x-api-key: YOUR_WEBHOOK_API_KEY" \
+ -d '{"jobId": "control-csv-1234567890"}'
+```
+
+---
+
+# Template: Ingestion - S3 CSV to Control GraphQL
+
+**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@^0.1.39`
+
+**Context**: Scheduled Versori workflow that reads control CSV files from S3 and creates/updates Fluent Commerce controls 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 with custom control ref building
+- GraphQL mutations for control upserts with rate limiting
+- Versori KV state management (duplicate prevention)
+- File archival after processing
+- Schema validation for control-specific rules
+
+## 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-control-graphql/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-control-sync.ts    # Scheduled: Daily control sync
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-control-sync.ts    # Webhook: Manual trigger
+    │       └── job-status-check.ts     # Webhook: Status query
+    │
+    ├── services/
+    │   └── control-sync.service.ts      # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── control-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-control-sync.ts`
+
+**Purpose**: Automatic daily control 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 { executeControlSync } from '../../services/control-sync.service';
+
+/**
+ * Scheduled Workflow: Daily Control Sync
+ *
+ * Runs automatically daily at 2 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Uses shared service: control-sync.service.ts
+ */
+export const dailyControlSync = schedule(
+  'control-sync-scheduled',
+  '0 2 * * *' // Daily at 2 AM UTC
+).then(
+  http('run-control-sync', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, openKv } = ctx;
+    const executionStartTime = Date.now();
+    const jobId = `control-sync-${executionStartTime}`;
+    const tracker = new JobTracker(openKv(':project:'), log);
+
+    await tracker.createJob(jobId, {
+      triggeredBy: 'schedule',
+      stage: 'initialization',
+      startTime: executionStartTime,
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+
+    try {
+      const result = await executeControlSync(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+      return { success: false, jobId, error: e?.message };
+    }
+  })
+);
+```
+
+---
+
+### 2. Webhook Workflows (`src/workflows/webhook/`)
+
+All HTTP-based triggers that create webhook endpoints.
+
+#### `src/workflows/webhook/adhoc-control-sync.ts`
+
+**Purpose**: Manual control sync trigger (on-demand)
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/control-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 { executeControlSync } from '../../services/control-sync.service';
+
+/**
+ * Webhook: Manual Control Sync Trigger
+ *
+ * Endpoint: POST https://{workspace}.versori.run/control-sync-adhoc
+ * Request body (optional): { filePattern: "urgent_*.csv", maxFiles: 5 }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: control-sync.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const adhocControlSync = webhook('control-sync-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'control-sync-adhoc', // Versori validates API key
+}).then(
+  http('run-control-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, openKv, data } = ctx;
+    const executionStartTime = Date.now();
+    const jobId = `control-sync-adhoc-${executionStartTime}`;
+    const tracker = new JobTracker(openKv(':project:'), log);
+
+    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 executeControlSync(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+      return { success: true, jobId, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+      return { success: false, jobId, error: e?.message };
+    }
+  })
+);
+```
+
+---
+
+#### `src/workflows/webhook/job-status-check.ts`
+
+**Purpose**: Query job status
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/control-sync-job-status`
+**Request body**: `{ "jobId": "control-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/control-sync-job-status
+ * Request body: { "jobId": "control-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 controlSyncJobStatus = webhook('control-sync-job-status', {
+  response: { mode: 'sync' },
+  connection: 'control-sync-job-status',
+}).then(
+  fn('status', async ctx => {
+    const { data, log, openKv } = ctx;
+    const jobId = data?.jobId as string;
+
+    if (!jobId) {
+      return { success: false, error: 'jobId required' };
+    }
+
+    const tracker = new JobTracker(openKv(':project:'), log);
+    const status = await tracker.getJob(jobId);
+
+    return status
+      ? { success: true, jobId, ...status }
+      : { success: false, error: 'Job not found', jobId };
+  })
+);
+```
+
+---
+
+### 3. Entry Point (`index.ts`)
+
+**Purpose**: Register all workflows with Versori platform
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/scheduled/ → Time-based triggers (cron)
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ */
+
+// Import scheduled workflows
+export { dailyControlSync } from './src/workflows/scheduled/daily-control-sync';
+
+// Import webhook workflows
+export { adhocControlSync } from './src/workflows/webhook/adhoc-control-sync';
+export { controlSyncJobStatus } from './src/workflows/webhook/job-status-check';
+```
+
+**What Gets Exposed:**
+- ✅ `adhocControlSync` → `https://{workspace}.versori.run/control-sync-adhoc`
+- ✅ `controlSyncJobStatus` → `https://{workspace}.versori.run/control-sync-job-status`
+- ❌ `dailyControlSync` → NOT exposed (runs automatically on cron)
+
+---
+
+## SDK Methods Used
+
+- `createClient(ctx)` - Create Fluent client (auto-detects Versori context)
+- `S3DataSource(config, log)` - S3 operations
+- `CSVParserService()` - CSV parsing
+- `GraphQLMutationMapper(mappingConfig, log, { fluentClient: client })` - Field mapping with schema validation
+- `mapper.map(record)` - Transform single record
+- `client.graphql({ query, variables })` - Execute GraphQL mutation
+- `VersoriKVAdapter` - Direct KV access for state management
+
+## Service Functions Architecture
+
+This template uses **three dedicated service functions** for clean separation of concerns:
+
+### 1. processFile()
+**Purpose:** Download, parse, map, and validate CSV file
+**Inputs:** S3DataSource, CSVParserService, GraphQLMutationMapper, ControlSchemaValidator, filePath, fileName, log
+**Returns:** FileProcessingResult with valid records ready for mutation
+**Responsibilities:**
+- Download file from S3 with retry
+- Parse CSV records
+- Map each record using GraphQLMutationMapper
+- Validate control schema
+- Return validated records for mutation
+
+### 2. executeMutations()
+**Purpose:** Execute GraphQL mutations for control records
+**Inputs:** FluentClient, ControlRecord[], delayMs (rate limit), log
+**Returns:** MutationResult[] with success/failure per control
+**Responsibilities:**
+- Check if control exists (query)
+- Create or update control (mutation)
+- Apply rate limiting between mutations
+- Track success/failure per control
+
+### 3. writeMutationLog()
+**Purpose:** Write detailed mutation results log to S3
+**Inputs:** S3DataSource, fileName, FileProcessingResult, logPrefix, log
+**Returns:** boolean (upload success)
+**Responsibilities:**
+- Create JSON log with processing summary
+- Include mutation results (created, updated, failed)
+- Upload to S3 logs directory using Buffer
+- Handle upload errors gracefully
+
+### Workflow Flow
+```
+Main Workflow (runControlSync)
+ ↓
+List S3 files → Filter CSV files
+ ↓
+For each file:
+ ↓
+ 1. processFile() → Download, parse, map, validate
+ ↓
+ 2. executeMutations() → Create/update controls with rate limiting
+ ↓
+ 3. writeMutationLog() → Write detailed logs to S3
+ ↓
+ Archive file → Update KV state
+ ↓
+Return summary
+```
+
+## Sample CSV Input Data
+
+### Option 1: Component-Based (Recommended)
+
+**File**: `controls-20250122-001.csv`
+
+```csv
+controlGroupRef,virtualCatalogueRef,controlType,productRef,categoryRef,locationRef,executionOrder,value,status,description
+CG-RETAIL,,EXCLUSION,,CAT-SEASONAL,,1,0,ACTIVE,Seasonal items - in-store only
+CG-RETAIL,,EXCLUSION,PROD-12345,,,2,0,ACTIVE,Product recall active
+,VC-RETAIL,QUANTITY_BUFFER,PROD-98765,,LOC-001,3,10,ACTIVE,NYC flagship - high foot traffic
+,VC-RETAIL,QUANTITY_BUFFER,PROD-11111,,,4,5,ACTIVE,Fast-moving product safety stock
+,VC-RETAIL,QUANTITY_BUFFER,,CAT-ELECTRONICS,,5,20,ACTIVE,All electronics buffer
+,VC-RETAIL,QUANTITY_BUFFER,,,LOC-002,6,100,ACTIVE,Flagship store large buffer
+```
+
+**Note**: Use `controlGroupRef` for EXCLUSION controls, `virtualCatalogueRef` for QUANTITY_BUFFER controls.
+
+### Option 2: Pre-Built Refs (Simple)
+
+```csv
+controlRef,catalogRef,controlType,executionOrder,value,status
+CG-RETAIL:EXCLUSION:CAT-SEASONAL,CG-RETAIL,EXCLUSION,1,0,ACTIVE
+CG-RETAIL:EXCLUSION:PROD-12345,CG-RETAIL,EXCLUSION,2,0,ACTIVE
+VC-RETAIL:QUANTITY_BUFFER:PROD-98765:LOC-001,VC-RETAIL,QUANTITY_BUFFER,3,10,ACTIVE
+VC-RETAIL:QUANTITY_BUFFER:PROD-11111,VC-RETAIL,QUANTITY_BUFFER,4,5,ACTIVE
+```
+
+**Field Mapping**:
+
+- `controlRef` → Unique control reference (auto-built from components or pre-built)
+- `controlGroupRef` → Control Group reference (for EXCLUSION controls)
+- `virtualCatalogueRef` → Virtual Catalogue reference (for QUANTITY_BUFFER controls)
+- `catalogRef` → Generic catalog reference (for pre-built format)
+- `controlType` → Control type: EXCLUSION or QUANTITY_BUFFER (required)
+- `productRef` → Product reference (optional, used in ref building)
+- `categoryRef` → Category reference (optional, used in ref building)
+- `locationRef` → Location reference (optional, used in ref building)
+- `executionOrder` → Execution priority: 1-999 (lower = higher priority) (required)
+- `value` → Control value: 0 for EXCLUSION, ≥0 for QUANTITY_BUFFER (required)
+- `status` → Control status: ACTIVE or INACTIVE (defaults to ACTIVE)
+
+## Project Setup
+
+```bash
+mkdir versori-s3-csv-control-sync && cd $_
+npm init -y
+npm install @fluentcommerce/fc-connect-sdk@^0.1.39 @versori/run
+mkdir -p src
+```
+
+### Package Configuration (package.json)
+
+```json
+{
+ "name": "versori-s3-csv-control-sync",
+ "version": "1.0.0",
+ "description": "Versori workflow: S3 CSV control 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-controls-bucket
+awsAccessKeyId=AKIAXXXXXXXXXXXX
+awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Optional Variables (with defaults shown)
+awsRegion=us-east-1
+s3Prefix=controls/
+archivePrefix=processed/
+errorPrefix=errors/
+logPrefix=logs/
+maxFilesToProcess=10
+filePattern=.csv
+enableArchival=true
+enableFileTracking=true
+validateConnection=true
+mutationRateLimit=10
+mutationBatchSize=1
+# mutationsPerAliasBatch=5 # Optional: Enable alias batching for high-volume scenarios
+
+# ⚠️ NOTE: 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
+# Standard createControl/updateControl do not have retailerId field - only use if your custom schema requires it
+```
+
+## Complete Workflow (src/index.ts)
+
+```typescript
+import { Buffer } from 'node:buffer'; // Required for Deno/Versori runtime
+import { schedule, webhook, http, fn } from '@versori/run';
+import {
+ createClient,
+ S3DataSource,
+ CSVParserService,
+ GraphQLMutationMapper,
+ VersoriKVAdapter,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+interface FileProcessingResult {
+ success: boolean;
+ fileName: string;
+ recordsProcessed: number;
+ recordsSuccessful: number;
+ recordsFailed: number;
+ mutations: MutationResult[];
+ errors: string[];
+}
+
+interface MutationResult {
+ success: boolean;
+ controlRef: string;
+ operation: 'create' | 'update';
+ error?: string;
+}
+
+interface ControlRecord {
+ controlRef: string;
+ catalogRef: string;
+ controlType: string;
+ executionOrder: number;
+ value: number;
+ status?: string;
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Retry utility with exponential backoff
+ */
+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;
+}
+
+/**
+ * Rate limiter with delay after operation
+ */
+async function rateLimitedMutation(operation: () => Promise<any>, delayMs: number): Promise<any> {
+ const result = await operation();
+ if (delayMs > 0) {
+  await new Promise(resolve => setTimeout(resolve, delayMs));
+ }
+ return result;
+}
+
+/**
+ * Build control ref from components
+ */
+function buildControlRef(data: {
+ controlGroupRef?: string;
+ virtualCatalogueRef?: string;
+ controlType: string;
+ productRef?: string;
+ categoryRef?: string;
+ locationRef?: string;
+}): string {
+ const { controlGroupRef, virtualCatalogueRef, controlType, productRef, categoryRef, locationRef } =
+  data;
+
+ if (controlType === 'EXCLUSION') {
+  if (!controlGroupRef) throw new Error('EXCLUSION requires controlGroupRef');
+  if (categoryRef) return `${controlGroupRef}:EXCLUSION:${categoryRef}`;
+  else if (productRef) return `${controlGroupRef}:EXCLUSION:${productRef}`;
+  throw new Error('EXCLUSION requires either categoryRef or productRef');
+ } else if (controlType === 'QUANTITY_BUFFER') {
+  if (!virtualCatalogueRef) throw new Error('QUANTITY_BUFFER requires virtualCatalogueRef');
+  if (productRef && locationRef)
+   return `${virtualCatalogueRef}:QUANTITY_BUFFER:${productRef}:${locationRef}`;
+  else if (productRef) return `${virtualCatalogueRef}:QUANTITY_BUFFER:${productRef}`;
+  else if (categoryRef) return `${virtualCatalogueRef}:QUANTITY_BUFFER:${categoryRef}`;
+  else if (locationRef) return `${virtualCatalogueRef}:QUANTITY_BUFFER:${locationRef}`;
+  throw new Error('QUANTITY_BUFFER requires productRef, categoryRef, or locationRef');
+ }
+ throw new Error(`Unknown control type: ${controlType}`);
+}
+
+/**
+ * Schema validator for Control entities
+ */
+class ControlSchemaValidator {
+ private readonly VALID_CONTROL_TYPES = ['QUANTITY_BUFFER', 'EXCLUSION'];
+ private readonly VALID_STATUSES = ['ACTIVE', 'INACTIVE'];
+ private readonly MIN_EXECUTION_ORDER = 1;
+ private readonly MAX_EXECUTION_ORDER = 999;
+
+ validateForCreate(control: any): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!control.controlRef?.trim()) errors.push('controlRef is required');
+  if (!control.catalogRef?.trim()) errors.push('catalogRef is required');
+
+  if (!control.controlType?.trim()) {
+   errors.push('controlType is required');
+  } else if (!this.VALID_CONTROL_TYPES.includes(control.controlType)) {
+   errors.push(`Invalid controlType: ${control.controlType}`);
+  }
+
+  if (control.executionOrder === undefined || control.executionOrder === null) {
+   errors.push('executionOrder is required');
+  } else {
+   const order = parseInt(control.executionOrder, 10);
+   if (isNaN(order) || order < this.MIN_EXECUTION_ORDER || order > this.MAX_EXECUTION_ORDER) {
+    errors.push(`executionOrder must be ${this.MIN_EXECUTION_ORDER}-${this.MAX_EXECUTION_ORDER}`);
+   }
+  }
+
+  if (control.value === undefined || control.value === null) {
+   errors.push('value is required');
+  } else {
+   const value = parseInt(control.value, 10);
+   if (isNaN(value)) errors.push('value must be integer');
+   if (control.controlType === 'EXCLUSION' && value !== 0) {
+    errors.push('EXCLUSION must have value=0');
+   }
+   if (control.controlType === 'QUANTITY_BUFFER' && value < 0) {
+    errors.push('QUANTITY_BUFFER value cannot be negative');
+   }
+  }
+
+  if (control.status && !this.VALID_STATUSES.includes(control.status)) {
+   errors.push(`Invalid status: ${control.status}`);
+  }
+
+  const ref = control.controlRef || '';
+  const type = control.controlType || '';
+
+  if (type === 'EXCLUSION' && !ref.includes(':EXCLUSION:')) {
+   errors.push('EXCLUSION ref must contain ":EXCLUSION:"');
+  }
+  if (type === 'QUANTITY_BUFFER' && !ref.includes(':QUANTITY_BUFFER:')) {
+   errors.push('QUANTITY_BUFFER ref must contain ":QUANTITY_BUFFER:"');
+  }
+
+  return { valid: errors.length === 0, errors };
+ }
+}
+
+// ============================================================================
+// SERVICE FUNCTIONS
+// ============================================================================
+
+/**
+ * SERVICE 1: Process a single CSV file
+ * - Downloads file from S3
+ * - Parses CSV records
+ * - Maps records using UniversalMapper
+ * - Validates control schema
+ * - Returns processed records ready for mutation
+ */
+async function processFile(
+ s3: S3DataSource,
+ parser: CSVParserService,
+ mapper: GraphQLMutationMapper,
+ validator: ControlSchemaValidator,
+ filePath: string,
+ fileName: string,
+ log: any
+): Promise<FileProcessingResult> {
+ const result: FileProcessingResult = {
+  success: false,
+  fileName,
+  recordsProcessed: 0,
+  recordsSuccessful: 0,
+  recordsFailed: 0,
+  mutations: [],
+  errors: [],
+ };
+
+ try {
+  log.info('[processFile] Downloading file', { fileName, filePath });
+
+  // Download file with retry
+  const content = await retryWithBackoff(
+   () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
+  );
+
+  // Parse CSV
+  const records = await parser.parse(content, {
+   columns: true,
+   skip_empty_lines: true,
+   trim: true,
+  });
+
+  log.info('[processFile] CSV parsed', { fileName, recordCount: records.length });
+
+  if (records.length === 0) {
+   result.success = true;
+   result.errors.push('Empty CSV file');
+   return result;
+  }
+
+  result.recordsProcessed = records.length;
+
+  // Map and validate each record using GraphQLMutationMapper
+  const validRecords: Array<{ query: string; variables: any; input: any }> = [];
+
+  // ✅ PRODUCTION ENHANCEMENT: Log transformation start
+  log.info('[processFile] Transforming records to GraphQL mutations', {
+   fileName,
+   totalRecords: records.length,
+  });
+
+  for (let i = 0; i < records.length; i++) {
+   const rec = records[i];
+   const recordNumber = i + 1;
+
+   // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 records
+   if (recordNumber % 50 === 0) {
+    log.info(`📤 Transforming record ${recordNumber}/${records.length}`, {
+     fileName,
+     recordNumber,
+     totalRecords: records.length,
+     validSoFar: validRecords.length,
+     failedSoFar: result.recordsFailed,
+     progress: `${((recordNumber / records.length) * 100).toFixed(1)}%`,
+    });
+   }
+
+   try {
+    // GraphQLMutationMapper returns { query, variables } directly
+    const mapped = await mapper.map(rec);
+    
+    const control = {
+     query: mapped.query,
+     variables: mapped.variables,
+     input: mapped.variables.input || mapped.variables,
+    };
+
+    // Validate schema using input
+    const validation = validator.validateForCreate(control.input);
+    if (!validation.valid) {
+     log.warn('[processFile] Validation error', { row: recordNumber, errors: validation.errors });
+     result.recordsFailed++;
+     result.errors.push(`Row ${recordNumber}: Validation failed - ${validation.errors.join(', ')}`);
+     continue;
+    }
+
+    validRecords.push(control);
+    result.recordsSuccessful++;
+   } catch (error: unknown) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    log.warn('[processFile] Mapping error', { row: recordNumber, error: errorMsg });
+    result.recordsFailed++;
+    result.errors.push(`Row ${recordNumber}: Mapping failed - ${errorMsg}`);
+   }
+  }
+
+  log.info('[processFile] Processing complete', {
+   fileName,
+   total: result.recordsProcessed,
+   valid: result.recordsSuccessful,
+   invalid: result.recordsFailed,
+   successRate: `${((result.recordsSuccessful / result.recordsProcessed) * 100).toFixed(1)}%`,
+  });
+
+  result.success = true;
+
+  // Store valid records in result for executeMutations
+  (result as any).validRecords = validRecords;
+
+  return result;
+ } catch (error: unknown) {
+  // ✅ Enhanced error logging: Extract all error details for visibility
+  const errorDetails = {
+   message: error instanceof Error ? error.message : String(error),
+   stack: error instanceof Error ? error.stack : undefined,
+   errorType: error instanceof Error ? error.constructor.name : 'Error',
+  };
+  log.error('[processFile] Failed to process file', errorDetails, { fileName });
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  result.errors.push(`File processing error: ${errorMsg}`);
+  return result;
+ }
+}
+
+/**
+ * ✅ NEW: Fetch all existing controls with pagination
+ * Returns Map for O(1) lookups during upsert logic
+ */
+async function fetchExistingControls(
+ client: any,
+ catalogRef: string,
+ log: any
+): Promise<Map<string, any>> {
+ const controlsMap = new Map();
+ let hasMore = true;
+ let cursor: string | null = null;
+ const MAX_PAGES = 50; // Safety limit
+
+ const query = `
+  query GetControls($catalogRef: String!, $first: Int!, $after: String) {
+   controlGroup(ref: $catalogRef) {
+    controls(first: $first, after: $after) {
+     edges {
+      node {
+       ref
+       type
+       status
+       executionOrder
+      }
+      cursor
+     }
+     pageInfo {
+      hasNextPage
+      endCursor
+     }
+    }
+   }
+  }
+ `;
+
+ let pageCount = 0;
+ while (hasMore && pageCount < MAX_PAGES) {
+  try {
+   const result = await client.graphql({
+    query,
+    variables: { catalogRef, first: 100, after: cursor },
+   });
+
+   const edges = result?.data?.controlGroup?.controls?.edges || [];
+   edges.forEach((edge: any) => {
+    if (edge?.node?.ref) {
+     controlsMap.set(edge.node.ref, edge.node);
+    }
+   });
+
+   const pageInfo = result?.data?.controlGroup?.controls?.pageInfo;
+   hasMore = pageInfo?.hasNextPage || false;
+   cursor = pageInfo?.endCursor || null;
+   pageCount++;
+
+   log.info(`Fetched page ${pageCount} of existing controls`, {
+    pageCount,
+    totalFound: controlsMap.size,
+   });
+  } catch (error: unknown) {
+   const errorMsg = error instanceof Error ? error.message : String(error);
+   log.error('Failed to fetch existing controls', {
+    message: errorMsg,
+    pageCount,
+   });
+   break;
+  }
+ }
+
+ log.info(`Bulk query complete: ${controlsMap.size} existing controls found`);
+ return controlsMap;
+}
+
+/**
+ * SERVICE 2: Execute GraphQL mutations for control records
+ * - Separates creates from updates
+ * - Supports alias batching for creates
+ * - Processes updates individually
+ * - Returns mutation results
+ */
+async function executeMutations(
+ controls: Array<{ query: string; variables: any; input: any }>,
+ existingControlsMap: Map<string, any>,
+ client: any,
+ mapper: GraphQLMutationMapper,
+ log: any,
+ batchSize: number = 1, // ✅ Default: 1 (sequential)
+ mutationsPerAliasBatch?: number // ✅ NEW: Alias batching parameter (default: undefined = disabled)
+): Promise<MutationResult[]> {
+ const results: MutationResult[] = [];
+
+ log.info('[executeMutations] Starting mutations', { 
+  controlCount: controls.length, 
+  batchSize,
+  mutationsPerAliasBatch,
+ });
+
+ // Separate creates from updates
+ const toCreate: Array<{ query: string; variables: any; input: any }> = [];
+ const toUpdate: Array<{ query: string; variables: any; input: any }> = [];
+
+ controls.forEach(control => {
+  const exists = existingControlsMap.has(control.input.controlRef);
+  if (exists) {
+   toUpdate.push(control);
+  } else {
+   toCreate.push(control);
+  }
+ });
+
+ log.info(`Mutation breakdown: ${toCreate.length} creates, ${toUpdate.length} updates`);
+
+ // ✅ Process creates with alias batching if enabled
+ if (toCreate.length > 0) {
+  const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
+  
+  if (useAliases) {
+   const createResults = await executeMutationsWithAliases(
+    toCreate,
+    client,
+    mapper,
+    log,
+    batchSize,
+    mutationsPerAliasBatch,
+    'createControl'
+   );
+   
+   // Convert to MutationResult format
+   toCreate.forEach((control, idx) => {
+    if (idx < createResults.executed) {
+     results.push({
+      success: true,
+      controlRef: control.input.controlRef,
+      operation: 'create',
+     });
+    } else {
+     results.push({
+      success: false,
+      controlRef: control.input.controlRef,
+      operation: 'create',
+      error: createResults.errors[idx - createResults.executed] || 'Unknown error',
+     });
+    }
+   });
+  } else {
+   // Process creates individually
+   for (const control of toCreate) {
+    try {
+     await retryWithBackoff(() =>
+      client.graphql({
+       query: control.query,
+       variables: control.variables,
+      })
+     );
+     results.push({
+      success: true,
+      controlRef: control.input.controlRef,
+      operation: 'create',
+     });
+    } catch (error: unknown) {
+     const errorMsg = error instanceof Error ? error.message : String(error);
+     results.push({
+      success: false,
+      controlRef: control.input.controlRef,
+      operation: 'create',
+      error: errorMsg,
+     });
+    }
+   }
+  }
+ }
+
+ // ✅ Process updates individually (conditional logic requires individual handling)
+ for (const control of toUpdate) {
+  const mutationResult: MutationResult = {
+   success: false,
+   controlRef: control.input.controlRef,
+   operation: 'update',
+  };
+
+  try {
+   await retryWithBackoff(() =>
+    client.graphql({
+     query: control.query,
+     variables: control.variables,
+    })
+   );
+   mutationResult.success = true;
+  } catch (error: unknown) {
+   const errorMsg = error instanceof Error ? error.message : String(error);
+   mutationResult.error = errorMsg;
+   const errorDetails = {
+    message: errorMsg,
+    stack: error instanceof Error ? error.stack : undefined,
+    errorType: error instanceof Error ? error.constructor.name : 'Error',
+   };
+   log.error('[executeMutations] Mutation failed', errorDetails, { ref: control.input.controlRef });
+  }
+
+  results.push(mutationResult);
+ }
+
+ log.info('[executeMutations] Mutations complete', {
+  total: results.length,
+  successful: results.filter(r => r.success).length,
+  failed: results.filter(r => !r.success).length,
+ });
+
+ return results;
+}
+
+/**
+ * ✅ NEW: Execute mutations with GraphQL alias batching
+ */
+async function executeMutationsWithAliases(
+ controls: Array<{ query: string; variables: any; input: any }>,
+ client: any,
+ mapper: GraphQLMutationMapper,
+ log: any,
+ 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 controls[0]>> = [];
+ for (let i = 0; i < controls.length; i += mutationsPerAliasBatch) {
+  aliasBatches.push(controls.slice(i, i + mutationsPerAliasBatch));
+ }
+ 
+ log.info(`Processing ${aliasBatches.length} alias batches`, {
+  totalControls: controls.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);
+    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(control => {
+     results.failed++;
+     const controlRef = control.input?.controlRef || 'unknown';
+     results.errors.push(`Failed to ${mutationName} ${controlRef}: ${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
+): { 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}) { ref type }`;
+ }).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((control, index) => {
+  const input = control.variables.input || control.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((control, 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 controlRef = control.input?.controlRef || 'unknown';
+   result.errors.push(`Failed to ${mutationName} ${controlRef}: ${errorMsg}`);
+  }
+ });
+ 
+ return result;
+}
+
+/**
+ * SERVICE 3: Write mutation results log to S3
+ * - Creates detailed JSON log with processing results
+ * - Uploads to S3 logs directory with Buffer
+ * - Returns upload success/failure
+ */
+async function writeMutationLog(
+ s3: S3DataSource,
+ fileName: string,
+ fileResult: FileProcessingResult,
+ logPrefix: string,
+ log: any
+): Promise<boolean> {
+ try {
+  const logFileName = `${fileName.replace('.csv', '')}-log-${Date.now()}.json`;
+  const logPath = `${logPrefix}${logFileName}`;
+
+  const logData = {
+   fileName,
+   timestamp: new Date().toISOString(),
+   summary: {
+    totalRecords: fileResult.recordsProcessed,
+    successful: fileResult.recordsSuccessful,
+    failed: fileResult.recordsFailed,
+    mutations: {
+     total: fileResult.mutations.length,
+     created: fileResult.mutations.filter(m => m.operation === 'create' && m.success).length,
+     updated: fileResult.mutations.filter(m => m.operation === 'update' && m.success).length,
+     failed: fileResult.mutations.filter(m => !m.success).length,
+    },
+   },
+   errors: fileResult.errors,
+   mutations: fileResult.mutations,
+  };
+
+  const logContent = JSON.stringify(logData, null, 2);
+
+  log.info('[writeMutationLog] Writing log to S3', { logPath, size: logContent.length });
+
+  // Upload log to S3 (uploadFile accepts string or Buffer)
+  await s3.uploadFile(logPath, logContent);
+
+  log.info('[writeMutationLog] Log written successfully', { logPath });
+  return true;
+ } catch (error: unknown) {
+  // ✅ Enhanced error logging: Extract all error details for visibility
+  const errorDetails = {
+   message: error instanceof Error ? error.message : String(error),
+   stack: error instanceof Error ? error.stack : undefined,
+   errorType: error instanceof Error ? error.constructor.name : 'Error',
+  };
+  log.error('[writeMutationLog] Failed to write log', errorDetails, { fileName });
+  return false;
+ }
+}
+
+// ============================================================================
+// MAIN WORKFLOW FUNCTION
+// ============================================================================
+
+/**
+ * Main workflow: Control CSV sync from S3
+ * Per-file processing with three service functions:
+ * 1. processFile() - Download, parse, map, validate
+ * 2. executeMutations() - Create/update controls via GraphQL
+ * 3. writeMutationLog() - Write detailed logs to S3
+ */
+async function runControlSync(ctx: any) {
+ const log = ctx.log;
+ const executionStartTime = Date.now();
+ log.info('🚀 [WORKFLOW] Starting control sync from S3');
+
+ // Read activation variables
+ const s3Bucket = ctx.activation?.getVariable('s3BucketName');
+ const s3Region = ctx.activation?.getVariable('awsRegion') || 'us-east-1';
+ const s3AccessKeyId = ctx.activation?.getVariable('awsAccessKeyId');
+ const s3SecretAccessKey = ctx.activation?.getVariable('awsSecretAccessKey');
+ const s3Prefix = ctx.activation?.getVariable('s3Prefix') || 'controls/';
+ const maxFiles = parseInt(ctx.activation?.getVariable('maxFilesToProcess') || '10', 10);
+ const filePattern = (ctx.activation?.getVariable('filePattern') || '.csv').toLowerCase();
+ const enableArchival = ctx.activation?.getVariable('enableArchival') !== 'false';
+ const enableFileTracking = ctx.activation?.getVariable('enableFileTracking') !== 'false';
+ const validateConnection = ctx.activation?.getVariable('validateConnection') !== 'false';
+ const archivePrefix = ctx.activation?.getVariable('archivePrefix') || 'processed/';
+ const errorPrefix = ctx.activation?.getVariable('errorPrefix') || 'errors/';
+ const logPrefix = ctx.activation?.getVariable('logPrefix') || 'logs/';
+ const rateLimit = parseInt(ctx.activation?.getVariable('mutationRateLimit') || '10', 10);
+ 
+ // ✅ 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)
+
+ // Validate required variables
+ const missingVars: string[] = [];
+ if (!s3Bucket) missingVars.push('s3BucketName');
+ if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
+ if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
+
+ if (missingVars.length > 0) {
+  const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
+  log.error('❌ ' + errorMsg);
+  return {
+   success: false,
+   error: errorMsg,
+   processed: 0,
+   recommendation: 'Please configure the missing activation variables in Versori settings',
+  };
+ }
+
+ log.info('⚙️ [WORKFLOW] Configuration loaded', {
+  bucket: s3Bucket,
+  region: s3Region,
+  prefix: s3Prefix,
+  maxFiles,
+  rateLimit,
+  enableArchival,
+  enableFileTracking,
+  validateConnection,
+ });
+
+ // Initialize services
+ log.info('🔌 [WORKFLOW] Initializing Fluent Commerce client');
+ const client = await createClient(ctx);
+ if (!client) {
+  log.error('❌ Failed to create Fluent Commerce client');
+  return {
+   success: false,
+   error: 'Failed to create Fluent Commerce client',
+   recommendation: 'Check Fluent Commerce connection configuration in Versori',
+  };
+ }
+ log.info('✅ [WORKFLOW] Fluent Commerce client initialized');
+
+ // ✅ CORRECT: GraphQL mutations don't need client.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('☁️ [WORKFLOW] Initializing S3 data source');
+ const s3 = new S3DataSource(
+  {
+   type: 'S3_CSV',
+   connectionId: 's3-control-sync',
+   name: 'Source S3',
+   s3Config: {
+    bucket: s3Bucket,
+    region: s3Region,
+    accessKeyId: s3AccessKeyId,
+    secretAccessKey: s3SecretAccessKey,
+   },
+  },
+  log
+ );
+
+ if (validateConnection) {
+  try {
+   log.info('🔍 [WORKFLOW] Validating S3 connection');
+   await s3.validateConnection();
+   log.info('✅ [WORKFLOW] S3 connection validated successfully');
+  } catch (error: any) {
+   log.error('❌ [WORKFLOW] S3 connection validation failed', {
+    message: error instanceof Error ? error.message : String(error),
+   });
+   return {
+    success: false,
+    error: 'S3 connection validation failed',
+    details: error instanceof Error ? error.message : String(error),
+    recommendation: 'Check S3 credentials and bucket permissions',
+   };
+  }
+ }
+
+ const parser = new CSVParserService();
+ const { openKv } = ctx;
+ const kv = new VersoriKVAdapter(openKv(':project:'));
+ const validator = new ControlSchemaValidator();
+
+ // Custom resolvers for control ref building
+ const customResolvers = {
+  'custom.buildOrUseControlRef': (_: any, sourceData: any) => {
+   if (sourceData.controlRef && sourceData.controlRef.trim()) {
+    return sourceData.controlRef.trim();
+   }
+   return buildControlRef({
+    controlGroupRef: sourceData.controlGroupRef,
+    virtualCatalogueRef: sourceData.virtualCatalogueRef,
+    controlType: sourceData.controlType,
+    productRef: sourceData.productRef,
+    categoryRef: sourceData.categoryRef,
+    locationRef: sourceData.locationRef,
+   });
+  },
+  'custom.resolveCatalogRef': (_: any, sourceData: any) => {
+   if (sourceData.catalogRef && sourceData.catalogRef.trim()) {
+    return sourceData.catalogRef.trim();
+   }
+   if (sourceData.controlType === 'EXCLUSION') {
+    return sourceData.controlGroupRef?.trim() || '';
+   } else if (sourceData.controlType === 'QUANTITY_BUFFER') {
+    return sourceData.virtualCatalogueRef?.trim() || '';
+   }
+   return '';
+  },
+ };
+
+ // ✅ CRITICAL: Load mapping config from external JSON file
+ // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
+ // File: src/config/control-mapping.json
+ const mappingConfigJson = await import('../config/control-mapping.json', { assert: { type: 'json' } });
+ const mappingConfig = mappingConfigJson.default;
+ 
+ // Initialize GraphQLMutationMapper with client for schema introspection
+ const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+
+ try {
+  // List files from S3 (pattern filtering handled by listFiles)
+  log.info('📂 [WORKFLOW] Listing files from S3', { prefix: s3Prefix, filePattern });
+  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('📋 [WORKFLOW] Files discovered', { total: files.length, toProcess: csvFiles.length });
+
+  // ✅ BULK QUERY: Fetch all existing controls once for efficient upsert detection
+  const catalogRef = ctx.activation?.getVariable('catalogRef');
+  const existingControlsMap = catalogRef 
+   ? await fetchExistingControls(client, catalogRef, log)
+   : new Map<string, any>();
+
+  const workflowResults = {
+   processed: 0,
+   skipped: 0,
+   failed: 0,
+   totalRecords: 0,
+   controlsCreated: 0,
+   controlsUpdated: 0,
+   errors: [] as string[],
+  };
+
+  // Process each file using service functions
+  for (const file of csvFiles) {
+   const fileStartTime = Date.now();
+   const filePath = file.path;
+   const fileName = file.name;
+
+   log.info('📄 [WORKFLOW] Processing file', { fileName, filePath });
+
+   // Check duplicate via KV state
+   if (enableFileTracking) {
+    const stateKey = ['processed-files', 's3-control-sync', fileName];
+    const existing = await kv.get(stateKey);
+    if (existing) {
+     log.info('⏭️ [WORKFLOW] Skipping already processed file', { fileName });
+     workflowResults.skipped++;
+     continue;
+    }
+   }
+
+   try {
+    // SERVICE 1: Process file (download, parse, map, validate)
+    const fileResult = await processFile(
+     s3,
+     parser,
+     mapper,
+     validator,
+     filePath,
+     fileName,
+     log
+    );
+
+    if (!fileResult.success) {
+     log.error('❌ [WORKFLOW] File processing failed', { fileName, errors: fileResult.errors });
+     workflowResults.failed++;
+     workflowResults.errors.push(...fileResult.errors);
+
+     // Move to error directory
+     if (enableArchival) {
+      try {
+       await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
+       log.info('🗂️ [WORKFLOW] Moved failed file to error directory', { fileName });
+      } catch (moveError: any) {
+       log.error('⚠️ [WORKFLOW] Failed to move error file', {
+        fileName,
+        error: moveError instanceof Error ? moveError.message : String(moveError),
+       });
+      }
+     }
+     continue;
+    }
+
+    workflowResults.totalRecords += fileResult.recordsProcessed;
+
+    // Get valid records from result
+    const validRecords = (fileResult as any).validRecords as ControlRecord[];
+
+    if (validRecords.length === 0) {
+     log.warn('⚠️ [WORKFLOW] No valid records to process', { fileName });
+     if (enableArchival) {
+      try {
+       await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+       log.info('📦 [WORKFLOW] Archived empty file', { fileName });
+      } catch (moveError: any) {
+       log.error('⚠️ [WORKFLOW] Failed to archive empty file', {
+        fileName,
+        error: moveError instanceof Error ? moveError.message : String(moveError),
+       });
+      }
+     }
+     workflowResults.skipped++;
+     continue;
+    }
+
+    // SERVICE 2: Execute mutations (create/update controls)
+    // ✅ 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)
+
+    log.info('🔄 [WORKFLOW] Executing mutations', {
+     fileName,
+     controlCount: validRecords.length,
+     batchSize: mutationBatchSize,
+     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch})` : 'disabled',
+    });
+
+    // ? Enhanced: Extract context for progress logging
+    const sampleControlRefs = validRecords.slice(0, 5).map((r: any) => r.input?.controlRef || 'unknown');
+    const mutationType = mapper?.mutationName || 'createControl';
+
+    // ? Enhanced: Start logging with context
+    log.info(`[GraphQLMutations] Sending mutations for file "${fileName}"`, {
+     totalMutations: validRecords.length,
+     mutationType,
+     batchSize: mutationBatchSize,
+     batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
+     sampleControlRefs: sampleControlRefs.join(', '),
+     aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled'
+    });
+
+    const mutationResults = await executeMutations(
+     validRecords,
+     existingControlsMap,
+     client,
+     mapper,
+     log,
+     mutationBatchSize, // Concurrency control (default: 1)
+     mutationsPerAliasBatch // ✅ NEW: Alias batching (default: undefined)
+    );
+
+    // Update workflow results
+    const created = mutationResults.filter(m => m.operation === 'create' && m.success).length;
+    const updated = mutationResults.filter(m => m.operation === 'update' && m.success).length;
+    const failed = mutationResults.filter(m => !m.success).length;
+
+    // ? Enhanced: Completion logging with summary
+    const successRate = validRecords.length > 0 ? Math.round(((created + updated) / validRecords.length) * 100) : 0;
+    log.info(`✅ [GraphQLMutations] Mutation submission completed for file "${fileName}"`, {
+     totalMutations: validRecords.length,
+     created,
+     updated,
+     failed,
+     successRate: `${successRate}%`,
+     mutationType,
+    });
+
+    workflowResults.controlsCreated += created;
+    workflowResults.controlsUpdated += updated;
+
+    // Store mutation results in fileResult for logging
+    fileResult.mutations = mutationResults;
+
+    const fileDuration = Date.now() - fileStartTime;
+    log.info('✅ [WORKFLOW] Mutations complete', {
+     fileName,
+     created,
+     updated,
+     failed,
+     duration: `${fileDuration}ms`,
+    });
+
+    // SERVICE 3: Write mutation log to S3
+    await writeMutationLog(s3, fileName, fileResult, logPrefix, log);
+
+    // Mark file as processed in KV state
+    if (enableFileTracking) {
+     const stateKey = ['processed-files', 's3-control-sync', fileName];
+     await kv.set(stateKey, {
+      processedAt: new Date().toISOString(),
+      recordsProcessed: fileResult.recordsProcessed,
+      recordsSuccessful: fileResult.recordsSuccessful,
+      recordsFailed: fileResult.recordsFailed,
+      controlsCreated: created,
+      controlsUpdated: updated,
+      duration: fileDuration,
+     });
+    }
+
+    // Archive processed file
+    if (enableArchival) {
+     try {
+      await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+      log.info('📦 [WORKFLOW] File archived', { fileName, destination: archivePrefix });
+     } catch (moveError: any) {
+      log.error('⚠️ [WORKFLOW] Failed to archive file', {
+       fileName,
+       error: moveError instanceof Error ? moveError.message : String(moveError),
+      });
+     }
+    }
+
+    workflowResults.processed++;
+    log.info('✅ [WORKFLOW] File complete', { fileName, duration: `${fileDuration}ms` });
+   } catch (error: any) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorDetails = {
+     message: error?.message || 'Unknown error',
+     stack: error?.stack,
+     fileName: error?.fileName,
+     lineNumber: error?.lineNumber,
+     originalError: error?.context?.originalError?.message,
+     errorType: error?.name || 'Error',
+    };
+    log.error('❌ [WORKFLOW] File processing error', errorDetails, { fileName });
+    workflowResults.failed++;
+    workflowResults.errors.push({
+     file: fileName,
+     error: error.message,
+     recommendation: getErrorRecommendation(error),
+    });
+
+    // Move to error directory
+    if (enableArchival) {
+     try {
+      await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
+      log.info('🗂️ [WORKFLOW] Moved failed file to error directory', { fileName });
+     } catch (moveError: any) {
+      log.error('⚠️ [WORKFLOW] Failed to move error file', {
+       fileName,
+       error: moveError instanceof Error ? moveError.message : String(moveError),
+      });
+     }
+    }
+
+    // Track error state with exponential backoff
+    const errorKey = ['error-state', fileName];
+    const prev = (await kv.get(errorKey))?.value as any;
+    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();
+
+    await kv.set(errorKey, {
+     fileName,
+     attemptCount: attempts,
+     lastError: error?.message || 'unknown',
+     lastAttemptAt: new Date().toISOString(),
+     firstFailedAt: prev?.firstFailedAt || new Date().toISOString(),
+     nextRetryAt,
+    });
+   }
+  }
+
+  // Final summary
+  const executionDuration = Date.now() - executionStartTime;
+  const summary = {
+   success: true,
+   processed: workflowResults.processed,
+   skipped: workflowResults.skipped,
+   failed: workflowResults.failed,
+   totalRecords: workflowResults.totalRecords,
+   controlsCreated: workflowResults.controlsCreated,
+   controlsUpdated: workflowResults.controlsUpdated,
+   errors: workflowResults.errors.length > 0 ? workflowResults.errors : undefined,
+   duration: executionDuration,
+   durationFormatted: `${(executionDuration / 1000).toFixed(2)}s`,
+   timestamp: new Date().toISOString(),
+  };
+
+  log.info('🎉 [WORKFLOW] Control sync completed', summary);
+  return summary;
+ } catch (error: unknown) {
+  // ✅ Enhanced error logging: Extract all error details for visibility
+  const errorDetails = {
+   message: error instanceof Error ? error.message : String(error),
+   stack: error instanceof Error ? error.stack : undefined,
+   errorType: error instanceof Error ? error.constructor.name : 'Error',
+  };
+  log.error('❌ [WORKFLOW] Sync failed', errorDetails);
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  const executionDuration = Date.now() - executionStartTime;
+  return {
+   success: false,
+   error: errorMsg,
+   recommendation: getErrorRecommendation(error),
+   processed: 0,
+   duration: executionDuration,
+   durationFormatted: `${(executionDuration / 1000).toFixed(2)}s`,
+   timestamp: new Date().toISOString(),
+  };
+ }
+}
+
+/**
+ * Get error recommendation based on error type
+ */
+function getErrorRecommendation(error: any): string {
+ const errorMsg = (error?.message || '').toLowerCase();
+
+ if (errorMsg.includes('credentials') || errorMsg.includes('access denied')) {
+  return 'Check AWS credentials and S3 bucket permissions';
+ }
+ if (errorMsg.includes('bucket') || errorMsg.includes('not found')) {
+  return 'Verify S3 bucket name and region configuration';
+ }
+ if (errorMsg.includes('connection') || errorMsg.includes('network')) {
+  return 'Check network connectivity and firewall settings';
+ }
+ if (errorMsg.includes('parse') || errorMsg.includes('invalid csv')) {
+  return 'Verify CSV file format and structure';
+ }
+ if (errorMsg.includes('validation') || errorMsg.includes('required field')) {
+  return 'Review control data validation rules and required fields';
+ }
+ if (errorMsg.includes('graphql') || errorMsg.includes('mutation')) {
+  return 'Check GraphQL schema and mutation configuration';
+ }
+ if (errorMsg.includes('rate limit') || errorMsg.includes('throttl')) {
+  return 'Reduce mutationRateLimit or mutationBatchSize in activation variables';
+ }
+
+ return 'Review error logs and activation variables configuration';
+}
+
+// Scheduled daily run
+export const scheduledControlSync = schedule('s3-control-daily', '0 2 * * *').then(
+ http('sync-controls', { connection: 'fluent_commerce' }, async ctx => {
+  return await runControlSync(ctx);
+ })
+);
+
+// Manual trigger
+export const syncNow = webhook('sync-controls-now').then(
+ http('sync-controls-manual', { connection: 'fluent_commerce' }, async ctx => {
+  return await runControlSync(ctx);
+ })
+);
+
+// Status check
+export const checkStatus = webhook('check-status').then(
+ fn('get-status', async (ctx: any) => {
+  const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
+  const processedKeys = await kv.list({ prefix: ['processed-files', 's3-control-sync'] });
+  return {
+   success: true,
+   recentFiles: processedKeys.slice(0, 10),
+   timestamp: new Date().toISOString(),
+  };
+ })
+);
+```
+
+## Key Patterns Explained
+
+### Pattern 1: Direct KV State Management
+
+```typescript
+const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
+
+// Check if file already processed
+const stateKey = ['processed-files', 's3-control-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,
+ processedAt: new Date().toISOString(),
+});
+```
+
+### Pattern 2: Rate-Limited GraphQL Mutations
+
+```typescript
+async function rateLimitedMutation(operation: () => Promise<any>, delayMs: number) {
+ const result = await operation();
+ if (delayMs > 0) {
+  await new Promise(resolve => setTimeout(resolve, delayMs));
+ }
+ return result;
+}
+
+// Configure rate limit (10 mutations/sec = 100ms delay)
+const rateLimit = 10;
+const delayMs = Math.floor(1000 / rateLimit);
+```
+
+### Pattern 3: S3 File Operations with Retry
+
+```typescript
+// List files with prefix filtering
+const files = await s3.listFiles({ prefix: 'controls/', maxKeys: 1000 });
+
+// Download with retry
+const content = await retryWithBackoff(
+ () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
+);
+
+// Move file (archive or error)
+await s3.moveFile('controls/file.csv', 'processed/file.csv');
+```
+
+### Pattern 4: Control Ref Building with Custom Resolvers
+
+```typescript
+const customResolvers = {
+ 'custom.buildOrUseControlRef': (_: any, sourceData: any) => {
+  // If pre-built ref exists, use it
+  if (sourceData.controlRef?.trim()) return sourceData.controlRef.trim();
+
+  // Otherwise build from components
+  return buildControlRef({ ...sourceData });
+ },
+};
+```
+
+### Pattern 5: UniversalMapper with Custom Resolvers
+
+Available SDK Resolvers:
+
+- **String**: `sdk.trim`, `sdk.uppercase`, `sdk.lowercase`, `sdk.toString`
+- **Number**: `sdk.parseInt`, `sdk.parseFloat`, `sdk.number`
+- **Date**: `sdk.formatDate`, `sdk.formatDateShort`, `sdk.parseDate`
+- **Type**: `sdk.boolean`, `sdk.parseJson`, `sdk.toJson`
+- **Utility**: `sdk.identity`, `sdk.coalesce`
+
+## Schema Validation (Before Deployment)
+
+Use SDK CLI tools to validate your GraphQL schema:
+
+```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
+cat > control-mutation.graphql << 'EOF'
+mutation CreateControl(
+ $controlRef: String!
+ $catalogRef: String!
+ $controlType: String!
+ $executionOrder: Int!
+ $value: Json!
+) {
+ createControl(input: {
+  type: $controlType
+  ref: $controlRef
+  name: $controlRef
+  values: { name: "CONTROL_VALUE", type: "INTEGER", value: $value }
+  controlGroup: { ref: $catalogRef }
+  executionOrder: $executionOrder
+ }) {
+  ref
+ }
+}
+EOF
+
+# 3. Generate mapping from mutation
+fc-connect generate-mutation-mapping \
+ --file control-mutation.graphql \
+ --output control-mapping.json
+
+# 4. Validate mapping against schema
+fc-connect validate-schema \
+ --mapping control-mapping.json \
+ --schema fluent-schema.json
+
+# 5. Analyze field coverage
+fc-connect analyze-coverage \
+ --mapping control-mapping.json \
+ --schema fluent-schema.json
+```
+
+**Output Example**:
+
+```bash
+✓ Schema validation passed
+✓ All required fields present: ref, type, executionOrder, values
+✓ Mutation structure matches GraphQL schema
+⚠ Optional fields not mapped: status, description
+```
+
+## Testing the Workflow
+
+### 1. Upload Test CSV to S3
+
+```bash
+aws s3 cp controls-test.csv s3://my-controls-bucket/controls/
+```
+
+### 2. Deploy to Versori
+
+```bash
+npm run deploy
+```
+
+### 3. Manual Testing via Webhook
+
+```bash
+curl -X POST https://your-workspace.versori.run/sync-controls-now
+```
+
+### 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": 50,
+ "mutationsExecuted": 50,
+ "mutationsFailed": 0,
+ "results": [
+  {
+   "file": "controls_2025-01-22.csv",
+   "success": true,
+   "recordsProcessed": 50,
+   "mutationsExecuted": 50,
+   "mutationsFailed": 0
+  }
+ ],
+ "duration": 12345
+}
+```
+
+### Partial Success Response
+
+```json
+{
+ "success": true,
+ "filesProcessed": 1,
+ "filesSkipped": 0,
+ "filesFailed": 0,
+ "totalRecords": 50,
+ "mutationsExecuted": 45,
+ "mutationsFailed": 5,
+ "results": [
+  {
+   "file": "controls_2025-01-22.csv",
+   "success": true,
+   "recordsProcessed": 50,
+   "mutationsExecuted": 45,
+   "mutationsFailed": 5,
+   "errors": ["CTRL-001: Invalid control ref", "CTRL-002: Missing required field"]
+  }
+ ],
+ "duration": 12345
+}
+```
+
+### Error Response
+
+```json
+{
+ "success": false,
+ "filesProcessed": 0,
+ "filesFailed": 1,
+ "totalRecords": 0,
+ "mutationsExecuted": 0,
+ "mutationsFailed": 0,
+ "results": [
+  {
+   "file": "controls_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: Duplicate File Processing
+
+**Solution**:
+
+```typescript
+const stateKey = ['processed-files', 's3-control-sync', fileName];
+const existing = await kv.get(stateKey);
+if (existing) continue;
+await kv.set(stateKey, { processedAt: new Date().toISOString() });
+```
+
+### Issue 2: "EXCLUSION must have value=0"
+
+**Solution**: Update CSV - EXCLUSION controls must always have value=0
+
+### Issue 3: "controlRef pattern mismatch"
+
+**Solution**: Verify required fields are populated:
+
+- EXCLUSION: `controlGroupRef` + (`productRef` OR `categoryRef`)
+- QUANTITY_BUFFER: `virtualCatalogueRef` + (`productRef` OR `categoryRef` OR `locationRef`)
+
+### Issue 4: 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-controls-bucket",
+    "arn:aws:s3:::my-controls-bucket/*"
+   ]
+  }
+ ]
+}
+```
+
+### Issue 5: Rate Limiting
+
+**Solution**:
+
+```typescript
+// Adjust rate limit in activation variables
+mutationRateLimit = 5; // Reduce to 5 mutations/sec
+```
+
+## Production Checklist
+
+- [ ] S3 credentials validated with correct IAM permissions
+- [ ] Activation secrets stored securely
+- [ ] GraphQL schema validated using CLI tools
+- [ ] Mapping configuration tested with sample data
+- [ ] File duplicate prevention working via KV state
+- [ ] Rate limiting configured appropriately
+- [ ] Control validation rules tested
+- [ ] Error handling tested with malformed CSV
+- [ ] Retry logic tested with transient failures
+- [ ] File archival working (processed and error directories)
+- [ ] Monitoring/alerting configured for failures
+- [ ] Clear runbook for error recovery
+
+## Related Guides
+
+- **SFTP Version**: [sftp-csv-control-to-graphql.md](template-ingestion-sftp-csv-control-graphql.md)
+- **Universal Mapping**: `docs/02-CORE-GUIDES/mapping/modules/`
+- **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/`