@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-inventory-quantities-to-s3-csv.md

@@ -1,2464 +1,2464 @@
----
-template_id: tpl-extract-inventory-quantities-to-s3-csv
-canonical_filename: template-extraction-inventory-quantities-to-s3-csv.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: extraction
-source: fluent-graphql
-destination: s3-csv
-entity: inventoryQuantities
-format: csv
-logging: versori
-status: stable
-features:
-  - memory-management
-  - enhanced-logging
-  - pagination-progress
----
-
-# Template: Extraction - Inventory Quantities to S3 CSV
-
-**Template Version:** 2.0.0
-**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
-**🆕 Version 2.0.0 Enhancements:**
-- ✅ **Memory Management** - Clear large result sets after processing batches
-- ✅ **Enhanced Logging** - Pagination progress tracking with emoji indicators (📊, 📥, ✅)
-- ✅ **Pagination Progress** - Real-time page-by-page progress logging with metrics
-
----
-
-## 📚 STEP 1: Load These Docs (Human Checklist)
-
-1. REQUIRED (load all)
-   - [ ] fc-connect-sdk/docs/02-CORE-GUIDES/api-reference/
-   - [ ] fc-connect-sdk/docs/02-CORE-GUIDES/mapping/
-   - [ ] fc-connect-sdk/docs/03-PATTERN-GUIDES/data-sources/
-   - [ ] fc-connect-sdk/docs/03-PATTERN-GUIDES/parsers/
-   - [ ] fc-connect-sdk/docs/03-PATTERN-GUIDES/extraction/
-   - [ ] fc-connect-sdk/docs/04-REFERENCE/platforms/versori/
-
-Copy-paste list (open these):
-fc-connect-sdk/docs/02-CORE-GUIDES/api-reference/
-fc-connect-sdk/docs/02-CORE-GUIDES/mapping/
-fc-connect-sdk/docs/03-PATTERN-GUIDES/data-sources/
-fc-connect-sdk/docs/03-PATTERN-GUIDES/parsers/
-fc-connect-sdk/docs/03-PATTERN-GUIDES/extraction/
-fc-connect-sdk/docs/04-REFERENCE/platforms/versori/
-
----
-
-## 📋 STEP 2: Tell Your AI (Prompt)
-
-Copy/paste this prompt into your AI tool after loading the documentation above:
-
-```
-I need a Versori scheduled extractor that:
-
-1) Queries Fluent Commerce GraphQL for inventoryQuantities with auto-pagination
-2) Uses incremental mode with a 60-second overlap buffer stored in Versori KV
-3) Transforms results using UniversalMapper per mapping JSON
-4) Generates CSV with CSVParserService and uploads to S3
-5) Uses native Versori log (LoggingService removed - use native log)
-
-Use the loaded docs for SDK specifics and best practices. Keep structure identical to the template.
-```
-
----
-
-## 📦 SDK Imports (Verified - Versori Optimized)
-
-```typescript
-import { Buffer } from 'node:buffer';
-import {
-  createClient,
-  UniversalMapper,
-  S3DataSource,
-  CSVParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-import { schedule, http } from '@versori/run';
-```
-
----
-
-# Versori Scheduled: Inventory Quantities Extraction to S3 CSV (Configurable)
-
-**FC Connect SDK Use Case Guide**
-
-> SDK: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> Version: `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`
-
-Context: Scheduled Versori workflow that extracts inventory quantities (detailed quantity records) from Fluent Commerce via GraphQL query with **configurable extraction modes**, transforms with `UniversalMapper`, and writes CSV files to S3 for analytics and reporting.
-
-**Pattern**: EXTRACTION (Fluent → S3 CSV)
-**Entity**: inventoryQuantities
-**Complexity**: High | Runtime: Versori Platform (Scheduled)
-
----
-
-## ⚠️ IMPORTANT: Sample Code for SDK Demonstration Only
-
-> **🔴 PRODUCTION WARNING**
->
-> This guide demonstrates FC Connect SDK capabilities for **extraction and mapping workflows**. The multiple extraction modes (incremental, dateRange, historical) are included to show SDK flexibility and serve as **reference examples**.
->
-> **✅ PRODUCTION RECOMMENDATION:**
->
-> - **ONLY use INCREMENTAL mode with scheduled runs** (e.g., daily/hourly)
-> - Incremental mode is safe, efficient, and production-ready
-> - Uses overlap buffer to prevent missed records
-> - Natural rate limiting via timestamps
->
-> **🚫 DO NOT USE IN PRODUCTION:**
->
-> - **dateRange mode** - High risk of platform overload with large date windows
-> - **historical mode** - Extremely dangerous, can fetch millions of records
-> - These modes are **demonstration only** to show SDK query patterns
-> - Using these modes on large inventory datasets can crash your runtime and impact platform stability
->
-> **📝 If you need historical data:**
->
-> - Run multiple small incremental extractions (e.g., daily for past 30 days)
-> - Use one-time migration scripts with proper monitoring (not scheduled workflows)
-> - Always validate date ranges and implement file splitting
-> - Get explicit approval before running large extractions
->
-> **This sample code shows HOW to use the SDK - not WHAT to use in production.**
-
----
-
-## What You'll Build
-
-- **Three extraction modes**: Incremental, Date Range, or Historical
-- **State management** with VersoriKVAdapter to track last successful run
-- GraphQL query with auto-pagination
-- UniversalMapper transformation for reporting schema
-- CSV file generation with CSVParserService
-- S3 upload to analytics system
-- **Failure recovery** with timestamp tracking
-
-## Business Use Cases
-
-**1. Incremental Daily Sync (Analytics)**
-
-- Extract only changed inventory quantities since last run
-- Run daily at 2 AM
-- Minimize data transfer
-- Track changes over time
-
-**2. Date Range Extract (Audit)**
-
-- Extract quantity changes within specific date window
-- For audits, reconciliation, historical analysis
-- Example: "Show all quantity changes between Jan 1-15"
-
-**3. Historical Backfill**
-
-- Extract all quantities created within date range
-- For initial data warehouse load
-- One-time backfill operation
-
-## Inventory Quantities vs Positions
-
-**InventoryQuantity** = Specific quantity record (retailer-defined types)
-
-- Individual records: e.g., LAST_ON_HAND, RESERVED, DELTA, SALE, CORRECTION (plus any custom IQ types)
-- Multiple quantities per product/location
-- Fields: locationRef, skuRef, qty, type, status, expectedOn (if applicable)
-- Used for: Detailed tracking, audit trails
-
-**InventoryPosition** = Aggregated on-hand calculation
-
-- One position per product/location
-- Calculated `onHand` from all associated quantities
-- Used for: Stock availability, reporting
-
-## SDK Methods Used
-
-```typescript
-import { Buffer } from 'node:buffer';
-import {
-  createClient,
-  UniversalMapper,
-  S3DataSource,
-  VersoriKVAdapter,
-  CSVParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-await createClient(ctx);
-await client.graphql({ query, variables, pagination });
-new VersoriKVAdapter(ctx.openKv(':project:'));
-new UniversalMapper(exportMapping);
-const csvParser = new CSVParserService({ includeHeaders: true });
-const csvContent = await csvParser.stringify(rows);
-await s3.uploadFile(key, Buffer.from(csvContent, 'utf8'), options);
-```
-
-## Activation Variables
-
-```json
-{
-  "retailerId": "your-retailer-id",
-  "s3BucketName": "inventory-audit-exports",
-  "awsAccessKeyId": "AKIAXXXXXXXXXXXX",
-  "awsSecretAccessKey": "********",
-  "awsRegion": "us-east-1",
-  "s3Prefix": "inventory-quantities/daily/",
-  "fileNamePrefix": "inventoryquantities",
-  "catalogueRef": "DEFAULT_CATALOGUE",
-  "pageSize": 200,
-  "maxRecords": 100000,
-  "extractionMode": "incremental",
-  "fallbackStartDate": "2024-01-01T00:00:00Z",
-  "overlapBufferSeconds": "60",
-  "startDate": "",
-  "endDate": ""
-}
-```
-
-### Variable Reference
-
-| Variable | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `retailerId` | string | Yes | - | Fluent Commerce retailer ID |
-| `s3BucketName` | string | Yes | - | S3 bucket for CSV export |
-| `awsAccessKeyId` | string | Yes | - | AWS access key with S3 write permissions |
-| `awsSecretAccessKey` | string | Yes | - | AWS secret access key |
-| `awsRegion` | string | Yes | - | AWS region (e.g., `us-east-1`) |
-| `s3Prefix` | string | No | `""` | S3 key prefix (e.g., `inventory-quantities/daily/`) |
-| `fileNamePrefix` | string | No | `"inventoryquantities"` | CSV filename prefix |
-| `catalogueRef` | string | No | - | Filter by catalogue reference (optional) |
-| `pageSize` | number | No | `200` | GraphQL page size (max 500) |
-| `maxRecords` | number | No | `100000` | Maximum records per extraction |
-| `extractionMode` | string | No | `"incremental"` | Extraction mode: `incremental`, `dateRange`, or `historical` |
-| `fallbackStartDate` | string | No | `"2024-01-01T00:00:00Z"` | Fallback date if no state exists |
-| `overlapBufferSeconds` | number | No | `60` | Overlap buffer to prevent missed records (seconds) |
-| `startDate` | string | No | - | Manual start date (for `dateRange`/`historical` modes) |
-| `endDate` | string | No | - | Manual end date (for `dateRange`/`historical` modes) |
-
-### Extraction Mode Configuration
-
-**Mode 1: Incremental (default)**
-
-```json
-{
-  "extractionMode": "incremental",
-  "fallbackStartDate": "2024-01-01T00:00:00Z"
-}
-```
-
-Extracts quantities with `updatedOn > lastRunTime`. Ideal for daily syncs.
-
-**Mode 2: Date Range**
-
-```json
-{
-  "extractionMode": "dateRange",
-  "startDate": "2025-01-01T00:00:00Z",
-  "endDate": "2025-01-15T23:59:59Z"
-}
-```
-
-Extracts quantities updated between `startDate` and `endDate`. Ideal for audits.
-
-**Mode 3: Historical**
-
-```json
-{
-  "extractionMode": "historical",
-  "startDate": "2024-01-01T00:00:00Z",
-  "endDate": "2024-12-31T23:59:59Z"
-}
-```
-
-Extracts quantities created between `startDate` and `endDate` using `createdOn` filter.
-
-## ⚠️ Production Safety & Guardrails
-
-### Critical: Extraction Mode Selection
-
-**🟢 RECOMMENDED: Incremental Mode (Production)**
-
-- Safe for automated schedules
-- Natural rate limiting via timestamps
-- Predictable resource usage
-- **Use this for all production workflows**
-
-**🟡 CAUTION: Date Range Mode (Audit/Backfill)**
-
-- **Maximum 30-day window enforced**
-- Use for specific audit requests only
-- Run during off-peak hours
-- Monitor resource usage
-
-**🔴 DANGER: Historical Mode (One-Time Only)**
-
-- **Maximum 90-day window enforced**
-- **Requires explicit approval**
-- **Risk of platform overload**
-- Can fetch millions of records
-- Use multiple small incremental runs instead
-- Only for initial data migration
-
-### Date Range Validation (Required)
-
-```typescript
-// Validate date range limits to prevent platform overload
-function validateDateRange(mode, startDate, endDate) {
-  if (mode === 'incremental') return { valid: true };
-
-  if (!startDate || !endDate) {
-    return {
-      valid: false,
-      error: `${mode} mode requires both startDate and endDate`,
-    };
-  }
-
-  const start = new Date(startDate);
-  const end = new Date(endDate);
-  const daysDiff = (end - start) / (1000 * 60 * 60 * 24);
-
-  // Guardrail: Maximum date ranges
-  const maxDays = mode === 'dateRange' ? 30 : 90;
-
-  if (daysDiff > maxDays) {
-    return {
-      valid: false,
-      error: `${mode} mode: Maximum ${maxDays}-day window. Requested: ${Math.round(daysDiff)} days. Use multiple smaller extractions or incremental mode.`,
-      recommendation: `Split into ${Math.ceil(daysDiff / maxDays)} separate extractions of ${maxDays} days each.`,
-    };
-  }
-
-  if (daysDiff < 0) {
-    return { valid: false, error: 'endDate must be after startDate' };
-  }
-
-  return { valid: true };
-}
-```
-
-### File Splitting Configuration
-
-Large extractions must split into multiple files to prevent memory issues and upload failures.
-
-```json
-{
-  "maxRecordsPerFile": 50000,
-  "maxFileSizeMB": 100,
-  "enableFileSplitting": true
-}
-```
-
-**File Naming Pattern:**
-
-```
-{prefix}inventory-quantities-{timestamp}-part-{sequence}.csv
-
-Examples:
-inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-001.csv
-inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-002.csv
-inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-manifest.json
-```
-
-**Manifest File (auto-generated):**
-
-```json
-{
-  "extractionId": "inventory-quantities-2025-01-22T14-30-00Z",
-  "totalRecords": 127543,
-  "totalFiles": 3,
-  "files": [
-    {
-      "filename": "inventory-quantities-2025-01-22T14-30-00Z-part-001.csv",
-      "recordCount": 50000,
-      "s3Key": "inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-001.csv"
-    },
-    {
-      "filename": "inventory-quantities-2025-01-22T14-30-00Z-part-002.csv",
-      "recordCount": 50000,
-      "s3Key": "inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-002.csv"
-    },
-    {
-      "filename": "inventory-quantities-2025-01-22T14-30-00Z-part-003.csv",
-      "recordCount": 27543,
-      "s3Key": "inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-003.csv"
-    }
-  ],
-  "extractionMode": "dateRange",
-  "dateRange": {
-    "from": "2025-01-01T00:00:00Z",
-    "to": "2025-01-31T23:59:59Z"
-  },
-  "completedAt": "2025-01-22T14:35:27Z"
-}
-```
-
-### Hard Limits (Enforced)
-
-```typescript
-const SAFETY_LIMITS = {
-  // Maximum records per single extraction
-  MAX_RECORDS_TOTAL: 500000, // 500k hard limit
-
-  // Maximum records per file before splitting
-  MAX_RECORDS_PER_FILE: 50000, // 50k per file
-
-  // Maximum file size before splitting
-  MAX_FILE_SIZE_MB: 100, // 100MB per file
-
-  // Date range limits
-  MAX_DATE_RANGE_DAYS: 30, // dateRange mode
-  MAX_HISTORICAL_DAYS: 90, // historical mode
-
-  // Pagination limits
-  MAX_PAGE_SIZE: 500, // Fluent API limit
-  RECOMMENDED_PAGE_SIZE: 200, // Balance throughput/memory
-
-  // Memory management
-  CHUNK_SIZE: 10000, // Process in chunks
-};
-```
-
-### Memory-Safe Implementation Pattern
-
-```typescript
-// Process large extractions in chunks to prevent OOM
-async function processLargeExtraction(edges, mapper, csvParser, s3, options) {
-  const CHUNK_SIZE = 10000;
-  const MAX_RECORDS_PER_FILE = options.maxRecordsPerFile || 50000;
-
-  let fileSequence = 1;
-  let currentFileRecords = [];
-  const manifestFiles = [];
-
-  for (let i = 0; i < edges.length; i += CHUNK_SIZE) {
-    const chunk = edges.slice(i, i + CHUNK_SIZE);
-
-    // Bulk mapping for chunk
-    const chunkNodes = chunk.map(edge => edge.node);
-    const mappingResult = await mapper.map(chunkNodes);
-
-    if (!mappingResult.success) {
-      const mappingErrors = mappingResult.errors || ['Unknown mapping failure'];
-      log.error('Chunk mapping failed', {
-        chunkIndex: i / CHUNK_SIZE,
-        errorCount: mappingErrors.length,
-        sampleErrors: mappingErrors.slice(0, 3),
-      });
-      throw new Error(`Mapping failed: ${mappingErrors[0] || 'Unknown error'}`);
-    }
-
-    const transformedChunk = mappingResult.data || [];
-    const mappingErrors = mappingResult.errors || [];
-
-    if (mappingErrors.length > 0) {
-      log.warn('Some records in chunk failed transformation', {
-        chunkIndex: i / CHUNK_SIZE,
-        errorCount: mappingErrors.length,
-      });
-    }
-
-    if (mappingResult.skippedFields && mappingResult.skippedFields.length > 0) {
-      log.info('ℹ️ [MAPPING] Optional fields skipped (undefined values)', {
-        chunkIndex: i / CHUNK_SIZE,
-        skippedFields: mappingResult.skippedFields,
-        note: 'These fields were not present in source data. Add defaultValue to mapping config if they should always appear.',
-      });
-    }
-
-    // Add to current file, handling splits
-    for (const record of transformedChunk) {
-      currentFileRecords.push(record);
-
-      // Split file when limit reached
-      if (currentFileRecords.length >= MAX_RECORDS_PER_FILE) {
-        const fileInfo = await writeFileToS3(
-          currentFileRecords,
-          fileSequence++,
-          csvParser,
-          s3,
-          options
-        );
-        manifestFiles.push(fileInfo);
-        currentFileRecords = []; // Reset for next file
-      }
-    }
-  }
-
-  // Write remaining records
-  if (currentFileRecords.length > 0) {
-    const fileInfo = await writeFileToS3(
-      currentFileRecords,
-      fileSequence++,
-      csvParser,
-      s3,
-      options
-    );
-    manifestFiles.push(fileInfo);
-  }
-
-  // Write manifest
-  await writeManifest(manifestFiles, s3, options);
-
-  return manifestFiles;
-}
-```
-
-### Enterprise Time Buffer Configuration
-
-```json
-{
-  "overlapBufferSeconds": "60"
-}
-```
-
-**Default: 60 seconds (recommended for most deployments)**
-
-**Purpose**: Prevents missed records due to:
-
-- **Clock skew** between Fluent API servers (typically 1-5 seconds)
-- **Transaction timing** - records updated during query execution
-- **Race conditions** - records updated between extraction runs
-
-**How It Works**:
-
-- **Query**: Uses `updatedOn >= (lastRunTime - 60 seconds)`
-- **Save**: Stores `MAX(updatedOn)` WITHOUT buffer
-- **Result**: Records from the last minute of previous extraction are included again
-
-**Buffer Sizes by Deployment**:
-
-- `30` - Low-latency single-region (minimal clock skew expected)
-- `60` - **Standard production** (recommended default)
-- `300` - Cross-region deployments or high-latency networks
-
-**Duplicate Handling**: Downstream systems should upsert by `quantity_id` (idempotent). Duplicates are safe and expected.
-
-### Timezone Handling
-
-**All timestamps are in ISO 8601 format (UTC)**:
-
-```typescript
-// Input: ISO 8601 UTC timestamp
-const timestamp = '2025-01-22T14:30:00.000Z';
-
-// JavaScript Date operations preserve UTC
-new Date(timestamp).toISOString();
-// Returns: "2025-01-22T14:30:00.000Z" (same format)
-
-new Date(timestamp).getTime();
-// Returns: 1737558600000 (UTC epoch milliseconds)
-
-// Subtract 60 seconds for buffer
-const buffered = new Date(new Date(timestamp).getTime() - 60000).toISOString();
-// Returns: "2025-01-22T14:29:00.000Z"
-```
-
-**Key Points**:
-
-- Fluent API returns all timestamps in UTC
-- `.getTime()` returns UTC epoch milliseconds
-- Buffer arithmetic is done in milliseconds
-- `.toISOString()` converts back to ISO 8601 UTC
-- No timezone conversion needed
-
-## Export Mapping Configuration
-
-Create file: `./config/inventory-quantities.export.json`
-
-```json
-{
-  "name": "inventory-quantities.export",
-  "version": "1.0.0",
-  "description": "Fluent Inventory Quantities → CSV Export Mapping",
-  "fields": {
-    "quantity_id": { "source": "id", "required": true, "resolver": "sdk.trim" },
-    "quantity_ref": { "source": "ref", "required": true, "resolver": "sdk.trim" },
-    "catalogue_ref": { "source": "catalogue.ref", "required": false, "resolver": "sdk.trim" },
-    "catalogue_name": { "source": "catalogue.name", "required": false, "resolver": "sdk.trim" },
-    "location": { "source": "locationRef", "required": true, "resolver": "sdk.trim" },
-    "sku": { "source": "skuRef", "required": true, "resolver": "sdk.trim" },
-    "quantity": { "source": "qty", "required": true, "resolver": "sdk.parseInt" },
-    "type": { "source": "type", "required": true, "resolver": "sdk.uppercase" },
-    "status": { "source": "status", "required": true, "resolver": "sdk.uppercase" },
-    "expected_on": { "source": "expectedOn", "resolver": "sdk.formatDate" },
-    "created_on": { "source": "createdOn", "resolver": "sdk.formatDate" },
-    "updated_on": { "source": "updatedOn", "required": true, "resolver": "sdk.formatDate" }
-  }
-}
-```
-
-## Mapping & Resolvers Explained
-
-This section explains how the SDK transforms raw GraphQL data into your CSV export format using **UniversalMapper** and **SDK resolvers**.
-
-### SDK Resolvers Used
-
-| Field            | Resolver         | Why?                                       | Example Transformation                          |
-| ---------------- | ---------------- | ------------------------------------------ | ----------------------------------------------- |
-| `quantity_id`    | `sdk.trim`       | Clean quantity IDs from whitespace         | `" Q001 "` → `"Q001"`                           |
-| `quantity_ref`   | `sdk.trim`       | Clean quantity references                  | `" QTY-REF-001 "` → `"QTY-REF-001"`             |
-| `catalogue_ref`  | `sdk.trim`       | Clean catalogue references                 | `" DEFAULT_CATALOGUE "` → `"DEFAULT_CATALOGUE"` |
-| `catalogue_name` | `sdk.trim`       | Clean catalogue names                      | `" Default Catalogue "` → `"Default Catalogue"` |
-| `location`       | `sdk.trim`       | Clean location references                  | `" DC01 "` → `"DC01"`                           |
-| `sku`            | `sdk.trim`       | Clean SKU references                       | `" SKU-001 "` → `"SKU-001"`                     |
-| `quantity`       | `sdk.parseInt`   | Parse quantity as integer for calculations | `"100"` → `100`                                 |
-| `type`           | `sdk.uppercase`  | Normalize type codes                       | `"available"` → `"AVAILABLE"`                   |
-| `status`         | `sdk.uppercase`  | Normalize status codes                     | `"active"` → `"ACTIVE"`                         |
-| `expected_on`    | `sdk.formatDate` | Format dates for CSV export                | `"2025-01-30T00:00:00.000Z"` → `"2025-01-30"`   |
-| `created_on`     | `sdk.formatDate` | Format created timestamps                  | `"2025-01-15T10:00:00.000Z"` → `"2025-01-15"`   |
-| `updated_on`     | `sdk.formatDate` | Format updated timestamps for tracking     | `"2025-01-22T08:30:00.000Z"` → `"2025-01-22"`   |
-
-### Transformation Flow
-
-```typescript
-// 1. GraphQL Response (raw data from Fluent Commerce)
-const rawQuantity = {
-  id: ' Q001 ',
-  ref: ' QTY-REF-001 ',
-  locationRef: ' DC01 ',
-  skuRef: ' SKU-001 ',
-  qty: '100',
-  type: 'available',
-  status: 'active',
-  expectedOn: null,
-  createdOn: '2025-01-15T10:00:00.000Z',
-  updatedOn: '2025-01-22T08:30:00.000Z',
-  catalogue: {
-    ref: ' DEFAULT_CATALOGUE ',
-    name: ' Default Catalogue ',
-  },
-};
-
-// 2. UniversalMapper applies SDK resolvers
-const mapper = new UniversalMapper(inventoryQuantitiesExportMapping);
-const result = await mapper.map(rawQuantity);
-
-// 3. Transformed Output (clean, normalized for CSV)
-const transformedQuantity = {
-  quantity_id: 'Q001',
-  quantity_ref: 'QTY-REF-001',
-  catalogue_ref: 'DEFAULT_CATALOGUE',
-  catalogue_name: 'Default Catalogue',
-  location: 'DC01',
-  sku: 'SKU-001',
-  quantity: 100,
-  type: 'AVAILABLE',
-  status: 'ACTIVE',
-  expected_on: '', // null → empty string
-  created_on: '2025-01-15',
-  updated_on: '2025-01-22',
-};
-```
-
-### Custom Resolvers for Inventory Quantity-Specific Logic
-
-While the mapping above uses built-in SDK resolvers, you can extend with custom business logic:
-
-```typescript
-const customResolvers = {
-  /**
-   * Validate that quantity values are positive
-   */
-  'custom.validateQuantity': (qty: any) => {
-    const parsed = parseInt(qty) || 0;
-    return parsed >= 0 ? parsed : 0; // Ensure non-negative
-  },
-
-  /**
-   * Add human-readable type descriptions for reporting
-   */
-  'custom.enrichQuantityType': (type: string) => {
-    const typeDescriptions: Record<string, string> = {
-      LAST_ON_HAND: 'Last recorded on-hand quantity',
-      RESERVED: 'Reserved against orders',
-      DELTA: 'Incremental change (adjustment delta)',
-      SALE: 'Quantity decreased due to sale',
-      CORRECTION: 'Manual correction entry',
-    };
-    return typeDescriptions[(type || '').toUpperCase()] || type;
-  },
-
-  /**
-   * Check if expected date is in the future
-   */
-  'custom.isExpectedInFuture': (expectedOn: string) => {
-    if (!expectedOn) return false;
-    return new Date(expectedOn) > new Date();
-  },
-
-  /**
-   * Calculate days until expected arrival
-   */
-  'custom.calculateDaysUntilExpected': (expectedOn: string) => {
-    if (!expectedOn) return null;
-    const expected = new Date(expectedOn);
-    const today = new Date();
-    const diffMs = expected.getTime() - today.getTime();
-    return Math.ceil(diffMs / (1000 * 60 * 60 * 24));
-  },
-
-  /**
-   * Validate status-type combinations
-   */
-  'custom.validateQuantityStatus': (_quantity: any) => {
-    // Example placeholder – adapt rules to your retailer-defined IQ types
-    return 'VALID';
-  },
-};
-
-// Use custom resolvers with UniversalMapper
-const mapper = new UniversalMapper(inventoryQuantitiesExportMapping, {
-  customResolvers,
-});
-```
-
-### Available SDK Resolvers
-
-The SDK provides these built-in resolvers (no custom code needed):
-
-**String Transformations:**
-
-- `sdk.trim` - Remove leading/trailing whitespace
-- `sdk.uppercase` - Convert to uppercase
-- `sdk.lowercase` - Convert to lowercase
-- `sdk.toString` - Convert to string
-
-**Number Parsing:**
-
-- `sdk.parseInt` - Parse as integer
-- `sdk.parseFloat` - Parse as decimal
-- `sdk.number` - Parse as number (auto-detect int/float)
-
-**Date Formatting:**
-
-- `sdk.formatDate` - ISO 8601 date only (YYYY-MM-DD)
-- `sdk.formatDateShort` - Short date format
-- `sdk.parseDate` - Parse various date formats
-
-**Type Conversions:**
-
-- `sdk.boolean` - Convert to boolean
-- `sdk.parseJson` - Parse JSON strings
-- `sdk.toJson` - Convert to JSON string
-
-**Utilities:**
-
-- `sdk.identity` - Return value unchanged
-- `sdk.coalesce` - Return first non-null value
-
-See [Universal Mapping Guide](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for complete resolver documentation.
-
-## GraphQL Query
-
-```graphql
-query GetInventoryQuantities(
-  $retailerId: ID!
-  $updatedAfter: DateTime
-  $createdAfter: DateTime
-  $first: Int!
-  $after: String
-) {
-  inventoryQuantities(
-    retailerId: $retailerId
-    updatedOn: { after: $updatedAfter }
-    createdOn: { after: $createdAfter }
-    first: $first
-    after: $after
-  ) {
-    edges {
-      node {
-        id
-        ref
-        locationRef
-        skuRef
-        qty
-        type
-        status
-        expectedOn
-        createdOn
-        updatedOn
-        catalogue {
-          ref
-          name
-        }
-      }
-      cursor
-    }
-    pageInfo {
-      hasNextPage
-      # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
-    }
-  }
-}
-```
-
-## Guardrails Implementation (Required)
-
-```typescript
-// Overlap buffer (safety window)
-const overlapBufferSeconds = parseInt(
-  ctx.activation?.getVariable('overlapBufferSeconds') || '60',
-  10
-);
-const OVERLAP_BUFFER_MS = overlapBufferSeconds * 1000;
-
-// Read last successful run and apply buffer
-const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
-const stateKey = ['extraction', 'inventory-quantities-csv', 'lastRunTime'];
-const lastRunState = await kv.get(stateKey);
-const rawLastRunTime = lastRunState?.value?.timestamp || fallbackStartDate;
-const bufferedLastRunTime = new Date(
-  new Date(rawLastRunTime).getTime() - OVERLAP_BUFFER_MS
-).toISOString();
-
-// Query WITH buffer
-const result = await client.graphql({
-  query: INVENTORY_QUANTITIES_QUERY,
-  variables: {
-    retailerId,
-    updatedAfter: bufferedLastRunTime,
-    first: pageSize,
-  },
-  pagination: { maxRecords },
-});
-
-const edges = result.data?.inventoryQuantities?.edges || [];
-
-// 🛡️ GUARDRAIL: Validate extraction size limits
-const MAX_RECORDS_PER_RUN = 500000;
-const ESTIMATED_BYTES_PER_RECORD = 300; // Smaller than positions
-const estimatedSizeMB = (edges.length * ESTIMATED_BYTES_PER_RECORD) / (1024 * 1024);
-const MAX_CSV_SIZE_MB = 100;
-
-if (edges.length > MAX_RECORDS_PER_RUN) {
-  log.error('Extraction limit exceeded', {
-    recordCount: edges.length,
-    maxAllowed: MAX_RECORDS_PER_RUN,
-  });
-  return {
-    success: false,
-    error: `Extraction limit exceeded: ${edges.length} records (max: ${MAX_RECORDS_PER_RUN})`,
-    recommendation: `Split into smaller extractions or increase extraction frequency`,
-    recordCount: edges.length,
-    maxAllowed: MAX_RECORDS_PER_RUN,
-  };
-}
-
-if (estimatedSizeMB > MAX_CSV_SIZE_MB) {
-  log.warn('CSV size approaching limit', {
-    estimatedSizeMB: estimatedSizeMB.toFixed(2),
-    maxAllowed: MAX_CSV_SIZE_MB,
-  });
-}
-
-log.info('Extraction limits validated', {
-  recordCount: edges.length,
-  estimatedSizeMB: estimatedSizeMB.toFixed(2),
-  withinLimits: true,
-});
-
-// Transform with UniversalMapper
-const mapper = new UniversalMapper(inventoryQuantitiesExportMapping);
-const transformedRecords: any[] = [];
-for (const edge of edges) {
-  const mapped = await mapper.map(edge.node);
-  if (mapped.success) {
-    transformedRecords.push(mapped.data);
-  }
-}
-
-// Save state WITHOUT buffer (use MAX(updatedOn))
-const maxUpdatedOn = transformedRecords.reduce((max, r) => {
-  const t = new Date(r.updated_on).getTime();
-  return t > max ? t : max;
-}, new Date(rawLastRunTime).getTime());
-
-await kv.set(stateKey, {
-  timestamp: new Date(maxUpdatedOn).toISOString(),
-  recordCount: transformedRecords.length,
-  extractedAt: new Date().toISOString(),
-  overlapBufferSeconds,
-});
-
-// Date range guardrails (if you add dateRange/historical modes)
-function validateDateRange(mode: 'dateRange' | 'historical', from: string, to: string) {
-  const start = new Date(from);
-  const end = new Date(to);
-  const daysDiff = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
-  const maxDays = mode === 'dateRange' ? 30 : 90;
-  if (daysDiff > maxDays) {
-    return {
-      valid: false,
-      error: `${mode} mode: Maximum ${maxDays}-day window. Requested: ${Math.round(daysDiff)} days.`,
-    };
-  }
-  if (daysDiff < 0) return { valid: false, error: 'endDate must be after startDate' };
-  return { valid: true };
-}
-```
-
----
-
-## Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`workflow()`** → Durable workflows (advanced, rarely used)
-
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from schedule/webhook)
-- **`fn()`** → Internal processing (chained from schedule/webhook)
-
-### Recommended Project Structure
-
-```
-inventory-quantities-extraction/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── scheduled/
-    │   │   └── daily-inventory-quantities-extraction.ts  # Scheduled: Daily extraction
-    │   │
-    │   └── webhook/
-    │       ├── adhoc-inventory-quantities-extraction.ts  # Webhook: Manual trigger
-    │       └── job-status-check.ts                      # Webhook: Status query
-    │
-    ├── services/
-    │   └── inventory-quantities-extraction.service.ts    # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── inventory-quantities.export.csv.json         # Mapping configuration
-```
-
----
-
-````csv
-quantity_id,quantity_ref,catalogue_ref,catalogue_name,location,sku,quantity,type,status,expected_on,created_on,updated_on
-Q001,QTY-REF-001,DEFAULT_CATALOGUE,Default Catalogue,DC01,SKU-001,100,AVAILABLE,ACTIVE,,2025-01-15T10:00:00Z,2025-01-22T08:30:00Z
-Q002,QTY-REF-002,DEFAULT_CATALOGUE,Default Catalogue,DC01,SKU-001,50,RESERVED,ACTIVE,,2025-01-16T11:00:00Z,2025-01-22T09:15:00Z
-Q003,QTY-REF-003,DEFAULT_CATALOGUE,Default Catalogue,DC02,SKU-002,200,EXPECTED,CREATED,2025-01-30T00:00:00Z,2025-01-17T12:00:00Z,2025-01-22T10:00:00Z
-Q004,QTY-REF-004,DEFAULT_CATALOGUE,Default Catalogue,STORE-NYC,SKU-003,25,AVAILABLE,ACTIVE,,2025-01-18T13:00:00Z,2025-01-22T11:00:00Z
-
-## Advanced Mapping Patterns
-
-### Array Mapping (Preserving Nested Structure)
-
-For nested data structures, use `isArray: true` pattern:
-
-```json
-{
-  "fields": {
-    "ref": { "source": "ref", "required": true },
-    "relatedItems": {
-      "source": "items",
-      "isArray": true,
-      "fields": {
-        "itemRef": { "source": "ref", "required": true },
-        "value": { "source": "value", "resolver": "sdk.parseFloat" }
-      }
-    }
-  }
-}
-````
-
-**When to use**:
-
-- **Flattened structure**: Simpler, easier for downstream systems
-- **Nested with arrays**: Complex data, preserves relationships
-
-### Nested Object Mapping
-
-**Option 1: Flattened paths** (recommended):
-
-```json
-{
-  "fields": {
-    "location_ref": { "source": "location.ref" },
-    "location_name": { "source": "location.name" }
-  }
-}
-```
-
-**Option 2: Nested object definition**:
-
-```json
-{
-  "fields": {
-    "location": {
-      "fields": {
-        "ref": { "source": "location.ref" },
-        "name": { "source": "location.name" }
-      }
-    }
-  }
-}
-```
-
-## Error Handling Strategies
-
-### Handling Mapping Failures
-
-**Strategy 1: Fail-fast (strict)**:
-
-```typescript
-if (errors.length > 0) {
-  throw new Error(`${errors.length} records failed mapping validation`);
-}
-```
-
-**Strategy 2: Threshold-based (recommended)**:
-
-```typescript
-const errorRate = errors.length / transformed.length;
-if (errorRate > 0.05) {
-  // 5% threshold
-  throw new Error(`Error rate too high: ${(errorRate * 100).toFixed(1)}%`);
-}
-```
-
-**Strategy 3: Upload error manifest**:
-
-```typescript
-if (errors.length > 0) {
-  const errorManifest = {
-    extractionTimestamp: new Date().toISOString(),
-    totalErrors: errors.length,
-    errors: errors.map(e => ({ record: e.record, errors: e.errors })),
-  };
-  // Upload to storage for review
-}
-```
-
-### State Management with Partial Failures
-
-**Recommended**: Only update state if extraction succeeded:
-
-```typescript
-if (errors.length === 0) {
-  await kv.set(stateKey, { timestamp: newTimestamp });
-  log.info('State updated - all records successful');
-} else {
-  log.warn('State NOT updated - will retry next run', {
-    failedRecords: errors.length,
-    willRetryNextRun: true,
-  });
-}
-```
-
-## GraphQL Query Validation & Testing
-
-### Schema Validation Workflow
-
-**Step 1: Introspect schema**
-
-```bash
-npx fc-connect introspect-schema \
-  --url https://your-instance.api.fluentcommerce.com/graphql \
-  --output fluent-schema.json
-```
-
-**Step 2: Validate mapping**
-
-```bash
-npx fc-connect validate-schema \
-  --mapping ./config/mapping.json \
-  --schema ./fluent-schema.json
-```
-
-**Step 3: Analyze coverage**
-
-```bash
-npx fc-connect analyze-coverage \
-  --mapping ./config/mapping.json \
-  --schema ./fluent-schema.json
-```
-
-### GraphQL Pagination Explained
-
-The SDK handles pagination automatically:
-
-```typescript
-await client.graphql({
-  query: QUERY,
-  variables: { first: pageSize },
-  pagination: { maxRecords }, // SDK handles cursors automatically
-});
-```
-
-## Date Format Handling
-
-| Format   | Resolver              | Output                     | Use Case  |
-| -------- | --------------------- | -------------------------- | --------- |
-| CSV/JSON | `sdk.formatDate`      | `2025-01-22T14:30:00.000Z` | ISO 8601  |
-| CSV/JSON | `sdk.formatDateShort` | `2025-01-22`               | Date only |
-| CSV/JSON | `sdk.toString`        | Pass through               | As-is     |
-
-## Monitoring & Alerting
-
-### Key Metrics to Track
-
-```typescript
-const metrics = {
-  extractionDurationMs: Date.now() - startTime,
-  recordCount: edges.length,
-  transformedCount: transformed.length,
-  failedCount: errors.length,
-  errorRate: ((errors.length / edges.length) * 100).toFixed(2) + '%',
-  fileSizeMB: (buffer.length / (1024 * 1024)).toFixed(2),
-  lastRunTime: rawLastRunTime,
-  newTimestamp: newTimestamp,
-};
-log.info('Extraction complete', metrics);
-```
-
-### Alert Thresholds
-
-```typescript
-const ALERTS = {
-  EXTRACTION_DURATION_MS: 5 * 60 * 1000, // 5 minutes
-  MAX_ERROR_RATE: 0.05, // 5%
-  MAX_FILE_SIZE_MB: 150, // 150MB
-  MAX_RECORDS_PER_RUN: 100000, // Adjust per entity
-};
-```
-
-## Testing Checklist
-
-**Before production deployment:**
-
-### 1. Schema Validation
-
-- [ ] Run `npx fc-connect introspect-schema`
-- [ ] Run `npx fc-connect validate-schema`
-- [ ] Run `npx fc-connect analyze-coverage`
-- [ ] Verify all `source` paths exist
-
-### 2. Mapping Testing
-
-- [ ] Test with sample data (maxRecords=10)
-- [ ] Verify required fields populated
-- [ ] Verify SDK resolvers work correctly
-- [ ] Test custom resolvers with edge cases
-
-### 3. Error Handling
-
-- [ ] Test with invalid data
-- [ ] Verify error collection
-- [ ] Test error threshold logic
-
-### 4. State Management
-
-- [ ] Verify overlap buffer prevents misses
-- [ ] Test state recovery after failure
-- [ ] Verify timestamp saved WITHOUT buffer
-
-### 5. File Operations
-
-- [ ] Test connection and upload
-- [ ] Verify file format validity
-- [ ] Test with large files (>50MB)
-
-### 6. Staging Environment
-
-- [ ] Run full extraction in staging
-- [ ] Verify file format with downstream system
-- [ ] Monitor duration and resource usage
-
-## Troubleshooting Guide
-
-**Issue**: "Extraction timeout after 10 minutes"
-
-- **Cause**: Too many records
-- **Fix**: Reduce maxRecords, increase frequency
-
-**Issue**: "Mapping errors for 50% of records"
-
-- **Cause**: Schema mismatch
-- **Fix**: Run schema validation, check field names
-
-**Issue**: "State not updating"
-
-- **Cause**: KV write failure or intentional retry
-- **Fix**: Check KV logs, verify state update code
-
-**Issue**: "First run exceeds limits"
-
-- **Cause**: No previous timestamp, fetches all
-- **Fix**: Set fallbackStartDate close to current, apply filters
-
-**Issue**: "Excessive duplicates"
-
-- **Cause**: Overlap buffer (expected) or timestamp not saved
-- **Fix**: Verify newTimestamp saved WITHOUT buffer
-
-## Security Best Practices
-
-### Credential Management
-
-**✅ DO**:
-
-- Store credentials in Versori activation variables
-- Rotate credentials quarterly
-- Use least-privilege accounts
-
-**❌ DON'T**:
-
-- Never log credentials
-- Never commit to git
-- Never share across environments
-
-### Data Security
-
-- Enable encryption in transit and at rest
-- Apply data retention policies
-- Monitor access logs
-- Use VPC/private networks for sensitive data
-
----
-
-```
-
----
-
-**Pattern**: Enterprise incremental extraction with overlap buffer for inventory quantities
-**⚠️ Sample Code**: For SDK demonstration only - **ONLY use incremental mode in production**
-**Key Learning**: Use VersoriKVAdapter for state management with 60-second overlap buffer
-**Critical**: Apply overlap buffer to prevent missed records due to clock skew (default: 60 seconds)
-**Buffer Pattern**: Query WITH buffer (`updatedOn >= lastRunTime - 60s`), save WITHOUT buffer (`MAX(updatedOn)`)
-**Timezone**: All timestamps are ISO 8601 UTC format - no conversion needed
-```
-
----
-
-## 🔧 Complete Production Code
-
-### 1. Entry Point (src/index.ts)
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * This file is the entry point for the Versori deployment.
- * It imports and re-exports workflows from their respective files:
- * 1. Scheduled extraction (runs automatically on cron schedule)
- * 2. Ad hoc webhook (manual trigger with optional date override)
- * 3. Job status webhook (query job progress)
- *
- * AI CUSTOMIZATION:
- * - Add new workflows by importing from their respective files
- * - Remove workflows by commenting out imports/exports
- * - Organize workflows by type (scheduled vs webhook) for clarity
- */
-
-import { scheduledInventoryQuantitiesExtraction } from './workflows/scheduled/daily-inventory-quantities-extraction';
-import { adhocInventoryQuantitiesExtraction } from './workflows/webhook/adhoc-inventory-quantities-extraction';
-import { inventoryQuantitiesJobStatus } from './workflows/webhook/job-status-check';
-
-// Register workflows with Versori platform
-// The platform will expose webhooks as HTTP endpoints and run scheduled workflows on cron schedule
-
-export {
-  scheduledInventoryQuantitiesExtraction, // Cron-based auto-run (NOT exposed as HTTP endpoint)
-  adhocInventoryQuantitiesExtraction,     // Manual webhook trigger (HTTP endpoint)
-  inventoryQuantitiesJobStatus,           // Job status query (HTTP endpoint)
-};
-```
-
----
-
-### 2. Workflows
-
-#### src/workflows/scheduled/daily-inventory-quantities-extraction.ts
-
-```typescript
-/**
- * WORKFLOW 1: Scheduled Extraction
- *
- * Purpose: Automated hourly extraction for incremental sync
- * Trigger: Cron schedule (every hour at minute 0)
- * State Update: Always updates lastSync timestamp
- *
- * AI CUSTOMIZATION:
- * - Change schedule: Replace '0 * * * *' with your cron expression
- *   Examples:
- *   - Every 30 min: '*/30 * * * *'
- *   - Daily at 2 AM: '0 2 * * *'
- *   - Every 15 min: '*/15 * * * *'
- */
-
-import { schedule, fn } from '@versori/run';
-import { executeInventoryQuantityExtraction } from '../../services/extraction-orchestration';
-import { generateJobId } from '../../utils/job-id-generator';
-
-/**
- * WORKFLOW 1: Scheduled Extraction
- *
- * Purpose: Automated hourly extraction for incremental sync
- * Trigger: Cron schedule (every hour at minute 0)
- * State Update: Always updates lastSync timestamp
- *
- * AI CUSTOMIZATION:
- * - Change schedule: Replace '0 * * * *' with your cron expression
- *   Examples:
- *   - Every 30 min: '*/30 * * * *'
- *   - Daily at 2 AM: '0 2 * * *'
- *   - Every 15 min: '*/15 * * * *'
- */
-export const scheduledInventoryQuantitiesExtraction = schedule(
-  'inventory-quantities-scheduled',
-  '0 * * * *',  // ← CUSTOMIZE: Cron expression
-  fn('execute-scheduled-extraction', async (ctx) => {
-    const { log, activation } = ctx;
-    const startTime = Date.now();
-
-    // Generate unique job ID for tracking
-    // Format: SCHEDULED_IQ_YYYYMMDD_HHMMSS_random
-    const jobId = generateJobId('SCHEDULED', 'INVENTORY_QUANTITIES');
-
-    log.info('🚀 [START] Scheduled extraction triggered', { jobId });
-
-    try {
-      // Execute main workflow (extraction → transform → upload)
-      const result = await executeInventoryQuantityExtraction(ctx, {
-        jobId,
-        triggeredBy: 'schedule',
-        updateState: true,        // Always update state for scheduled runs
-      });
-
-      const durationMs = Date.now() - startTime;
-
-      log.info('✅ [END] Scheduled extraction completed', {
-        jobId,
-        recordCount: result.recordsExtracted,
-        fileName: result.fileName,
-        durationMs,
-        durationSec: (durationMs / 1000).toFixed(2)
-      });
-
-      return result;
-
-    } catch (error: any) {
-      const durationMs = Date.now() - startTime;
-
-      log.error('❌ [ERROR] Scheduled extraction failed', {
-        jobId,
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        durationMs,
-        recommendation: 'Check Fluent API connectivity, S3 credentials, and date range configuration'
-      });
-      throw error;
-    }
-  }));
-```
-
----
-
-#### src/workflows/webhook/adhoc-inventory-quantities-extraction.ts
-
-```typescript
-/**
- * WORKFLOW 2: Ad hoc Extraction (Manual Trigger)
- *
- * Purpose: Manual extraction with optional date range override
- * Trigger: Webhook POST to /webhooks/inventory-quantities-adhoc
- * State Update: Optional (controlled by request payload)
- *
- * WEBHOOK PAYLOAD EXAMPLES:
- *
- * 1. Incremental (use last sync timestamp):
- *    {}
- *
- * 2. Date range (manual override):
- *    {
- *      "fromDate": "2025-01-01T00:00:00Z",
- *      "toDate": "2025-01-31T23:59:59Z",
- *      "updateState": false
- *    }
- *
- * AI CUSTOMIZATION:
- * - Add request validation
- * - Add authentication check
- * - Add custom filters from payload
- */
-
-import { webhook, fn } from '@versori/run';
-import { executeInventoryQuantityExtraction } from '../../services/extraction-orchestration';
-import { generateJobId } from '../../utils/job-id-generator';
-
-export const adhocInventoryQuantitiesExtraction = webhook(
-  'inventory-quantities-adhoc',
-  { connection: 'inventory-quantities-adhoc', response: { mode: 'sync' } },
-  fn('execute-adhoc-extraction', async (ctx) => {
-    const { data, log, connections, activation } = ctx;
-    const startTime = Date.now();
-
-    // Generate unique job ID
-    const jobId = generateJobId('ADHOC', 'INVENTORY_QUANTITIES');
-
-    // SECURITY: Authentication is enforced by Versori connection configuration
-    // Configure auth on the connection and reference it in webhook({ connection: '...' })
-
-    // Extract optional date override from webhook payload
-    const fromDate = data.fromDate as string | undefined;
-    const toDate = data.toDate as string | undefined;
-    const updateState = data.updateState === true;  // Default false; advance state only if explicitly true
-
-    log.info('🌐 [START] Ad hoc extraction triggered via webhook', {
-      jobId,
-      hasDateOverride: !!fromDate,
-      fromDate: fromDate || 'not specified',
-      toDate: toDate || 'not specified',
-      updateState
-    });
-
-    try {
-      // Execute main workflow with optional overrides
-      const result = await executeInventoryQuantityExtraction(ctx, {
-        jobId,
-        triggeredBy: 'webhook',
-        fromDate,              // Optional: override start date
-        toDate,                // Optional: override end date
-        updateState,           // Optional: skip state update for historical queries
-      });
-
-      const durationMs = Date.now() - startTime;
-
-      log.info('✅ [END] Ad hoc extraction completed', {
-        jobId,
-        recordCount: result.recordsExtracted,
-        fileName: result.fileName,
-        isManualOverride: !!fromDate,
-        stateUpdated: result.stateUpdated,
-        durationMs,
-        durationSec: (durationMs / 1000).toFixed(2)
-      });
-
-      // Return success with job details
-      return {
-        success: true,
-        jobId,
-        recordsExtracted: result.recordsExtracted,
-        fileName: result.fileName,
-        s3Path: result.s3Path,
-        statusUrl: `/webhooks/inventory-quantities-job-status?jobId=${jobId}`,
-        durationMs,
-        dateRange: fromDate ? {
-          from: fromDate,
-          to: toDate || 'not specified',
-          updateState
-        } : undefined
-      };
-
-    } catch (error: any) {
-      const durationMs = Date.now() - startTime;
-
-      log.error('❌ [ERROR] Ad hoc extraction failed', {
-        jobId,
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        durationMs,
-        recommendation: 'Verify date range format (ISO 8601), check S3 credentials, and ensure Fluent API access'
-      });
-
-      return {
-        success: false,
-        jobId,
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        durationMs,
-        recommendation: 'Verify date range format (ISO 8601), check S3 credentials, and ensure Fluent API access'
-      };
-    }
-  }));
-```
-
----
-
-#### src/workflows/webhook/job-status-check.ts
-
-```typescript
-/**
- * WORKFLOW 3: Job Status Query
- *
- * Purpose: Check job progress and status
- * Trigger: Webhook GET/POST to /webhooks/inventory-quantities-job-status?jobId=xxx
- * Returns: Current job status, stage, progress
- *
- * QUERY EXAMPLES:
- *
- * 1. HTTP GET:
- *    GET /webhooks/inventory-quantities-job-status?jobId=ADHOC_IQ_20251027_183045_abc123
- *
- * 2. HTTP POST:
- *    POST /webhooks/inventory-quantities-job-status
- *    { "jobId": "ADHOC_IQ_20251027_183045_abc123" }
- */
-
-import { webhook, fn } from '@versori/run';
-import { getJobStatus } from '../../services/extraction-orchestration';
-
-export const inventoryQuantitiesJobStatus = webhook(
-  'inventory-quantities-job-status',
-  { connection: 'inventory-quantities-job-status', response: { mode: 'sync' } },
-  fn('query-job-status', async (ctx) => {
-    const { data, log, openKv, activation } = ctx;
-    const startTime = Date.now();
-
-    // SECURITY: Authentication is enforced by Versori connection configuration
-    // Configure auth on the connection and reference it in webhook({ connection: '...' })
-
-    // Get jobId from query param or POST body
-    const jobId = data.jobId as string;
-
-    if (!jobId) {
-      log.error('❌ Job ID not provided in request');
-      return {
-        success: false,
-        error: 'Job ID is required. Provide jobId in query param or request body.'
-      };
-    }
-
-    log.info('🔍 [START] Querying job status', { jobId });
-
-    try {
-      // Query job status from KV store
-      const status = await getJobStatus(openKv(':project:'), jobId, log);
-
-      const durationMs = Date.now() - startTime;
-
-      if (!status) {
-        log.info('⚠️ Job not found', { jobId, durationMs });
-        return {
-          success: false,
-          error: 'Job not found',
-          jobId,
-          durationMs
-        };
-      }
-
-      log.info('✅ [END] Job status retrieved', {
-        jobId,
-        status: status.status,
-        durationMs
-      });
-
-      return {
-        success: true,
-        jobId,
-        ...status,
-        queryDurationMs: durationMs
-      };
-
-    } catch (error: any) {
-      const durationMs = Date.now() - startTime;
-
-      log.error('❌ [ERROR] Failed to query job status', {
-        jobId,
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        durationMs,
-        recommendation: 'Verify KV store access and job ID format'
-      });
-
-      return {
-        success: false,
-        jobId,
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        durationMs,
-        recommendation: 'Verify KV store access and job ID format'
-      };
-    }
-  }));
-```
-
----
-
-### 3. Main Orchestration Service (src/services/extraction-orchestration.ts)
-
-```typescript
-/**
- * MAIN ORCHESTRATION SERVICE
- *
- * This is the heart of the extraction workflow. It coordinates all steps:
- * 1. Initialize clients and services
- * 2. Determine date range (incremental vs manual)
- * 3. Extract data using ExtractionOrchestrator
- * 4. Transform using UniversalMapper
- * 5. Generate CSV using CSVParserService
- * 6. Upload to S3
- * 7. Track job progress with JobTracker
- * 8. Update state for next run
- *
- * NAMING PATTERN (consistent across all use cases):
- * - Interface: {Entity}ExtractionParams (e.g., InventoryQuantityExtractionParams)
- * - Result: {Entity}ExtractionResult (e.g., InventoryQuantityExtractionResult)
- * - Main function: execute{Entity}Extraction (e.g., executeInventoryQuantityExtraction)
- *
- * AI CUSTOMIZATION HINTS:
- * - Change entity: Replace "InventoryQuantity" with "Order", "Product", etc.
- * - Change output: Replace CSVParserService with XMLBuilder
- * - Change destination: Replace S3DataSource with SftpDataSource
- * - Add steps: Insert new service calls between existing steps
- */
-
-import { Buffer } from 'node:buffer';
-import {
-  createClient,
-  ExtractionOrchestrator,
-  JobTracker,
-  UniversalMapper,
-  CSVParserService,
-  S3DataSource,
-} from '@fluentcommerce/fc-connect-sdk';
-
-import mappingConfig from '../../config/inventory-quantities.export.csv.json' with { type: 'json' };
-
-// ✅ VERSORI PLATFORM: Use native log from context, not LoggingService
-
-/**
- * Parameters for extraction workflow
- *
- * NAMING: {Entity}ExtractionParams
- */
-export interface InventoryQuantityExtractionParams {
-  jobId: string;
-  triggeredBy: 'schedule' | 'webhook';
-  fromDate?: string; // Optional: manual date override
-  toDate?: string; // Optional: manual date override
-  updateState: boolean; // Whether to update lastSync timestamp
-
-  // AI CUSTOMIZATION: Add filters specific to entity
-  quantityTypes?: string[]; // e.g., ['LAST_ON_HAND', 'RESERVED']
-  catalogueRef?: string; // e.g., 'DEFAULT_CATALOGUE'
-}
-
-/**
- * Result from extraction workflow
- *
- * NAMING: {Entity}ExtractionResult
- */
-export interface InventoryQuantityExtractionResult {
-  success: boolean;
-  jobId: string;
-  recordsExtracted: number;
-  fileName?: string;
-  s3Path?: string;
-  error?: string;
-  errors?: any[];
-  isManualOverride?: boolean;
-  stateUpdated?: boolean;
-  newTimestamp?: string;
-}
-
-/**
- * GraphQL Query for Inventory Quantities
- *
- * NAMING: {ENTITY}_EXTRACTION_QUERY (uppercase constant)
- */
-const INVENTORY_QUANTITIES_EXTRACTION_QUERY = `
-  query GetInventoryQuantities(
-    $catalogues: [InventoryCatalogueKey]
-    $dateRangeFilter: DateRange
-    $productRefs: [String!]
-    $types: [String!]
-    $first: Int!
-    $after: String
-  ) {
-    inventoryQuantities(
-      catalogues: $catalogues
-      updatedOn: $dateRangeFilter
-      productRef: $productRefs
-      type: $types
-      first: $first
-      after: $after
-    ) {
-      edges {
-        node {
-          id
-          ref
-          locationRef
-          productRef
-          qty
-          type
-          status
-          expectedOn
-          createdOn
-          updatedOn
-          catalogue {
-            ref
-            name
-          }
-        }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-      }
-    }
-  }
-`;
-
-/**
- * Query job status from KV store
- *
- * ✅ VERSORI PLATFORM: Uses native log from context (passed as parameter)
- */
-export async function getJobStatus(
-  kv: any, // ✅ Versori KV (compatible with JobTracker's KVAdapter interface)
-  jobId: string,
-  log: any // ✅ Native Versori log from context
-): Promise<any | undefined> {
-  try {
-    const tracker = new JobTracker(kv, log);
-    return await tracker.getJob(jobId);
-  } catch (error: any) {
-    log.error('Failed to get job status', { jobId, message: error instanceof Error ? error.message : String(error),
- stack: error instanceof Error ? error.stack : undefined,
- errorType: error instanceof Error ? error.constructor.name : 'Error', });
-    return undefined;
-  }
-}
-
-/**
- * MAIN ORCHESTRATION FUNCTION
- *
- * NAMING: execute{Entity}Extraction (e.g., executeInventoryQuantityExtraction)
- *
- * This function implements the complete workflow in steps.
- * Each step is clearly commented for AI understanding.
- */
-export async function executeInventoryQuantityExtraction(
-  ctx: any,
-  params: InventoryQuantityExtractionParams
-): Promise<InventoryQuantityExtractionResult> {
-  // ✅ VERSORI PLATFORM: Extract native log from context
-  const { log, openKv, activation } = ctx;
-  const { jobId, triggeredBy, fromDate, toDate, updateState } = params;
-
-  // Open KV store for state management and job tracking
-  // ✅ Pass raw Versori KV directly - it matches KVAdapter interface
-  // ✅ Pass native log to JobTracker
-  const kv = openKv(':project:');
-  const tracker = new JobTracker(kv, log);
-
-  try {
-    // ═══════════════════════════════════════════════════════════
-    // STEP 1/8: Initialize Job Tracking
-    // ═══════════════════════════════════════════════════════════
-    log.info('📝 [STEP 1/8] Initializing job tracking', { jobId });
-
-    await tracker.createJob(jobId, {
-      triggeredBy,
-      hasDateOverride: !!fromDate,
-      fromDate,
-      toDate,
-      updateStateAfterRun: updateState,
-    });
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 2/8: Initialize Fluent Client
-    // ═══════════════════════════════════════════════════════════
-    log.info('📡 [STEP 2/8] Initializing Fluent Commerce client', { jobId });
-
-    const client = await createClient(ctx, { validateConnection: true });
-
-    if (!client) {
-      throw new Error('Failed to create Fluent Commerce client');
-    }
-
-    log.info('✅ Fluent client initialized and connection validated', { jobId });
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 3/8: Determine Date Range
-    // ═══════════════════════════════════════════════════════════
-    log.info('📅 [STEP 3/8] Determining date range for extraction', { jobId });
-
-    // State key for incremental sync tracking
-    // NAMING: last{Entity}Sync (e.g., lastInventoryQuantitySync)
-    const STATE_KEY = 'lastInventoryQuantitySync';
-    const DEFAULT_FALLBACK = '2024-01-01T00:00:00Z';
-    const OVERLAP_BUFFER_SECONDS = parseInt(
-      activation.getVariable('overlapBufferSeconds') || '60',
-      10
-    );
-
-    let dateRangeFilter: { from?: string; to?: string } | null = null;
-    const isManualOverride = !!fromDate;
-
-    if (isManualOverride) {
-      // Manual date override from webhook
-      dateRangeFilter = { from: fromDate, to: toDate };
-      log.info('Using manual date override', { fromDate, toDate });
-    } else {
-      // Incremental sync - get last sync timestamp
-      const rawLastRunTime = (await kv.get<string>(STATE_KEY)) || DEFAULT_FALLBACK;
-
-      // Apply overlap buffer (prevents missed records)
-      const bufferedLastRunTime = new Date(
-        new Date(rawLastRunTime).getTime() - OVERLAP_BUFFER_SECONDS * 1000
-      ).toISOString();
-
-      const effectiveEndTime = toDate || new Date().toISOString();
-
-      dateRangeFilter = {
-        from: bufferedLastRunTime,
-        to: effectiveEndTime, // End of extraction window
-      };
-
-      log.info('Using incremental sync with overlap buffer', {
-        rawLastRunTime,
-        bufferedLastRunTime,
-        effectiveEndTime,
-        overlapBufferSeconds: OVERLAP_BUFFER_SECONDS,
-      });
-    }
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 4/8: Extract Data (ExtractionOrchestrator)
-    // ═══════════════════════════════════════════════════════════
-    log.info('🔄 [STEP 4/8] Extracting data from Fluent Commerce', { jobId });
-
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'extraction',
-      message: 'Extracting data with auto-pagination',
-    });
-
-    // Build catalogues array from config
-    const catalogueRef = params.catalogueRef || activation.getVariable('catalogueRef');
-    const catalogues = catalogueRef ? [{ ref: catalogueRef }] : [];
-
-    // Configure extraction
-    const pageSize = parseInt(activation.getVariable('pageSize') || '200', 10);
-    const maxRecords = parseInt(activation.getVariable('maxRecords') || '100000', 10);
-
-    // Initialize ExtractionOrchestrator
-    const orchestrator = new ExtractionOrchestrator(client, log);
-
-    // ? Enhanced: Extract context for progress logging
-    const dateRangeInfo = {
-      start: dateRangeFilter?.from || 'N/A',
-      end: dateRangeFilter?.to || 'N/A',
-      catalogues: catalogues.map((c: any) => c.ref).join(', ') || 'all',
-      types: params.quantityTypes?.join(', ') || 'all'
-    };
-
-    // ? Enhanced: Start logging with context
-    log.info(`🔍 [ExtractionOrchestrator] Starting extraction`, {
-     query: 'inventoryQuantities',
-     pageSize,
-     maxRecords,
-     dateRange: `${dateRangeInfo.start} to ${dateRangeInfo.end}`,
-     catalogues: dateRangeInfo.catalogues,
-     quantityTypes: dateRangeInfo.types,
-     jobId
-    });
-
-    // Execute extraction with auto-pagination
-    const extractionResult = await orchestrator.extract({
-      query: INVENTORY_QUANTITIES_EXTRACTION_QUERY,
-      resultPath: 'inventoryQuantities.edges.node',
-      variables: {
-        catalogues,
-        dateRangeFilter,
-        types: params.quantityTypes,
-        // Note: Don't include 'first' or 'after' here; orchestrator injects them
-      },
-      pageSize,
-      maxRecords,
-      // Optional: validate each record
-      validateItem: (item: any) => {
-        return !!(item.ref && item.productRef);
-      },
-    });
-
-    const records = extractionResult.data || [];
-
-    log.info('Extraction complete', {
-      totalRecords: extractionResult.stats.totalRecords,
-      totalPages: extractionResult.stats.totalPages,
-      validRecords: extractionResult.stats.validRecords ?? records.length,
-      failedValidations: extractionResult.stats.failedValidations,
-      errors: extractionResult.errors ? extractionResult.errors.length : 0,
-    });
-
-    // ? Enhanced: Completion logging with summary
-    log.info(`✅ [ExtractionOrchestrator] Extraction completed`, {
-     totalRecords: extractionResult.stats.totalRecords,
-     totalPages: extractionResult.stats.totalPages,
-     validRecords: extractionResult.stats.validRecords ?? records.length,
-     failedValidations: extractionResult.stats.failedValidations,
-     truncated: extractionResult.stats.truncated,
-     truncationReason: extractionResult.stats.truncationReason,
-     dateRange: `${dateRangeInfo.start} to ${dateRangeInfo.end}`,
-     jobId
-    });
-
-    if (extractionResult.errors && extractionResult.errors.length > 0) {
-      log.warn('Non-fatal extraction errors encountered', {
-        errorCount: extractionResult.errors.length,
-        sampleErrors: extractionResult.errors.slice(0, 3),
-      });
-    }
-
-    // Handle empty result
-    if (records.length === 0) {
-      log.info('No records to process');
-
-      // Update state even with no records (prevents re-querying empty window)
-      if (updateState && !isManualOverride) {
-        await kv.set(STATE_KEY, new Date().toISOString());
-      }
-
-      await tracker.markCompleted(jobId, {
-        recordCount: 0,
-        message: 'No records to extract',
-      });
-
-      return {
-        success: true,
-        jobId,
-        recordsExtracted: 0,
-      };
-    }
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 5/8: Transform Data (UniversalMapper)
-    // ═══════════════════════════════════════════════════════════
-    log.info('🔧 [STEP 5/8] Transforming data with UniversalMapper', {
-      jobId,
-      recordCount: records.length,
-    });
-
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'transformation',
-      message: `Transforming ${records.length} records`,
-    });
-
-    const mapper = new UniversalMapper(mappingConfig);
-    const mappingResult = await mapper.map(records);
-
-    if (!mappingResult.success) {
-      const mappingErrors = mappingResult.errors || ['Unknown mapping failure'];
-      await tracker.markFailed(jobId, {
-        error: mappingErrors[0] || 'UniversalMapper returned unsuccessful result',
-        failedCount: mappingErrors.length,
-      });
-      return {
-        success: false,
-        error: `Transformation failed: ${mappingErrors[0] || 'Unknown error'}`,
-        jobId,
-        errors: mappingErrors,
-      };
-    }
-
-    const transformedRecords = Array.isArray(mappingResult.data) ? mappingResult.data : [];
-    const mappingErrors = mappingResult.errors || [];
-
-    if (mappingErrors.length > 0) {
-      log.warn('Some records failed transformation', {
-        jobId,
-        errorCount: mappingErrors.length,
-        sampleErrors: mappingErrors.slice(0, 3),
-      });
-    }
-
-    if (transformedRecords.length === 0) {
-      await tracker.markFailed(jobId, {
-        error: 'All records failed mapping',
-        failedCount: mappingErrors.length,
-        errors: mappingErrors,
-      });
-      return {
-        success: false,
-        error: 'All records failed mapping',
-        jobId,
-        errors: mappingErrors,
-      };
-    }
-
-    log.info('Transformation complete', {
-      successful: transformedRecords.length,
-      failed: mappingErrors.length,
-      skippedRecords: records.length - transformedRecords.length,
-    });
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 6/8: Generate CSV (CSVParserService)
-    // ═══════════════════════════════════════════════════════════
-    log.info('📄 [STEP 6/8] Generating CSV file', { jobId });
-
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'csv_generation',
-      message: `Generating CSV for ${transformedRecords.length} records`,
-    });
-
-    // Initialize CSVParserService
-    const csvParser = new CSVParserService({ includeHeaders: true });
-
-    // Generate CSV content
-    const csvContent = await csvParser.stringify(transformedRecords);
-
-    // Generate filename
-    const fileNamePrefix = activation.getVariable('fileNamePrefix') || 'inventoryquantities';
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const fileName = `${fileNamePrefix}-${timestamp}.csv`;
-
-    log.info('CSV file generated', {
-      fileName,
-      sizeBytes: csvContent.length,
-      recordCount: transformedRecords.length,
-    });
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 7/8: Upload to S3 (S3DataSource)
-    // ═══════════════════════════════════════════════════════════
-    log.info('☁️ [STEP 7/8] Uploading to S3', { jobId, fileName });
-
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 's3_upload',
-      message: `Uploading ${fileName} to S3`,
-    });
-
-    // Get S3 configuration from activation variables
-    const s3Config = {
-      bucket: activation.getVariable('s3BucketName'),
-      region: activation.getVariable('awsRegion') || 'us-east-1',
-      accessKeyId: activation.getVariable('awsAccessKeyId'),
-      secretAccessKey: activation.getVariable('awsSecretAccessKey'),
-    };
-    const s3Prefix = activation.getVariable('s3Prefix') || 'inventory-quantities/daily/';
-
-    // Validate S3 config
-    if (!s3Config.bucket || !s3Config.accessKeyId || !s3Config.secretAccessKey) {
-      throw new Error(
-        'S3 configuration incomplete: missing bucket, accessKeyId, or secretAccessKey'
-      );
-    }
-
-    // Initialize S3 data source
-    // ✅ VERSORI PLATFORM: Pass native log from context
-    const s3 = new S3DataSource(
-      {
-        type: 'S3_CSV',
-        connectionId: 'inventory-quantities-s3',
-        name: 'Inventory Quantities S3 Upload',
-        s3Config,
-      },
-      log
-    );
-
-    // Construct S3 key
-    const s3Key = `${s3Prefix}${fileName}`;
-
-    // Upload with retry logic (built into S3DataSource)
-    await s3.uploadFile(s3Key, Buffer.from(csvContent, 'utf-8'), {
-      contentType: 'text/csv',
-      metadata: {
-        recordCount: String(transformedRecords.length),
-        extractedAt: new Date().toISOString(),
-        jobId,
-        mappingErrors: mappingErrors.length > 0 ? String(mappingErrors.length) : undefined,
-      },
-    });
-
-    log.info('S3 upload successful', { fileName, s3Key });
-
-    // ═══════════════════════════════════════════════════════════
-    // STEP 8/8: Update State & Complete Job
-    // ═══════════════════════════════════════════════════════════
-    log.info('💾 [STEP 8/8] Updating state and completing job', { jobId });
-
-    // Calculate new timestamp for next incremental run
-    let newTimestamp: string | undefined;
-
-    if (updateState && !isManualOverride) {
-      // Find max updatedOn from extracted records
-      const maxUpdatedOn = records.reduce(
-        (max, record) => {
-          const recordTime = new Date(record.updatedOn).getTime();
-          return recordTime > max ? recordTime : max;
-        },
-        new Date(dateRangeFilter?.from || DEFAULT_FALLBACK).getTime()
-      );
-
-      newTimestamp = new Date(maxUpdatedOn).toISOString();
-
-      // Store new timestamp (WITHOUT buffer - buffer only applied on read)
-      await kv.set(STATE_KEY, newTimestamp);
-
-      log.info('State updated', {
-        oldTimestamp: dateRangeFilter?.from,
-        newTimestamp,
-      });
-    }
-
-    // Mark job as completed
-    await tracker.markCompleted(jobId, {
-      recordCount: transformedRecords.length,
-      fileName,
-      s3Key,
-      errorCount: mappingErrors.length,
-      errors: mappingErrors,
-      isManualOverride,
-      stateUpdated: updateState,
-      newTimestamp,
-    });
-
-    return {
-      success: true,
-      jobId,
-      recordsExtracted: transformedRecords.length,
-      fileName,
-      s3Path: s3Key,
-      isManualOverride,
-      stateUpdated: updateState,
-      newTimestamp,
-      errors: mappingErrors.length > 0 ? mappingErrors : undefined,
-    };
-  } catch (error: any) {
-    log.error('Extraction workflow failed', {
-      jobId,
-      message: error instanceof Error ? error.message : String(error),
-
-      stack: error instanceof Error ? error.stack : undefined,
-
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-    });
-
-    // Mark job as failed
-    await tracker.markFailed(jobId, error);
-
-    return {
-      success: false,
-      jobId,
-      recordsExtracted: 0,
-      message: error instanceof Error ? error.message : String(error),
-
-      stack: error instanceof Error ? error.stack : undefined,
-
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-    };
-  }
-}
-```
-
----
-
-### 4. Utility Functions (src/utils/job-id-generator.ts)
-
-```typescript
-/**
- * Job ID Generator
- *
- * Generates unique job IDs for tracking extraction workflows
- *
- * FORMAT: {TYPE}_{ENTITY}_{YYYYMMDD}_{HHMMSS}_{RANDOM}
- * Example: SCHEDULED_IQ_20251027_183045_a1b2c3
- */
-
-/**
- * Generate unique job ID
- *
- * @param type - Job trigger type (SCHEDULED, ADHOC, MANUAL)
- * @param entity - Entity abbreviation (IQ=Inventory Quantities, IP, VP, ORD, PRD)
- * @returns Unique job ID string
- */
-export function generateJobId(type: string, entity: string): string {
-  const now = new Date();
-
-  // Format: YYYYMMDD
-  const dateStr = now.toISOString().slice(0, 10).replace(/-/g, '');
-
-  // Format: HHMMSS
-  const timeStr = now.toISOString().slice(11, 19).replace(/:/g, '');
-
-  // Random suffix (6 chars)
-  const randomStr = Math.random().toString(36).substring(2, 8);
-
-  return `${type}_${entity}_${dateStr}_${timeStr}_${randomStr}`;
-}
-
-/**
- * Parse job ID components
- */
-export function parseJobId(jobId: string): {
-  type: string;
-  entity: string;
-  date: string;
-  time: string;
-  random: string;
-} | null {
-  const parts = jobId.split('_');
-
-  if (parts.length !== 5) {
-    return null;
-  }
-
-  return {
-    type: parts[0],
-    entity: parts[1],
-    date: parts[2],
-    time: parts[3],
-    random: parts[4],
-  };
-}
-```
-
----
-
-### 5. Package Configuration
-
-#### package.json
-
-```json
-{
-  "name": "inventory-quantities-to-s3-csv",
-  "version": "1.0.0",
-  "description": "Extract inventory quantities from Fluent Commerce and export to S3 as CSV",
-  "type": "module",
-  "main": "src/index.ts",
-  "scripts": {
-    "dev": "versori dev",
-    "build": "versori build",
-    "deploy": "versori deploy"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  }
-}
-```
-
-#### tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
-
----
-
-## 6. Deployment Instructions
-
-### Deploy to Versori
-
-```bash
-# 1. Install dependencies
-npm install
-
-# 2. Test locally (if using Versori CLI)
-npm run dev
-
-# 3. Deploy to Versori platform
-npm run deploy
-```
-
-### Configure Activation Variables
-
-In Versori platform settings, configure:
-
-```json
-{
-  "catalogueRef": "DEFAULT_CATALOGUE",
-  "s3BucketName": "inventory-audit-exports",
-  "awsAccessKeyId": "AKIAXXXXXXXXXXXX",
-  "awsSecretAccessKey": "********",
-  "awsRegion": "us-east-1",
-  "s3Prefix": "inventory-quantities/daily/",
-  "fileNamePrefix": "inventoryquantities",
-  "pageSize": 200,
-  "maxRecords": 100000,
-  "overlapBufferSeconds": 60,
-  "webhookApiKey": "your-secure-api-key-here"
-}
-```
-
----
-
-## 7. Testing
-
-### Test Scheduled Extraction
-
-The scheduled workflow runs automatically based on cron schedule.
-
-**Check logs:**
-
-```
-[STEP 1/8] Initializing job tracking
-[STEP 2/8] Initializing Fluent Commerce client
-[STEP 3/8] Determining date range for extraction
-[STEP 4/8] Extracting data from Fluent Commerce
-[STEP 5/8] Transforming data with UniversalMapper
-[STEP 6/8] Generating CSV file
-[STEP 7/8] Uploading to S3
-[STEP 8/8] Updating state and completing job
-```
-
-### Test Ad hoc Extraction
-
-```bash
-# Incremental (uses last sync timestamp)
-curl -X POST https://api.versori.com/webhooks/inventory-quantities-adhoc \
-  -H "X-API-Key: your-api-key" \
-  -H "Content-Type: application/json" \
-  -d '{}'
-
-# Date range override
-curl -X POST https://api.versori.com/webhooks/inventory-quantities-adhoc \
-  -H "X-API-Key: your-api-key" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "fromDate": "2025-01-01T00:00:00Z",
-    "toDate": "2025-01-31T23:59:59Z",
-    "updateState": false
-  }'
-```
-
-### Test Job Status Query
-
-```bash
-curl -X POST https://api.versori.com/webhooks/inventory-quantities-job-status \
-  -H "X-API-Key: your-api-key" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jobId": "ADHOC_IQ_20251027_183045_abc123"
-  }'
-```
-
-**Response:**
-
-```json
-{
-  "success": true,
-  "jobId": "ADHOC_IQ_20251027_183045_abc123",
-  "status": "processing",
-  "stage": "transformation",
-  "message": "Transforming 15000 records",
-  "createdAt": "2025-10-27T18:30:45.000Z",
-  "startedAt": "2025-10-27T18:30:46.000Z"
-}
-```
-
----
-
-## 8. Troubleshooting
-
-**Issue**: "No records extracted"
-
-- Check dateRange (manual override vs incremental)
-- Check catalogueRef filter
-- Verify quantity types filter
-
-**Issue**: "S3 upload failed"
-
-- Job fails; state not advanced
-- Next run retries same window
-- Check S3 credentials and bucket permissions
-
-**Issue**: "GraphQL pagination error"
-
-- Ensure edges.cursor and pageInfo.hasNextPage are in query
-
-**Issue**: "Memory pressure"
-
-- Lower pageSize or maxRecords
-- Consider file splitting for large extractions
-
-**Issue**: "Transformation errors"
-
-- Check mapping config field paths
-- Verify required fields are present in GraphQL response
-- Review transformation error details in logs
-
----
-
-## 9. Replication Checklist
-
-**To replicate this template for other entities/formats:**
-
-1. **File Naming:** Replace `inventory-quantities`, `IQ`, `InventoryQuantity` with your entity name
-2. **GraphQL Query:** Update query constant and field selection to match your entity schema
-3. **Mapping Config:** Create new mapping file in `config/` with correct field paths
-4. **Workflows:** Rename workflow exports to match entity (e.g., `scheduledOrdersExtraction`)
-5. **Service Function:** Rename main function (e.g., `executeOrderExtraction`)
-6. **State Key:** Update KV key (e.g., `lastOrderSync`)
-7. **Output Format:** For XML use `XMLBuilder`, for JSON use `JSON.stringify()`, for CSV use `CSVParserService`
-8. **Upload Destination:** For SFTP replace `S3DataSource` with `SftpDataSource` (and add `dispose()` in finally block)
-9. **Job ID Entity Code:** Update entity abbreviation in generateJobId() (e.g., 'ORD' for orders)
-10. **Result Path:** Update `resultPath` in ExtractionOrchestrator (e.g., `'orders.edges.node'`)
-
----
-
-**Pattern**: Enterprise incremental extraction with overlap buffer for inventory quantities
-**Key Learning**: Use ExtractionOrchestrator for auto-pagination, JobTracker for job status, CSVParserService for CSV generation
-**Critical**: Apply 60-second overlap buffer to prevent missed records due to clock skew
-**Buffer Pattern**: Query WITH buffer (`updatedOn >= lastRunTime - 60s`), save WITHOUT buffer (`MAX(updatedOn)`)
-**SDK Services**: ExtractionOrchestrator, UniversalMapper, CSVParserService, S3DataSource, JobTracker
-**Entity-Specific**: Query uses `inventoryQuantities`, resultPath is `'inventoryQuantities.edges.node'`, state key is `lastInventoryQuantitySync`
-
----
-
-### Optional: Backward Pagination (Advanced)
-
-- Default: forward ($first/$after) + pageInfo.hasNextPage.
-- Reverse: define $last/$before and include pageInfo.hasPreviousPage; set direction='backward'.
-
-GraphQL:
-
-```graphql
-query GetInventoryQuantitiesBackward($retailerId: ID!, $last: Int!, $before: String) {
-  inventoryQuantities(retailerId: $retailerId, last: $last, before: $before) {
-    edges {
-      cursor
-      node {
-        id
-        ref
-        updatedOn
-      }
-    }
-    pageInfo {
-      hasPreviousPage
-    }
-  }
-}
-```
-
-SDK:
-
-```typescript
-await orchestrator.extract({
-  query: INVENTORY_QUANTITIES_BACKWARD_QUERY,
-  resultPath: 'inventoryQuantities.edges.node',
-  variables: { retailerId },
-  pageSize,
-  direction: 'backward',
-});
-```
+---
+template_id: tpl-extract-inventory-quantities-to-s3-csv
+canonical_filename: template-extraction-inventory-quantities-to-s3-csv.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: extraction
+source: fluent-graphql
+destination: s3-csv
+entity: inventoryQuantities
+format: csv
+logging: versori
+status: stable
+features:
+  - memory-management
+  - enhanced-logging
+  - pagination-progress
+---
+
+# Template: Extraction - Inventory Quantities to S3 CSV
+
+**Template Version:** 2.0.0
+**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+**🆕 Version 2.0.0 Enhancements:**
+- ✅ **Memory Management** - Clear large result sets after processing batches
+- ✅ **Enhanced Logging** - Pagination progress tracking with emoji indicators (📊, 📥, ✅)
+- ✅ **Pagination Progress** - Real-time page-by-page progress logging with metrics
+
+---
+
+## 📚 STEP 1: Load These Docs (Human Checklist)
+
+1. REQUIRED (load all)
+   - [ ] fc-connect-sdk/docs/02-CORE-GUIDES/api-reference/
+   - [ ] fc-connect-sdk/docs/02-CORE-GUIDES/mapping/
+   - [ ] fc-connect-sdk/docs/03-PATTERN-GUIDES/data-sources/
+   - [ ] fc-connect-sdk/docs/03-PATTERN-GUIDES/parsers/
+   - [ ] fc-connect-sdk/docs/03-PATTERN-GUIDES/extraction/
+   - [ ] fc-connect-sdk/docs/04-REFERENCE/platforms/versori/
+
+Copy-paste list (open these):
+fc-connect-sdk/docs/02-CORE-GUIDES/api-reference/
+fc-connect-sdk/docs/02-CORE-GUIDES/mapping/
+fc-connect-sdk/docs/03-PATTERN-GUIDES/data-sources/
+fc-connect-sdk/docs/03-PATTERN-GUIDES/parsers/
+fc-connect-sdk/docs/03-PATTERN-GUIDES/extraction/
+fc-connect-sdk/docs/04-REFERENCE/platforms/versori/
+
+---
+
+## 📋 STEP 2: Tell Your AI (Prompt)
+
+Copy/paste this prompt into your AI tool after loading the documentation above:
+
+```
+I need a Versori scheduled extractor that:
+
+1) Queries Fluent Commerce GraphQL for inventoryQuantities with auto-pagination
+2) Uses incremental mode with a 60-second overlap buffer stored in Versori KV
+3) Transforms results using UniversalMapper per mapping JSON
+4) Generates CSV with CSVParserService and uploads to S3
+5) Uses native Versori log (LoggingService removed - use native log)
+
+Use the loaded docs for SDK specifics and best practices. Keep structure identical to the template.
+```
+
+---
+
+## 📦 SDK Imports (Verified - Versori Optimized)
+
+```typescript
+import { Buffer } from 'node:buffer';
+import {
+  createClient,
+  UniversalMapper,
+  S3DataSource,
+  CSVParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+import { schedule, http } from '@versori/run';
+```
+
+---
+
+# Versori Scheduled: Inventory Quantities Extraction to S3 CSV (Configurable)
+
+**FC Connect SDK Use Case Guide**
+
+> SDK: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> Version: `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`
+
+Context: Scheduled Versori workflow that extracts inventory quantities (detailed quantity records) from Fluent Commerce via GraphQL query with **configurable extraction modes**, transforms with `UniversalMapper`, and writes CSV files to S3 for analytics and reporting.
+
+**Pattern**: EXTRACTION (Fluent → S3 CSV)
+**Entity**: inventoryQuantities
+**Complexity**: High | Runtime: Versori Platform (Scheduled)
+
+---
+
+## ⚠️ IMPORTANT: Sample Code for SDK Demonstration Only
+
+> **🔴 PRODUCTION WARNING**
+>
+> This guide demonstrates FC Connect SDK capabilities for **extraction and mapping workflows**. The multiple extraction modes (incremental, dateRange, historical) are included to show SDK flexibility and serve as **reference examples**.
+>
+> **✅ PRODUCTION RECOMMENDATION:**
+>
+> - **ONLY use INCREMENTAL mode with scheduled runs** (e.g., daily/hourly)
+> - Incremental mode is safe, efficient, and production-ready
+> - Uses overlap buffer to prevent missed records
+> - Natural rate limiting via timestamps
+>
+> **🚫 DO NOT USE IN PRODUCTION:**
+>
+> - **dateRange mode** - High risk of platform overload with large date windows
+> - **historical mode** - Extremely dangerous, can fetch millions of records
+> - These modes are **demonstration only** to show SDK query patterns
+> - Using these modes on large inventory datasets can crash your runtime and impact platform stability
+>
+> **📝 If you need historical data:**
+>
+> - Run multiple small incremental extractions (e.g., daily for past 30 days)
+> - Use one-time migration scripts with proper monitoring (not scheduled workflows)
+> - Always validate date ranges and implement file splitting
+> - Get explicit approval before running large extractions
+>
+> **This sample code shows HOW to use the SDK - not WHAT to use in production.**
+
+---
+
+## What You'll Build
+
+- **Three extraction modes**: Incremental, Date Range, or Historical
+- **State management** with VersoriKVAdapter to track last successful run
+- GraphQL query with auto-pagination
+- UniversalMapper transformation for reporting schema
+- CSV file generation with CSVParserService
+- S3 upload to analytics system
+- **Failure recovery** with timestamp tracking
+
+## Business Use Cases
+
+**1. Incremental Daily Sync (Analytics)**
+
+- Extract only changed inventory quantities since last run
+- Run daily at 2 AM
+- Minimize data transfer
+- Track changes over time
+
+**2. Date Range Extract (Audit)**
+
+- Extract quantity changes within specific date window
+- For audits, reconciliation, historical analysis
+- Example: "Show all quantity changes between Jan 1-15"
+
+**3. Historical Backfill**
+
+- Extract all quantities created within date range
+- For initial data warehouse load
+- One-time backfill operation
+
+## Inventory Quantities vs Positions
+
+**InventoryQuantity** = Specific quantity record (retailer-defined types)
+
+- Individual records: e.g., LAST_ON_HAND, RESERVED, DELTA, SALE, CORRECTION (plus any custom IQ types)
+- Multiple quantities per product/location
+- Fields: locationRef, skuRef, qty, type, status, expectedOn (if applicable)
+- Used for: Detailed tracking, audit trails
+
+**InventoryPosition** = Aggregated on-hand calculation
+
+- One position per product/location
+- Calculated `onHand` from all associated quantities
+- Used for: Stock availability, reporting
+
+## SDK Methods Used
+
+```typescript
+import { Buffer } from 'node:buffer';
+import {
+  createClient,
+  UniversalMapper,
+  S3DataSource,
+  VersoriKVAdapter,
+  CSVParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+await createClient(ctx);
+await client.graphql({ query, variables, pagination });
+new VersoriKVAdapter(ctx.openKv(':project:'));
+new UniversalMapper(exportMapping);
+const csvParser = new CSVParserService({ includeHeaders: true });
+const csvContent = await csvParser.stringify(rows);
+await s3.uploadFile(key, Buffer.from(csvContent, 'utf8'), options);
+```
+
+## Activation Variables
+
+```json
+{
+  "retailerId": "your-retailer-id",
+  "s3BucketName": "inventory-audit-exports",
+  "awsAccessKeyId": "AKIAXXXXXXXXXXXX",
+  "awsSecretAccessKey": "********",
+  "awsRegion": "us-east-1",
+  "s3Prefix": "inventory-quantities/daily/",
+  "fileNamePrefix": "inventoryquantities",
+  "catalogueRef": "DEFAULT_CATALOGUE",
+  "pageSize": 200,
+  "maxRecords": 100000,
+  "extractionMode": "incremental",
+  "fallbackStartDate": "2024-01-01T00:00:00Z",
+  "overlapBufferSeconds": "60",
+  "startDate": "",
+  "endDate": ""
+}
+```
+
+### Variable Reference
+
+| Variable | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `retailerId` | string | Yes | - | Fluent Commerce retailer ID |
+| `s3BucketName` | string | Yes | - | S3 bucket for CSV export |
+| `awsAccessKeyId` | string | Yes | - | AWS access key with S3 write permissions |
+| `awsSecretAccessKey` | string | Yes | - | AWS secret access key |
+| `awsRegion` | string | Yes | - | AWS region (e.g., `us-east-1`) |
+| `s3Prefix` | string | No | `""` | S3 key prefix (e.g., `inventory-quantities/daily/`) |
+| `fileNamePrefix` | string | No | `"inventoryquantities"` | CSV filename prefix |
+| `catalogueRef` | string | No | - | Filter by catalogue reference (optional) |
+| `pageSize` | number | No | `200` | GraphQL page size (max 500) |
+| `maxRecords` | number | No | `100000` | Maximum records per extraction |
+| `extractionMode` | string | No | `"incremental"` | Extraction mode: `incremental`, `dateRange`, or `historical` |
+| `fallbackStartDate` | string | No | `"2024-01-01T00:00:00Z"` | Fallback date if no state exists |
+| `overlapBufferSeconds` | number | No | `60` | Overlap buffer to prevent missed records (seconds) |
+| `startDate` | string | No | - | Manual start date (for `dateRange`/`historical` modes) |
+| `endDate` | string | No | - | Manual end date (for `dateRange`/`historical` modes) |
+
+### Extraction Mode Configuration
+
+**Mode 1: Incremental (default)**
+
+```json
+{
+  "extractionMode": "incremental",
+  "fallbackStartDate": "2024-01-01T00:00:00Z"
+}
+```
+
+Extracts quantities with `updatedOn > lastRunTime`. Ideal for daily syncs.
+
+**Mode 2: Date Range**
+
+```json
+{
+  "extractionMode": "dateRange",
+  "startDate": "2025-01-01T00:00:00Z",
+  "endDate": "2025-01-15T23:59:59Z"
+}
+```
+
+Extracts quantities updated between `startDate` and `endDate`. Ideal for audits.
+
+**Mode 3: Historical**
+
+```json
+{
+  "extractionMode": "historical",
+  "startDate": "2024-01-01T00:00:00Z",
+  "endDate": "2024-12-31T23:59:59Z"
+}
+```
+
+Extracts quantities created between `startDate` and `endDate` using `createdOn` filter.
+
+## ⚠️ Production Safety & Guardrails
+
+### Critical: Extraction Mode Selection
+
+**🟢 RECOMMENDED: Incremental Mode (Production)**
+
+- Safe for automated schedules
+- Natural rate limiting via timestamps
+- Predictable resource usage
+- **Use this for all production workflows**
+
+**🟡 CAUTION: Date Range Mode (Audit/Backfill)**
+
+- **Maximum 30-day window enforced**
+- Use for specific audit requests only
+- Run during off-peak hours
+- Monitor resource usage
+
+**🔴 DANGER: Historical Mode (One-Time Only)**
+
+- **Maximum 90-day window enforced**
+- **Requires explicit approval**
+- **Risk of platform overload**
+- Can fetch millions of records
+- Use multiple small incremental runs instead
+- Only for initial data migration
+
+### Date Range Validation (Required)
+
+```typescript
+// Validate date range limits to prevent platform overload
+function validateDateRange(mode, startDate, endDate) {
+  if (mode === 'incremental') return { valid: true };
+
+  if (!startDate || !endDate) {
+    return {
+      valid: false,
+      error: `${mode} mode requires both startDate and endDate`,
+    };
+  }
+
+  const start = new Date(startDate);
+  const end = new Date(endDate);
+  const daysDiff = (end - start) / (1000 * 60 * 60 * 24);
+
+  // Guardrail: Maximum date ranges
+  const maxDays = mode === 'dateRange' ? 30 : 90;
+
+  if (daysDiff > maxDays) {
+    return {
+      valid: false,
+      error: `${mode} mode: Maximum ${maxDays}-day window. Requested: ${Math.round(daysDiff)} days. Use multiple smaller extractions or incremental mode.`,
+      recommendation: `Split into ${Math.ceil(daysDiff / maxDays)} separate extractions of ${maxDays} days each.`,
+    };
+  }
+
+  if (daysDiff < 0) {
+    return { valid: false, error: 'endDate must be after startDate' };
+  }
+
+  return { valid: true };
+}
+```
+
+### File Splitting Configuration
+
+Large extractions must split into multiple files to prevent memory issues and upload failures.
+
+```json
+{
+  "maxRecordsPerFile": 50000,
+  "maxFileSizeMB": 100,
+  "enableFileSplitting": true
+}
+```
+
+**File Naming Pattern:**
+
+```
+{prefix}inventory-quantities-{timestamp}-part-{sequence}.csv
+
+Examples:
+inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-001.csv
+inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-002.csv
+inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-manifest.json
+```
+
+**Manifest File (auto-generated):**
+
+```json
+{
+  "extractionId": "inventory-quantities-2025-01-22T14-30-00Z",
+  "totalRecords": 127543,
+  "totalFiles": 3,
+  "files": [
+    {
+      "filename": "inventory-quantities-2025-01-22T14-30-00Z-part-001.csv",
+      "recordCount": 50000,
+      "s3Key": "inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-001.csv"
+    },
+    {
+      "filename": "inventory-quantities-2025-01-22T14-30-00Z-part-002.csv",
+      "recordCount": 50000,
+      "s3Key": "inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-002.csv"
+    },
+    {
+      "filename": "inventory-quantities-2025-01-22T14-30-00Z-part-003.csv",
+      "recordCount": 27543,
+      "s3Key": "inventory-quantities/daily/inventory-quantities-2025-01-22T14-30-00Z-part-003.csv"
+    }
+  ],
+  "extractionMode": "dateRange",
+  "dateRange": {
+    "from": "2025-01-01T00:00:00Z",
+    "to": "2025-01-31T23:59:59Z"
+  },
+  "completedAt": "2025-01-22T14:35:27Z"
+}
+```
+
+### Hard Limits (Enforced)
+
+```typescript
+const SAFETY_LIMITS = {
+  // Maximum records per single extraction
+  MAX_RECORDS_TOTAL: 500000, // 500k hard limit
+
+  // Maximum records per file before splitting
+  MAX_RECORDS_PER_FILE: 50000, // 50k per file
+
+  // Maximum file size before splitting
+  MAX_FILE_SIZE_MB: 100, // 100MB per file
+
+  // Date range limits
+  MAX_DATE_RANGE_DAYS: 30, // dateRange mode
+  MAX_HISTORICAL_DAYS: 90, // historical mode
+
+  // Pagination limits
+  MAX_PAGE_SIZE: 500, // Fluent API limit
+  RECOMMENDED_PAGE_SIZE: 200, // Balance throughput/memory
+
+  // Memory management
+  CHUNK_SIZE: 10000, // Process in chunks
+};
+```
+
+### Memory-Safe Implementation Pattern
+
+```typescript
+// Process large extractions in chunks to prevent OOM
+async function processLargeExtraction(edges, mapper, csvParser, s3, options) {
+  const CHUNK_SIZE = 10000;
+  const MAX_RECORDS_PER_FILE = options.maxRecordsPerFile || 50000;
+
+  let fileSequence = 1;
+  let currentFileRecords = [];
+  const manifestFiles = [];
+
+  for (let i = 0; i < edges.length; i += CHUNK_SIZE) {
+    const chunk = edges.slice(i, i + CHUNK_SIZE);
+
+    // Bulk mapping for chunk
+    const chunkNodes = chunk.map(edge => edge.node);
+    const mappingResult = await mapper.map(chunkNodes);
+
+    if (!mappingResult.success) {
+      const mappingErrors = mappingResult.errors || ['Unknown mapping failure'];
+      log.error('Chunk mapping failed', {
+        chunkIndex: i / CHUNK_SIZE,
+        errorCount: mappingErrors.length,
+        sampleErrors: mappingErrors.slice(0, 3),
+      });
+      throw new Error(`Mapping failed: ${mappingErrors[0] || 'Unknown error'}`);
+    }
+
+    const transformedChunk = mappingResult.data || [];
+    const mappingErrors = mappingResult.errors || [];
+
+    if (mappingErrors.length > 0) {
+      log.warn('Some records in chunk failed transformation', {
+        chunkIndex: i / CHUNK_SIZE,
+        errorCount: mappingErrors.length,
+      });
+    }
+
+    if (mappingResult.skippedFields && mappingResult.skippedFields.length > 0) {
+      log.info('ℹ️ [MAPPING] Optional fields skipped (undefined values)', {
+        chunkIndex: i / CHUNK_SIZE,
+        skippedFields: mappingResult.skippedFields,
+        note: 'These fields were not present in source data. Add defaultValue to mapping config if they should always appear.',
+      });
+    }
+
+    // Add to current file, handling splits
+    for (const record of transformedChunk) {
+      currentFileRecords.push(record);
+
+      // Split file when limit reached
+      if (currentFileRecords.length >= MAX_RECORDS_PER_FILE) {
+        const fileInfo = await writeFileToS3(
+          currentFileRecords,
+          fileSequence++,
+          csvParser,
+          s3,
+          options
+        );
+        manifestFiles.push(fileInfo);
+        currentFileRecords = []; // Reset for next file
+      }
+    }
+  }
+
+  // Write remaining records
+  if (currentFileRecords.length > 0) {
+    const fileInfo = await writeFileToS3(
+      currentFileRecords,
+      fileSequence++,
+      csvParser,
+      s3,
+      options
+    );
+    manifestFiles.push(fileInfo);
+  }
+
+  // Write manifest
+  await writeManifest(manifestFiles, s3, options);
+
+  return manifestFiles;
+}
+```
+
+### Enterprise Time Buffer Configuration
+
+```json
+{
+  "overlapBufferSeconds": "60"
+}
+```
+
+**Default: 60 seconds (recommended for most deployments)**
+
+**Purpose**: Prevents missed records due to:
+
+- **Clock skew** between Fluent API servers (typically 1-5 seconds)
+- **Transaction timing** - records updated during query execution
+- **Race conditions** - records updated between extraction runs
+
+**How It Works**:
+
+- **Query**: Uses `updatedOn >= (lastRunTime - 60 seconds)`
+- **Save**: Stores `MAX(updatedOn)` WITHOUT buffer
+- **Result**: Records from the last minute of previous extraction are included again
+
+**Buffer Sizes by Deployment**:
+
+- `30` - Low-latency single-region (minimal clock skew expected)
+- `60` - **Standard production** (recommended default)
+- `300` - Cross-region deployments or high-latency networks
+
+**Duplicate Handling**: Downstream systems should upsert by `quantity_id` (idempotent). Duplicates are safe and expected.
+
+### Timezone Handling
+
+**All timestamps are in ISO 8601 format (UTC)**:
+
+```typescript
+// Input: ISO 8601 UTC timestamp
+const timestamp = '2025-01-22T14:30:00.000Z';
+
+// JavaScript Date operations preserve UTC
+new Date(timestamp).toISOString();
+// Returns: "2025-01-22T14:30:00.000Z" (same format)
+
+new Date(timestamp).getTime();
+// Returns: 1737558600000 (UTC epoch milliseconds)
+
+// Subtract 60 seconds for buffer
+const buffered = new Date(new Date(timestamp).getTime() - 60000).toISOString();
+// Returns: "2025-01-22T14:29:00.000Z"
+```
+
+**Key Points**:
+
+- Fluent API returns all timestamps in UTC
+- `.getTime()` returns UTC epoch milliseconds
+- Buffer arithmetic is done in milliseconds
+- `.toISOString()` converts back to ISO 8601 UTC
+- No timezone conversion needed
+
+## Export Mapping Configuration
+
+Create file: `./config/inventory-quantities.export.json`
+
+```json
+{
+  "name": "inventory-quantities.export",
+  "version": "1.0.0",
+  "description": "Fluent Inventory Quantities → CSV Export Mapping",
+  "fields": {
+    "quantity_id": { "source": "id", "required": true, "resolver": "sdk.trim" },
+    "quantity_ref": { "source": "ref", "required": true, "resolver": "sdk.trim" },
+    "catalogue_ref": { "source": "catalogue.ref", "required": false, "resolver": "sdk.trim" },
+    "catalogue_name": { "source": "catalogue.name", "required": false, "resolver": "sdk.trim" },
+    "location": { "source": "locationRef", "required": true, "resolver": "sdk.trim" },
+    "sku": { "source": "skuRef", "required": true, "resolver": "sdk.trim" },
+    "quantity": { "source": "qty", "required": true, "resolver": "sdk.parseInt" },
+    "type": { "source": "type", "required": true, "resolver": "sdk.uppercase" },
+    "status": { "source": "status", "required": true, "resolver": "sdk.uppercase" },
+    "expected_on": { "source": "expectedOn", "resolver": "sdk.formatDate" },
+    "created_on": { "source": "createdOn", "resolver": "sdk.formatDate" },
+    "updated_on": { "source": "updatedOn", "required": true, "resolver": "sdk.formatDate" }
+  }
+}
+```
+
+## Mapping & Resolvers Explained
+
+This section explains how the SDK transforms raw GraphQL data into your CSV export format using **UniversalMapper** and **SDK resolvers**.
+
+### SDK Resolvers Used
+
+| Field            | Resolver         | Why?                                       | Example Transformation                          |
+| ---------------- | ---------------- | ------------------------------------------ | ----------------------------------------------- |
+| `quantity_id`    | `sdk.trim`       | Clean quantity IDs from whitespace         | `" Q001 "` → `"Q001"`                           |
+| `quantity_ref`   | `sdk.trim`       | Clean quantity references                  | `" QTY-REF-001 "` → `"QTY-REF-001"`             |
+| `catalogue_ref`  | `sdk.trim`       | Clean catalogue references                 | `" DEFAULT_CATALOGUE "` → `"DEFAULT_CATALOGUE"` |
+| `catalogue_name` | `sdk.trim`       | Clean catalogue names                      | `" Default Catalogue "` → `"Default Catalogue"` |
+| `location`       | `sdk.trim`       | Clean location references                  | `" DC01 "` → `"DC01"`                           |
+| `sku`            | `sdk.trim`       | Clean SKU references                       | `" SKU-001 "` → `"SKU-001"`                     |
+| `quantity`       | `sdk.parseInt`   | Parse quantity as integer for calculations | `"100"` → `100`                                 |
+| `type`           | `sdk.uppercase`  | Normalize type codes                       | `"available"` → `"AVAILABLE"`                   |
+| `status`         | `sdk.uppercase`  | Normalize status codes                     | `"active"` → `"ACTIVE"`                         |
+| `expected_on`    | `sdk.formatDate` | Format dates for CSV export                | `"2025-01-30T00:00:00.000Z"` → `"2025-01-30"`   |
+| `created_on`     | `sdk.formatDate` | Format created timestamps                  | `"2025-01-15T10:00:00.000Z"` → `"2025-01-15"`   |
+| `updated_on`     | `sdk.formatDate` | Format updated timestamps for tracking     | `"2025-01-22T08:30:00.000Z"` → `"2025-01-22"`   |
+
+### Transformation Flow
+
+```typescript
+// 1. GraphQL Response (raw data from Fluent Commerce)
+const rawQuantity = {
+  id: ' Q001 ',
+  ref: ' QTY-REF-001 ',
+  locationRef: ' DC01 ',
+  skuRef: ' SKU-001 ',
+  qty: '100',
+  type: 'available',
+  status: 'active',
+  expectedOn: null,
+  createdOn: '2025-01-15T10:00:00.000Z',
+  updatedOn: '2025-01-22T08:30:00.000Z',
+  catalogue: {
+    ref: ' DEFAULT_CATALOGUE ',
+    name: ' Default Catalogue ',
+  },
+};
+
+// 2. UniversalMapper applies SDK resolvers
+const mapper = new UniversalMapper(inventoryQuantitiesExportMapping);
+const result = await mapper.map(rawQuantity);
+
+// 3. Transformed Output (clean, normalized for CSV)
+const transformedQuantity = {
+  quantity_id: 'Q001',
+  quantity_ref: 'QTY-REF-001',
+  catalogue_ref: 'DEFAULT_CATALOGUE',
+  catalogue_name: 'Default Catalogue',
+  location: 'DC01',
+  sku: 'SKU-001',
+  quantity: 100,
+  type: 'AVAILABLE',
+  status: 'ACTIVE',
+  expected_on: '', // null → empty string
+  created_on: '2025-01-15',
+  updated_on: '2025-01-22',
+};
+```
+
+### Custom Resolvers for Inventory Quantity-Specific Logic
+
+While the mapping above uses built-in SDK resolvers, you can extend with custom business logic:
+
+```typescript
+const customResolvers = {
+  /**
+   * Validate that quantity values are positive
+   */
+  'custom.validateQuantity': (qty: any) => {
+    const parsed = parseInt(qty) || 0;
+    return parsed >= 0 ? parsed : 0; // Ensure non-negative
+  },
+
+  /**
+   * Add human-readable type descriptions for reporting
+   */
+  'custom.enrichQuantityType': (type: string) => {
+    const typeDescriptions: Record<string, string> = {
+      LAST_ON_HAND: 'Last recorded on-hand quantity',
+      RESERVED: 'Reserved against orders',
+      DELTA: 'Incremental change (adjustment delta)',
+      SALE: 'Quantity decreased due to sale',
+      CORRECTION: 'Manual correction entry',
+    };
+    return typeDescriptions[(type || '').toUpperCase()] || type;
+  },
+
+  /**
+   * Check if expected date is in the future
+   */
+  'custom.isExpectedInFuture': (expectedOn: string) => {
+    if (!expectedOn) return false;
+    return new Date(expectedOn) > new Date();
+  },
+
+  /**
+   * Calculate days until expected arrival
+   */
+  'custom.calculateDaysUntilExpected': (expectedOn: string) => {
+    if (!expectedOn) return null;
+    const expected = new Date(expectedOn);
+    const today = new Date();
+    const diffMs = expected.getTime() - today.getTime();
+    return Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+  },
+
+  /**
+   * Validate status-type combinations
+   */
+  'custom.validateQuantityStatus': (_quantity: any) => {
+    // Example placeholder – adapt rules to your retailer-defined IQ types
+    return 'VALID';
+  },
+};
+
+// Use custom resolvers with UniversalMapper
+const mapper = new UniversalMapper(inventoryQuantitiesExportMapping, {
+  customResolvers,
+});
+```
+
+### Available SDK Resolvers
+
+The SDK provides these built-in resolvers (no custom code needed):
+
+**String Transformations:**
+
+- `sdk.trim` - Remove leading/trailing whitespace
+- `sdk.uppercase` - Convert to uppercase
+- `sdk.lowercase` - Convert to lowercase
+- `sdk.toString` - Convert to string
+
+**Number Parsing:**
+
+- `sdk.parseInt` - Parse as integer
+- `sdk.parseFloat` - Parse as decimal
+- `sdk.number` - Parse as number (auto-detect int/float)
+
+**Date Formatting:**
+
+- `sdk.formatDate` - ISO 8601 date only (YYYY-MM-DD)
+- `sdk.formatDateShort` - Short date format
+- `sdk.parseDate` - Parse various date formats
+
+**Type Conversions:**
+
+- `sdk.boolean` - Convert to boolean
+- `sdk.parseJson` - Parse JSON strings
+- `sdk.toJson` - Convert to JSON string
+
+**Utilities:**
+
+- `sdk.identity` - Return value unchanged
+- `sdk.coalesce` - Return first non-null value
+
+See [Universal Mapping Guide](../../../../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for complete resolver documentation.
+
+## GraphQL Query
+
+```graphql
+query GetInventoryQuantities(
+  $retailerId: ID!
+  $updatedAfter: DateTime
+  $createdAfter: DateTime
+  $first: Int!
+  $after: String
+) {
+  inventoryQuantities(
+    retailerId: $retailerId
+    updatedOn: { after: $updatedAfter }
+    createdOn: { after: $createdAfter }
+    first: $first
+    after: $after
+  ) {
+    edges {
+      node {
+        id
+        ref
+        locationRef
+        skuRef
+        qty
+        type
+        status
+        expectedOn
+        createdOn
+        updatedOn
+        catalogue {
+          ref
+          name
+        }
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+      # Note: Fluent doesn't return endCursor/startCursor - cursors are in edges[].cursor
+    }
+  }
+}
+```
+
+## Guardrails Implementation (Required)
+
+```typescript
+// Overlap buffer (safety window)
+const overlapBufferSeconds = parseInt(
+  ctx.activation?.getVariable('overlapBufferSeconds') || '60',
+  10
+);
+const OVERLAP_BUFFER_MS = overlapBufferSeconds * 1000;
+
+// Read last successful run and apply buffer
+const kv = new VersoriKVAdapter(ctx.openKv(':project:'));
+const stateKey = ['extraction', 'inventory-quantities-csv', 'lastRunTime'];
+const lastRunState = await kv.get(stateKey);
+const rawLastRunTime = lastRunState?.value?.timestamp || fallbackStartDate;
+const bufferedLastRunTime = new Date(
+  new Date(rawLastRunTime).getTime() - OVERLAP_BUFFER_MS
+).toISOString();
+
+// Query WITH buffer
+const result = await client.graphql({
+  query: INVENTORY_QUANTITIES_QUERY,
+  variables: {
+    retailerId,
+    updatedAfter: bufferedLastRunTime,
+    first: pageSize,
+  },
+  pagination: { maxRecords },
+});
+
+const edges = result.data?.inventoryQuantities?.edges || [];
+
+// 🛡️ GUARDRAIL: Validate extraction size limits
+const MAX_RECORDS_PER_RUN = 500000;
+const ESTIMATED_BYTES_PER_RECORD = 300; // Smaller than positions
+const estimatedSizeMB = (edges.length * ESTIMATED_BYTES_PER_RECORD) / (1024 * 1024);
+const MAX_CSV_SIZE_MB = 100;
+
+if (edges.length > MAX_RECORDS_PER_RUN) {
+  log.error('Extraction limit exceeded', {
+    recordCount: edges.length,
+    maxAllowed: MAX_RECORDS_PER_RUN,
+  });
+  return {
+    success: false,
+    error: `Extraction limit exceeded: ${edges.length} records (max: ${MAX_RECORDS_PER_RUN})`,
+    recommendation: `Split into smaller extractions or increase extraction frequency`,
+    recordCount: edges.length,
+    maxAllowed: MAX_RECORDS_PER_RUN,
+  };
+}
+
+if (estimatedSizeMB > MAX_CSV_SIZE_MB) {
+  log.warn('CSV size approaching limit', {
+    estimatedSizeMB: estimatedSizeMB.toFixed(2),
+    maxAllowed: MAX_CSV_SIZE_MB,
+  });
+}
+
+log.info('Extraction limits validated', {
+  recordCount: edges.length,
+  estimatedSizeMB: estimatedSizeMB.toFixed(2),
+  withinLimits: true,
+});
+
+// Transform with UniversalMapper
+const mapper = new UniversalMapper(inventoryQuantitiesExportMapping);
+const transformedRecords: any[] = [];
+for (const edge of edges) {
+  const mapped = await mapper.map(edge.node);
+  if (mapped.success) {
+    transformedRecords.push(mapped.data);
+  }
+}
+
+// Save state WITHOUT buffer (use MAX(updatedOn))
+const maxUpdatedOn = transformedRecords.reduce((max, r) => {
+  const t = new Date(r.updated_on).getTime();
+  return t > max ? t : max;
+}, new Date(rawLastRunTime).getTime());
+
+await kv.set(stateKey, {
+  timestamp: new Date(maxUpdatedOn).toISOString(),
+  recordCount: transformedRecords.length,
+  extractedAt: new Date().toISOString(),
+  overlapBufferSeconds,
+});
+
+// Date range guardrails (if you add dateRange/historical modes)
+function validateDateRange(mode: 'dateRange' | 'historical', from: string, to: string) {
+  const start = new Date(from);
+  const end = new Date(to);
+  const daysDiff = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
+  const maxDays = mode === 'dateRange' ? 30 : 90;
+  if (daysDiff > maxDays) {
+    return {
+      valid: false,
+      error: `${mode} mode: Maximum ${maxDays}-day window. Requested: ${Math.round(daysDiff)} days.`,
+    };
+  }
+  if (daysDiff < 0) return { valid: false, error: 'endDate must be after startDate' };
+  return { valid: true };
+}
+```
+
+---
+
+## Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`workflow()`** → Durable workflows (advanced, rarely used)
+
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from schedule/webhook)
+- **`fn()`** → Internal processing (chained from schedule/webhook)
+
+### Recommended Project Structure
+
+```
+inventory-quantities-extraction/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── scheduled/
+    │   │   └── daily-inventory-quantities-extraction.ts  # Scheduled: Daily extraction
+    │   │
+    │   └── webhook/
+    │       ├── adhoc-inventory-quantities-extraction.ts  # Webhook: Manual trigger
+    │       └── job-status-check.ts                      # Webhook: Status query
+    │
+    ├── services/
+    │   └── inventory-quantities-extraction.service.ts    # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── inventory-quantities.export.csv.json         # Mapping configuration
+```
+
+---
+
+````csv
+quantity_id,quantity_ref,catalogue_ref,catalogue_name,location,sku,quantity,type,status,expected_on,created_on,updated_on
+Q001,QTY-REF-001,DEFAULT_CATALOGUE,Default Catalogue,DC01,SKU-001,100,AVAILABLE,ACTIVE,,2025-01-15T10:00:00Z,2025-01-22T08:30:00Z
+Q002,QTY-REF-002,DEFAULT_CATALOGUE,Default Catalogue,DC01,SKU-001,50,RESERVED,ACTIVE,,2025-01-16T11:00:00Z,2025-01-22T09:15:00Z
+Q003,QTY-REF-003,DEFAULT_CATALOGUE,Default Catalogue,DC02,SKU-002,200,EXPECTED,CREATED,2025-01-30T00:00:00Z,2025-01-17T12:00:00Z,2025-01-22T10:00:00Z
+Q004,QTY-REF-004,DEFAULT_CATALOGUE,Default Catalogue,STORE-NYC,SKU-003,25,AVAILABLE,ACTIVE,,2025-01-18T13:00:00Z,2025-01-22T11:00:00Z
+
+## Advanced Mapping Patterns
+
+### Array Mapping (Preserving Nested Structure)
+
+For nested data structures, use `isArray: true` pattern:
+
+```json
+{
+  "fields": {
+    "ref": { "source": "ref", "required": true },
+    "relatedItems": {
+      "source": "items",
+      "isArray": true,
+      "fields": {
+        "itemRef": { "source": "ref", "required": true },
+        "value": { "source": "value", "resolver": "sdk.parseFloat" }
+      }
+    }
+  }
+}
+````
+
+**When to use**:
+
+- **Flattened structure**: Simpler, easier for downstream systems
+- **Nested with arrays**: Complex data, preserves relationships
+
+### Nested Object Mapping
+
+**Option 1: Flattened paths** (recommended):
+
+```json
+{
+  "fields": {
+    "location_ref": { "source": "location.ref" },
+    "location_name": { "source": "location.name" }
+  }
+}
+```
+
+**Option 2: Nested object definition**:
+
+```json
+{
+  "fields": {
+    "location": {
+      "fields": {
+        "ref": { "source": "location.ref" },
+        "name": { "source": "location.name" }
+      }
+    }
+  }
+}
+```
+
+## Error Handling Strategies
+
+### Handling Mapping Failures
+
+**Strategy 1: Fail-fast (strict)**:
+
+```typescript
+if (errors.length > 0) {
+  throw new Error(`${errors.length} records failed mapping validation`);
+}
+```
+
+**Strategy 2: Threshold-based (recommended)**:
+
+```typescript
+const errorRate = errors.length / transformed.length;
+if (errorRate > 0.05) {
+  // 5% threshold
+  throw new Error(`Error rate too high: ${(errorRate * 100).toFixed(1)}%`);
+}
+```
+
+**Strategy 3: Upload error manifest**:
+
+```typescript
+if (errors.length > 0) {
+  const errorManifest = {
+    extractionTimestamp: new Date().toISOString(),
+    totalErrors: errors.length,
+    errors: errors.map(e => ({ record: e.record, errors: e.errors })),
+  };
+  // Upload to storage for review
+}
+```
+
+### State Management with Partial Failures
+
+**Recommended**: Only update state if extraction succeeded:
+
+```typescript
+if (errors.length === 0) {
+  await kv.set(stateKey, { timestamp: newTimestamp });
+  log.info('State updated - all records successful');
+} else {
+  log.warn('State NOT updated - will retry next run', {
+    failedRecords: errors.length,
+    willRetryNextRun: true,
+  });
+}
+```
+
+## GraphQL Query Validation & Testing
+
+### Schema Validation Workflow
+
+**Step 1: Introspect schema**
+
+```bash
+npx fc-connect introspect-schema \
+  --url https://your-instance.api.fluentcommerce.com/graphql \
+  --output fluent-schema.json
+```
+
+**Step 2: Validate mapping**
+
+```bash
+npx fc-connect validate-schema \
+  --mapping ./config/mapping.json \
+  --schema ./fluent-schema.json
+```
+
+**Step 3: Analyze coverage**
+
+```bash
+npx fc-connect analyze-coverage \
+  --mapping ./config/mapping.json \
+  --schema ./fluent-schema.json
+```
+
+### GraphQL Pagination Explained
+
+The SDK handles pagination automatically:
+
+```typescript
+await client.graphql({
+  query: QUERY,
+  variables: { first: pageSize },
+  pagination: { maxRecords }, // SDK handles cursors automatically
+});
+```
+
+## Date Format Handling
+
+| Format   | Resolver              | Output                     | Use Case  |
+| -------- | --------------------- | -------------------------- | --------- |
+| CSV/JSON | `sdk.formatDate`      | `2025-01-22T14:30:00.000Z` | ISO 8601  |
+| CSV/JSON | `sdk.formatDateShort` | `2025-01-22`               | Date only |
+| CSV/JSON | `sdk.toString`        | Pass through               | As-is     |
+
+## Monitoring & Alerting
+
+### Key Metrics to Track
+
+```typescript
+const metrics = {
+  extractionDurationMs: Date.now() - startTime,
+  recordCount: edges.length,
+  transformedCount: transformed.length,
+  failedCount: errors.length,
+  errorRate: ((errors.length / edges.length) * 100).toFixed(2) + '%',
+  fileSizeMB: (buffer.length / (1024 * 1024)).toFixed(2),
+  lastRunTime: rawLastRunTime,
+  newTimestamp: newTimestamp,
+};
+log.info('Extraction complete', metrics);
+```
+
+### Alert Thresholds
+
+```typescript
+const ALERTS = {
+  EXTRACTION_DURATION_MS: 5 * 60 * 1000, // 5 minutes
+  MAX_ERROR_RATE: 0.05, // 5%
+  MAX_FILE_SIZE_MB: 150, // 150MB
+  MAX_RECORDS_PER_RUN: 100000, // Adjust per entity
+};
+```
+
+## Testing Checklist
+
+**Before production deployment:**
+
+### 1. Schema Validation
+
+- [ ] Run `npx fc-connect introspect-schema`
+- [ ] Run `npx fc-connect validate-schema`
+- [ ] Run `npx fc-connect analyze-coverage`
+- [ ] Verify all `source` paths exist
+
+### 2. Mapping Testing
+
+- [ ] Test with sample data (maxRecords=10)
+- [ ] Verify required fields populated
+- [ ] Verify SDK resolvers work correctly
+- [ ] Test custom resolvers with edge cases
+
+### 3. Error Handling
+
+- [ ] Test with invalid data
+- [ ] Verify error collection
+- [ ] Test error threshold logic
+
+### 4. State Management
+
+- [ ] Verify overlap buffer prevents misses
+- [ ] Test state recovery after failure
+- [ ] Verify timestamp saved WITHOUT buffer
+
+### 5. File Operations
+
+- [ ] Test connection and upload
+- [ ] Verify file format validity
+- [ ] Test with large files (>50MB)
+
+### 6. Staging Environment
+
+- [ ] Run full extraction in staging
+- [ ] Verify file format with downstream system
+- [ ] Monitor duration and resource usage
+
+## Troubleshooting Guide
+
+**Issue**: "Extraction timeout after 10 minutes"
+
+- **Cause**: Too many records
+- **Fix**: Reduce maxRecords, increase frequency
+
+**Issue**: "Mapping errors for 50% of records"
+
+- **Cause**: Schema mismatch
+- **Fix**: Run schema validation, check field names
+
+**Issue**: "State not updating"
+
+- **Cause**: KV write failure or intentional retry
+- **Fix**: Check KV logs, verify state update code
+
+**Issue**: "First run exceeds limits"
+
+- **Cause**: No previous timestamp, fetches all
+- **Fix**: Set fallbackStartDate close to current, apply filters
+
+**Issue**: "Excessive duplicates"
+
+- **Cause**: Overlap buffer (expected) or timestamp not saved
+- **Fix**: Verify newTimestamp saved WITHOUT buffer
+
+## Security Best Practices
+
+### Credential Management
+
+**✅ DO**:
+
+- Store credentials in Versori activation variables
+- Rotate credentials quarterly
+- Use least-privilege accounts
+
+**❌ DON'T**:
+
+- Never log credentials
+- Never commit to git
+- Never share across environments
+
+### Data Security
+
+- Enable encryption in transit and at rest
+- Apply data retention policies
+- Monitor access logs
+- Use VPC/private networks for sensitive data
+
+---
+
+```
+
+---
+
+**Pattern**: Enterprise incremental extraction with overlap buffer for inventory quantities
+**⚠️ Sample Code**: For SDK demonstration only - **ONLY use incremental mode in production**
+**Key Learning**: Use VersoriKVAdapter for state management with 60-second overlap buffer
+**Critical**: Apply overlap buffer to prevent missed records due to clock skew (default: 60 seconds)
+**Buffer Pattern**: Query WITH buffer (`updatedOn >= lastRunTime - 60s`), save WITHOUT buffer (`MAX(updatedOn)`)
+**Timezone**: All timestamps are ISO 8601 UTC format - no conversion needed
+```
+
+---
+
+## 🔧 Complete Production Code
+
+### 1. Entry Point (src/index.ts)
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * This file is the entry point for the Versori deployment.
+ * It imports and re-exports workflows from their respective files:
+ * 1. Scheduled extraction (runs automatically on cron schedule)
+ * 2. Ad hoc webhook (manual trigger with optional date override)
+ * 3. Job status webhook (query job progress)
+ *
+ * AI CUSTOMIZATION:
+ * - Add new workflows by importing from their respective files
+ * - Remove workflows by commenting out imports/exports
+ * - Organize workflows by type (scheduled vs webhook) for clarity
+ */
+
+import { scheduledInventoryQuantitiesExtraction } from './workflows/scheduled/daily-inventory-quantities-extraction';
+import { adhocInventoryQuantitiesExtraction } from './workflows/webhook/adhoc-inventory-quantities-extraction';
+import { inventoryQuantitiesJobStatus } from './workflows/webhook/job-status-check';
+
+// Register workflows with Versori platform
+// The platform will expose webhooks as HTTP endpoints and run scheduled workflows on cron schedule
+
+export {
+  scheduledInventoryQuantitiesExtraction, // Cron-based auto-run (NOT exposed as HTTP endpoint)
+  adhocInventoryQuantitiesExtraction,     // Manual webhook trigger (HTTP endpoint)
+  inventoryQuantitiesJobStatus,           // Job status query (HTTP endpoint)
+};
+```
+
+---
+
+### 2. Workflows
+
+#### src/workflows/scheduled/daily-inventory-quantities-extraction.ts
+
+```typescript
+/**
+ * WORKFLOW 1: Scheduled Extraction
+ *
+ * Purpose: Automated hourly extraction for incremental sync
+ * Trigger: Cron schedule (every hour at minute 0)
+ * State Update: Always updates lastSync timestamp
+ *
+ * AI CUSTOMIZATION:
+ * - Change schedule: Replace '0 * * * *' with your cron expression
+ *   Examples:
+ *   - Every 30 min: '*/30 * * * *'
+ *   - Daily at 2 AM: '0 2 * * *'
+ *   - Every 15 min: '*/15 * * * *'
+ */
+
+import { schedule, fn } from '@versori/run';
+import { executeInventoryQuantityExtraction } from '../../services/extraction-orchestration';
+import { generateJobId } from '../../utils/job-id-generator';
+
+/**
+ * WORKFLOW 1: Scheduled Extraction
+ *
+ * Purpose: Automated hourly extraction for incremental sync
+ * Trigger: Cron schedule (every hour at minute 0)
+ * State Update: Always updates lastSync timestamp
+ *
+ * AI CUSTOMIZATION:
+ * - Change schedule: Replace '0 * * * *' with your cron expression
+ *   Examples:
+ *   - Every 30 min: '*/30 * * * *'
+ *   - Daily at 2 AM: '0 2 * * *'
+ *   - Every 15 min: '*/15 * * * *'
+ */
+export const scheduledInventoryQuantitiesExtraction = schedule(
+  'inventory-quantities-scheduled',
+  '0 * * * *',  // ← CUSTOMIZE: Cron expression
+  fn('execute-scheduled-extraction', async (ctx) => {
+    const { log, activation } = ctx;
+    const startTime = Date.now();
+
+    // Generate unique job ID for tracking
+    // Format: SCHEDULED_IQ_YYYYMMDD_HHMMSS_random
+    const jobId = generateJobId('SCHEDULED', 'INVENTORY_QUANTITIES');
+
+    log.info('🚀 [START] Scheduled extraction triggered', { jobId });
+
+    try {
+      // Execute main workflow (extraction → transform → upload)
+      const result = await executeInventoryQuantityExtraction(ctx, {
+        jobId,
+        triggeredBy: 'schedule',
+        updateState: true,        // Always update state for scheduled runs
+      });
+
+      const durationMs = Date.now() - startTime;
+
+      log.info('✅ [END] Scheduled extraction completed', {
+        jobId,
+        recordCount: result.recordsExtracted,
+        fileName: result.fileName,
+        durationMs,
+        durationSec: (durationMs / 1000).toFixed(2)
+      });
+
+      return result;
+
+    } catch (error: any) {
+      const durationMs = Date.now() - startTime;
+
+      log.error('❌ [ERROR] Scheduled extraction failed', {
+        jobId,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        durationMs,
+        recommendation: 'Check Fluent API connectivity, S3 credentials, and date range configuration'
+      });
+      throw error;
+    }
+  }));
+```
+
+---
+
+#### src/workflows/webhook/adhoc-inventory-quantities-extraction.ts
+
+```typescript
+/**
+ * WORKFLOW 2: Ad hoc Extraction (Manual Trigger)
+ *
+ * Purpose: Manual extraction with optional date range override
+ * Trigger: Webhook POST to /webhooks/inventory-quantities-adhoc
+ * State Update: Optional (controlled by request payload)
+ *
+ * WEBHOOK PAYLOAD EXAMPLES:
+ *
+ * 1. Incremental (use last sync timestamp):
+ *    {}
+ *
+ * 2. Date range (manual override):
+ *    {
+ *      "fromDate": "2025-01-01T00:00:00Z",
+ *      "toDate": "2025-01-31T23:59:59Z",
+ *      "updateState": false
+ *    }
+ *
+ * AI CUSTOMIZATION:
+ * - Add request validation
+ * - Add authentication check
+ * - Add custom filters from payload
+ */
+
+import { webhook, fn } from '@versori/run';
+import { executeInventoryQuantityExtraction } from '../../services/extraction-orchestration';
+import { generateJobId } from '../../utils/job-id-generator';
+
+export const adhocInventoryQuantitiesExtraction = webhook(
+  'inventory-quantities-adhoc',
+  { connection: 'inventory-quantities-adhoc', response: { mode: 'sync' } },
+  fn('execute-adhoc-extraction', async (ctx) => {
+    const { data, log, connections, activation } = ctx;
+    const startTime = Date.now();
+
+    // Generate unique job ID
+    const jobId = generateJobId('ADHOC', 'INVENTORY_QUANTITIES');
+
+    // SECURITY: Authentication is enforced by Versori connection configuration
+    // Configure auth on the connection and reference it in webhook({ connection: '...' })
+
+    // Extract optional date override from webhook payload
+    const fromDate = data.fromDate as string | undefined;
+    const toDate = data.toDate as string | undefined;
+    const updateState = data.updateState === true;  // Default false; advance state only if explicitly true
+
+    log.info('🌐 [START] Ad hoc extraction triggered via webhook', {
+      jobId,
+      hasDateOverride: !!fromDate,
+      fromDate: fromDate || 'not specified',
+      toDate: toDate || 'not specified',
+      updateState
+    });
+
+    try {
+      // Execute main workflow with optional overrides
+      const result = await executeInventoryQuantityExtraction(ctx, {
+        jobId,
+        triggeredBy: 'webhook',
+        fromDate,              // Optional: override start date
+        toDate,                // Optional: override end date
+        updateState,           // Optional: skip state update for historical queries
+      });
+
+      const durationMs = Date.now() - startTime;
+
+      log.info('✅ [END] Ad hoc extraction completed', {
+        jobId,
+        recordCount: result.recordsExtracted,
+        fileName: result.fileName,
+        isManualOverride: !!fromDate,
+        stateUpdated: result.stateUpdated,
+        durationMs,
+        durationSec: (durationMs / 1000).toFixed(2)
+      });
+
+      // Return success with job details
+      return {
+        success: true,
+        jobId,
+        recordsExtracted: result.recordsExtracted,
+        fileName: result.fileName,
+        s3Path: result.s3Path,
+        statusUrl: `/webhooks/inventory-quantities-job-status?jobId=${jobId}`,
+        durationMs,
+        dateRange: fromDate ? {
+          from: fromDate,
+          to: toDate || 'not specified',
+          updateState
+        } : undefined
+      };
+
+    } catch (error: any) {
+      const durationMs = Date.now() - startTime;
+
+      log.error('❌ [ERROR] Ad hoc extraction failed', {
+        jobId,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        durationMs,
+        recommendation: 'Verify date range format (ISO 8601), check S3 credentials, and ensure Fluent API access'
+      });
+
+      return {
+        success: false,
+        jobId,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        durationMs,
+        recommendation: 'Verify date range format (ISO 8601), check S3 credentials, and ensure Fluent API access'
+      };
+    }
+  }));
+```
+
+---
+
+#### src/workflows/webhook/job-status-check.ts
+
+```typescript
+/**
+ * WORKFLOW 3: Job Status Query
+ *
+ * Purpose: Check job progress and status
+ * Trigger: Webhook GET/POST to /webhooks/inventory-quantities-job-status?jobId=xxx
+ * Returns: Current job status, stage, progress
+ *
+ * QUERY EXAMPLES:
+ *
+ * 1. HTTP GET:
+ *    GET /webhooks/inventory-quantities-job-status?jobId=ADHOC_IQ_20251027_183045_abc123
+ *
+ * 2. HTTP POST:
+ *    POST /webhooks/inventory-quantities-job-status
+ *    { "jobId": "ADHOC_IQ_20251027_183045_abc123" }
+ */
+
+import { webhook, fn } from '@versori/run';
+import { getJobStatus } from '../../services/extraction-orchestration';
+
+export const inventoryQuantitiesJobStatus = webhook(
+  'inventory-quantities-job-status',
+  { connection: 'inventory-quantities-job-status', response: { mode: 'sync' } },
+  fn('query-job-status', async (ctx) => {
+    const { data, log, openKv, activation } = ctx;
+    const startTime = Date.now();
+
+    // SECURITY: Authentication is enforced by Versori connection configuration
+    // Configure auth on the connection and reference it in webhook({ connection: '...' })
+
+    // Get jobId from query param or POST body
+    const jobId = data.jobId as string;
+
+    if (!jobId) {
+      log.error('❌ Job ID not provided in request');
+      return {
+        success: false,
+        error: 'Job ID is required. Provide jobId in query param or request body.'
+      };
+    }
+
+    log.info('🔍 [START] Querying job status', { jobId });
+
+    try {
+      // Query job status from KV store
+      const status = await getJobStatus(openKv(':project:'), jobId, log);
+
+      const durationMs = Date.now() - startTime;
+
+      if (!status) {
+        log.info('⚠️ Job not found', { jobId, durationMs });
+        return {
+          success: false,
+          error: 'Job not found',
+          jobId,
+          durationMs
+        };
+      }
+
+      log.info('✅ [END] Job status retrieved', {
+        jobId,
+        status: status.status,
+        durationMs
+      });
+
+      return {
+        success: true,
+        jobId,
+        ...status,
+        queryDurationMs: durationMs
+      };
+
+    } catch (error: any) {
+      const durationMs = Date.now() - startTime;
+
+      log.error('❌ [ERROR] Failed to query job status', {
+        jobId,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        durationMs,
+        recommendation: 'Verify KV store access and job ID format'
+      });
+
+      return {
+        success: false,
+        jobId,
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        durationMs,
+        recommendation: 'Verify KV store access and job ID format'
+      };
+    }
+  }));
+```
+
+---
+
+### 3. Main Orchestration Service (src/services/extraction-orchestration.ts)
+
+```typescript
+/**
+ * MAIN ORCHESTRATION SERVICE
+ *
+ * This is the heart of the extraction workflow. It coordinates all steps:
+ * 1. Initialize clients and services
+ * 2. Determine date range (incremental vs manual)
+ * 3. Extract data using ExtractionOrchestrator
+ * 4. Transform using UniversalMapper
+ * 5. Generate CSV using CSVParserService
+ * 6. Upload to S3
+ * 7. Track job progress with JobTracker
+ * 8. Update state for next run
+ *
+ * NAMING PATTERN (consistent across all use cases):
+ * - Interface: {Entity}ExtractionParams (e.g., InventoryQuantityExtractionParams)
+ * - Result: {Entity}ExtractionResult (e.g., InventoryQuantityExtractionResult)
+ * - Main function: execute{Entity}Extraction (e.g., executeInventoryQuantityExtraction)
+ *
+ * AI CUSTOMIZATION HINTS:
+ * - Change entity: Replace "InventoryQuantity" with "Order", "Product", etc.
+ * - Change output: Replace CSVParserService with XMLBuilder
+ * - Change destination: Replace S3DataSource with SftpDataSource
+ * - Add steps: Insert new service calls between existing steps
+ */
+
+import { Buffer } from 'node:buffer';
+import {
+  createClient,
+  ExtractionOrchestrator,
+  JobTracker,
+  UniversalMapper,
+  CSVParserService,
+  S3DataSource,
+} from '@fluentcommerce/fc-connect-sdk';
+
+import mappingConfig from '../../config/inventory-quantities.export.csv.json' with { type: 'json' };
+
+// ✅ VERSORI PLATFORM: Use native log from context, not LoggingService
+
+/**
+ * Parameters for extraction workflow
+ *
+ * NAMING: {Entity}ExtractionParams
+ */
+export interface InventoryQuantityExtractionParams {
+  jobId: string;
+  triggeredBy: 'schedule' | 'webhook';
+  fromDate?: string; // Optional: manual date override
+  toDate?: string; // Optional: manual date override
+  updateState: boolean; // Whether to update lastSync timestamp
+
+  // AI CUSTOMIZATION: Add filters specific to entity
+  quantityTypes?: string[]; // e.g., ['LAST_ON_HAND', 'RESERVED']
+  catalogueRef?: string; // e.g., 'DEFAULT_CATALOGUE'
+}
+
+/**
+ * Result from extraction workflow
+ *
+ * NAMING: {Entity}ExtractionResult
+ */
+export interface InventoryQuantityExtractionResult {
+  success: boolean;
+  jobId: string;
+  recordsExtracted: number;
+  fileName?: string;
+  s3Path?: string;
+  error?: string;
+  errors?: any[];
+  isManualOverride?: boolean;
+  stateUpdated?: boolean;
+  newTimestamp?: string;
+}
+
+/**
+ * GraphQL Query for Inventory Quantities
+ *
+ * NAMING: {ENTITY}_EXTRACTION_QUERY (uppercase constant)
+ */
+const INVENTORY_QUANTITIES_EXTRACTION_QUERY = `
+  query GetInventoryQuantities(
+    $catalogues: [InventoryCatalogueKey]
+    $dateRangeFilter: DateRange
+    $productRefs: [String!]
+    $types: [String!]
+    $first: Int!
+    $after: String
+  ) {
+    inventoryQuantities(
+      catalogues: $catalogues
+      updatedOn: $dateRangeFilter
+      productRef: $productRefs
+      type: $types
+      first: $first
+      after: $after
+    ) {
+      edges {
+        node {
+          id
+          ref
+          locationRef
+          productRef
+          qty
+          type
+          status
+          expectedOn
+          createdOn
+          updatedOn
+          catalogue {
+            ref
+            name
+          }
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+  }
+`;
+
+/**
+ * Query job status from KV store
+ *
+ * ✅ VERSORI PLATFORM: Uses native log from context (passed as parameter)
+ */
+export async function getJobStatus(
+  kv: any, // ✅ Versori KV (compatible with JobTracker's KVAdapter interface)
+  jobId: string,
+  log: any // ✅ Native Versori log from context
+): Promise<any | undefined> {
+  try {
+    const tracker = new JobTracker(kv, log);
+    return await tracker.getJob(jobId);
+  } catch (error: any) {
+    log.error('Failed to get job status', { jobId, message: error instanceof Error ? error.message : String(error),
+ stack: error instanceof Error ? error.stack : undefined,
+ errorType: error instanceof Error ? error.constructor.name : 'Error', });
+    return undefined;
+  }
+}
+
+/**
+ * MAIN ORCHESTRATION FUNCTION
+ *
+ * NAMING: execute{Entity}Extraction (e.g., executeInventoryQuantityExtraction)
+ *
+ * This function implements the complete workflow in steps.
+ * Each step is clearly commented for AI understanding.
+ */
+export async function executeInventoryQuantityExtraction(
+  ctx: any,
+  params: InventoryQuantityExtractionParams
+): Promise<InventoryQuantityExtractionResult> {
+  // ✅ VERSORI PLATFORM: Extract native log from context
+  const { log, openKv, activation } = ctx;
+  const { jobId, triggeredBy, fromDate, toDate, updateState } = params;
+
+  // Open KV store for state management and job tracking
+  // ✅ Pass raw Versori KV directly - it matches KVAdapter interface
+  // ✅ Pass native log to JobTracker
+  const kv = openKv(':project:');
+  const tracker = new JobTracker(kv, log);
+
+  try {
+    // ═══════════════════════════════════════════════════════════
+    // STEP 1/8: Initialize Job Tracking
+    // ═══════════════════════════════════════════════════════════
+    log.info('📝 [STEP 1/8] Initializing job tracking', { jobId });
+
+    await tracker.createJob(jobId, {
+      triggeredBy,
+      hasDateOverride: !!fromDate,
+      fromDate,
+      toDate,
+      updateStateAfterRun: updateState,
+    });
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 2/8: Initialize Fluent Client
+    // ═══════════════════════════════════════════════════════════
+    log.info('📡 [STEP 2/8] Initializing Fluent Commerce client', { jobId });
+
+    const client = await createClient(ctx, { validateConnection: true });
+
+    if (!client) {
+      throw new Error('Failed to create Fluent Commerce client');
+    }
+
+    log.info('✅ Fluent client initialized and connection validated', { jobId });
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 3/8: Determine Date Range
+    // ═══════════════════════════════════════════════════════════
+    log.info('📅 [STEP 3/8] Determining date range for extraction', { jobId });
+
+    // State key for incremental sync tracking
+    // NAMING: last{Entity}Sync (e.g., lastInventoryQuantitySync)
+    const STATE_KEY = 'lastInventoryQuantitySync';
+    const DEFAULT_FALLBACK = '2024-01-01T00:00:00Z';
+    const OVERLAP_BUFFER_SECONDS = parseInt(
+      activation.getVariable('overlapBufferSeconds') || '60',
+      10
+    );
+
+    let dateRangeFilter: { from?: string; to?: string } | null = null;
+    const isManualOverride = !!fromDate;
+
+    if (isManualOverride) {
+      // Manual date override from webhook
+      dateRangeFilter = { from: fromDate, to: toDate };
+      log.info('Using manual date override', { fromDate, toDate });
+    } else {
+      // Incremental sync - get last sync timestamp
+      const rawLastRunTime = (await kv.get<string>(STATE_KEY)) || DEFAULT_FALLBACK;
+
+      // Apply overlap buffer (prevents missed records)
+      const bufferedLastRunTime = new Date(
+        new Date(rawLastRunTime).getTime() - OVERLAP_BUFFER_SECONDS * 1000
+      ).toISOString();
+
+      const effectiveEndTime = toDate || new Date().toISOString();
+
+      dateRangeFilter = {
+        from: bufferedLastRunTime,
+        to: effectiveEndTime, // End of extraction window
+      };
+
+      log.info('Using incremental sync with overlap buffer', {
+        rawLastRunTime,
+        bufferedLastRunTime,
+        effectiveEndTime,
+        overlapBufferSeconds: OVERLAP_BUFFER_SECONDS,
+      });
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 4/8: Extract Data (ExtractionOrchestrator)
+    // ═══════════════════════════════════════════════════════════
+    log.info('🔄 [STEP 4/8] Extracting data from Fluent Commerce', { jobId });
+
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'extraction',
+      message: 'Extracting data with auto-pagination',
+    });
+
+    // Build catalogues array from config
+    const catalogueRef = params.catalogueRef || activation.getVariable('catalogueRef');
+    const catalogues = catalogueRef ? [{ ref: catalogueRef }] : [];
+
+    // Configure extraction
+    const pageSize = parseInt(activation.getVariable('pageSize') || '200', 10);
+    const maxRecords = parseInt(activation.getVariable('maxRecords') || '100000', 10);
+
+    // Initialize ExtractionOrchestrator
+    const orchestrator = new ExtractionOrchestrator(client, log);
+
+    // ? Enhanced: Extract context for progress logging
+    const dateRangeInfo = {
+      start: dateRangeFilter?.from || 'N/A',
+      end: dateRangeFilter?.to || 'N/A',
+      catalogues: catalogues.map((c: any) => c.ref).join(', ') || 'all',
+      types: params.quantityTypes?.join(', ') || 'all'
+    };
+
+    // ? Enhanced: Start logging with context
+    log.info(`🔍 [ExtractionOrchestrator] Starting extraction`, {
+     query: 'inventoryQuantities',
+     pageSize,
+     maxRecords,
+     dateRange: `${dateRangeInfo.start} to ${dateRangeInfo.end}`,
+     catalogues: dateRangeInfo.catalogues,
+     quantityTypes: dateRangeInfo.types,
+     jobId
+    });
+
+    // Execute extraction with auto-pagination
+    const extractionResult = await orchestrator.extract({
+      query: INVENTORY_QUANTITIES_EXTRACTION_QUERY,
+      resultPath: 'inventoryQuantities.edges.node',
+      variables: {
+        catalogues,
+        dateRangeFilter,
+        types: params.quantityTypes,
+        // Note: Don't include 'first' or 'after' here; orchestrator injects them
+      },
+      pageSize,
+      maxRecords,
+      // Optional: validate each record
+      validateItem: (item: any) => {
+        return !!(item.ref && item.productRef);
+      },
+    });
+
+    const records = extractionResult.data || [];
+
+    log.info('Extraction complete', {
+      totalRecords: extractionResult.stats.totalRecords,
+      totalPages: extractionResult.stats.totalPages,
+      validRecords: extractionResult.stats.validRecords ?? records.length,
+      failedValidations: extractionResult.stats.failedValidations,
+      errors: extractionResult.errors ? extractionResult.errors.length : 0,
+    });
+
+    // ? Enhanced: Completion logging with summary
+    log.info(`✅ [ExtractionOrchestrator] Extraction completed`, {
+     totalRecords: extractionResult.stats.totalRecords,
+     totalPages: extractionResult.stats.totalPages,
+     validRecords: extractionResult.stats.validRecords ?? records.length,
+     failedValidations: extractionResult.stats.failedValidations,
+     truncated: extractionResult.stats.truncated,
+     truncationReason: extractionResult.stats.truncationReason,
+     dateRange: `${dateRangeInfo.start} to ${dateRangeInfo.end}`,
+     jobId
+    });
+
+    if (extractionResult.errors && extractionResult.errors.length > 0) {
+      log.warn('Non-fatal extraction errors encountered', {
+        errorCount: extractionResult.errors.length,
+        sampleErrors: extractionResult.errors.slice(0, 3),
+      });
+    }
+
+    // Handle empty result
+    if (records.length === 0) {
+      log.info('No records to process');
+
+      // Update state even with no records (prevents re-querying empty window)
+      if (updateState && !isManualOverride) {
+        await kv.set(STATE_KEY, new Date().toISOString());
+      }
+
+      await tracker.markCompleted(jobId, {
+        recordCount: 0,
+        message: 'No records to extract',
+      });
+
+      return {
+        success: true,
+        jobId,
+        recordsExtracted: 0,
+      };
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 5/8: Transform Data (UniversalMapper)
+    // ═══════════════════════════════════════════════════════════
+    log.info('🔧 [STEP 5/8] Transforming data with UniversalMapper', {
+      jobId,
+      recordCount: records.length,
+    });
+
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'transformation',
+      message: `Transforming ${records.length} records`,
+    });
+
+    const mapper = new UniversalMapper(mappingConfig);
+    const mappingResult = await mapper.map(records);
+
+    if (!mappingResult.success) {
+      const mappingErrors = mappingResult.errors || ['Unknown mapping failure'];
+      await tracker.markFailed(jobId, {
+        error: mappingErrors[0] || 'UniversalMapper returned unsuccessful result',
+        failedCount: mappingErrors.length,
+      });
+      return {
+        success: false,
+        error: `Transformation failed: ${mappingErrors[0] || 'Unknown error'}`,
+        jobId,
+        errors: mappingErrors,
+      };
+    }
+
+    const transformedRecords = Array.isArray(mappingResult.data) ? mappingResult.data : [];
+    const mappingErrors = mappingResult.errors || [];
+
+    if (mappingErrors.length > 0) {
+      log.warn('Some records failed transformation', {
+        jobId,
+        errorCount: mappingErrors.length,
+        sampleErrors: mappingErrors.slice(0, 3),
+      });
+    }
+
+    if (transformedRecords.length === 0) {
+      await tracker.markFailed(jobId, {
+        error: 'All records failed mapping',
+        failedCount: mappingErrors.length,
+        errors: mappingErrors,
+      });
+      return {
+        success: false,
+        error: 'All records failed mapping',
+        jobId,
+        errors: mappingErrors,
+      };
+    }
+
+    log.info('Transformation complete', {
+      successful: transformedRecords.length,
+      failed: mappingErrors.length,
+      skippedRecords: records.length - transformedRecords.length,
+    });
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 6/8: Generate CSV (CSVParserService)
+    // ═══════════════════════════════════════════════════════════
+    log.info('📄 [STEP 6/8] Generating CSV file', { jobId });
+
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'csv_generation',
+      message: `Generating CSV for ${transformedRecords.length} records`,
+    });
+
+    // Initialize CSVParserService
+    const csvParser = new CSVParserService({ includeHeaders: true });
+
+    // Generate CSV content
+    const csvContent = await csvParser.stringify(transformedRecords);
+
+    // Generate filename
+    const fileNamePrefix = activation.getVariable('fileNamePrefix') || 'inventoryquantities';
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const fileName = `${fileNamePrefix}-${timestamp}.csv`;
+
+    log.info('CSV file generated', {
+      fileName,
+      sizeBytes: csvContent.length,
+      recordCount: transformedRecords.length,
+    });
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 7/8: Upload to S3 (S3DataSource)
+    // ═══════════════════════════════════════════════════════════
+    log.info('☁️ [STEP 7/8] Uploading to S3', { jobId, fileName });
+
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 's3_upload',
+      message: `Uploading ${fileName} to S3`,
+    });
+
+    // Get S3 configuration from activation variables
+    const s3Config = {
+      bucket: activation.getVariable('s3BucketName'),
+      region: activation.getVariable('awsRegion') || 'us-east-1',
+      accessKeyId: activation.getVariable('awsAccessKeyId'),
+      secretAccessKey: activation.getVariable('awsSecretAccessKey'),
+    };
+    const s3Prefix = activation.getVariable('s3Prefix') || 'inventory-quantities/daily/';
+
+    // Validate S3 config
+    if (!s3Config.bucket || !s3Config.accessKeyId || !s3Config.secretAccessKey) {
+      throw new Error(
+        'S3 configuration incomplete: missing bucket, accessKeyId, or secretAccessKey'
+      );
+    }
+
+    // Initialize S3 data source
+    // ✅ VERSORI PLATFORM: Pass native log from context
+    const s3 = new S3DataSource(
+      {
+        type: 'S3_CSV',
+        connectionId: 'inventory-quantities-s3',
+        name: 'Inventory Quantities S3 Upload',
+        s3Config,
+      },
+      log
+    );
+
+    // Construct S3 key
+    const s3Key = `${s3Prefix}${fileName}`;
+
+    // Upload with retry logic (built into S3DataSource)
+    await s3.uploadFile(s3Key, Buffer.from(csvContent, 'utf-8'), {
+      contentType: 'text/csv',
+      metadata: {
+        recordCount: String(transformedRecords.length),
+        extractedAt: new Date().toISOString(),
+        jobId,
+        mappingErrors: mappingErrors.length > 0 ? String(mappingErrors.length) : undefined,
+      },
+    });
+
+    log.info('S3 upload successful', { fileName, s3Key });
+
+    // ═══════════════════════════════════════════════════════════
+    // STEP 8/8: Update State & Complete Job
+    // ═══════════════════════════════════════════════════════════
+    log.info('💾 [STEP 8/8] Updating state and completing job', { jobId });
+
+    // Calculate new timestamp for next incremental run
+    let newTimestamp: string | undefined;
+
+    if (updateState && !isManualOverride) {
+      // Find max updatedOn from extracted records
+      const maxUpdatedOn = records.reduce(
+        (max, record) => {
+          const recordTime = new Date(record.updatedOn).getTime();
+          return recordTime > max ? recordTime : max;
+        },
+        new Date(dateRangeFilter?.from || DEFAULT_FALLBACK).getTime()
+      );
+
+      newTimestamp = new Date(maxUpdatedOn).toISOString();
+
+      // Store new timestamp (WITHOUT buffer - buffer only applied on read)
+      await kv.set(STATE_KEY, newTimestamp);
+
+      log.info('State updated', {
+        oldTimestamp: dateRangeFilter?.from,
+        newTimestamp,
+      });
+    }
+
+    // Mark job as completed
+    await tracker.markCompleted(jobId, {
+      recordCount: transformedRecords.length,
+      fileName,
+      s3Key,
+      errorCount: mappingErrors.length,
+      errors: mappingErrors,
+      isManualOverride,
+      stateUpdated: updateState,
+      newTimestamp,
+    });
+
+    return {
+      success: true,
+      jobId,
+      recordsExtracted: transformedRecords.length,
+      fileName,
+      s3Path: s3Key,
+      isManualOverride,
+      stateUpdated: updateState,
+      newTimestamp,
+      errors: mappingErrors.length > 0 ? mappingErrors : undefined,
+    };
+  } catch (error: any) {
+    log.error('Extraction workflow failed', {
+      jobId,
+      message: error instanceof Error ? error.message : String(error),
+
+      stack: error instanceof Error ? error.stack : undefined,
+
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+    });
+
+    // Mark job as failed
+    await tracker.markFailed(jobId, error);
+
+    return {
+      success: false,
+      jobId,
+      recordsExtracted: 0,
+      message: error instanceof Error ? error.message : String(error),
+
+      stack: error instanceof Error ? error.stack : undefined,
+
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+    };
+  }
+}
+```
+
+---
+
+### 4. Utility Functions (src/utils/job-id-generator.ts)
+
+```typescript
+/**
+ * Job ID Generator
+ *
+ * Generates unique job IDs for tracking extraction workflows
+ *
+ * FORMAT: {TYPE}_{ENTITY}_{YYYYMMDD}_{HHMMSS}_{RANDOM}
+ * Example: SCHEDULED_IQ_20251027_183045_a1b2c3
+ */
+
+/**
+ * Generate unique job ID
+ *
+ * @param type - Job trigger type (SCHEDULED, ADHOC, MANUAL)
+ * @param entity - Entity abbreviation (IQ=Inventory Quantities, IP, VP, ORD, PRD)
+ * @returns Unique job ID string
+ */
+export function generateJobId(type: string, entity: string): string {
+  const now = new Date();
+
+  // Format: YYYYMMDD
+  const dateStr = now.toISOString().slice(0, 10).replace(/-/g, '');
+
+  // Format: HHMMSS
+  const timeStr = now.toISOString().slice(11, 19).replace(/:/g, '');
+
+  // Random suffix (6 chars)
+  const randomStr = Math.random().toString(36).substring(2, 8);
+
+  return `${type}_${entity}_${dateStr}_${timeStr}_${randomStr}`;
+}
+
+/**
+ * Parse job ID components
+ */
+export function parseJobId(jobId: string): {
+  type: string;
+  entity: string;
+  date: string;
+  time: string;
+  random: string;
+} | null {
+  const parts = jobId.split('_');
+
+  if (parts.length !== 5) {
+    return null;
+  }
+
+  return {
+    type: parts[0],
+    entity: parts[1],
+    date: parts[2],
+    time: parts[3],
+    random: parts[4],
+  };
+}
+```
+
+---
+
+### 5. Package Configuration
+
+#### package.json
+
+```json
+{
+  "name": "inventory-quantities-to-s3-csv",
+  "version": "1.0.0",
+  "description": "Extract inventory quantities from Fluent Commerce and export to S3 as CSV",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "versori dev",
+    "build": "versori build",
+    "deploy": "versori deploy"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+#### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+
+---
+
+## 6. Deployment Instructions
+
+### Deploy to Versori
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Test locally (if using Versori CLI)
+npm run dev
+
+# 3. Deploy to Versori platform
+npm run deploy
+```
+
+### Configure Activation Variables
+
+In Versori platform settings, configure:
+
+```json
+{
+  "catalogueRef": "DEFAULT_CATALOGUE",
+  "s3BucketName": "inventory-audit-exports",
+  "awsAccessKeyId": "AKIAXXXXXXXXXXXX",
+  "awsSecretAccessKey": "********",
+  "awsRegion": "us-east-1",
+  "s3Prefix": "inventory-quantities/daily/",
+  "fileNamePrefix": "inventoryquantities",
+  "pageSize": 200,
+  "maxRecords": 100000,
+  "overlapBufferSeconds": 60,
+  "webhookApiKey": "your-secure-api-key-here"
+}
+```
+
+---
+
+## 7. Testing
+
+### Test Scheduled Extraction
+
+The scheduled workflow runs automatically based on cron schedule.
+
+**Check logs:**
+
+```
+[STEP 1/8] Initializing job tracking
+[STEP 2/8] Initializing Fluent Commerce client
+[STEP 3/8] Determining date range for extraction
+[STEP 4/8] Extracting data from Fluent Commerce
+[STEP 5/8] Transforming data with UniversalMapper
+[STEP 6/8] Generating CSV file
+[STEP 7/8] Uploading to S3
+[STEP 8/8] Updating state and completing job
+```
+
+### Test Ad hoc Extraction
+
+```bash
+# Incremental (uses last sync timestamp)
+curl -X POST https://api.versori.com/webhooks/inventory-quantities-adhoc \
+  -H "X-API-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Date range override
+curl -X POST https://api.versori.com/webhooks/inventory-quantities-adhoc \
+  -H "X-API-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fromDate": "2025-01-01T00:00:00Z",
+    "toDate": "2025-01-31T23:59:59Z",
+    "updateState": false
+  }'
+```
+
+### Test Job Status Query
+
+```bash
+curl -X POST https://api.versori.com/webhooks/inventory-quantities-job-status \
+  -H "X-API-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jobId": "ADHOC_IQ_20251027_183045_abc123"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "jobId": "ADHOC_IQ_20251027_183045_abc123",
+  "status": "processing",
+  "stage": "transformation",
+  "message": "Transforming 15000 records",
+  "createdAt": "2025-10-27T18:30:45.000Z",
+  "startedAt": "2025-10-27T18:30:46.000Z"
+}
+```
+
+---
+
+## 8. Troubleshooting
+
+**Issue**: "No records extracted"
+
+- Check dateRange (manual override vs incremental)
+- Check catalogueRef filter
+- Verify quantity types filter
+
+**Issue**: "S3 upload failed"
+
+- Job fails; state not advanced
+- Next run retries same window
+- Check S3 credentials and bucket permissions
+
+**Issue**: "GraphQL pagination error"
+
+- Ensure edges.cursor and pageInfo.hasNextPage are in query
+
+**Issue**: "Memory pressure"
+
+- Lower pageSize or maxRecords
+- Consider file splitting for large extractions
+
+**Issue**: "Transformation errors"
+
+- Check mapping config field paths
+- Verify required fields are present in GraphQL response
+- Review transformation error details in logs
+
+---
+
+## 9. Replication Checklist
+
+**To replicate this template for other entities/formats:**
+
+1. **File Naming:** Replace `inventory-quantities`, `IQ`, `InventoryQuantity` with your entity name
+2. **GraphQL Query:** Update query constant and field selection to match your entity schema
+3. **Mapping Config:** Create new mapping file in `config/` with correct field paths
+4. **Workflows:** Rename workflow exports to match entity (e.g., `scheduledOrdersExtraction`)
+5. **Service Function:** Rename main function (e.g., `executeOrderExtraction`)
+6. **State Key:** Update KV key (e.g., `lastOrderSync`)
+7. **Output Format:** For XML use `XMLBuilder`, for JSON use `JSON.stringify()`, for CSV use `CSVParserService`
+8. **Upload Destination:** For SFTP replace `S3DataSource` with `SftpDataSource` (and add `dispose()` in finally block)
+9. **Job ID Entity Code:** Update entity abbreviation in generateJobId() (e.g., 'ORD' for orders)
+10. **Result Path:** Update `resultPath` in ExtractionOrchestrator (e.g., `'orders.edges.node'`)
+
+---
+
+**Pattern**: Enterprise incremental extraction with overlap buffer for inventory quantities
+**Key Learning**: Use ExtractionOrchestrator for auto-pagination, JobTracker for job status, CSVParserService for CSV generation
+**Critical**: Apply 60-second overlap buffer to prevent missed records due to clock skew
+**Buffer Pattern**: Query WITH buffer (`updatedOn >= lastRunTime - 60s`), save WITHOUT buffer (`MAX(updatedOn)`)
+**SDK Services**: ExtractionOrchestrator, UniversalMapper, CSVParserService, S3DataSource, JobTracker
+**Entity-Specific**: Query uses `inventoryQuantities`, resultPath is `'inventoryQuantities.edges.node'`, state key is `lastInventoryQuantitySync`
+
+---
+
+### Optional: Backward Pagination (Advanced)
+
+- Default: forward ($first/$after) + pageInfo.hasNextPage.
+- Reverse: define $last/$before and include pageInfo.hasPreviousPage; set direction='backward'.
+
+GraphQL:
+
+```graphql
+query GetInventoryQuantitiesBackward($retailerId: ID!, $last: Int!, $before: String) {
+  inventoryQuantities(retailerId: $retailerId, last: $last, before: $before) {
+    edges {
+      cursor
+      node {
+        id
+        ref
+        updatedOn
+      }
+    }
+    pageInfo {
+      hasPreviousPage
+    }
+  }
+}
+```
+
+SDK:
+
+```typescript
+await orchestrator.extract({
+  query: INVENTORY_QUANTITIES_BACKWARD_QUERY,
+  resultPath: 'inventoryQuantities.edges.node',
+  variables: { retailerId },
+  pageSize,
+  direction: 'backward',
+});
+```