npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (495) hide show

package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-xml-location-graphql.md CHANGED Viewed

@@ -1,2373 +1,2373 @@
----
-template_id: tpl-ingest-s3-xml-to-location-graphql
-canonical_filename: template-ingestion-s3-xml-location-graphql.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: s3-xml
-destination: fluent-graphql
-entity: location
-format: xml
-logging: versori
-status: stable
-compliance: gold-standard
-features:
-  - graphql-mutation-mapper
-  - memory-management
-  - enhanced-logging
-  - attribute-transformation
----
-Template: Ingestion - S3 XML to Location 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
----
-## Implementation Prompt
-"Create a Versori scheduled workflow that reads location XML files from S3, transforms the data using GraphQLMutationMapper with nested object mapping, and creates/updates Fluent Commerce locations via direct GraphQL mutations with alias batching support.
-**Requirements:**
-1. **S3 Source**:
-   - List and download XML files with configurable prefix and pattern
-   - Archive processed files to `processed/` directory (deduplication via archiving)
-   - Move failed files to `errors/` directory
-   - Use S3DataSource with retry logic and built-in archival
-   - Support configurable bucket, region, credentials
-2. **XML Parsing**:
-   - Use XMLParserService with @ prefix for attribute access
-   - Handle both single and multiple `<location>` elements (array normalization)
-   - Support nested XML paths (`location.address.street1`, `location.coordinates.@lat`)
-   - Parse complex structures (addresses, coordinates, opening schedules)
-3. **Field Mapping**:
-   - Map XML fields to Location GraphQL input type with nested objects:
-     - `ref`, `name`, `type` (root fields)
-     - `primaryAddress.*` (nested address object with coordinates)
-     - `openingSchedule.*` (nested schedule object with 7-day hours)
-   - Use SDK resolvers (trim, uppercase, parseFloat, parseInt, boolean)
-   - Support custom resolvers for complex transformations
-   - Validate required fields
-   - Note: Check your GraphQL schema to determine if `retailer.id` field exists and is mandatory/optional
-4. **GraphQL Mutations** (Direct - NO Batch API):
-   - Execute `createLocation` mutation directly for each location
-   - **NO BPP (Batch Pre-Processing)** - Not applicable for direct GraphQL mutations
-   - **NO Batch API** - Use direct GraphQL mutations with rate limiting instead
-   - Use rate limiting (configurable mutations per second)
-   - Add delay between mutations to avoid API throttling
-   - Retry failed mutations with exponential backoff
-   - Track successful vs failed mutations per file
-5. **Job Tracking & State Management**:
-   - **Use JobTracker** - Track job lifecycle (start, complete, fail) in KV store
-   - Use StateService + VersoriKVAdapter for duplicate file prevention
-   - Track processed files in KV store with metadata
-   - Store error state with exponential backoff tracking
-   - Support distributed state across workflow runs
-   - Provide job status endpoint for monitoring
-6. **Error Handling**:
-   - File-level errors archived to `/errors/` subdirectory
-   - Record-level errors tracked but don't stop file processing
-   - Mapping errors logged with specific location context
-   - Mutation errors retried with exponential backoff
-   - Error state tracking with next retry timestamp
-7. **Advanced Features**:
-   - Configurable rate limiting (mutations per second)
-   - Empty file detection and archival
-   - Timestamp-based error tracking
-   - Comprehensive monitoring and logging
-   - Manual webhook trigger with job tracking
-   - Job status query endpoint
-**Use SDK Components:**
-- `createClient()` - Universal client factory for Versori
-- `S3DataSource` - S3 operations with retry logic
-- `XMLParserService` - XML parsing with @ prefix attribute support
-- `GraphQLMutationMapper` - Field transformation with schema validation and nested object support
-- `StateService` + `VersoriKVAdapter` - Duplicate prevention with KV storage
-- Native Versori `log` - Structured logging
-**Configuration Variables** (from Versori activation):
-```typescript
-{
-  s3: {
-    bucketName: string;
-    region: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    prefix: string;           // e.g., 'locations/'
-    archivePrefix: string;    // e.g., 'processed/'
-    errorPrefix: string;      // e.g., 'errors/'
-    filePattern: string;      // e.g., '.xml'
-    maxFilesToProcess: number;
-    enableArchival: boolean;
-  },
-  fluent: {
-    retailerId: string;         // Optional: Only if mutation schema requires retailerId in input
-    mutationRateLimit: number;  // mutations per second (e.g., 5)
-  }
-}
-```
-**Architecture Pattern:**
-```
-S3 Bucket → List Files → Download XML → Parse → Map → GraphQL Mutation → Archive/Move
-    ↓           ↓            ↓           ↓      ↓          ↓                ↓
- Configure   Filter by  S3DataSource  XML   Universal   Direct        S3 moveFile()
- Connection   Pattern    + Retry      Parser  Mapper   createLocation to processed/
-                                       (@)    (nested)  + Rate Limit   or errors/
-                                                                       (deduplication)
-```
-**Deliverables:**
-1. Complete Versori workflow with package.json
-2. Main workflow logic with S3 + XML + GraphQL patterns
-3. Helper functions for rate limiting and retry
-4. XML path resolution examples
-5. Sample XML files with nested structures
-6. Schema validation CLI commands
-7. Testing and deployment instructions
-8. Monitoring and troubleshooting guidance"
----
-# STEP 3: Complete Implementation
-## Versori Scheduled: S3 XML → Location 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@latest`
-**Context**: Versori scheduled workflow that reads location XML files from S3 and creates/updates Fluent Commerce locations via GraphQL mutations with XML path resolution and rate limiting
-**Complexity**: Medium
-**Runtime**: Versori Platform
-**Estimated Lines**: ~850 lines (with comprehensive documentation)
----
-## What You'll Build
-- Scheduled Versori workflow (daily location sync)
-- S3 file listing, download, and archival/move
-- XML parsing with @ prefix for attributes (XPath-style)
-- Array normalization (single element → array conversion)
-- GraphQLMutationMapper-based field transformations with nested objects
-- GraphQL mutations for location upserts with alias batching support
-- Retry logic with exponential backoff
-- StateService duplicate prevention (KV-backed)
-- Error state tracking and file error archival
-- Manual webhook trigger and job status endpoint
----
-## When to Use GraphQL Mutations vs Batch API vs Event API
-### ✅ Use GraphQL Mutations For:
-| Entity Type    | Use Case                                 | Why GraphQL                           |
-| -------------- | ---------------------------------------- | ------------------------------------- |
-| **Locations**  | Store/warehouse master data (low volume) | Direct control, immediate validation  |
-| **Controls**   | System configuration, settings           | Single operations, complex queries    |
-| **Prices**     | Price updates (moderate volume)          | Immediate feedback, custom logic      |
-| **Single Ops** | One-off creates/updates                  | Testing, debugging, direct API access |
-### ❌ Use Event API Instead For:
-| Entity Type         | Use Case                               | Why Event API                                |
-| ------------------- | -------------------------------------- | -------------------------------------------- |
-| **Products**        | Product catalog sync, variant updates  | Triggers workflows, validates business rules |
-| **Customers**       | Customer registration, profile updates | Needs workflow for downstream systems        |
-| **Orders**          | Order creation, status updates         | Event-driven fulfillment workflows           |
-| **Custom Entities** | Any entity needing workflow triggers   | Full Rubix workflow support                  |
-### 🔄 Use Batch API For:
-| Entity Type        | Use Case                           | Why Batch API                                   |
-| ------------------ | ---------------------------------- | ----------------------------------------------- |
-| **Inventory ONLY** | Bulk inventory updates, daily sync | Optimized for high-volume, BPP change detection |
----
-## XML File Format
-### Sample: locations.xml
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<locations>
-  <location ref="LOC-001" type="WAREHOUSE">
-    <name>Downtown Warehouse</name>
-    <address country="USA">
-      <street1>123 Main St</street1>
-      <street2>Building A</street2>
-      <city>New York</city>
-      <state>NY</state>
-      <postalCode>10001</postalCode>
-    </address>
-    <coordinates lat="40.7128" lon="-74.0060"/>
-    <timeZone>America/New_York</timeZone>
-    <openingSchedule>
-      <allHours>false</allHours>
-      <monStart>800</monStart>
-      <monEnd>1800</monEnd>
-      <tueStart>800</tueStart>
-      <tueEnd>1800</tueEnd>
-      <wedStart>800</wedStart>
-      <wedEnd>1800</wedEnd>
-      <thuStart>800</thuStart>
-      <thuEnd>1800</thuEnd>
-      <friStart>800</friStart>
-      <friEnd>1800</friEnd>
-      <satStart>0</satStart>
-      <satEnd>0</satEnd>
-      <sunStart>0</sunStart>
-      <sunEnd>0</sunEnd>
-    </openingSchedule>
-  </location>
-  <location ref="LOC-002" type="DC">
-    <name>Regional DC</name>
-    <address country="USA">
-      <street1>456 Industrial Pkwy</street1>
-      <city>Los Angeles</city>
-      <state>CA</state>
-      <postalCode>90001</postalCode>
-    </address>
-    <coordinates lat="34.0522" lon="-118.2437"/>
-    <timeZone>America/Los_Angeles</timeZone>
-    <openingSchedule>
-      <allHours>true</allHours>
-      <monStart>0</monStart>
-      <monEnd>0</monEnd>
-      <tueStart>0</tueStart>
-      <tueEnd>0</tueEnd>
-      <wedStart>0</wedStart>
-      <wedEnd>0</wedEnd>
-      <thuStart>0</thuStart>
-      <thuEnd>0</thuEnd>
-      <friStart>0</friStart>
-      <friEnd>0</friEnd>
-      <satStart>0</satStart>
-      <satEnd>0</satEnd>
-      <sunStart>0</sunStart>
-      <sunEnd>0</sunEnd>
-    </openingSchedule>
-  </location>
-</locations>
-```
-**XML Path Syntax (with @ prefix for attributes):**
-- `location.@ref` → XML attribute `ref` on `<location>` element
-- `location.name` → Text content of `<name>` element
-- `location.address.street1` → Nested element path
-- `location.address.@country` → XML attribute on nested `<address>` element
-- `location.coordinates.@lat` → XML attribute for latitude
-- `location.openingSchedule.monStart` → Deeply nested element
-**Note**: The SDK's `XMLParserService` automatically handles XML attributes using `@` prefix notation.
----
-## 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-xml-location-graphql/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-location-sync.ts   # Scheduled: Daily location sync
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-location-sync.ts   # Webhook: Manual trigger
-    │       └── job-status-check.ts     # Webhook: Status query
-    │
-    ├── services/
-    │   └── location-sync.service.ts     # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── location-mapping.json        # GraphQL mapping config
-```
----
-## Complete Versori Workflow
-### Step 1: Package Configuration
-**File: package.json**
-```json
-{
-  "name": "versori-s3-xml-location-sync",
-  "version": "1.0.0",
-  "description": "Versori workflow: S3 XML location sync to Fluent GraphQL",
-  "versori": {
-    "workflows": "./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"
-  }
-}
-```
-### Step 2: Workflow 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)
- */
-// Scheduled workflows
-export { dailyLocationSync } from './src/workflows/scheduled/daily-location-sync';
-// Webhook workflows
-export { adhocLocationSync } from './src/workflows/webhook/adhoc-location-sync';
-export { locationSyncJobStatus } from './src/workflows/webhook/job-status-check';
-```
-**What Gets Exposed:**
-- ✅ `adhocLocationSync` → `https://{workspace}.versori.run/location-sync-adhoc`
-- ✅ `locationSyncJobStatus` → `https://{workspace}.versori.run/location-sync-job-status`
-- ❌ `dailyLocationSync` → NOT exposed (runs automatically on cron)
----
-### Step 3: Workflow Files
-#### `src/workflows/scheduled/daily-location-sync.ts`
-**Purpose**: Automatic daily location 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 { executeLocationSync } from '../../services/location-sync.service';
-/**
- * Scheduled Workflow: Daily Location Sync
- *
- * Runs automatically daily at 2 AM UTC
- * NOT exposed as HTTP endpoint - Versori executes on schedule
- *
- * Uses shared service: location-sync.service.ts
- */
-export const dailyLocationSync = schedule(
-  'location-sync-scheduled',
-  '0 2 * * *' // Daily at 2 AM UTC
-).then(
-  http('run-location-sync', { connection: 'fluent_commerce' }, async ctx => {
-    const startTime = Date.now();
-    const { log, openKv } = ctx;
-    const jobId = `location-sync-${Date.now()}`;
-    const tracker = new JobTracker(openKv(':project:'), log);
-    log.info('🚀 [START] Daily location sync initiated', { jobId, trigger: 'schedule' });
-    await tracker.createJob(jobId, { triggeredBy: 'schedule', stage: 'initialization' });
-    await tracker.updateJob(jobId, { status: 'processing' });
-    try {
-      log.info('⚙️ [PROCESSING] Starting location synchronization workflow', { jobId });
-      const result = await executeLocationSync(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-      const duration = Date.now() - startTime;
-      log.info('✅ [SUCCESS] Daily location sync completed', {
-        jobId,
-        duration: `${duration}ms`,
-        processed: result.processed,
-        totalRecords: result.totalRecords
-      });
-      return { success: true, jobId, duration, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-      const duration = Date.now() - startTime;
-      log.error('❌ [FAILED] Daily location sync failed', {
-        jobId,
-        duration: `${duration}ms`,
-        error: e?.message,
-        errorType: e?.name
-      });
-      return { success: false, jobId, duration, error: e?.message };
-    }
-  })
-);
-```
----
-#### `src/workflows/webhook/adhoc-location-sync.ts`
-**Purpose**: Manual location sync trigger (on-demand)
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/location-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 { executeLocationSync } from '../../services/location-sync.service';
-/**
- * Webhook: Manual Location Sync Trigger
- *
- * Endpoint: POST https://{workspace}.versori.run/location-sync-adhoc
- * Request body (optional): { filePattern: "urgent_*.xml", maxFiles: 5 }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: location-sync.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const adhocLocationSync = webhook('location-sync-adhoc', {
-  response: { mode: 'sync' },
-  connection: 'location-sync-adhoc', // Versori validates API key
-}).then(
-  http('run-location-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
-    const startTime = Date.now();
-    const { log, openKv, data } = ctx;
-    const jobId = `location-sync-adhoc-${Date.now()}`;
-    const tracker = new JobTracker(openKv(':project:'), log);
-    log.info('🚀 [START] Manual location sync triggered', { jobId, trigger: 'webhook', options: data });
-    await tracker.createJob(jobId, {
-      triggeredBy: 'manual',
-      stage: 'initialization',
-      options: data // Optional: filePattern, maxFiles, etc.
-    });
-    await tracker.updateJob(jobId, { status: 'processing' });
-    try {
-      log.info('⚙️ [PROCESSING] Starting manual location synchronization', { jobId });
-      const result = await executeLocationSync(ctx, jobId, tracker);
-      await tracker.markCompleted(jobId, result);
-      const duration = Date.now() - startTime;
-      log.info('✅ [SUCCESS] Manual location sync completed', {
-        jobId,
-        duration: `${duration}ms`,
-        processed: result.processed,
-        totalRecords: result.totalRecords
-      });
-      return { success: true, jobId, duration, ...result };
-    } catch (e: any) {
-      await tracker.markFailed(jobId, e);
-      const duration = Date.now() - startTime;
-      log.error('❌ [FAILED] Manual location sync failed', {
-        jobId,
-        duration: `${duration}ms`,
-        error: e?.message,
-        errorType: e?.name
-      });
-      return { success: false, jobId, duration, error: e?.message };
-    }
-  })
-);
-```
----
-#### `src/workflows/webhook/job-status-check.ts`
-**Purpose**: Query job status
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/location-sync-job-status`
-**Request body**: `{ "jobId": "location-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/location-sync-job-status
- * Request body: { "jobId": "location-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 locationSyncJobStatus = webhook('location-sync-job-status', {
-  response: { mode: 'sync' },
-  connection: 'location-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 };
-  })
-);
-```
----
-### Step 4: Main Orchestration Service (`src/services/location-sync.service.ts`)
-**Note:** This service file should contain the `executeLocationSync` function (renamed from `runLocationXmlWorkflow`). The main workflow logic should be moved here.
-```typescript
-/**
- * Main Orchestration Service: Location Sync
- *
- * This service contains the core business logic for location synchronization.
- *
- * Features:
- * - S3 file operations with archival-based deduplication (moveFile to processed/)
- * - XML parsing with @ prefix for attributes
- * - Single element → array normalization
- * - GraphQLMutationMapper for nested field transformations
- * - GraphQL mutations with alias batching support
- * - StateService for metadata tracking (secondary to archival)
- * - Error state tracking with exponential backoff
- *
- * Deduplication Strategy:
- * - PRIMARY: S3 archival via moveFile() - Files in processed/ won't be re-listed
- * - SECONDARY: StateService KV tracking - Provides metadata and processing history
- */
-import { Buffer } from 'node:buffer';  // Required for Deno/Versori runtime
-import {
-  createClient,
-  S3DataSource,
-  XMLParserService,
-  GraphQLMutationMapper,
-  StateService,
-  VersoriKVAdapter,
-  JobTracker,
-  FluentClient,
-} from '@fluentcommerce/fc-connect-sdk';
-// ============================================================================
-// Type Definitions
-// ============================================================================
-interface FileProcessingResult {
-  success: boolean;
-  locations: any[];
-  errors: string[];
-}
-interface MutationResult {
-  successful: number;
-  failed: number;
-  errors: string[];
-}
-interface MutationLogEntry {
-  timestamp: string;
-  fileName: string;
-  locationRef: string;
-  status: 'success' | 'failure';
-  error?: string;
-}
-// ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * Retry utility with exponential backoff
- * (User-defined - not part of SDK public API)
- */
-async function retryWithBackoff<T>(
-  operation: () => Promise<T>,
-  maxRetries = 3,
-  baseDelayMs = 1000
-): Promise<T> {
-  let lastError: any;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      lastError = error;
-      if (attempt < maxRetries - 1) {
-        const delay = baseDelayMs * Math.pow(2, attempt) + Math.floor(Math.random() * 200);
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-  }
-  throw lastError;
-}
-/**
- * Rate limiter for GraphQL mutations
- */
-async function rateLimitedMutation(operation: () => Promise<any>, delayMs: number): Promise<any> {
-  const result = await operation();
-  await new Promise(resolve => setTimeout(resolve, delayMs));
-  return result;
-}
-// ============================================================================
-// Service Functions
-// ============================================================================
-/**
- * Service Function 1: Process File
- *
- * Downloads XML from S3, parses with XMLParserService, normalizes arrays,
- * and maps fields with GraphQLMutationMapper.
- *
- * @param s3 - S3DataSource instance
- * @param parser - XMLParserService instance
- * @param mapper - GraphQLMutationMapper instance
- * @param filePath - Full S3 path to file
- * @param fileName - File name only (for logging)
- * @param log - Logger instance
- * @returns FileProcessingResult with locations array and errors
- */
-async function processFile(
-  s3: S3DataSource,
-  parser: XMLParserService,
-  mapper: GraphQLMutationMapper,
-  filePath: string,
-  fileName: string,
-  log: any
-): Promise<FileProcessingResult> {
-  try {
-    log.info('Processing file', { fileName });
-    // Download with retry
-    const content = await retryWithBackoff(
-      () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
-    );
-    // Parse XML
-    const xmlData = await parser.parse(content);
-    // Extract location array (handle both single and multiple locations)
-    // CRITICAL: XML array normalization - single <location> becomes object, not array
-    const locationsData = xmlData.locations?.location;
-    const locationsArray = Array.isArray(locationsData) ? locationsData : [locationsData];
-    if (!locationsArray || locationsArray.length === 0) {
-      log.warn('Empty file (no locations)', { fileName });
-      return {
-        success: true,
-        locations: [],
-        errors: [],
-      };
-    }
-    // Map each location using GraphQLMutationMapper
-    const mappedLocations: Array<{ query: string; variables: any; input: any }> = [];
-    const mappingErrors: string[] = [];
-    // ✅ PRODUCTION ENHANCEMENT: Log transformation start
-    log.info('Transforming locations to GraphQL mutations', {
-      fileName,
-      totalLocations: locationsArray.length,
-    });
-    for (let i = 0; i < locationsArray.length; i++) {
-      const locationNumber = i + 1;
-      // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 locations
-      if (locationNumber % 50 === 0) {
-        log.info(`📤 Transforming location ${locationNumber}/${locationsArray.length}`, {
-          fileName,
-          locationNumber,
-          totalLocations: locationsArray.length,
-          validSoFar: mappedLocations.length,
-          errorsSoFar: mappingErrors.length,
-          progress: `${((locationNumber / locationsArray.length) * 100).toFixed(1)}%`,
-        });
-      }
-      // Wrap location in context for mapping
-      const record = { location: locationsArray[i] };
-      try {
-        // GraphQLMutationMapper returns { query, variables } directly
-        const mappingResult = await mapper.map(record);
-        mappedLocations.push({
-          query: mappingResult.query,
-          variables: mappingResult.variables,
-          input: mappingResult.variables.input || mappingResult.variables,
-        });
-      } catch (error: unknown) {
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        mappingErrors.push(`Location ${locationNumber}: ${errorMsg}`);
-        log.warn('Mapping failed for location', { fileName, index: i, error: errorMsg });
-      }
-    }
-    log.info('File processed', {
-      fileName,
-      total: locationsArray.length,
-      mapped: mappedLocations.length,
-      errors: mappingErrors.length,
-      successRate: `${((mappedLocations.length / locationsArray.length) * 100).toFixed(1)}%`,
-    });
-    return {
-      success: true,
-      locations: mappedLocations,
-      errors: mappingErrors,
-    };
-  } 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('File processing failed', errorDetails, { fileName });
-    return {
-      success: false,
-      locations: [],
-      errors: [error.message || 'Unknown error'],
-    };
-  }
-}
-/**
- * Service Function 2: Execute Mutations
- *
- * Executes GraphQL createLocation mutations with alias batching support.
- *
- * @param client - FluentClient instance
- * @param mapper - GraphQLMutationMapper instance
- * @param locations - Array of mapped location objects with query and variables
- * @param log - Logger instance
- * @param retailerId - Fluent retailer ID
- * @param batchSize - Number of concurrent requests (default: 1)
- * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (default: undefined)
- * @returns MutationResult with success/failure counts
- */
-async function executeMutations(
-  client: FluentClient,
-  mapper: GraphQLMutationMapper,
-  locations: Array<{ query: string; variables: any; input: any }>,
-  log: any,
-  retailerId: string,
-  batchSize: number = 1,  // ✅ Default: 1 (sequential)
-  mutationsPerAliasBatch?: number  // ✅ NEW: Alias batching parameter (default: undefined = disabled)
-): Promise<MutationResult> {
-  // Determine mode: use aliases if mutationsPerAliasBatch is set and > 1
-  const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
-  if (useAliases) {
-    return await executeMutationsWithAliases(
-      client,
-      mapper,
-      locations,
-      log,
-      retailerId,
-      batchSize,
-      mutationsPerAliasBatch!
-    );
-  } else {
-    return await executeMutationsSeparate(
-      client,
-      locations,
-      log,
-      batchSize
-    );
-  }
-}
-/**
- * Execute mutations using separate concurrent requests (current mode)
- */
-async function executeMutationsSeparate(
-  client: FluentClient,
-  locations: Array<{ query: string; variables: any; input: any }>,
-  log: any,
-  batchSize: number
-): Promise<MutationResult> {
-  const result: MutationResult = {
-    successful: 0,
-    failed: 0,
-    errors: [],
-  };
-  const safeConc = Math.max(1, Math.floor(batchSize));
-  // Sequential mode
-  if (safeConc === 1) {
-    for (const location of locations) {
-      try {
-        await retryWithBackoff(() =>
-          client.graphql({
-            query: location.query,
-            variables: location.variables,
-          })
-        );
-        result.successful++;
-      } catch (error: unknown) {
-        result.failed++;
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        result.errors.push(errorMsg);
-      }
-    }
-    return result;
-  }
-  // Parallel mode
-  for (let i = 0; i < locations.length; i += safeConc) {
-    const chunk = locations.slice(i, i + safeConc);
-    const results = await Promise.allSettled(
-      chunk.map(loc =>
-        retryWithBackoff(() =>
-          client.graphql({
-            query: loc.query,
-            variables: loc.variables,
-          })
-        )
-      )
-    );
-    results.forEach((settledResult, idx) => {
-      if (settledResult.status === 'fulfilled') {
-        result.successful++;
-      } else {
-        result.failed++;
-        result.errors.push(
-          settledResult.reason instanceof Error ? settledResult.reason.message : String(settledResult.reason)
-        );
-      }
-    });
-  }
-  return result;
-}
-/**
- * ✅ NEW: Execute mutations using GraphQL aliases (batched requests)
- */
-async function executeMutationsWithAliases(
-  client: FluentClient,
-  mapper: GraphQLMutationMapper,
-  locations: Array<{ query: string; variables: any; input: any }>,
-  log: any,
-  retailerId: string,
-  maxParallel: number,
-  mutationsPerAliasBatch: number
-): Promise<MutationResult> {
-  const result: MutationResult = { successful: 0, failed: 0, errors: [] };
-  const mutationName = (mapper as any).config.mutation || 'createLocation';
-  const aliasBatches: Array<Array<typeof locations[0]>> = [];
-  for (let i = 0; i < locations.length; i += mutationsPerAliasBatch) {
-    aliasBatches.push(locations.slice(i, i + mutationsPerAliasBatch));
-  }
-  // Process batches with concurrency control
-  for (let i = 0; i < aliasBatches.length; i += maxParallel) {
-    const concurrentBatches = aliasBatches.slice(i, i + maxParallel);
-    const batchResults = await Promise.allSettled(
-      concurrentBatches.map(async (batch) => {
-        const { query, variables } = buildAliasedBatch(batch, mutationName, retailerId);
-        const response = await retryWithBackoff(() => client.graphql({ query, variables }));
-        return parseAliasResponse(response, batch, mutationName);
-      })
-    );
-    batchResults.forEach((batchResult, idx) => {
-      if (batchResult.status === 'fulfilled') {
-        const batchRes = batchResult.value;
-        result.successful += batchRes.executed;
-        result.failed += batchRes.failed;
-        result.errors.push(...batchRes.errors);
-      } else {
-        const batch = concurrentBatches[idx];
-        const errorMsg = batchResult.reason instanceof Error ? batchResult.reason.message : String(batchResult.reason);
-        batch.forEach(loc => {
-          result.failed++;
-          result.errors.push(`Batch execution failed: ${errorMsg}`);
-        });
-      }
-    });
-    if (i + maxParallel < aliasBatches.length) {
-      await new Promise(resolve => setTimeout(resolve, 500));
-    }
-  }
-  return result;
-}
-/**
- * ✅ NEW: Build aliased batch query and variables
- */
-function buildAliasedBatch(
-  batch: Array<{ query: string; variables: any; input: any }>,
-  mutationName: string,
-  retailerId: string
-): { query: string; variables: Record<string, any> } {
-  const batchSize = batch.length;
-  const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
-  const variables = Array.from({ length: batchSize }, (_, i) =>
-    `$input${i + 1}: ${inputTypeName}!`
-  ).join(', ');
-  const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
-    const alias = `${mutationName}${i + 1}`;
-    return `  ${alias}: ${mutationName}(input: $input${i + 1}) { id ref name }`;
-  }).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((loc, index) => {
-    const input = loc.variables.input || loc.variables;
-    if (input && !input.retailer) {
-      input.retailer = { id: parseInt(retailerId) };
-    }
-    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((loc, index) => {
-    const alias = `${mutationName}${index + 1}`;
-    const aliasData = data[alias];
-    const aliasErrors = errors.filter((e: any) =>
-      e.path && Array.isArray(e.path) && e.path.includes(alias)
-    );
-    if (aliasData && !aliasErrors.length) {
-      result.executed++;
-    } else {
-      result.failed++;
-      const errorMsg = aliasErrors[0]?.message || 'Mutation failed';
-      result.errors.push(`${loc.input?.ref || 'unknown'}: ${errorMsg}`);
-    }
-  });
-  return result;
-}
-/**
- * Service Function 3: Write Mutation Log
- *
- * Writes mutation results to S3 as a JSON log file.
- *
- * @param s3 - S3DataSource instance
- * @param logEntries - Array of mutation log entries
- * @param fileName - Original file name (used to generate log path)
- * @param logPrefix - S3 prefix for logs (e.g., 'logs/')
- * @param log - Logger instance
- */
-async function writeMutationLog(
-  s3: S3DataSource,
-  logEntries: MutationLogEntry[],
-  fileName: string,
-  logPrefix: string,
-  log: any
-): Promise<void> {
-  try {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const logFileName = `${logPrefix}${fileName.replace('.xml', '')}_${timestamp}.json`;
-    const logContent = JSON.stringify(
-      {
-        fileName,
-        timestamp: new Date().toISOString(),
-        totalMutations: logEntries.length,
-        successful: logEntries.filter(e => e.status === 'success').length,
-        failed: logEntries.filter(e => e.status === 'failure').length,
-        entries: logEntries,
-      },
-      null,
-      2
-    );
-    // Write to S3 (uploadFile accepts string or Buffer)
-    await s3.uploadFile(logFileName, logContent);
-    log.info('Mutation log written', { logFileName, entries: logEntries.length });
-  } catch (error: any) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorDetails = {
-      message: error?.message || 'Unknown error',
-      stack: error?.stack,
-      errorType: error?.name || 'Error',
-    };
-    log.error('Failed to write mutation log', errorDetails, { fileName });
-    // Don't throw - logging failure shouldn't stop workflow
-  }
-}
-// ============================================================================
-// Main Workflow Function
-// ============================================================================
-/**
- * Main Orchestration Function: Execute Location Sync
- *
- * This function orchestrates the location synchronization workflow.
- *
- * Architecture:
- * 1. List files from S3
- * 2. For each file:
- *    a. processFile() - Download, parse, map
- *    b. executeMutations() - Send GraphQL mutations with rate limiting
- *    c. writeMutationLog() - Log results to S3
- *    d. Archive file (primary deduplication)
- *    e. Mark processed in KV (metadata tracking)
- *
- * @param ctx - Versori context
- * @param jobId - Job identifier
- * @param tracker - JobTracker instance
- * @returns Processing result
- */
-export async function executeLocationSync(ctx: any, jobId: string, tracker: JobTracker) {
-  const { log, activation } = ctx;
-  log.info('📋 [INIT] Reading activation variables', { jobId });
-  // Read activation variables
-  const s3Bucket = activation?.getVariable('s3BucketName');
-  const s3Region = activation?.getVariable('awsRegion') || 'us-east-1';
-  const s3AccessKeyId = activation?.getVariable('awsAccessKeyId');
-  const s3SecretAccessKey = activation?.getVariable('awsSecretAccessKey');
-  const s3Prefix = activation?.getVariable('s3Prefix') || 'locations/';
-  const archivePrefix = activation?.getVariable('archivePrefix') || 'processed/';
-  const errorPrefix = activation?.getVariable('errorPrefix') || 'errors/';
-  const logPrefix = activation?.getVariable('logPrefix') || 'logs/';
-  const filePattern = (activation?.getVariable('filePattern') || '.xml').toLowerCase();
-  const maxFiles = parseInt(activation?.getVariable('maxFilesToProcess') || '10', 10);
-  const retailerId = activation?.getVariable('retailerId');  // Optional: Only if mutation schema requires it
-  const enableArchival = activation?.getVariable('enableArchival') !== 'false';
-  const enableMutationLogs = activation?.getVariable('enableMutationLogs') !== 'false';
-  const enableFileTracking = activation?.getVariable('enableFileTracking') !== 'false';
-  // ✅ Configuration with defaults
-  const mutationBatchSize = parseInt(
-    activation?.getVariable('mutationBatchSize') || '1',  // ✅ Default: 1 (sequential)
-    10
-  );
-  const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
-    ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
-    : undefined;  // ✅ Default: undefined (disabled, use separate requests)
-  // Validate required variables
-  const missingVars: string[] = [];
-  if (!s3Bucket) missingVars.push('s3BucketName');
-  if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
-  if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
-  // Note: retailerId is optional - only needed if mutation schema requires it
-  if (missingVars.length > 0) {
-    const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
-    log.error('❌ [VALIDATION] Missing required activation variables', {
-      missingVars,
-      recommendation: 'Add missing variables in Versori activation settings'
-    });
-    return { success: false, error: errorMsg, processed: 0 };
-  }
-  log.info('✅ [VALIDATION] All required variables present', {
-    s3Bucket,
-    s3Region,
-    s3Prefix,
-    enableFileTracking,
-    mutationBatchSize
-  });
-  try {
-    log.info('🔧 [INIT] Initializing Fluent Commerce client', { jobId });
-    // Initialize services with validateConnection
-    const client = await createClient(ctx, { validateConnection: true });
-    if (!client) {
-      throw new Error('Failed to create Fluent Commerce client');
-    }
-    log.info('✅ [INIT] Fluent Commerce client validated and ready', { jobId });
-    // ✅ CORRECT: GraphQL mutations do NOT need client.setRetailerId()
-    // setRetailerId() is only for Job/Event API, NOT GraphQL
-    // 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('🗄️ [INIT] Initializing S3 data source', { s3Bucket, s3Region, s3Prefix });
-    const s3 = new S3DataSource(
-      {
-        type: 'S3_XML',
-        connectionId: 's3-location-sync',
-        name: 'Source S3',
-        s3Config: {
-          bucket: s3Bucket,
-          region: s3Region,
-          accessKeyId: s3AccessKeyId,
-          secretAccessKey: s3SecretAccessKey,
-        },
-      },
-      log
-    );
-    const parser = new XMLParserService();
-    // Initialize state tracking (only if enabled)
-    let stateService: StateService | null = null;
-    if (enableFileTracking) {
-      log.info('🔄 [INIT] Enabling file tracking with StateService', { jobId });
-      const stateKV = new VersoriKVAdapter(ctx);
-      stateService = new StateService(stateKV);
-    } else {
-      log.info('⏭️ [INIT] File tracking disabled - relying on S3 archival only', { jobId });
-    }
-    log.info('📝 [INIT] Loading mapping configuration', { jobId });
-    // ✅ CRITICAL: Load mapping config from external JSON file
-    // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
-    // File: src/config/location-mapping.json
-    const mappingConfigJson = await import('../config/location-mapping.json', { assert: { type: 'json' } });
-    const mappingConfig = mappingConfigJson.default;
-    // Initialize GraphQLMutationMapper with client for schema introspection
-    const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-    log.info('📂 [S3] Listing files from S3', { s3Bucket, s3Prefix, filePattern });
-    // List files (pattern filtering handled by listFiles)
-    const files = await s3.listFiles({
-      prefix: s3Prefix,
-      pattern: filePattern,
-      maxKeys: 1000
-    });
-    // Newest-first ordering
-    const xmlFiles = files
-      .sort((a: any, b: any) => {
-        const aTime = a.lastModified ? new Date(a.lastModified).getTime() : 0;
-        const bTime = b.lastModified ? new Date(b.lastModified).getTime() : 0;
-        return bTime - aTime;
-      })
-      .slice(0, maxFiles);
-    log.info('📊 [S3] File discovery complete', {
-      totalFiles: files.length,
-      xmlFiles: xmlFiles.length,
-      maxFiles,
-      selectedFiles: xmlFiles.map(f => f.name)
-    });
-    const results = {
-      processed: 0,
-      skipped: 0,
-      failed: 0,
-      totalRecords: 0,
-      errors: [] as string[],
-    };
-    log.info('🔄 [PROCESSING] Starting file processing loop', {
-      fileCount: xmlFiles.length,
-      jobId
-    });
-    // Per-file processing loop
-    for (const file of xmlFiles) {
-      const filePath = file.path;
-      const fileName = file.name;
-      log.info('📄 [FILE] Processing file', { fileName, filePath });
-      // Duplicate prevention (secondary check - files in processed/ won't be listed)
-      // Primary deduplication: S3 archival (files moved to processed/ subdirectory)
-      if (enableFileTracking && stateService) {
-        const wasProcessed = await stateService.isFileProcessed(fileName);
-        if (wasProcessed) {
-          log.info('⏭️ [SKIP] File already processed (KV check)', { fileName });
-          results.skipped++;
-          continue;
-        }
-      }
-      try {
-        // Step 1: Process file (download, parse, map)
-        log.info('📥 [DOWNLOAD] Downloading and parsing file', { fileName });
-        const processingResult = await processFile(s3, parser, mapper, filePath, fileName, log);
-        if (!processingResult.success) {
-          throw new Error(`File processing failed: ${processingResult.errors.join(', ')}`);
-        }
-        if (processingResult.locations.length === 0) {
-          log.warn('⚠️ [SKIP] Empty file detected, archiving', { fileName });
-          if (enableArchival) {
-            await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-            log.info('📦 [ARCHIVE] Empty file archived', { fileName, destination: `${archivePrefix}${fileName}` });
-          }
-          results.skipped++;
-          continue;
-        }
-        log.info('✅ [PARSE] File parsed successfully', {
-          fileName,
-          locationCount: processingResult.locations.length,
-          mappingErrors: processingResult.errors.length
-        });
-        // Step 2: Execute mutations
-        // Step 2: Execute mutations with alias batching support
-        // ? Enhanced: Extract context for progress logging
-        const sampleLocationRefs = processingResult.locations.slice(0, 5).map((loc: any) => loc.input?.ref || loc.ref || 'unknown');
-        const mutationType = mapper?.mutationName || 'createLocation';
-        // ? Enhanced: Start logging with context
-        log.info(`[GraphQLMutations] Sending mutations for file "${fileName}"`, {
-         totalMutations: processingResult.locations.length,
-         mutationType,
-         batchSize: mutationBatchSize,
-         batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
-         sampleLocationRefs: sampleLocationRefs.join(', '),
-         aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled'
-        });
-        const mutationResult = await executeMutations(
-          client,
-          mapper,
-          processingResult.locations,
-          log,
-          retailerId,  // Pass retailerId for mutations that require it in input
-          mutationBatchSize,  // Concurrency control (default: 1)
-          mutationsPerAliasBatch  // ✅ NEW: Alias batching (default: undefined)
-        );
-        // ? Enhanced: Completion logging with summary
-        log.info(`[GraphQLMutations] Mutation submission completed for file "${fileName}"`, {
-         totalMutations: processingResult.locations.length,
-         successful: mutationResult.successful,
-         failed: mutationResult.failed,
-         successRate: processingResult.locations.length > 0 ? `${Math.round((mutationResult.successful / processingResult.locations.length) * 100)}%` : '0%',
-         mutationType
-        });
-        // Step 3: Write mutation log (if enabled)
-        if (enableMutationLogs) {
-          const logEntries: MutationLogEntry[] = processingResult.locations.map(loc => {
-            const failed = mutationResult.errors.find(e => e.startsWith(loc.ref));
-            return {
-              timestamp: new Date().toISOString(),
-              fileName,
-              locationRef: loc.ref,
-              status: failed ? 'failure' : 'success',
-              error: failed,
-            };
-          });
-          await writeMutationLog(s3, logEntries, fileName, logPrefix, log);
-        }
-        // Step 4: Archive file (PRIMARY deduplication - file won't be listed again)
-        if (enableArchival) {
-          log.info('📦 [ARCHIVE] Moving file to processed directory', { fileName });
-          await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
-          log.info('✅ [ARCHIVE] File archived successfully', {
-            fileName,
-            destination: `${archivePrefix}${fileName}`
-          });
-        }
-        // Step 5: Mark processed in KV (SECONDARY - provides metadata/history)
-        if (enableFileTracking && stateService) {
-          log.info('💾 [STATE] Recording file processing metadata', { fileName });
-          await stateService.markFileProcessed(fileName, {
-            recordCount: processingResult.locations.length,
-            successful: mutationResult.successful,
-            failed: mutationResult.failed,
-            mappingErrors: processingResult.errors.length,
-            timestamp: new Date().toISOString(),
-          });
-        }
-        results.processed++;
-        results.totalRecords += mutationResult.successful;
-        log.info('✅ [COMPLETE] File processing complete', {
-          fileName,
-          locations: processingResult.locations.length,
-          successful: mutationResult.successful,
-          failed: mutationResult.failed,
-          mappingErrors: processingResult.errors.length,
-        });
-        if (processingResult.errors.length > 0 || mutationResult.errors.length > 0) {
-          results.errors.push(
-            `${fileName}: ${processingResult.errors.length} mapping errors, ${mutationResult.errors.length} mutation errors`
-          );
-        }
-      } 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('❌ [ERROR] File processing failed', errorDetails, { fileName });
-        // Provide error recommendations based on error type
-        const recommendation = getErrorRecommendation(error);
-        if (recommendation) {
-          log.warn('💡 [RECOMMENDATION]', { fileName, recommendation });
-        }
-        results.failed++;
-        results.errors.push(`${fileName}: ${error.message}`);
-        // Attempt to move to error directory, ignore failures
-        try {
-          log.info('🗂️ [ERROR] Moving failed file to error directory', { fileName });
-          await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
-          log.info('✅ [ERROR] Failed file moved to error directory', {
-            fileName,
-            destination: `${errorPrefix}${fileName}`
-          });
-        } catch (moveError) {
-          log.warn('⚠️ [ERROR] Failed to move file to error directory', {
-            fileName,
-            moveError: moveError instanceof Error ? moveError.message : String(moveError)
-          });
-        }
-        // Track error state with exponential backoff (only if file tracking enabled)
-        if (enableFileTracking && stateService) {
-          try {
-            const stateKV = new VersoriKVAdapter(ctx);
-            const key = ['error-state', fileName];
-            const prev = (await stateKV.get(key))?.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 stateKV.set(key, {
-              fileName,
-              attemptCount: attempts,
-              lastError: error?.message || 'unknown',
-              lastAttemptAt: new Date().toISOString(),
-              firstFailedAt: prev?.firstFailedAt || new Date().toISOString(),
-              nextRetryAt,
-            });
-            log.info('💾 [ERROR] Error state tracked with exponential backoff', {
-              fileName,
-              attempts,
-              nextRetryAt
-            });
-          } catch (stateError) {
-            log.warn('⚠️ [ERROR] Failed to track error state', {
-              fileName,
-              stateError: stateError instanceof Error ? stateError.message : String(stateError)
-            });
-          }
-        }
-      }
-    }
-    log.info('🏁 [COMPLETE] File processing loop finished', {
-      processed: results.processed,
-      skipped: results.skipped,
-      failed: results.failed,
-      totalRecords: results.totalRecords
-    });
-    return results;
-  } catch (error: any) {
-    // ✅ Enhanced error logging: Extract all error details for visibility
-    const errorDetails = {
-      message: error?.message || 'Unknown error',
-      stack: error?.stack,
-      errorType: error?.name || 'Error',
-    };
-    log.error('❌ [FATAL] Location sync failed', errorDetails);
-    // Provide fatal error recommendations
-    const recommendation = getErrorRecommendation(error);
-    if (recommendation) {
-      log.warn('💡 [RECOMMENDATION]', { recommendation });
-    }
-    return {
-      success: false,
-      error: error.message,
-      processed: 0,
-      timestamp: new Date().toISOString(),
-    };
-  }
-}
-/**
- * Get error recommendation based on error type
- */
-function getErrorRecommendation(error: any): string | null {
-  const message = error?.message?.toLowerCase() || '';
-  if (message.includes('s3') || message.includes('access denied')) {
-    return 'Check S3 credentials and bucket permissions. Verify IAM policy includes s3:ListBucket, s3:GetObject, s3:PutObject, s3:DeleteObject.';
-  }
-  if (message.includes('xml') || message.includes('parse')) {
-    return 'Verify XML file structure matches expected schema. Check for malformed XML or encoding issues.';
-  }
-  if (message.includes('mapping') || message.includes('field')) {
-    return 'Review field mapping configuration. Ensure all required fields are present and source paths are correct.';
-  }
-  if (message.includes('graphql') || message.includes('mutation')) {
-    return 'Check GraphQL schema and mutation input. Verify all required fields are provided and types match schema.';
-  }
-  if (message.includes('auth') || message.includes('401') || message.includes('403')) {
-    return 'Verify Fluent Commerce credentials. Check OAuth2 client ID/secret and ensure connection is active.';
-  }
-  if (message.includes('timeout') || message.includes('econnrefused')) {
-    return 'Check network connectivity. Verify API endpoints are accessible and not rate-limited.';
-  }
-  return null;
-}
-```
-**Note:** The `executeLocationSync` function should contain the full implementation of `runLocationXmlWorkflow` (renamed to `executeLocationSync`), including all the logic for processing files, executing mutations, and logging. The implementation details are shown in the service function code above.
----
-### Step 5: TypeScript Configuration
-**File: tsconfig.json**
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
----
-## Code Flow Explanation
-### Initialization Phase
-1. **Read activation variables** - S3 config, Fluent config, rate limiting, logging options
-2. **Validate required variables** - Fail fast if missing credentials
-3. **Initialize SDK services** - FluentClient, S3DataSource, XMLParserService, StateService
-4. **Create mapping configuration** - Define XML → GraphQL field mappings with nested objects
-5. **Calculate rate limit delay** - Convert mutations/second to delay in milliseconds
-### File Discovery Phase
-1. **List S3 files** - Use `s3.listFiles()` with prefix filter (excludes processed/ subdirectory)
-2. **Filter by pattern** - Match file extension (e.g., `.xml`)
-3. **Sort newest-first** - Process most recent files first
-4. **Apply max files limit** - Prevent overwhelming the workflow
-5. **Note**: Files in `processed/` subdirectory won't be listed (primary deduplication)
-### Per-File Processing (Service Functions)
-**Step 1: processFile()** - Download, parse, map
-1. **Download file** - Use S3DataSource with retry logic
-2. **Parse XML** - XMLParserService converts to JavaScript object
-3. **Normalize array** - Handle single vs multiple `<location>` elements (CRITICAL for XML)
-4. **Map locations** - Use UniversalMapper with nested field mapping
-5. **Collect errors** - Track mapping errors without stopping
-6. **Return result** - FileProcessingResult with locations array and errors
-**Step 2: executeMutations()** - GraphQL mutations with rate limiting
-1. **Loop through locations** - Process each location individually
-2. **Build mutation input** - Extract nested fields (primaryAddress, openingSchedule)
-3. **Execute mutation** - Direct GraphQL `createLocation` with retry logic
-4. **Apply rate limiting** - Add configurable delay between mutations
-5. **Track results** - Count successful vs failed, collect error messages
-6. **Return result** - MutationResult with counts and errors
-**Step 3: writeMutationLog()** - S3 log file (optional)
-1. **Create log entries** - Map locations to log entries with status
-2. **Build JSON log** - Include timestamp, summary, detailed entries
-3. **Write to S3** - Use Buffer.from() for Deno/Versori runtime compatibility
-4. **Non-blocking** - Logging failure doesn't stop workflow
-5. **Timestamped naming** - Unique log file per processed file
-### Cleanup Phase
-1. **Archive file FIRST** - Move to `processed/` or `errors/` (PRIMARY deduplication)
-2. **Mark processed in KV** - StateService tracks metadata and processing history
-3. **Error state tracking** - Store error info with exponential backoff timestamp
-4. **Return results** - Summary of processed, skipped, failed files
-**Note**: The order matters! Archive first (primary deduplication), then KV tracking (metadata/history).
-### Service Function Benefits
-- **Composability**: Each function has single responsibility and can be reused
-- **Testability**: Service functions can be unit tested independently
-- **Clarity**: Main workflow shows high-level orchestration
-- **Error Handling**: Isolated error handling per service function
-- **Logging**: Detailed logging at each step with structured context
----
-## S3 Archival Deduplication Pattern
-This template uses **S3 archival** as the primary deduplication mechanism, NOT VersoriFileTracker.
-### How It Works
-**S3 Directory Structure:**
-```
-s3://my-bucket/
-├── locations/           ← listFiles() reads from here
-│   ├── new-file-1.xml
-│   └── new-file-2.xml
-├── processed/           ← Successfully processed files
-│   ├── old-file-1.xml
-│   └── old-file-2.xml
-└── errors/              ← Failed files
-    └── bad-file.xml
-```
-**Deduplication Flow:**
-1. **List files**: `s3.listFiles({ prefix: 'locations/' })` - Only lists `locations/` subdirectory
-2. **Process file**: Download, parse, transform, send mutations
-3. **Archive**: `s3.moveFile(filePath, 'processed/new-file-1.xml')` - Moves file out of `locations/`
-4. **Next run**: File is now in `processed/`, won't be listed again
-**Why This Works:**
-- Files in `processed/` subdirectory are **never listed** when prefix is `locations/`
-- No need to track file state in KV store for deduplication
-- S3 is the single source of truth for file status
-- Simple, reliable, scales to millions of files
-**StateService Role (Secondary):**
-- Provides metadata and processing history
-- Backup check in case archival fails mid-process
-- Useful for monitoring and debugging
-- NOT the primary deduplication mechanism
-**When to Use VersoriFileTracker:**
-- **NEVER for S3 sources** - Use archival pattern instead
-- **Only for SFTP sources** - Where archival might not be possible
-- See SFTP templates for VersoriFileTracker usage
----
-## XML Path Resolution Patterns
-### Pattern 1: XML Attribute Access with @ Prefix
-```typescript
-const mappingConfig = {
-  fields: {
-    // XML attribute access
-    ref: { source: 'location.@ref' }, // <location ref="LOC-001">
-    type: { source: 'location.@type' }, // <location type="WAREHOUSE">
-    country: { source: 'location.address.@country' }, // <address country="USA">
-    // XML element text content
-    name: { source: 'location.name' }, // <name>Downtown</name>
-    city: { source: 'location.address.city' }, // <address><city>NYC</city></address>
-  },
-};
-```
-### Pattern 2: Handling Single vs Multiple Elements
-```typescript
-// XML can have single or multiple <location> elements
-const locationsData = xmlData.locations?.location;
-// Normalize to array
-const locations = Array.isArray(locationsData) ? locationsData : [locationsData];
-// Process each location
-for (const loc of locations) {
-  const record = { location: loc }; // Wrap for mapping
-  const result = await mapper.map(record);
-}
-```
-### Pattern 3: Nested Object Mapping
-```typescript
-const mappingConfig = {
-  fields: {
-    // Root fields
-    ref: { source: 'location.@ref', required: true },
-    name: { source: 'location.name', required: true },
-    type: { source: 'location.@type', required: true },
-    // Nested primaryAddress object
-    'primaryAddress.ref': { source: 'location.@ref' },
-    'primaryAddress.street': { source: 'location.address.street1' },
-    'primaryAddress.city': { source: 'location.address.city' },
-    'primaryAddress.latitude': { source: 'location.coordinates.@lat', resolver: 'sdk.parseFloat' },
-    // Nested openingSchedule object
-    'openingSchedule.allHours': {
-      source: 'location.openingSchedule.allHours',
-      resolver: 'sdk.boolean',
-    },
-    'openingSchedule.monStart': {
-      source: 'location.openingSchedule.monStart',
-      resolver: 'sdk.parseInt',
-    },
-    // Note: retailer.id not shown - standard createLocation does not have this field
-    // If your schema requires it, add: 'retailer.id': { value: parseInt(retailerId) }
-  },
-};
-```
----
-## Sample XML Files
-### Minimal Test File
-**File: test-location.xml**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<locations>
-  <location ref="TEST-001" type="WAREHOUSE">
-    <name>Test Warehouse</name>
-    <address country="USA">
-      <street1>123 Test St</street1>
-      <city>TestCity</city>
-      <state>TC</state>
-      <postalCode>12345</postalCode>
-    </address>
-    <coordinates lat="40.7128" lon="-74.0060"/>
-    <timeZone>America/New_York</timeZone>
-    <openingSchedule>
-      <allHours>false</allHours>
-      <monStart>800</monStart>
-      <monEnd>1800</monEnd>
-      <tueStart>800</tueStart>
-      <tueEnd>1800</tueEnd>
-      <wedStart>800</wedStart>
-      <wedEnd>1800</wedEnd>
-      <thuStart>800</thuStart>
-      <thuEnd>1800</thuEnd>
-      <friStart>800</friStart>
-      <friEnd>1800</friEnd>
-      <satStart>0</satStart>
-      <satEnd>0</satEnd>
-      <sunStart>0</sunStart>
-      <sunEnd>0</sunEnd>
-    </openingSchedule>
-  </location>
-</locations>
-```
----
-## Service Functions Deep Dive
-This template demonstrates service function composition for maintainable workflows.
-### Function 1: processFile()
-**Purpose**: Download, parse, normalize, and map XML data
-**Inputs**:
-- `s3: S3DataSource` - For file download
-- `parser: XMLParserService` - For XML parsing
-- `mapper: UniversalMapper` - For field mapping
-- `filePath: string` - S3 path to file
-- `fileName: string` - File name for logging
-- `log: any` - Logger instance
-**Outputs**: `FileProcessingResult`
-```typescript
-{
-  success: boolean;      // Overall success
-  locations: any[];      // Mapped location objects
-  errors: string[];      // Mapping error messages
-}
-```
-**Key Operations**:
-1. Downloads file with retry logic
-2. Parses XML using XMLParserService
-3. **Normalizes arrays** - Handles single vs multiple `<location>` elements
-4. Maps each location using UniversalMapper
-5. Collects errors without stopping processing
-6. Returns all mapped locations + errors
-**Why separate function?**
-- Testable independently with mock data
-- Reusable across workflows (scheduled, webhook, adhoc)
-- Clear error boundaries - file-level errors vs record-level errors
-- Easy to add XML validation or schema checks
-### Function 2: executeMutations()
-**Purpose**: Execute GraphQL createLocation mutations with rate limiting
-**Inputs**:
-- `client: FluentClient` - For GraphQL mutations
-- `locations: any[]` - Mapped location data
-- `mutationDelayMs: number` - Rate limit delay
-- `fileName: string` - For logging context
-- `log: any` - Logger instance
-**Outputs**: `MutationResult`
-```typescript
-{
-  successful: number;    // Count of successful mutations
-  failed: number;        // Count of failed mutations
-  errors: string[];      // Error messages with location refs
-}
-```
-**Key Operations**:
-1. Loops through locations
-2. Builds GraphQL mutation input
-3. Executes with retry logic + rate limiting
-4. Tracks success/failure per location
-5. Returns summary counts + errors
-**Why separate function?**
-- Clear separation: mapping vs mutation execution
-- Rate limiting logic isolated and configurable
-- Easy to swap mutation types (create vs update)
-- Testable with mock FluentClient
-- Can parallelize in future (batch mutations)
-### Function 3: writeMutationLog()
-**Purpose**: Write detailed mutation results to S3 as JSON log
-**Inputs**:
-- `s3: S3DataSource` - For log upload
-- `logEntries: MutationLogEntry[]` - Mutation status per location
-- `fileName: string` - Original file name
-- `logPrefix: string` - S3 prefix for logs (e.g., `logs/`)
-- `log: any` - Logger instance
-**Outputs**: `void` (non-blocking - errors logged but not thrown)
-**Key Operations**:
-1. Creates timestamped log file name
-2. Builds JSON log with summary + entries
-3. **Uses Buffer.from()** - Required for Deno/Versori runtime
-4. Writes to S3 with `uploadFile()`
-5. Errors don't stop workflow (logging is non-critical)
-**Why separate function?**
-- Optional feature - can be disabled via config
-- Non-blocking - logging failure doesn't fail workflow
-- Structured logging for audit trails
-- Easy to change log format (JSON, CSV, XML)
-- Can add log rotation/cleanup logic later
-### Service Function Composition Benefits
-**1. Maintainability**
-```typescript
-// Clear workflow orchestration
-const processingResult = await processFile(...);
-const mutationResult = await executeMutations(...);
-await writeMutationLog(...);
-```
-**2. Testability**
-```typescript
-// Unit test processFile() with mock XML
-const mockS3 = { downloadFile: jest.fn() };
-const result = await processFile(mockS3, parser, mapper, ...);
-expect(result.locations).toHaveLength(5);
-```
-**3. Reusability**
-```typescript
-// Use processFile() in different workflows
-export const webhook = webhook('location-webhook').then(async ctx => {
-  const result = await processFile(s3, parser, mapper, filePath, fileName, log);
-  return { locations: result.locations };
-});
-```
-**4. Error Isolation**
-```typescript
-// Each function has clear error boundaries
-try {
-  const processingResult = await processFile(...);
-  // File-level errors caught here
-} catch (error) {
-  // Handle file processing failure
-}
-// Mutation errors don't stop file processing
-const mutationResult = await executeMutations(...);
-// mutationResult.errors contains per-location failures
-```
-**5. Progressive Enhancement**
-```typescript
-// Easy to add features without touching core logic
-async function validateLocations(locations: any[]) {
-  // Add validation step
-}
-const processingResult = await processFile(...);
-await validateLocations(processingResult.locations);  // New step
-const mutationResult = await executeMutations(...);
-```
----
-## Versori Environment Variables
-**Activation Variables:**
-```bash
-# ============================================================================
-# Required Variables
-# ============================================================================
-s3BucketName=my-location-bucket
-awsAccessKeyId=AKIAXXXXXXXXXXXX
-awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-# ============================================================================
-# S3 Configuration (Optional - with defaults)
-# ============================================================================
-awsRegion=us-east-1
-s3Prefix=locations/
-archivePrefix=processed/
-errorPrefix=errors/
-logPrefix=logs/
-filePattern=.xml
-maxFilesToProcess=10
-# ============================================================================
-# Feature Toggles (Optional - with defaults)
-# ============================================================================
-# Enable S3 archival (move files to processed/errors directories)
-enableArchival=true
-# Enable mutation logs (write detailed mutation results to S3)
-enableMutationLogs=true
-# Enable file tracking via StateService + KV store
-# When disabled, relies on S3 archival only for deduplication
-enableFileTracking=true
-# ============================================================================
-# Mutation Configuration (Optional - with defaults)
-# ============================================================================
-# Mutation batch size (concurrent requests)
-# - 1 = Sequential (default, safest)
-# - 5 = Process 5 mutations in parallel
-# - 10 = Process 10 mutations in parallel
-mutationBatchSize=1
-# Alias batching (combine multiple mutations into single request)
-# - undefined = Disabled (default, use separate requests)
-# - 5 = Combine 5 mutations per aliased request
-# - 10 = Combine 10 mutations per aliased request
-mutationsPerAliasBatch=
-# ============================================================================
-# Fluent Commerce Configuration (Optional)
-# ============================================================================
-# Retailer ID - Only if mutation schema requires retailerId in input
-# Standard createLocation does NOT require this field
-# Check your GraphQL schema to determine if needed
-retailerId=my-retailer-id
-```
-**Notes:**
-- Webhook security is handled by Versori's native connection authentication. No manual API key configuration needed.
-- `retailerId` - Standard createLocation does not have this field. Only use if YOUR custom schema requires it.
-- See `fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md` for details.
----
-## Schema Validation CLI Commands
-Before deploying, validate your field mappings against the Fluent GraphQL schema:
-### 1. Introspect Schema
-```bash
-# Generate schema.json from live Fluent API
-npx fc-connect introspect-schema \
-  --url https://api.fluentcommerce.com/graphql \
-  --client-id your-client-id \
-  --client-secret your-client-secret \
-  --output schema.json
-```
-### 2. Create Mapping Config File
-**File: location-mapping.json**
-```json
-{
-  "version": "1.0.0",
-  "mutation": "createLocation",
-  "sourceFormat": "xml",
-  "returnFields": ["id", "ref", "name", "type", "status"],
-  "description": "XML location to Fluent Commerce GraphQL mapping",
-  "fields": {
-    "ref": { "source": "location.@ref", "required": true, "resolver": "sdk.trim" },
-    "name": { "source": "location.name", "required": true, "resolver": "sdk.trim" },
-    "type": { "source": "location.@type", "required": true, "resolver": "sdk.uppercase" },
-    "primaryAddress.ref": { "source": "location.@ref", "required": true },
-    "primaryAddress.street": { "source": "location.address.street1" },
-    "primaryAddress.latitude": {
-      "source": "location.coordinates.@lat",
-      "resolver": "sdk.parseFloat"
-    },
-    "primaryAddress.longitude": {
-      "source": "location.coordinates.@lon",
-      "resolver": "sdk.parseFloat"
-    }
-  }
-}
-```
-### 3. Validate Mapping
-```bash
-# Validate that all target fields exist in schema
-npx fc-connect validate-schema \
-  --mapping location-mapping.json \
-  --schema schema.json
-```
-### 4. Analyze Coverage
-```bash
-# Check which Location fields are mapped vs available
-npx fc-connect analyze-coverage \
-  --mapping location-mapping.json \
-  --schema schema.json \
-  --type CreateLocationInput
-```
-**Output:**
-```
-✅ Mapped: 15/42 fields (35%)
-❌ Missing required: timezone (String!)
-⚠️  Optional unmapped: supportPhoneNumber, networkId, attributes
-```
----
-## Testing Locally
-### 1. Upload Test XML to S3
-```bash
-aws s3 cp test-location.xml s3://my-location-bucket/locations/test-location.xml
-```
-### 2. Deploy to Versori
-```bash
-npm run deploy
-```
-### 3. Manual Testing
-```bash
-# Trigger manual sync (auth handled by Versori connection)
-curl -X POST https://your-workspace.versori.run/location-xml-adhoc
-# Check job status
-curl -X POST https://your-workspace.versori.run/location-xml-job-status \
-  -H "Content-Type: application/json" \
-  -d '{"jobId": "location-xml-adhoc-1737525600000"}'
-```
-### 4. Verify Processing
-- Upload a small XML to S3 (2-3 locations) and trigger `adhoc` webhook
-- Verify GraphQL mutations are executed for each location
-- Confirm file moved from `locations/` to `processed/` in S3
-- Check KV state: errors and last processed metadata
-- Monitor rate limiting: verify mutations respect configured rate
----
-## Deployment
-```bash
-# Deploy to Versori
-npm run deploy
-# View logs
-npm run logs
-# Monitor execution
-versori logs --follow
-```
----
-## Monitoring
-### Success Response
-```json
-{
-  "success": true,
-  "jobId": "location-xml-scheduled-1737525600000",
-  "processed": 3,
-  "skipped": 0,
-  "failed": 0,
-  "totalRecords": 12,
-  "errors": []
-}
-```
-### Partial Success Response
-```json
-{
-  "success": true,
-  "jobId": "location-xml-scheduled-1737525600000",
-  "processed": 3,
-  "skipped": 1,
-  "failed": 0,
-  "totalRecords": 10,
-  "errors": ["locations-003.xml: 2 mapping errors"]
-}
-```
-### Error Response
-```json
-{
-  "success": false,
-  "jobId": "location-xml-scheduled-1737525600000",
-  "processed": 0,
-  "skipped": 0,
-  "failed": 1,
-  "totalRecords": 0,
-  "errors": ["locations-001.xml: Invalid XML structure"]
-}
-```
----
-## Common Pitfalls and Solutions
-### 1. XML Attribute Not Found
-**Symptoms**: Mapping errors like "field not found"
-**Solution**:
-```typescript
-// ❌ WRONG - Missing @ prefix for attribute
-ref: {
-  source: 'location.ref';
-}
-// ✅ CORRECT - Use @ prefix for XML attributes
-ref: {
-  source: 'location.@ref';
-}
-```
-### 2. Single Element Not Array
-**Symptoms**: "Cannot read property forEach of undefined"
-**Solution**:
-```typescript
-// Always normalize to array
-const locationsData = xmlData.locations?.location;
-const locations = Array.isArray(locationsData) ? locationsData : [locationsData];
-```
-### 3. Rate Limiting Too Aggressive
-**Symptoms**: Slow processing, mutations taking too long
-**Solution**:
-```bash
-# Increase rate limit (mutations per second)
-mutationRateLimit=10  # Default is 5
-```
-### 4. Empty Element vs Missing Element
-**Solution**:
-```typescript
-// Use required: false and defaultValue for optional fields
-'primaryAddress.street2': {
-  source: 'location.address.street2',
-  required: false,
-  defaultValue: ''
-}
-```
-### 5. S3 Access Denied
-**Symptoms**: S3 operations fail with 403 errors
-**Solution**: Validate IAM permissions
-**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-location-bucket", "arn:aws:s3:::my-location-bucket/*"]
-    }
-  ]
-}
-```
-### 6. GraphQL Schema Mismatch
-**Symptoms**: Mutation errors like "Unknown field", "Invalid input type"
-**Solution**: Use CLI tools to validate mappings
-```bash
-npx fc-connect validate-schema --mapping location-mapping.json --schema schema.json
-```
-### 7. Nested Object Mapping Errors
-**Symptoms**: Flat structure instead of nested objects in mutation input
-**Solution**: Use dot notation in field mapping
-```typescript
-// ✅ CORRECT - Creates nested structure
-'primaryAddress.city': { source: 'location.address.city' }
-// ❌ WRONG - Creates flat structure
-primaryAddress_city: { source: 'location.address.city' }
-```
-### 8. retailerId Configuration Errors
-**Symptoms**: "retailerId is required" errors or confusion about when to use `setRetailerId()`
-**Solution**: Understand the correct pattern
-```typescript
-// ✅ CORRECT - GraphQL mutations don't need setRetailerId()
-// Check your GraphQL schema to determine retailerId handling:
-// - Mandatory retailerId → Must pass it in mutation input
-// - Optional retailerId → Can pass it if needed
-// - No retailerId field → Don't pass it
-// Standard createLocation does not have retailerId field in schema
-// ✅ IF mutation schema requires retailerId (mandatory):
-const { query, variables } = await mapper.map(location);
-if (retailerId && variables.input) {
-  variables.input.retailer = { id: parseInt(retailerId) };
-}
-await client.graphql({ query, variables });
-```
-**Reference:** `fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md`
----
-## Key Takeaways
-### Architecture Patterns
-- **Service Function Composition**: Workflow broken into 3 service functions - `processFile()`, `executeMutations()`, `writeMutationLog()`
-- **Per-File Processing**: Main workflow orchestrates service functions for each file
-- **Clear Separation of Concerns**: Parse/map, execute mutations, logging are independent functions
-### SDK Usage
-- **Buffer Import (CRITICAL)**: Always `import { Buffer } from 'node:buffer'` for Deno/Versori runtime
-- **S3 Archival Deduplication**: Use `s3.moveFile()` to `processed/` subdirectory - PRIMARY deduplication mechanism
-- **NO VersoriFileTracker for S3**: S3 archival is simpler and more reliable
-- **StateService Role**: SECONDARY - provides metadata/history, not primary deduplication
-### XML Processing
-- **XML @ Prefix**: Always use `@` prefix for XML attributes (`location.@ref`)
-- **Array Normalization (CRITICAL)**: Handle single vs multiple elements with `Array.isArray()` check - single `<location>` becomes object, not array
-- **Nested Mapping**: Use dot notation for nested objects (`primaryAddress.street`, `openingSchedule.monStart`)
-### GraphQL Mutations
-- **NO setRetailerId() Required**: GraphQL mutations do NOT need `client.setRetailerId()` - only Job/Event API needs it
-- **retailerId in Input**: Check your GraphQL schema to determine retailerId handling:
-  - **Mandatory retailerId** - Field exists and is required (`!`) → Must pass it
-  - **Optional retailerId** - Field exists and is optional → Can pass it if needed
-  - **No retailerId field** - Field doesn't exist → Don't pass it
-- **Rate Limiting**: Implement configurable delays between mutations to avoid API throttling
-- **Retry Logic**: Exponential backoff for failed mutations with `retryWithBackoff()`
-- **Direct Mutations**: Use `client.graphql()` for location upserts (NOT Batch API)
-- **GraphQL vs Batch API**: Use GraphQL for low-volume master data, Batch API for high-volume inventory
-### Error Handling & Monitoring
-- **Error Recovery**: Exponential backoff for error state tracking with retry timestamps
-- **Mutation Logging**: Optional S3 JSON logs with detailed per-location mutation status
-- **Schema Validation**: Use CLI tools before deployment to catch mapping errors
-- **Archival Order**: Archive FIRST (deduplication), then KV tracking (metadata)
----
-## Related Documentation
-### Core Guides
-- **GraphQL Mutation Mapping**: `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/readme.md`
-- **Universal Mapping**: `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/modules/readme.md`
-- **XML Parser**: `fc-connect-sdk/docs/02-CORE-GUIDES/parsers/modules/05-xml-parser.md`
-- **Data Sources**: `fc-connect-sdk/docs/02-CORE-GUIDES/data-sources/readme.md`
-- **State Management**: `fc-connect-sdk/docs/03-PATTERN-GUIDES/file-operations/state-duplicate-prevention.md`
-### Related Templates
-- **CSV Version**: `template-ingestion-s3-csv-location-graphql.md`
-- **JSON Version**: `template-ingestion-s3-json-location-graphql.md`
-- **SFTP XML Version**: `template-ingestion-sftp-xml-location-graphql.md`
-- **Event API Pattern**: `../event-api/template-ingestion-s3-xml-product-event.md`
-- **Batch API Pattern**: `../batch-api/template-ingestion-s3-xml-inventory-batch.md`
-### CLI Tools
-- **Schema Introspection**: `fc-connect-sdk/bin/readme.md#introspect-schema`
-- **Mapping Validation**: `fc-connect-sdk/bin/readme.md#validate-schema`
-- **Coverage Analysis**: `fc-connect-sdk/bin/readme.md#analyze-coverage`
-### Patterns
-- **Error Handling**: `fc-connect-sdk/docs/01-TEMPLATES/patterns/error-handling-retry.md`
-- **Rate Limiting**: `fc-connect-sdk/docs/03-PATTERN-GUIDES/integration-patterns/rate-limiting.md`
-- **XML Patterns**: `fc-connect-sdk/docs/01-TEMPLATES/versori/patterns/xml-response-patterns.md`
+---
+template_id: tpl-ingest-s3-xml-to-location-graphql
+canonical_filename: template-ingestion-s3-xml-location-graphql.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: s3-xml
+destination: fluent-graphql
+entity: location
+format: xml
+logging: versori
+status: stable
+compliance: gold-standard
+features:
+  - graphql-mutation-mapper
+  - memory-management
+  - enhanced-logging
+  - attribute-transformation
+---
+Template: Ingestion - S3 XML to Location 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
+---
+## Implementation Prompt
+"Create a Versori scheduled workflow that reads location XML files from S3, transforms the data using GraphQLMutationMapper with nested object mapping, and creates/updates Fluent Commerce locations via direct GraphQL mutations with alias batching support.
+**Requirements:**
+1. **S3 Source**:
+   - List and download XML files with configurable prefix and pattern
+   - Archive processed files to `processed/` directory (deduplication via archiving)
+   - Move failed files to `errors/` directory
+   - Use S3DataSource with retry logic and built-in archival
+   - Support configurable bucket, region, credentials
+2. **XML Parsing**:
+   - Use XMLParserService with @ prefix for attribute access
+   - Handle both single and multiple `<location>` elements (array normalization)
+   - Support nested XML paths (`location.address.street1`, `location.coordinates.@lat`)
+   - Parse complex structures (addresses, coordinates, opening schedules)
+3. **Field Mapping**:
+   - Map XML fields to Location GraphQL input type with nested objects:
+     - `ref`, `name`, `type` (root fields)
+     - `primaryAddress.*` (nested address object with coordinates)
+     - `openingSchedule.*` (nested schedule object with 7-day hours)
+   - Use SDK resolvers (trim, uppercase, parseFloat, parseInt, boolean)
+   - Support custom resolvers for complex transformations
+   - Validate required fields
+   - Note: Check your GraphQL schema to determine if `retailer.id` field exists and is mandatory/optional
+4. **GraphQL Mutations** (Direct - NO Batch API):
+   - Execute `createLocation` mutation directly for each location
+   - **NO BPP (Batch Pre-Processing)** - Not applicable for direct GraphQL mutations
+   - **NO Batch API** - Use direct GraphQL mutations with rate limiting instead
+   - Use rate limiting (configurable mutations per second)
+   - Add delay between mutations to avoid API throttling
+   - Retry failed mutations with exponential backoff
+   - Track successful vs failed mutations per file
+5. **Job Tracking & State Management**:
+   - **Use JobTracker** - Track job lifecycle (start, complete, fail) in KV store
+   - Use StateService + VersoriKVAdapter for duplicate file prevention
+   - Track processed files in KV store with metadata
+   - Store error state with exponential backoff tracking
+   - Support distributed state across workflow runs
+   - Provide job status endpoint for monitoring
+6. **Error Handling**:
+   - File-level errors archived to `/errors/` subdirectory
+   - Record-level errors tracked but don't stop file processing
+   - Mapping errors logged with specific location context
+   - Mutation errors retried with exponential backoff
+   - Error state tracking with next retry timestamp
+7. **Advanced Features**:
+   - Configurable rate limiting (mutations per second)
+   - Empty file detection and archival
+   - Timestamp-based error tracking
+   - Comprehensive monitoring and logging
+   - Manual webhook trigger with job tracking
+   - Job status query endpoint
+**Use SDK Components:**
+- `createClient()` - Universal client factory for Versori
+- `S3DataSource` - S3 operations with retry logic
+- `XMLParserService` - XML parsing with @ prefix attribute support
+- `GraphQLMutationMapper` - Field transformation with schema validation and nested object support
+- `StateService` + `VersoriKVAdapter` - Duplicate prevention with KV storage
+- Native Versori `log` - Structured logging
+**Configuration Variables** (from Versori activation):
+```typescript
+{
+  s3: {
+    bucketName: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    prefix: string;           // e.g., 'locations/'
+    archivePrefix: string;    // e.g., 'processed/'
+    errorPrefix: string;      // e.g., 'errors/'
+    filePattern: string;      // e.g., '.xml'
+    maxFilesToProcess: number;
+    enableArchival: boolean;
+  },
+  fluent: {
+    retailerId: string;         // Optional: Only if mutation schema requires retailerId in input
+    mutationRateLimit: number;  // mutations per second (e.g., 5)
+  }
+}
+```
+**Architecture Pattern:**
+```
+S3 Bucket → List Files → Download XML → Parse → Map → GraphQL Mutation → Archive/Move
+    ↓           ↓            ↓           ↓      ↓          ↓                ↓
+ Configure   Filter by  S3DataSource  XML   Universal   Direct        S3 moveFile()
+ Connection   Pattern    + Retry      Parser  Mapper   createLocation to processed/
+                                       (@)    (nested)  + Rate Limit   or errors/
+                                                                       (deduplication)
+```
+**Deliverables:**
+1. Complete Versori workflow with package.json
+2. Main workflow logic with S3 + XML + GraphQL patterns
+3. Helper functions for rate limiting and retry
+4. XML path resolution examples
+5. Sample XML files with nested structures
+6. Schema validation CLI commands
+7. Testing and deployment instructions
+8. Monitoring and troubleshooting guidance"
+---
+# STEP 3: Complete Implementation
+## Versori Scheduled: S3 XML → Location 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@latest`
+**Context**: Versori scheduled workflow that reads location XML files from S3 and creates/updates Fluent Commerce locations via GraphQL mutations with XML path resolution and rate limiting
+**Complexity**: Medium
+**Runtime**: Versori Platform
+**Estimated Lines**: ~850 lines (with comprehensive documentation)
+---
+## What You'll Build
+- Scheduled Versori workflow (daily location sync)
+- S3 file listing, download, and archival/move
+- XML parsing with @ prefix for attributes (XPath-style)
+- Array normalization (single element → array conversion)
+- GraphQLMutationMapper-based field transformations with nested objects
+- GraphQL mutations for location upserts with alias batching support
+- Retry logic with exponential backoff
+- StateService duplicate prevention (KV-backed)
+- Error state tracking and file error archival
+- Manual webhook trigger and job status endpoint
+---
+## When to Use GraphQL Mutations vs Batch API vs Event API
+### ✅ Use GraphQL Mutations For:
+| Entity Type    | Use Case                                 | Why GraphQL                           |
+| -------------- | ---------------------------------------- | ------------------------------------- |
+| **Locations**  | Store/warehouse master data (low volume) | Direct control, immediate validation  |
+| **Controls**   | System configuration, settings           | Single operations, complex queries    |
+| **Prices**     | Price updates (moderate volume)          | Immediate feedback, custom logic      |
+| **Single Ops** | One-off creates/updates                  | Testing, debugging, direct API access |
+### ❌ Use Event API Instead For:
+| Entity Type         | Use Case                               | Why Event API                                |
+| ------------------- | -------------------------------------- | -------------------------------------------- |
+| **Products**        | Product catalog sync, variant updates  | Triggers workflows, validates business rules |
+| **Customers**       | Customer registration, profile updates | Needs workflow for downstream systems        |
+| **Orders**          | Order creation, status updates         | Event-driven fulfillment workflows           |
+| **Custom Entities** | Any entity needing workflow triggers   | Full Rubix workflow support                  |
+### 🔄 Use Batch API For:
+| Entity Type        | Use Case                           | Why Batch API                                   |
+| ------------------ | ---------------------------------- | ----------------------------------------------- |
+| **Inventory ONLY** | Bulk inventory updates, daily sync | Optimized for high-volume, BPP change detection |
+---
+## XML File Format
+### Sample: locations.xml
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<locations>
+  <location ref="LOC-001" type="WAREHOUSE">
+    <name>Downtown Warehouse</name>
+    <address country="USA">
+      <street1>123 Main St</street1>
+      <street2>Building A</street2>
+      <city>New York</city>
+      <state>NY</state>
+      <postalCode>10001</postalCode>
+    </address>
+    <coordinates lat="40.7128" lon="-74.0060"/>
+    <timeZone>America/New_York</timeZone>
+    <openingSchedule>
+      <allHours>false</allHours>
+      <monStart>800</monStart>
+      <monEnd>1800</monEnd>
+      <tueStart>800</tueStart>
+      <tueEnd>1800</tueEnd>
+      <wedStart>800</wedStart>
+      <wedEnd>1800</wedEnd>
+      <thuStart>800</thuStart>
+      <thuEnd>1800</thuEnd>
+      <friStart>800</friStart>
+      <friEnd>1800</friEnd>
+      <satStart>0</satStart>
+      <satEnd>0</satEnd>
+      <sunStart>0</sunStart>
+      <sunEnd>0</sunEnd>
+    </openingSchedule>
+  </location>
+  <location ref="LOC-002" type="DC">
+    <name>Regional DC</name>
+    <address country="USA">
+      <street1>456 Industrial Pkwy</street1>
+      <city>Los Angeles</city>
+      <state>CA</state>
+      <postalCode>90001</postalCode>
+    </address>
+    <coordinates lat="34.0522" lon="-118.2437"/>
+    <timeZone>America/Los_Angeles</timeZone>
+    <openingSchedule>
+      <allHours>true</allHours>
+      <monStart>0</monStart>
+      <monEnd>0</monEnd>
+      <tueStart>0</tueStart>
+      <tueEnd>0</tueEnd>
+      <wedStart>0</wedStart>
+      <wedEnd>0</wedEnd>
+      <thuStart>0</thuStart>
+      <thuEnd>0</thuEnd>
+      <friStart>0</friStart>
+      <friEnd>0</friEnd>
+      <satStart>0</satStart>
+      <satEnd>0</satEnd>
+      <sunStart>0</sunStart>
+      <sunEnd>0</sunEnd>
+    </openingSchedule>
+  </location>
+</locations>
+```
+**XML Path Syntax (with @ prefix for attributes):**
+- `location.@ref` → XML attribute `ref` on `<location>` element
+- `location.name` → Text content of `<name>` element
+- `location.address.street1` → Nested element path
+- `location.address.@country` → XML attribute on nested `<address>` element
+- `location.coordinates.@lat` → XML attribute for latitude
+- `location.openingSchedule.monStart` → Deeply nested element
+**Note**: The SDK's `XMLParserService` automatically handles XML attributes using `@` prefix notation.
+---
+## 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-xml-location-graphql/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-location-sync.ts   # Scheduled: Daily location sync
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-location-sync.ts   # Webhook: Manual trigger
+    │       └── job-status-check.ts     # Webhook: Status query
+    │
+    ├── services/
+    │   └── location-sync.service.ts     # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── location-mapping.json        # GraphQL mapping config
+```
+---
+## Complete Versori Workflow
+### Step 1: Package Configuration
+**File: package.json**
+```json
+{
+  "name": "versori-s3-xml-location-sync",
+  "version": "1.0.0",
+  "description": "Versori workflow: S3 XML location sync to Fluent GraphQL",
+  "versori": {
+    "workflows": "./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"
+  }
+}
+```
+### Step 2: Workflow 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)
+ */
+// Scheduled workflows
+export { dailyLocationSync } from './src/workflows/scheduled/daily-location-sync';
+// Webhook workflows
+export { adhocLocationSync } from './src/workflows/webhook/adhoc-location-sync';
+export { locationSyncJobStatus } from './src/workflows/webhook/job-status-check';
+```
+**What Gets Exposed:**
+- ✅ `adhocLocationSync` → `https://{workspace}.versori.run/location-sync-adhoc`
+- ✅ `locationSyncJobStatus` → `https://{workspace}.versori.run/location-sync-job-status`
+- ❌ `dailyLocationSync` → NOT exposed (runs automatically on cron)
+---
+### Step 3: Workflow Files
+#### `src/workflows/scheduled/daily-location-sync.ts`
+**Purpose**: Automatic daily location 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 { executeLocationSync } from '../../services/location-sync.service';
+/**
+ * Scheduled Workflow: Daily Location Sync
+ *
+ * Runs automatically daily at 2 AM UTC
+ * NOT exposed as HTTP endpoint - Versori executes on schedule
+ *
+ * Uses shared service: location-sync.service.ts
+ */
+export const dailyLocationSync = schedule(
+  'location-sync-scheduled',
+  '0 2 * * *' // Daily at 2 AM UTC
+).then(
+  http('run-location-sync', { connection: 'fluent_commerce' }, async ctx => {
+    const startTime = Date.now();
+    const { log, openKv } = ctx;
+    const jobId = `location-sync-${Date.now()}`;
+    const tracker = new JobTracker(openKv(':project:'), log);
+    log.info('🚀 [START] Daily location sync initiated', { jobId, trigger: 'schedule' });
+    await tracker.createJob(jobId, { triggeredBy: 'schedule', stage: 'initialization' });
+    await tracker.updateJob(jobId, { status: 'processing' });
+    try {
+      log.info('⚙️ [PROCESSING] Starting location synchronization workflow', { jobId });
+      const result = await executeLocationSync(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+      const duration = Date.now() - startTime;
+      log.info('✅ [SUCCESS] Daily location sync completed', {
+        jobId,
+        duration: `${duration}ms`,
+        processed: result.processed,
+        totalRecords: result.totalRecords
+      });
+      return { success: true, jobId, duration, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+      const duration = Date.now() - startTime;
+      log.error('❌ [FAILED] Daily location sync failed', {
+        jobId,
+        duration: `${duration}ms`,
+        error: e?.message,
+        errorType: e?.name
+      });
+      return { success: false, jobId, duration, error: e?.message };
+    }
+  })
+);
+```
+---
+#### `src/workflows/webhook/adhoc-location-sync.ts`
+**Purpose**: Manual location sync trigger (on-demand)
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/location-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 { executeLocationSync } from '../../services/location-sync.service';
+/**
+ * Webhook: Manual Location Sync Trigger
+ *
+ * Endpoint: POST https://{workspace}.versori.run/location-sync-adhoc
+ * Request body (optional): { filePattern: "urgent_*.xml", maxFiles: 5 }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: location-sync.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const adhocLocationSync = webhook('location-sync-adhoc', {
+  response: { mode: 'sync' },
+  connection: 'location-sync-adhoc', // Versori validates API key
+}).then(
+  http('run-location-sync-adhoc', { connection: 'fluent_commerce' }, async ctx => {
+    const startTime = Date.now();
+    const { log, openKv, data } = ctx;
+    const jobId = `location-sync-adhoc-${Date.now()}`;
+    const tracker = new JobTracker(openKv(':project:'), log);
+    log.info('🚀 [START] Manual location sync triggered', { jobId, trigger: 'webhook', options: data });
+    await tracker.createJob(jobId, {
+      triggeredBy: 'manual',
+      stage: 'initialization',
+      options: data // Optional: filePattern, maxFiles, etc.
+    });
+    await tracker.updateJob(jobId, { status: 'processing' });
+    try {
+      log.info('⚙️ [PROCESSING] Starting manual location synchronization', { jobId });
+      const result = await executeLocationSync(ctx, jobId, tracker);
+      await tracker.markCompleted(jobId, result);
+      const duration = Date.now() - startTime;
+      log.info('✅ [SUCCESS] Manual location sync completed', {
+        jobId,
+        duration: `${duration}ms`,
+        processed: result.processed,
+        totalRecords: result.totalRecords
+      });
+      return { success: true, jobId, duration, ...result };
+    } catch (e: any) {
+      await tracker.markFailed(jobId, e);
+      const duration = Date.now() - startTime;
+      log.error('❌ [FAILED] Manual location sync failed', {
+        jobId,
+        duration: `${duration}ms`,
+        error: e?.message,
+        errorType: e?.name
+      });
+      return { success: false, jobId, duration, error: e?.message };
+    }
+  })
+);
+```
+---
+#### `src/workflows/webhook/job-status-check.ts`
+**Purpose**: Query job status
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/location-sync-job-status`
+**Request body**: `{ "jobId": "location-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/location-sync-job-status
+ * Request body: { "jobId": "location-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 locationSyncJobStatus = webhook('location-sync-job-status', {
+  response: { mode: 'sync' },
+  connection: 'location-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 };
+  })
+);
+```
+---
+### Step 4: Main Orchestration Service (`src/services/location-sync.service.ts`)
+**Note:** This service file should contain the `executeLocationSync` function (renamed from `runLocationXmlWorkflow`). The main workflow logic should be moved here.
+```typescript
+/**
+ * Main Orchestration Service: Location Sync
+ *
+ * This service contains the core business logic for location synchronization.
+ *
+ * Features:
+ * - S3 file operations with archival-based deduplication (moveFile to processed/)
+ * - XML parsing with @ prefix for attributes
+ * - Single element → array normalization
+ * - GraphQLMutationMapper for nested field transformations
+ * - GraphQL mutations with alias batching support
+ * - StateService for metadata tracking (secondary to archival)
+ * - Error state tracking with exponential backoff
+ *
+ * Deduplication Strategy:
+ * - PRIMARY: S3 archival via moveFile() - Files in processed/ won't be re-listed
+ * - SECONDARY: StateService KV tracking - Provides metadata and processing history
+ */
+import { Buffer } from 'node:buffer';  // Required for Deno/Versori runtime
+import {
+  createClient,
+  S3DataSource,
+  XMLParserService,
+  GraphQLMutationMapper,
+  StateService,
+  VersoriKVAdapter,
+  JobTracker,
+  FluentClient,
+} from '@fluentcommerce/fc-connect-sdk';
+// ============================================================================
+// Type Definitions
+// ============================================================================
+interface FileProcessingResult {
+  success: boolean;
+  locations: any[];
+  errors: string[];
+}
+interface MutationResult {
+  successful: number;
+  failed: number;
+  errors: string[];
+}
+interface MutationLogEntry {
+  timestamp: string;
+  fileName: string;
+  locationRef: string;
+  status: 'success' | 'failure';
+  error?: string;
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Retry utility with exponential backoff
+ * (User-defined - not part of SDK public API)
+ */
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  baseDelayMs = 1000
+): Promise<T> {
+  let lastError: any;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries - 1) {
+        const delay = baseDelayMs * Math.pow(2, attempt) + Math.floor(Math.random() * 200);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+/**
+ * Rate limiter for GraphQL mutations
+ */
+async function rateLimitedMutation(operation: () => Promise<any>, delayMs: number): Promise<any> {
+  const result = await operation();
+  await new Promise(resolve => setTimeout(resolve, delayMs));
+  return result;
+}
+// ============================================================================
+// Service Functions
+// ============================================================================
+/**
+ * Service Function 1: Process File
+ *
+ * Downloads XML from S3, parses with XMLParserService, normalizes arrays,
+ * and maps fields with GraphQLMutationMapper.
+ *
+ * @param s3 - S3DataSource instance
+ * @param parser - XMLParserService instance
+ * @param mapper - GraphQLMutationMapper instance
+ * @param filePath - Full S3 path to file
+ * @param fileName - File name only (for logging)
+ * @param log - Logger instance
+ * @returns FileProcessingResult with locations array and errors
+ */
+async function processFile(
+  s3: S3DataSource,
+  parser: XMLParserService,
+  mapper: GraphQLMutationMapper,
+  filePath: string,
+  fileName: string,
+  log: any
+): Promise<FileProcessingResult> {
+  try {
+    log.info('Processing file', { fileName });
+    // Download with retry
+    const content = await retryWithBackoff(
+      () => s3.downloadFile(filePath, { encoding: 'utf8' }) as Promise<string>
+    );
+    // Parse XML
+    const xmlData = await parser.parse(content);
+    // Extract location array (handle both single and multiple locations)
+    // CRITICAL: XML array normalization - single <location> becomes object, not array
+    const locationsData = xmlData.locations?.location;
+    const locationsArray = Array.isArray(locationsData) ? locationsData : [locationsData];
+    if (!locationsArray || locationsArray.length === 0) {
+      log.warn('Empty file (no locations)', { fileName });
+      return {
+        success: true,
+        locations: [],
+        errors: [],
+      };
+    }
+    // Map each location using GraphQLMutationMapper
+    const mappedLocations: Array<{ query: string; variables: any; input: any }> = [];
+    const mappingErrors: string[] = [];
+    // ✅ PRODUCTION ENHANCEMENT: Log transformation start
+    log.info('Transforming locations to GraphQL mutations', {
+      fileName,
+      totalLocations: locationsArray.length,
+    });
+    for (let i = 0; i < locationsArray.length; i++) {
+      const locationNumber = i + 1;
+      // ✅ PRODUCTION ENHANCEMENT: Log progress every 50 locations
+      if (locationNumber % 50 === 0) {
+        log.info(`📤 Transforming location ${locationNumber}/${locationsArray.length}`, {
+          fileName,
+          locationNumber,
+          totalLocations: locationsArray.length,
+          validSoFar: mappedLocations.length,
+          errorsSoFar: mappingErrors.length,
+          progress: `${((locationNumber / locationsArray.length) * 100).toFixed(1)}%`,
+        });
+      }
+      // Wrap location in context for mapping
+      const record = { location: locationsArray[i] };
+      try {
+        // GraphQLMutationMapper returns { query, variables } directly
+        const mappingResult = await mapper.map(record);
+        mappedLocations.push({
+          query: mappingResult.query,
+          variables: mappingResult.variables,
+          input: mappingResult.variables.input || mappingResult.variables,
+        });
+      } catch (error: unknown) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        mappingErrors.push(`Location ${locationNumber}: ${errorMsg}`);
+        log.warn('Mapping failed for location', { fileName, index: i, error: errorMsg });
+      }
+    }
+    log.info('File processed', {
+      fileName,
+      total: locationsArray.length,
+      mapped: mappedLocations.length,
+      errors: mappingErrors.length,
+      successRate: `${((mappedLocations.length / locationsArray.length) * 100).toFixed(1)}%`,
+    });
+    return {
+      success: true,
+      locations: mappedLocations,
+      errors: mappingErrors,
+    };
+  } 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('File processing failed', errorDetails, { fileName });
+    return {
+      success: false,
+      locations: [],
+      errors: [error.message || 'Unknown error'],
+    };
+  }
+}
+/**
+ * Service Function 2: Execute Mutations
+ *
+ * Executes GraphQL createLocation mutations with alias batching support.
+ *
+ * @param client - FluentClient instance
+ * @param mapper - GraphQLMutationMapper instance
+ * @param locations - Array of mapped location objects with query and variables
+ * @param log - Logger instance
+ * @param retailerId - Fluent retailer ID
+ * @param batchSize - Number of concurrent requests (default: 1)
+ * @param mutationsPerAliasBatch - Optional: Number of mutations per aliased request (default: undefined)
+ * @returns MutationResult with success/failure counts
+ */
+async function executeMutations(
+  client: FluentClient,
+  mapper: GraphQLMutationMapper,
+  locations: Array<{ query: string; variables: any; input: any }>,
+  log: any,
+  retailerId: string,
+  batchSize: number = 1,  // ✅ Default: 1 (sequential)
+  mutationsPerAliasBatch?: number  // ✅ NEW: Alias batching parameter (default: undefined = disabled)
+): Promise<MutationResult> {
+  // Determine mode: use aliases if mutationsPerAliasBatch is set and > 1
+  const useAliases = mutationsPerAliasBatch && mutationsPerAliasBatch > 1;
+  if (useAliases) {
+    return await executeMutationsWithAliases(
+      client,
+      mapper,
+      locations,
+      log,
+      retailerId,
+      batchSize,
+      mutationsPerAliasBatch!
+    );
+  } else {
+    return await executeMutationsSeparate(
+      client,
+      locations,
+      log,
+      batchSize
+    );
+  }
+}
+/**
+ * Execute mutations using separate concurrent requests (current mode)
+ */
+async function executeMutationsSeparate(
+  client: FluentClient,
+  locations: Array<{ query: string; variables: any; input: any }>,
+  log: any,
+  batchSize: number
+): Promise<MutationResult> {
+  const result: MutationResult = {
+    successful: 0,
+    failed: 0,
+    errors: [],
+  };
+  const safeConc = Math.max(1, Math.floor(batchSize));
+  // Sequential mode
+  if (safeConc === 1) {
+    for (const location of locations) {
+      try {
+        await retryWithBackoff(() =>
+          client.graphql({
+            query: location.query,
+            variables: location.variables,
+          })
+        );
+        result.successful++;
+      } catch (error: unknown) {
+        result.failed++;
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        result.errors.push(errorMsg);
+      }
+    }
+    return result;
+  }
+  // Parallel mode
+  for (let i = 0; i < locations.length; i += safeConc) {
+    const chunk = locations.slice(i, i + safeConc);
+    const results = await Promise.allSettled(
+      chunk.map(loc =>
+        retryWithBackoff(() =>
+          client.graphql({
+            query: loc.query,
+            variables: loc.variables,
+          })
+        )
+      )
+    );
+    results.forEach((settledResult, idx) => {
+      if (settledResult.status === 'fulfilled') {
+        result.successful++;
+      } else {
+        result.failed++;
+        result.errors.push(
+          settledResult.reason instanceof Error ? settledResult.reason.message : String(settledResult.reason)
+        );
+      }
+    });
+  }
+  return result;
+}
+/**
+ * ✅ NEW: Execute mutations using GraphQL aliases (batched requests)
+ */
+async function executeMutationsWithAliases(
+  client: FluentClient,
+  mapper: GraphQLMutationMapper,
+  locations: Array<{ query: string; variables: any; input: any }>,
+  log: any,
+  retailerId: string,
+  maxParallel: number,
+  mutationsPerAliasBatch: number
+): Promise<MutationResult> {
+  const result: MutationResult = { successful: 0, failed: 0, errors: [] };
+  const mutationName = (mapper as any).config.mutation || 'createLocation';
+  const aliasBatches: Array<Array<typeof locations[0]>> = [];
+  for (let i = 0; i < locations.length; i += mutationsPerAliasBatch) {
+    aliasBatches.push(locations.slice(i, i + mutationsPerAliasBatch));
+  }
+  // Process batches with concurrency control
+  for (let i = 0; i < aliasBatches.length; i += maxParallel) {
+    const concurrentBatches = aliasBatches.slice(i, i + maxParallel);
+    const batchResults = await Promise.allSettled(
+      concurrentBatches.map(async (batch) => {
+        const { query, variables } = buildAliasedBatch(batch, mutationName, retailerId);
+        const response = await retryWithBackoff(() => client.graphql({ query, variables }));
+        return parseAliasResponse(response, batch, mutationName);
+      })
+    );
+    batchResults.forEach((batchResult, idx) => {
+      if (batchResult.status === 'fulfilled') {
+        const batchRes = batchResult.value;
+        result.successful += batchRes.executed;
+        result.failed += batchRes.failed;
+        result.errors.push(...batchRes.errors);
+      } else {
+        const batch = concurrentBatches[idx];
+        const errorMsg = batchResult.reason instanceof Error ? batchResult.reason.message : String(batchResult.reason);
+        batch.forEach(loc => {
+          result.failed++;
+          result.errors.push(`Batch execution failed: ${errorMsg}`);
+        });
+      }
+    });
+    if (i + maxParallel < aliasBatches.length) {
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  }
+  return result;
+}
+/**
+ * ✅ NEW: Build aliased batch query and variables
+ */
+function buildAliasedBatch(
+  batch: Array<{ query: string; variables: any; input: any }>,
+  mutationName: string,
+  retailerId: string
+): { query: string; variables: Record<string, any> } {
+  const batchSize = batch.length;
+  const inputTypeName = `${mutationName.charAt(0).toUpperCase() + mutationName.slice(1)}Input`;
+  const variables = Array.from({ length: batchSize }, (_, i) =>
+    `$input${i + 1}: ${inputTypeName}!`
+  ).join(', ');
+  const aliasedMutations = Array.from({ length: batchSize }, (_, i) => {
+    const alias = `${mutationName}${i + 1}`;
+    return `  ${alias}: ${mutationName}(input: $input${i + 1}) { id ref name }`;
+  }).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((loc, index) => {
+    const input = loc.variables.input || loc.variables;
+    if (input && !input.retailer) {
+      input.retailer = { id: parseInt(retailerId) };
+    }
+    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((loc, index) => {
+    const alias = `${mutationName}${index + 1}`;
+    const aliasData = data[alias];
+    const aliasErrors = errors.filter((e: any) =>
+      e.path && Array.isArray(e.path) && e.path.includes(alias)
+    );
+    if (aliasData && !aliasErrors.length) {
+      result.executed++;
+    } else {
+      result.failed++;
+      const errorMsg = aliasErrors[0]?.message || 'Mutation failed';
+      result.errors.push(`${loc.input?.ref || 'unknown'}: ${errorMsg}`);
+    }
+  });
+  return result;
+}
+/**
+ * Service Function 3: Write Mutation Log
+ *
+ * Writes mutation results to S3 as a JSON log file.
+ *
+ * @param s3 - S3DataSource instance
+ * @param logEntries - Array of mutation log entries
+ * @param fileName - Original file name (used to generate log path)
+ * @param logPrefix - S3 prefix for logs (e.g., 'logs/')
+ * @param log - Logger instance
+ */
+async function writeMutationLog(
+  s3: S3DataSource,
+  logEntries: MutationLogEntry[],
+  fileName: string,
+  logPrefix: string,
+  log: any
+): Promise<void> {
+  try {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const logFileName = `${logPrefix}${fileName.replace('.xml', '')}_${timestamp}.json`;
+    const logContent = JSON.stringify(
+      {
+        fileName,
+        timestamp: new Date().toISOString(),
+        totalMutations: logEntries.length,
+        successful: logEntries.filter(e => e.status === 'success').length,
+        failed: logEntries.filter(e => e.status === 'failure').length,
+        entries: logEntries,
+      },
+      null,
+      2
+    );
+    // Write to S3 (uploadFile accepts string or Buffer)
+    await s3.uploadFile(logFileName, logContent);
+    log.info('Mutation log written', { logFileName, entries: logEntries.length });
+  } catch (error: any) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorDetails = {
+      message: error?.message || 'Unknown error',
+      stack: error?.stack,
+      errorType: error?.name || 'Error',
+    };
+    log.error('Failed to write mutation log', errorDetails, { fileName });
+    // Don't throw - logging failure shouldn't stop workflow
+  }
+}
+// ============================================================================
+// Main Workflow Function
+// ============================================================================
+/**
+ * Main Orchestration Function: Execute Location Sync
+ *
+ * This function orchestrates the location synchronization workflow.
+ *
+ * Architecture:
+ * 1. List files from S3
+ * 2. For each file:
+ *    a. processFile() - Download, parse, map
+ *    b. executeMutations() - Send GraphQL mutations with rate limiting
+ *    c. writeMutationLog() - Log results to S3
+ *    d. Archive file (primary deduplication)
+ *    e. Mark processed in KV (metadata tracking)
+ *
+ * @param ctx - Versori context
+ * @param jobId - Job identifier
+ * @param tracker - JobTracker instance
+ * @returns Processing result
+ */
+export async function executeLocationSync(ctx: any, jobId: string, tracker: JobTracker) {
+  const { log, activation } = ctx;
+  log.info('📋 [INIT] Reading activation variables', { jobId });
+  // Read activation variables
+  const s3Bucket = activation?.getVariable('s3BucketName');
+  const s3Region = activation?.getVariable('awsRegion') || 'us-east-1';
+  const s3AccessKeyId = activation?.getVariable('awsAccessKeyId');
+  const s3SecretAccessKey = activation?.getVariable('awsSecretAccessKey');
+  const s3Prefix = activation?.getVariable('s3Prefix') || 'locations/';
+  const archivePrefix = activation?.getVariable('archivePrefix') || 'processed/';
+  const errorPrefix = activation?.getVariable('errorPrefix') || 'errors/';
+  const logPrefix = activation?.getVariable('logPrefix') || 'logs/';
+  const filePattern = (activation?.getVariable('filePattern') || '.xml').toLowerCase();
+  const maxFiles = parseInt(activation?.getVariable('maxFilesToProcess') || '10', 10);
+  const retailerId = activation?.getVariable('retailerId');  // Optional: Only if mutation schema requires it
+  const enableArchival = activation?.getVariable('enableArchival') !== 'false';
+  const enableMutationLogs = activation?.getVariable('enableMutationLogs') !== 'false';
+  const enableFileTracking = activation?.getVariable('enableFileTracking') !== 'false';
+  // ✅ Configuration with defaults
+  const mutationBatchSize = parseInt(
+    activation?.getVariable('mutationBatchSize') || '1',  // ✅ Default: 1 (sequential)
+    10
+  );
+  const mutationsPerAliasBatch = activation?.getVariable('mutationsPerAliasBatch')
+    ? parseInt(activation?.getVariable('mutationsPerAliasBatch') || '1', 10)
+    : undefined;  // ✅ Default: undefined (disabled, use separate requests)
+  // Validate required variables
+  const missingVars: string[] = [];
+  if (!s3Bucket) missingVars.push('s3BucketName');
+  if (!s3AccessKeyId) missingVars.push('awsAccessKeyId');
+  if (!s3SecretAccessKey) missingVars.push('awsSecretAccessKey');
+  // Note: retailerId is optional - only needed if mutation schema requires it
+  if (missingVars.length > 0) {
+    const errorMsg = `Missing required variables: ${missingVars.join(', ')}`;
+    log.error('❌ [VALIDATION] Missing required activation variables', {
+      missingVars,
+      recommendation: 'Add missing variables in Versori activation settings'
+    });
+    return { success: false, error: errorMsg, processed: 0 };
+  }
+  log.info('✅ [VALIDATION] All required variables present', {
+    s3Bucket,
+    s3Region,
+    s3Prefix,
+    enableFileTracking,
+    mutationBatchSize
+  });
+  try {
+    log.info('🔧 [INIT] Initializing Fluent Commerce client', { jobId });
+    // Initialize services with validateConnection
+    const client = await createClient(ctx, { validateConnection: true });
+    if (!client) {
+      throw new Error('Failed to create Fluent Commerce client');
+    }
+    log.info('✅ [INIT] Fluent Commerce client validated and ready', { jobId });
+    // ✅ CORRECT: GraphQL mutations do NOT need client.setRetailerId()
+    // setRetailerId() is only for Job/Event API, NOT GraphQL
+    // 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('🗄️ [INIT] Initializing S3 data source', { s3Bucket, s3Region, s3Prefix });
+    const s3 = new S3DataSource(
+      {
+        type: 'S3_XML',
+        connectionId: 's3-location-sync',
+        name: 'Source S3',
+        s3Config: {
+          bucket: s3Bucket,
+          region: s3Region,
+          accessKeyId: s3AccessKeyId,
+          secretAccessKey: s3SecretAccessKey,
+        },
+      },
+      log
+    );
+    const parser = new XMLParserService();
+    // Initialize state tracking (only if enabled)
+    let stateService: StateService | null = null;
+    if (enableFileTracking) {
+      log.info('🔄 [INIT] Enabling file tracking with StateService', { jobId });
+      const stateKV = new VersoriKVAdapter(ctx);
+      stateService = new StateService(stateKV);
+    } else {
+      log.info('⏭️ [INIT] File tracking disabled - relying on S3 archival only', { jobId });
+    }
+    log.info('📝 [INIT] Loading mapping configuration', { jobId });
+    // ✅ CRITICAL: Load mapping config from external JSON file
+    // Mapping config uses GraphQLMutationMapper structure (nested objects, not dot notation)
+    // File: src/config/location-mapping.json
+    const mappingConfigJson = await import('../config/location-mapping.json', { assert: { type: 'json' } });
+    const mappingConfig = mappingConfigJson.default;
+    // Initialize GraphQLMutationMapper with client for schema introspection
+    const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+    log.info('📂 [S3] Listing files from S3', { s3Bucket, s3Prefix, filePattern });
+    // List files (pattern filtering handled by listFiles)
+    const files = await s3.listFiles({
+      prefix: s3Prefix,
+      pattern: filePattern,
+      maxKeys: 1000
+    });
+    // Newest-first ordering
+    const xmlFiles = files
+      .sort((a: any, b: any) => {
+        const aTime = a.lastModified ? new Date(a.lastModified).getTime() : 0;
+        const bTime = b.lastModified ? new Date(b.lastModified).getTime() : 0;
+        return bTime - aTime;
+      })
+      .slice(0, maxFiles);
+    log.info('📊 [S3] File discovery complete', {
+      totalFiles: files.length,
+      xmlFiles: xmlFiles.length,
+      maxFiles,
+      selectedFiles: xmlFiles.map(f => f.name)
+    });
+    const results = {
+      processed: 0,
+      skipped: 0,
+      failed: 0,
+      totalRecords: 0,
+      errors: [] as string[],
+    };
+    log.info('🔄 [PROCESSING] Starting file processing loop', {
+      fileCount: xmlFiles.length,
+      jobId
+    });
+    // Per-file processing loop
+    for (const file of xmlFiles) {
+      const filePath = file.path;
+      const fileName = file.name;
+      log.info('📄 [FILE] Processing file', { fileName, filePath });
+      // Duplicate prevention (secondary check - files in processed/ won't be listed)
+      // Primary deduplication: S3 archival (files moved to processed/ subdirectory)
+      if (enableFileTracking && stateService) {
+        const wasProcessed = await stateService.isFileProcessed(fileName);
+        if (wasProcessed) {
+          log.info('⏭️ [SKIP] File already processed (KV check)', { fileName });
+          results.skipped++;
+          continue;
+        }
+      }
+      try {
+        // Step 1: Process file (download, parse, map)
+        log.info('📥 [DOWNLOAD] Downloading and parsing file', { fileName });
+        const processingResult = await processFile(s3, parser, mapper, filePath, fileName, log);
+        if (!processingResult.success) {
+          throw new Error(`File processing failed: ${processingResult.errors.join(', ')}`);
+        }
+        if (processingResult.locations.length === 0) {
+          log.warn('⚠️ [SKIP] Empty file detected, archiving', { fileName });
+          if (enableArchival) {
+            await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+            log.info('📦 [ARCHIVE] Empty file archived', { fileName, destination: `${archivePrefix}${fileName}` });
+          }
+          results.skipped++;
+          continue;
+        }
+        log.info('✅ [PARSE] File parsed successfully', {
+          fileName,
+          locationCount: processingResult.locations.length,
+          mappingErrors: processingResult.errors.length
+        });
+        // Step 2: Execute mutations
+        // Step 2: Execute mutations with alias batching support
+        // ? Enhanced: Extract context for progress logging
+        const sampleLocationRefs = processingResult.locations.slice(0, 5).map((loc: any) => loc.input?.ref || loc.ref || 'unknown');
+        const mutationType = mapper?.mutationName || 'createLocation';
+        // ? Enhanced: Start logging with context
+        log.info(`[GraphQLMutations] Sending mutations for file "${fileName}"`, {
+         totalMutations: processingResult.locations.length,
+         mutationType,
+         batchSize: mutationBatchSize,
+         batchMode: mutationBatchSize === 1 ? 'sequential' : `parallel (${mutationBatchSize})`,
+         sampleLocationRefs: sampleLocationRefs.join(', '),
+         aliasBatching: mutationsPerAliasBatch ? `enabled (${mutationsPerAliasBatch} per alias)` : 'disabled'
+        });
+        const mutationResult = await executeMutations(
+          client,
+          mapper,
+          processingResult.locations,
+          log,
+          retailerId,  // Pass retailerId for mutations that require it in input
+          mutationBatchSize,  // Concurrency control (default: 1)
+          mutationsPerAliasBatch  // ✅ NEW: Alias batching (default: undefined)
+        );
+        // ? Enhanced: Completion logging with summary
+        log.info(`[GraphQLMutations] Mutation submission completed for file "${fileName}"`, {
+         totalMutations: processingResult.locations.length,
+         successful: mutationResult.successful,
+         failed: mutationResult.failed,
+         successRate: processingResult.locations.length > 0 ? `${Math.round((mutationResult.successful / processingResult.locations.length) * 100)}%` : '0%',
+         mutationType
+        });
+        // Step 3: Write mutation log (if enabled)
+        if (enableMutationLogs) {
+          const logEntries: MutationLogEntry[] = processingResult.locations.map(loc => {
+            const failed = mutationResult.errors.find(e => e.startsWith(loc.ref));
+            return {
+              timestamp: new Date().toISOString(),
+              fileName,
+              locationRef: loc.ref,
+              status: failed ? 'failure' : 'success',
+              error: failed,
+            };
+          });
+          await writeMutationLog(s3, logEntries, fileName, logPrefix, log);
+        }
+        // Step 4: Archive file (PRIMARY deduplication - file won't be listed again)
+        if (enableArchival) {
+          log.info('📦 [ARCHIVE] Moving file to processed directory', { fileName });
+          await s3.moveFile(filePath, `${archivePrefix}${fileName}`);
+          log.info('✅ [ARCHIVE] File archived successfully', {
+            fileName,
+            destination: `${archivePrefix}${fileName}`
+          });
+        }
+        // Step 5: Mark processed in KV (SECONDARY - provides metadata/history)
+        if (enableFileTracking && stateService) {
+          log.info('💾 [STATE] Recording file processing metadata', { fileName });
+          await stateService.markFileProcessed(fileName, {
+            recordCount: processingResult.locations.length,
+            successful: mutationResult.successful,
+            failed: mutationResult.failed,
+            mappingErrors: processingResult.errors.length,
+            timestamp: new Date().toISOString(),
+          });
+        }
+        results.processed++;
+        results.totalRecords += mutationResult.successful;
+        log.info('✅ [COMPLETE] File processing complete', {
+          fileName,
+          locations: processingResult.locations.length,
+          successful: mutationResult.successful,
+          failed: mutationResult.failed,
+          mappingErrors: processingResult.errors.length,
+        });
+        if (processingResult.errors.length > 0 || mutationResult.errors.length > 0) {
+          results.errors.push(
+            `${fileName}: ${processingResult.errors.length} mapping errors, ${mutationResult.errors.length} mutation errors`
+          );
+        }
+      } 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('❌ [ERROR] File processing failed', errorDetails, { fileName });
+        // Provide error recommendations based on error type
+        const recommendation = getErrorRecommendation(error);
+        if (recommendation) {
+          log.warn('💡 [RECOMMENDATION]', { fileName, recommendation });
+        }
+        results.failed++;
+        results.errors.push(`${fileName}: ${error.message}`);
+        // Attempt to move to error directory, ignore failures
+        try {
+          log.info('🗂️ [ERROR] Moving failed file to error directory', { fileName });
+          await s3.moveFile(filePath, `${errorPrefix}${fileName}`);
+          log.info('✅ [ERROR] Failed file moved to error directory', {
+            fileName,
+            destination: `${errorPrefix}${fileName}`
+          });
+        } catch (moveError) {
+          log.warn('⚠️ [ERROR] Failed to move file to error directory', {
+            fileName,
+            moveError: moveError instanceof Error ? moveError.message : String(moveError)
+          });
+        }
+        // Track error state with exponential backoff (only if file tracking enabled)
+        if (enableFileTracking && stateService) {
+          try {
+            const stateKV = new VersoriKVAdapter(ctx);
+            const key = ['error-state', fileName];
+            const prev = (await stateKV.get(key))?.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 stateKV.set(key, {
+              fileName,
+              attemptCount: attempts,
+              lastError: error?.message || 'unknown',
+              lastAttemptAt: new Date().toISOString(),
+              firstFailedAt: prev?.firstFailedAt || new Date().toISOString(),
+              nextRetryAt,
+            });
+            log.info('💾 [ERROR] Error state tracked with exponential backoff', {
+              fileName,
+              attempts,
+              nextRetryAt
+            });
+          } catch (stateError) {
+            log.warn('⚠️ [ERROR] Failed to track error state', {
+              fileName,
+              stateError: stateError instanceof Error ? stateError.message : String(stateError)
+            });
+          }
+        }
+      }
+    }
+    log.info('🏁 [COMPLETE] File processing loop finished', {
+      processed: results.processed,
+      skipped: results.skipped,
+      failed: results.failed,
+      totalRecords: results.totalRecords
+    });
+    return results;
+  } catch (error: any) {
+    // ✅ Enhanced error logging: Extract all error details for visibility
+    const errorDetails = {
+      message: error?.message || 'Unknown error',
+      stack: error?.stack,
+      errorType: error?.name || 'Error',
+    };
+    log.error('❌ [FATAL] Location sync failed', errorDetails);
+    // Provide fatal error recommendations
+    const recommendation = getErrorRecommendation(error);
+    if (recommendation) {
+      log.warn('💡 [RECOMMENDATION]', { recommendation });
+    }
+    return {
+      success: false,
+      error: error.message,
+      processed: 0,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+/**
+ * Get error recommendation based on error type
+ */
+function getErrorRecommendation(error: any): string | null {
+  const message = error?.message?.toLowerCase() || '';
+  if (message.includes('s3') || message.includes('access denied')) {
+    return 'Check S3 credentials and bucket permissions. Verify IAM policy includes s3:ListBucket, s3:GetObject, s3:PutObject, s3:DeleteObject.';
+  }
+  if (message.includes('xml') || message.includes('parse')) {
+    return 'Verify XML file structure matches expected schema. Check for malformed XML or encoding issues.';
+  }
+  if (message.includes('mapping') || message.includes('field')) {
+    return 'Review field mapping configuration. Ensure all required fields are present and source paths are correct.';
+  }
+  if (message.includes('graphql') || message.includes('mutation')) {
+    return 'Check GraphQL schema and mutation input. Verify all required fields are provided and types match schema.';
+  }
+  if (message.includes('auth') || message.includes('401') || message.includes('403')) {
+    return 'Verify Fluent Commerce credentials. Check OAuth2 client ID/secret and ensure connection is active.';
+  }
+  if (message.includes('timeout') || message.includes('econnrefused')) {
+    return 'Check network connectivity. Verify API endpoints are accessible and not rate-limited.';
+  }
+  return null;
+}
+```
+**Note:** The `executeLocationSync` function should contain the full implementation of `runLocationXmlWorkflow` (renamed to `executeLocationSync`), including all the logic for processing files, executing mutations, and logging. The implementation details are shown in the service function code above.
+---
+### Step 5: TypeScript Configuration
+**File: tsconfig.json**
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+---
+## Code Flow Explanation
+### Initialization Phase
+1. **Read activation variables** - S3 config, Fluent config, rate limiting, logging options
+2. **Validate required variables** - Fail fast if missing credentials
+3. **Initialize SDK services** - FluentClient, S3DataSource, XMLParserService, StateService
+4. **Create mapping configuration** - Define XML → GraphQL field mappings with nested objects
+5. **Calculate rate limit delay** - Convert mutations/second to delay in milliseconds
+### File Discovery Phase
+1. **List S3 files** - Use `s3.listFiles()` with prefix filter (excludes processed/ subdirectory)
+2. **Filter by pattern** - Match file extension (e.g., `.xml`)
+3. **Sort newest-first** - Process most recent files first
+4. **Apply max files limit** - Prevent overwhelming the workflow
+5. **Note**: Files in `processed/` subdirectory won't be listed (primary deduplication)
+### Per-File Processing (Service Functions)
+**Step 1: processFile()** - Download, parse, map
+1. **Download file** - Use S3DataSource with retry logic
+2. **Parse XML** - XMLParserService converts to JavaScript object
+3. **Normalize array** - Handle single vs multiple `<location>` elements (CRITICAL for XML)
+4. **Map locations** - Use UniversalMapper with nested field mapping
+5. **Collect errors** - Track mapping errors without stopping
+6. **Return result** - FileProcessingResult with locations array and errors
+**Step 2: executeMutations()** - GraphQL mutations with rate limiting
+1. **Loop through locations** - Process each location individually
+2. **Build mutation input** - Extract nested fields (primaryAddress, openingSchedule)
+3. **Execute mutation** - Direct GraphQL `createLocation` with retry logic
+4. **Apply rate limiting** - Add configurable delay between mutations
+5. **Track results** - Count successful vs failed, collect error messages
+6. **Return result** - MutationResult with counts and errors
+**Step 3: writeMutationLog()** - S3 log file (optional)
+1. **Create log entries** - Map locations to log entries with status
+2. **Build JSON log** - Include timestamp, summary, detailed entries
+3. **Write to S3** - Use Buffer.from() for Deno/Versori runtime compatibility
+4. **Non-blocking** - Logging failure doesn't stop workflow
+5. **Timestamped naming** - Unique log file per processed file
+### Cleanup Phase
+1. **Archive file FIRST** - Move to `processed/` or `errors/` (PRIMARY deduplication)
+2. **Mark processed in KV** - StateService tracks metadata and processing history
+3. **Error state tracking** - Store error info with exponential backoff timestamp
+4. **Return results** - Summary of processed, skipped, failed files
+**Note**: The order matters! Archive first (primary deduplication), then KV tracking (metadata/history).
+### Service Function Benefits
+- **Composability**: Each function has single responsibility and can be reused
+- **Testability**: Service functions can be unit tested independently
+- **Clarity**: Main workflow shows high-level orchestration
+- **Error Handling**: Isolated error handling per service function
+- **Logging**: Detailed logging at each step with structured context
+---
+## S3 Archival Deduplication Pattern
+This template uses **S3 archival** as the primary deduplication mechanism, NOT VersoriFileTracker.
+### How It Works
+**S3 Directory Structure:**
+```
+s3://my-bucket/
+├── locations/           ← listFiles() reads from here
+│   ├── new-file-1.xml
+│   └── new-file-2.xml
+├── processed/           ← Successfully processed files
+│   ├── old-file-1.xml
+│   └── old-file-2.xml
+└── errors/              ← Failed files
+    └── bad-file.xml
+```
+**Deduplication Flow:**
+1. **List files**: `s3.listFiles({ prefix: 'locations/' })` - Only lists `locations/` subdirectory
+2. **Process file**: Download, parse, transform, send mutations
+3. **Archive**: `s3.moveFile(filePath, 'processed/new-file-1.xml')` - Moves file out of `locations/`
+4. **Next run**: File is now in `processed/`, won't be listed again
+**Why This Works:**
+- Files in `processed/` subdirectory are **never listed** when prefix is `locations/`
+- No need to track file state in KV store for deduplication
+- S3 is the single source of truth for file status
+- Simple, reliable, scales to millions of files
+**StateService Role (Secondary):**
+- Provides metadata and processing history
+- Backup check in case archival fails mid-process
+- Useful for monitoring and debugging
+- NOT the primary deduplication mechanism
+**When to Use VersoriFileTracker:**
+- **NEVER for S3 sources** - Use archival pattern instead
+- **Only for SFTP sources** - Where archival might not be possible
+- See SFTP templates for VersoriFileTracker usage
+---
+## XML Path Resolution Patterns
+### Pattern 1: XML Attribute Access with @ Prefix
+```typescript
+const mappingConfig = {
+  fields: {
+    // XML attribute access
+    ref: { source: 'location.@ref' }, // <location ref="LOC-001">
+    type: { source: 'location.@type' }, // <location type="WAREHOUSE">
+    country: { source: 'location.address.@country' }, // <address country="USA">
+    // XML element text content
+    name: { source: 'location.name' }, // <name>Downtown</name>
+    city: { source: 'location.address.city' }, // <address><city>NYC</city></address>
+  },
+};
+```
+### Pattern 2: Handling Single vs Multiple Elements
+```typescript
+// XML can have single or multiple <location> elements
+const locationsData = xmlData.locations?.location;
+// Normalize to array
+const locations = Array.isArray(locationsData) ? locationsData : [locationsData];
+// Process each location
+for (const loc of locations) {
+  const record = { location: loc }; // Wrap for mapping
+  const result = await mapper.map(record);
+}
+```
+### Pattern 3: Nested Object Mapping
+```typescript
+const mappingConfig = {
+  fields: {
+    // Root fields
+    ref: { source: 'location.@ref', required: true },
+    name: { source: 'location.name', required: true },
+    type: { source: 'location.@type', required: true },
+    // Nested primaryAddress object
+    'primaryAddress.ref': { source: 'location.@ref' },
+    'primaryAddress.street': { source: 'location.address.street1' },
+    'primaryAddress.city': { source: 'location.address.city' },
+    'primaryAddress.latitude': { source: 'location.coordinates.@lat', resolver: 'sdk.parseFloat' },
+    // Nested openingSchedule object
+    'openingSchedule.allHours': {
+      source: 'location.openingSchedule.allHours',
+      resolver: 'sdk.boolean',
+    },
+    'openingSchedule.monStart': {
+      source: 'location.openingSchedule.monStart',
+      resolver: 'sdk.parseInt',
+    },
+    // Note: retailer.id not shown - standard createLocation does not have this field
+    // If your schema requires it, add: 'retailer.id': { value: parseInt(retailerId) }
+  },
+};
+```
+---
+## Sample XML Files
+### Minimal Test File
+**File: test-location.xml**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<locations>
+  <location ref="TEST-001" type="WAREHOUSE">
+    <name>Test Warehouse</name>
+    <address country="USA">
+      <street1>123 Test St</street1>
+      <city>TestCity</city>
+      <state>TC</state>
+      <postalCode>12345</postalCode>
+    </address>
+    <coordinates lat="40.7128" lon="-74.0060"/>
+    <timeZone>America/New_York</timeZone>
+    <openingSchedule>
+      <allHours>false</allHours>
+      <monStart>800</monStart>
+      <monEnd>1800</monEnd>
+      <tueStart>800</tueStart>
+      <tueEnd>1800</tueEnd>
+      <wedStart>800</wedStart>
+      <wedEnd>1800</wedEnd>
+      <thuStart>800</thuStart>
+      <thuEnd>1800</thuEnd>
+      <friStart>800</friStart>
+      <friEnd>1800</friEnd>
+      <satStart>0</satStart>
+      <satEnd>0</satEnd>
+      <sunStart>0</sunStart>
+      <sunEnd>0</sunEnd>
+    </openingSchedule>
+  </location>
+</locations>
+```
+---
+## Service Functions Deep Dive
+This template demonstrates service function composition for maintainable workflows.
+### Function 1: processFile()
+**Purpose**: Download, parse, normalize, and map XML data
+**Inputs**:
+- `s3: S3DataSource` - For file download
+- `parser: XMLParserService` - For XML parsing
+- `mapper: UniversalMapper` - For field mapping
+- `filePath: string` - S3 path to file
+- `fileName: string` - File name for logging
+- `log: any` - Logger instance
+**Outputs**: `FileProcessingResult`
+```typescript
+{
+  success: boolean;      // Overall success
+  locations: any[];      // Mapped location objects
+  errors: string[];      // Mapping error messages
+}
+```
+**Key Operations**:
+1. Downloads file with retry logic
+2. Parses XML using XMLParserService
+3. **Normalizes arrays** - Handles single vs multiple `<location>` elements
+4. Maps each location using UniversalMapper
+5. Collects errors without stopping processing
+6. Returns all mapped locations + errors
+**Why separate function?**
+- Testable independently with mock data
+- Reusable across workflows (scheduled, webhook, adhoc)
+- Clear error boundaries - file-level errors vs record-level errors
+- Easy to add XML validation or schema checks
+### Function 2: executeMutations()
+**Purpose**: Execute GraphQL createLocation mutations with rate limiting
+**Inputs**:
+- `client: FluentClient` - For GraphQL mutations
+- `locations: any[]` - Mapped location data
+- `mutationDelayMs: number` - Rate limit delay
+- `fileName: string` - For logging context
+- `log: any` - Logger instance
+**Outputs**: `MutationResult`
+```typescript
+{
+  successful: number;    // Count of successful mutations
+  failed: number;        // Count of failed mutations
+  errors: string[];      // Error messages with location refs
+}
+```
+**Key Operations**:
+1. Loops through locations
+2. Builds GraphQL mutation input
+3. Executes with retry logic + rate limiting
+4. Tracks success/failure per location
+5. Returns summary counts + errors
+**Why separate function?**
+- Clear separation: mapping vs mutation execution
+- Rate limiting logic isolated and configurable
+- Easy to swap mutation types (create vs update)
+- Testable with mock FluentClient
+- Can parallelize in future (batch mutations)
+### Function 3: writeMutationLog()
+**Purpose**: Write detailed mutation results to S3 as JSON log
+**Inputs**:
+- `s3: S3DataSource` - For log upload
+- `logEntries: MutationLogEntry[]` - Mutation status per location
+- `fileName: string` - Original file name
+- `logPrefix: string` - S3 prefix for logs (e.g., `logs/`)
+- `log: any` - Logger instance
+**Outputs**: `void` (non-blocking - errors logged but not thrown)
+**Key Operations**:
+1. Creates timestamped log file name
+2. Builds JSON log with summary + entries
+3. **Uses Buffer.from()** - Required for Deno/Versori runtime
+4. Writes to S3 with `uploadFile()`
+5. Errors don't stop workflow (logging is non-critical)
+**Why separate function?**
+- Optional feature - can be disabled via config
+- Non-blocking - logging failure doesn't fail workflow
+- Structured logging for audit trails
+- Easy to change log format (JSON, CSV, XML)
+- Can add log rotation/cleanup logic later
+### Service Function Composition Benefits
+**1. Maintainability**
+```typescript
+// Clear workflow orchestration
+const processingResult = await processFile(...);
+const mutationResult = await executeMutations(...);
+await writeMutationLog(...);
+```
+**2. Testability**
+```typescript
+// Unit test processFile() with mock XML
+const mockS3 = { downloadFile: jest.fn() };
+const result = await processFile(mockS3, parser, mapper, ...);
+expect(result.locations).toHaveLength(5);
+```
+**3. Reusability**
+```typescript
+// Use processFile() in different workflows
+export const webhook = webhook('location-webhook').then(async ctx => {
+  const result = await processFile(s3, parser, mapper, filePath, fileName, log);
+  return { locations: result.locations };
+});
+```
+**4. Error Isolation**
+```typescript
+// Each function has clear error boundaries
+try {
+  const processingResult = await processFile(...);
+  // File-level errors caught here
+} catch (error) {
+  // Handle file processing failure
+}
+// Mutation errors don't stop file processing
+const mutationResult = await executeMutations(...);
+// mutationResult.errors contains per-location failures
+```
+**5. Progressive Enhancement**
+```typescript
+// Easy to add features without touching core logic
+async function validateLocations(locations: any[]) {
+  // Add validation step
+}
+const processingResult = await processFile(...);
+await validateLocations(processingResult.locations);  // New step
+const mutationResult = await executeMutations(...);
+```
+---
+## Versori Environment Variables
+**Activation Variables:**
+```bash
+# ============================================================================
+# Required Variables
+# ============================================================================
+s3BucketName=my-location-bucket
+awsAccessKeyId=AKIAXXXXXXXXXXXX
+awsSecretAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# ============================================================================
+# S3 Configuration (Optional - with defaults)
+# ============================================================================
+awsRegion=us-east-1
+s3Prefix=locations/
+archivePrefix=processed/
+errorPrefix=errors/
+logPrefix=logs/
+filePattern=.xml
+maxFilesToProcess=10
+# ============================================================================
+# Feature Toggles (Optional - with defaults)
+# ============================================================================
+# Enable S3 archival (move files to processed/errors directories)
+enableArchival=true
+# Enable mutation logs (write detailed mutation results to S3)
+enableMutationLogs=true
+# Enable file tracking via StateService + KV store
+# When disabled, relies on S3 archival only for deduplication
+enableFileTracking=true
+# ============================================================================
+# Mutation Configuration (Optional - with defaults)
+# ============================================================================
+# Mutation batch size (concurrent requests)
+# - 1 = Sequential (default, safest)
+# - 5 = Process 5 mutations in parallel
+# - 10 = Process 10 mutations in parallel
+mutationBatchSize=1
+# Alias batching (combine multiple mutations into single request)
+# - undefined = Disabled (default, use separate requests)
+# - 5 = Combine 5 mutations per aliased request
+# - 10 = Combine 10 mutations per aliased request
+mutationsPerAliasBatch=
+# ============================================================================
+# Fluent Commerce Configuration (Optional)
+# ============================================================================
+# Retailer ID - Only if mutation schema requires retailerId in input
+# Standard createLocation does NOT require this field
+# Check your GraphQL schema to determine if needed
+retailerId=my-retailer-id
+```
+**Notes:**
+- Webhook security is handled by Versori's native connection authentication. No manual API key configuration needed.
+- `retailerId` - Standard createLocation does not have this field. Only use if YOUR custom schema requires it.
+- See `fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md` for details.
+---
+## Schema Validation CLI Commands
+Before deploying, validate your field mappings against the Fluent GraphQL schema:
+### 1. Introspect Schema
+```bash
+# Generate schema.json from live Fluent API
+npx fc-connect introspect-schema \
+  --url https://api.fluentcommerce.com/graphql \
+  --client-id your-client-id \
+  --client-secret your-client-secret \
+  --output schema.json
+```
+### 2. Create Mapping Config File
+**File: location-mapping.json**
+```json
+{
+  "version": "1.0.0",
+  "mutation": "createLocation",
+  "sourceFormat": "xml",
+  "returnFields": ["id", "ref", "name", "type", "status"],
+  "description": "XML location to Fluent Commerce GraphQL mapping",
+  "fields": {
+    "ref": { "source": "location.@ref", "required": true, "resolver": "sdk.trim" },
+    "name": { "source": "location.name", "required": true, "resolver": "sdk.trim" },
+    "type": { "source": "location.@type", "required": true, "resolver": "sdk.uppercase" },
+    "primaryAddress.ref": { "source": "location.@ref", "required": true },
+    "primaryAddress.street": { "source": "location.address.street1" },
+    "primaryAddress.latitude": {
+      "source": "location.coordinates.@lat",
+      "resolver": "sdk.parseFloat"
+    },
+    "primaryAddress.longitude": {
+      "source": "location.coordinates.@lon",
+      "resolver": "sdk.parseFloat"
+    }
+  }
+}
+```
+### 3. Validate Mapping
+```bash
+# Validate that all target fields exist in schema
+npx fc-connect validate-schema \
+  --mapping location-mapping.json \
+  --schema schema.json
+```
+### 4. Analyze Coverage
+```bash
+# Check which Location fields are mapped vs available
+npx fc-connect analyze-coverage \
+  --mapping location-mapping.json \
+  --schema schema.json \
+  --type CreateLocationInput
+```
+**Output:**
+```
+✅ Mapped: 15/42 fields (35%)
+❌ Missing required: timezone (String!)
+⚠️  Optional unmapped: supportPhoneNumber, networkId, attributes
+```
+---
+## Testing Locally
+### 1. Upload Test XML to S3
+```bash
+aws s3 cp test-location.xml s3://my-location-bucket/locations/test-location.xml
+```
+### 2. Deploy to Versori
+```bash
+npm run deploy
+```
+### 3. Manual Testing
+```bash
+# Trigger manual sync (auth handled by Versori connection)
+curl -X POST https://your-workspace.versori.run/location-xml-adhoc
+# Check job status
+curl -X POST https://your-workspace.versori.run/location-xml-job-status \
+  -H "Content-Type: application/json" \
+  -d '{"jobId": "location-xml-adhoc-1737525600000"}'
+```
+### 4. Verify Processing
+- Upload a small XML to S3 (2-3 locations) and trigger `adhoc` webhook
+- Verify GraphQL mutations are executed for each location
+- Confirm file moved from `locations/` to `processed/` in S3
+- Check KV state: errors and last processed metadata
+- Monitor rate limiting: verify mutations respect configured rate
+---
+## Deployment
+```bash
+# Deploy to Versori
+npm run deploy
+# View logs
+npm run logs
+# Monitor execution
+versori logs --follow
+```
+---
+## Monitoring
+### Success Response
+```json
+{
+  "success": true,
+  "jobId": "location-xml-scheduled-1737525600000",
+  "processed": 3,
+  "skipped": 0,
+  "failed": 0,
+  "totalRecords": 12,
+  "errors": []
+}
+```
+### Partial Success Response
+```json
+{
+  "success": true,
+  "jobId": "location-xml-scheduled-1737525600000",
+  "processed": 3,
+  "skipped": 1,
+  "failed": 0,
+  "totalRecords": 10,
+  "errors": ["locations-003.xml: 2 mapping errors"]
+}
+```
+### Error Response
+```json
+{
+  "success": false,
+  "jobId": "location-xml-scheduled-1737525600000",
+  "processed": 0,
+  "skipped": 0,
+  "failed": 1,
+  "totalRecords": 0,
+  "errors": ["locations-001.xml: Invalid XML structure"]
+}
+```
+---
+## Common Pitfalls and Solutions
+### 1. XML Attribute Not Found
+**Symptoms**: Mapping errors like "field not found"
+**Solution**:
+```typescript
+// ❌ WRONG - Missing @ prefix for attribute
+ref: {
+  source: 'location.ref';
+}
+// ✅ CORRECT - Use @ prefix for XML attributes
+ref: {
+  source: 'location.@ref';
+}
+```
+### 2. Single Element Not Array
+**Symptoms**: "Cannot read property forEach of undefined"
+**Solution**:
+```typescript
+// Always normalize to array
+const locationsData = xmlData.locations?.location;
+const locations = Array.isArray(locationsData) ? locationsData : [locationsData];
+```
+### 3. Rate Limiting Too Aggressive
+**Symptoms**: Slow processing, mutations taking too long
+**Solution**:
+```bash
+# Increase rate limit (mutations per second)
+mutationRateLimit=10  # Default is 5
+```
+### 4. Empty Element vs Missing Element
+**Solution**:
+```typescript
+// Use required: false and defaultValue for optional fields
+'primaryAddress.street2': {
+  source: 'location.address.street2',
+  required: false,
+  defaultValue: ''
+}
+```
+### 5. S3 Access Denied
+**Symptoms**: S3 operations fail with 403 errors
+**Solution**: Validate IAM permissions
+**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-location-bucket", "arn:aws:s3:::my-location-bucket/*"]
+    }
+  ]
+}
+```
+### 6. GraphQL Schema Mismatch
+**Symptoms**: Mutation errors like "Unknown field", "Invalid input type"
+**Solution**: Use CLI tools to validate mappings
+```bash
+npx fc-connect validate-schema --mapping location-mapping.json --schema schema.json
+```
+### 7. Nested Object Mapping Errors
+**Symptoms**: Flat structure instead of nested objects in mutation input
+**Solution**: Use dot notation in field mapping
+```typescript
+// ✅ CORRECT - Creates nested structure
+'primaryAddress.city': { source: 'location.address.city' }
+// ❌ WRONG - Creates flat structure
+primaryAddress_city: { source: 'location.address.city' }
+```
+### 8. retailerId Configuration Errors
+**Symptoms**: "retailerId is required" errors or confusion about when to use `setRetailerId()`
+**Solution**: Understand the correct pattern
+```typescript
+// ✅ CORRECT - GraphQL mutations don't need setRetailerId()
+// Check your GraphQL schema to determine retailerId handling:
+// - Mandatory retailerId → Must pass it in mutation input
+// - Optional retailerId → Can pass it if needed
+// - No retailerId field → Don't pass it
+// Standard createLocation does not have retailerId field in schema
+// ✅ IF mutation schema requires retailerId (mandatory):
+const { query, variables } = await mapper.map(location);
+if (retailerId && variables.input) {
+  variables.input.retailer = { id: parseInt(retailerId) };
+}
+await client.graphql({ query, variables });
+```
+**Reference:** `fc-connect-sdk/docs/00-START-HERE/retailerid-configuration.md`
+---
+## Key Takeaways
+### Architecture Patterns
+- **Service Function Composition**: Workflow broken into 3 service functions - `processFile()`, `executeMutations()`, `writeMutationLog()`
+- **Per-File Processing**: Main workflow orchestrates service functions for each file
+- **Clear Separation of Concerns**: Parse/map, execute mutations, logging are independent functions
+### SDK Usage
+- **Buffer Import (CRITICAL)**: Always `import { Buffer } from 'node:buffer'` for Deno/Versori runtime
+- **S3 Archival Deduplication**: Use `s3.moveFile()` to `processed/` subdirectory - PRIMARY deduplication mechanism
+- **NO VersoriFileTracker for S3**: S3 archival is simpler and more reliable
+- **StateService Role**: SECONDARY - provides metadata/history, not primary deduplication
+### XML Processing
+- **XML @ Prefix**: Always use `@` prefix for XML attributes (`location.@ref`)
+- **Array Normalization (CRITICAL)**: Handle single vs multiple elements with `Array.isArray()` check - single `<location>` becomes object, not array
+- **Nested Mapping**: Use dot notation for nested objects (`primaryAddress.street`, `openingSchedule.monStart`)
+### GraphQL Mutations
+- **NO setRetailerId() Required**: GraphQL mutations do NOT need `client.setRetailerId()` - only Job/Event API needs it
+- **retailerId in Input**: Check your GraphQL schema to determine retailerId handling:
+  - **Mandatory retailerId** - Field exists and is required (`!`) → Must pass it
+  - **Optional retailerId** - Field exists and is optional → Can pass it if needed
+  - **No retailerId field** - Field doesn't exist → Don't pass it
+- **Rate Limiting**: Implement configurable delays between mutations to avoid API throttling
+- **Retry Logic**: Exponential backoff for failed mutations with `retryWithBackoff()`
+- **Direct Mutations**: Use `client.graphql()` for location upserts (NOT Batch API)
+- **GraphQL vs Batch API**: Use GraphQL for low-volume master data, Batch API for high-volume inventory
+### Error Handling & Monitoring
+- **Error Recovery**: Exponential backoff for error state tracking with retry timestamps
+- **Mutation Logging**: Optional S3 JSON logs with detailed per-location mutation status
+- **Schema Validation**: Use CLI tools before deployment to catch mapping errors
+- **Archival Order**: Archive FIRST (deduplication), then KV tracking (metadata)
+---
+## Related Documentation
+### Core Guides
+- **GraphQL Mutation Mapping**: `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/readme.md`
+- **Universal Mapping**: `fc-connect-sdk/docs/02-CORE-GUIDES/mapping/modules/readme.md`
+- **XML Parser**: `fc-connect-sdk/docs/02-CORE-GUIDES/parsers/modules/05-xml-parser.md`
+- **Data Sources**: `fc-connect-sdk/docs/02-CORE-GUIDES/data-sources/readme.md`
+- **State Management**: `fc-connect-sdk/docs/03-PATTERN-GUIDES/file-operations/state-duplicate-prevention.md`
+### Related Templates
+- **CSV Version**: `template-ingestion-s3-csv-location-graphql.md`
+- **JSON Version**: `template-ingestion-s3-json-location-graphql.md`
+- **SFTP XML Version**: `template-ingestion-sftp-xml-location-graphql.md`
+- **Event API Pattern**: `../event-api/template-ingestion-s3-xml-product-event.md`
+- **Batch API Pattern**: `../batch-api/template-ingestion-s3-xml-inventory-batch.md`
+### CLI Tools
+- **Schema Introspection**: `fc-connect-sdk/bin/readme.md#introspect-schema`
+- **Mapping Validation**: `fc-connect-sdk/bin/readme.md#validate-schema`
+- **Coverage Analysis**: `fc-connect-sdk/bin/readme.md#analyze-coverage`
+### Patterns
+- **Error Handling**: `fc-connect-sdk/docs/01-TEMPLATES/patterns/error-handling-retry.md`
+- **Rate Limiting**: `fc-connect-sdk/docs/03-PATTERN-GUIDES/integration-patterns/rate-limiting.md`
+- **XML Patterns**: `fc-connect-sdk/docs/01-TEMPLATES/versori/patterns/xml-response-patterns.md`