@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/business-examples/business-examples-pre-order-allocation.md

@@ -1,2226 +1,2226 @@
-# Versori Pre-Order Allocation Management
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Real-time pre-order reservation system with future ATP (Available to Promise) calculation and priority queuing
-
-**Complexity**: High
-
-**Volume**: High during launches (100-10,000 pre-orders)
-
-**Latency**: Real-time (< 2 seconds)
-
-**Runtime**: Versori Platform (HTTP Webhook + Scheduled)
-
-**Pattern**: Webhook + future ATP check + reservation + priority queue + scheduled release
-
-**Estimated Lines**: ~1200 lines
-
-## What You'll Build
-
-- **Pre-Order Webhook**: Receive pre-order requests from e-commerce platforms
-
-- **Future ATP Calculation**: Calculate available inventory for future ship dates
-  - Query current inventory levels
-  - Query existing reservations for target date
-  - Calculate net available quantity
-  - Apply overbooking strategy (105% of expected inventory)
-
-- **Reservation Management**: Create and track reservations in Fluent
-  - Store reservation with priority tier (VIP, Standard)
-  - Assign queue position within tier
-  - Set expiration window (7 days before ship date)
-
-- **Priority Queuing**: VIP customers get priority allocation
-  - Tier-based scoring (VIP=100, Standard=50)
-  - First-come-first-served within tier
-  - Queue position tracking via VersoriKV
-
-- **Scheduled Release Workflow**: Convert reservations to allocations on ship date
-  - Query all reservations for current date
-  - Convert to fulfillment orders
-  - Handle insufficient inventory (cancel lower priority)
-  - Email notifications to customers
-
-- **Cancellation Workflow**: Release reservation and offer to next in queue
-
-- **Admin Dashboard Export**: Export reservation status to S3
-
-## SDK Methods Used
-
-- `webhook('name', { response: { mode } })` - HTTP webhook endpoints
-- `schedule('name', 'cron')` - Scheduled workflows
-- `createClient(ctx)` - Create Fluent client
-- `client.graphql({ query, variables })` - Execute GraphQL queries/mutations
-- `VersoriKVAdapter(openKv())` - State management
-- `VersoriFileTracker` - Track processed reservations
-- `GraphQLMutationMapper` - Custom mutations for reservations
-- `UniversalMapper` - Field transformations
-- `XMLBuilder` - Response formatting
-
----
-
-## 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:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-pre-order-allocation/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── webhook/
-    │   │   └── reservation.ts            # Webhook: Create reservations
-    │   │
-    │   └── scheduled/
-    │       └── release-reservations.ts    # Scheduled: Release reservations
-    │
-    ├── services/
-    │   └── reservation.service.ts        # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── reservation-config.json       # Configuration
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Scalable (add new workflows without cluttering)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Easy to modify individual workflows without affecting others
-
----
-
-## Complete Working Code
-
-### 1. Main Workflow File: `index.ts`
-
-```typescript
-/**
- * Pre-Order Allocation Management System
- *
- * Handles high-volume product launches with priority-based reservations
- * and future inventory allocation.
- *
- * Key Features:
- * - Real-time ATP (Available to Promise) calculation for future dates
- * - Priority queuing (VIP vs Standard customers)
- * - Reservation expiration management
- * - Overbooking strategy (105% allocation)
- * - Scheduled release on ship date
- * - Cancellation with queue reallocation
- */
-
-import { webhook, schedule, http, fn } from '@versori/run';
-import {
-  createClient,
-  VersoriKVAdapter,
-  VersoriFileTracker,
-  UniversalMapper,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// =============================================================================
-// TYPE DEFINITIONS
-// =============================================================================
-
-interface PreOrderRequest {
-  orderId: string;
-  customerId: string;
-  customerEmail: string;
-  customerTier: 'VIP' | 'STANDARD'; // Priority tier
-  items: PreOrderItem[];
-  shipDate: string; // Future ship date (ISO 8601)
-  source: string; // E-commerce platform identifier
-}
-
-interface PreOrderItem {
-  sku: string;
-  productName: string;
-  quantity: number;
-  locationRef: string;
-}
-
-interface ReservationRecord {
-  reservationId: string;
-  orderId: string;
-  customerId: string;
-  customerEmail: string;
-  sku: string;
-  quantity: number;
-  locationRef: string;
-  shipDate: string;
-  priority: number; // Calculated priority score
-  queuePosition: number;
-  tier: 'VIP' | 'STANDARD';
-  status: 'RESERVED' | 'CONFIRMED' | 'CANCELLED' | 'EXPIRED';
-  createdAt: string;
-  expiresAt: string; // 7 days before ship date
-  confirmedAt?: string;
-  cancelledAt?: string;
-}
-
-interface ATPCalculation {
-  sku: string;
-  locationRef: string;
-  shipDate: string;
-  currentInventory: number;
-  existingReservations: number;
-  expectedArrival: number; // Expected inventory by ship date
-  availableToPromise: number;
-  overbookingLimit: number; // 105% of expected
-  canFulfill: boolean;
-}
-
-// =============================================================================
-// WORKFLOW 1: PRE-ORDER WEBHOOK (Real-time)
-// =============================================================================
-
-/**
- * Pre-Order Webhook - Receives pre-order from e-commerce platform
- *
- * Flow:
- * 1. Parse and validate pre-order request
- * 2. Calculate future ATP for each item
- * 3. Create reservation if inventory available
- * 4. Assign priority and queue position
- * 5. Store reservation in VersoriKV
- * 6. Send confirmation response
- */
-export const preOrderWebhook = webhook('pre-order', {
-  response: {
-    mode: 'sync',
-    // Custom response handler for JSON
-    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    }),
-    onError: (ctx) => new Response(JSON.stringify({
-      success: false,
-      error: ctx.data instanceof Error ? ctx.data.message : String(ctx.data),
-      timestamp: new Date().toISOString()
-    }), {
-      status: 400,
-      headers: { 'Content-Type': 'application/json' }
-    })
-  },
-  cors: true
-})
-  // Step 1: Validate pre-order request
-  .then(fn('validate-request', (ctx) => {
-    const { data, log } = ctx;
-
-    log.info('🔍 Validating pre-order request');
-    const request = data as PreOrderRequest;
-
-    // Validation checks
-    if (!request.orderId || !request.customerId || !request.customerEmail) {
-      log.error('[PreOrderAllocation] Validation error: Missing required fields', {
-        recommendation: 'Ensure pre-order request includes orderId, customerId, and customerEmail'
-      });
-      throw new Error('Missing required fields: orderId, customerId, or customerEmail');
-    }
-
-    if (!request.items || request.items.length === 0) {
-      log.error('[PreOrderAllocation] Validation error: No items in pre-order', {
-        recommendation: 'Pre-order must contain at least one item'
-      });
-      throw new Error('Pre-order must contain at least one item');
-    }
-
-    if (!request.shipDate) {
-      log.error('[PreOrderAllocation] Validation error: Missing ship date', {
-        recommendation: 'Ship date is required for pre-orders'
-      });
-      throw new Error('Ship date is required for pre-orders');
-    }
-
-    // Validate ship date is in the future
-    const shipDate = new Date(request.shipDate);
-    const now = new Date();
-    const daysDiff = Math.floor((shipDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
-
-    if (daysDiff < 7) {
-      log.error('[PreOrderAllocation] Validation error: Ship date too soon', {
-        daysDiff,
-        recommendation: 'Ship date must be at least 7 days in the future for pre-orders'
-      });
-      throw new Error(`Ship date must be at least 7 days in the future (got ${daysDiff} days)`);
-    }
-
-    if (daysDiff > 180) {
-      log.error('[PreOrderAllocation] Validation error: Ship date too far in future', {
-        daysDiff,
-        recommendation: 'Ship date cannot be more than 180 days in the future'
-      });
-      throw new Error(`Ship date cannot be more than 180 days in the future (got ${daysDiff} days)`);
-    }
-
-    log.info('✅ Pre-order request validated', {
-      orderId: request.orderId,
-      itemCount: request.items.length,
-      shipDate: request.shipDate,
-      daysUntilShip: daysDiff,
-      tier: request.customerTier || 'STANDARD'
-    });
-
-    return {
-      request,
-      shipDate,
-      daysUntilShip: daysDiff,
-      expiresAt: new Date(shipDate.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString() // 7 days before
-    };
-  }))
-
-  // Step 2: Calculate future ATP for each item
-  .then(http('calculate-atp', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { request, shipDate, expiresAt } = ctx.data;
-    const { log } = ctx;
-
-    log.info('📊 Calculating future ATP for items');
-
-    const startTime = Date.now();
-    const client = await createClient(ctx, { validateConnection: true });
-    const atpResults: ATPCalculation[] = [];
-
-    for (const item of request.items) {
-      try {
-        // Query current inventory
-        const inventoryResult = await client.graphql({
-          query: `
-            query GetInventory($locationRef: String!, $skuRef: String!) {
-              inventoryQuantities(
-                first: 1
-                locationRef: $locationRef
-                skuRef: $skuRef
-                type: "LAST_ON_HAND"
-              ) {
-                edges {
-                  node {
-                    id
-                    quantity
-                    expectedOn
-                  }
-                }
-              }
-            }`,
-          variables: {
-            locationRef: item.locationRef,
-            skuRef: item.sku
-          }
-        });
-
-        const currentInventory = inventoryResult.data?.inventoryQuantities?.edges?.[0]?.node?.quantity || 0;
-
-        // Query existing reservations for this SKU + ship date
-        // NOTE: This assumes reservations are stored as custom attributes
-        // In production, you'd query a custom entity type or use attributes
-        const reservationsResult = await client.graphql({
-          query: `
-            query GetReservations($sku: String!, $shipDate: String!) {
-              # This is a placeholder - implement based on your reservation storage
-              # Option 1: Custom entity type
-              # Option 2: Inventory attributes
-              # Option 3: External database
-              inventoryQuantities(
-                first: 100
-                skuRef: $sku
-                status: "RESERVED"
-              ) {
-                edges {
-                  node {
-                    id
-                    quantity
-                    attributes {
-                      name
-                      value
-                    }
-                  }
-                }
-              }
-            }
-          `,
-          variables: {
-            sku: item.sku,
-            shipDate: request.shipDate
-          }
-        });
-
-        // Calculate existing reservations
-        let existingReservations = 0;
-        const reservationEdges = reservationsResult.data?.inventoryQuantities?.edges || [];
-        for (const edge of reservationEdges) {
-          const shipDateAttr = edge.node.attributes?.find((a: any) => a.name === 'shipDate');
-          if (shipDateAttr?.value === request.shipDate) {
-            existingReservations += edge.node.quantity || 0;
-          }
-        }
-
-        // Query expected arrivals (purchase orders, transfers)
-        const expectedArrivalResult = await client.graphql({
-          query: `
-            query GetExpectedArrivals($locationRef: String!, $skuRef: String!, $beforeDate: String!) {
-              inventoryQuantities(
-                first: 50
-                locationRef: $locationRef
-                skuRef: $skuRef
-                type: "EXPECTED"
-                expectedOnBefore: $beforeDate
-              ) {
-                edges {
-                  node {
-                    quantity
-                    expectedOn
-                  }
-                }
-              }
-            }
-          `,
-          variables: {
-            locationRef: item.locationRef,
-            skuRef: item.sku,
-            beforeDate: request.shipDate
-          }
-        });
-
-        const expectedArrival = expectedArrivalResult.data?.inventoryQuantities?.edges?.reduce(
-          (sum: number, edge: any) => sum + (edge.node.quantity || 0),
-          0
-        ) || 0;
-
-        // Calculate ATP with overbooking strategy
-        const totalExpected = currentInventory + expectedArrival;
-        const overbookingLimit = Math.floor(totalExpected * 1.05); // 105% overbooking
-        const availableToPromise = overbookingLimit - existingReservations;
-
-        const atp: ATPCalculation = {
-          sku: item.sku,
-          locationRef: item.locationRef,
-          shipDate: request.shipDate,
-          currentInventory,
-          existingReservations,
-          expectedArrival,
-          availableToPromise,
-          overbookingLimit,
-          canFulfill: availableToPromise >= item.quantity
-        };
-
-        atpResults.push(atp);
-
-        log.info('✅ ATP calculated', {
-          sku: item.sku,
-          current: currentInventory,
-          expected: expectedArrival,
-          reserved: existingReservations,
-          atp: availableToPromise,
-          requested: item.quantity,
-          canFulfill: atp.canFulfill
-        });
-      } catch (error) {
-        // ? Enhanced: Error logging with recommendations
-        log.error('[PreOrderAllocation] Failed to calculate ATP for SKU', {
-          sku: item.sku,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('query') || error.message?.includes('GraphQL')
-            ? 'Check GraphQL query syntax and inventory query structure'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details and check ATP calculation logic'
-        });
-        throw error;
-      }
-    }
-
-    // Check if all items can be fulfilled
-    const allAvailable = atpResults.every(atp => atp.canFulfill);
-    const duration = Date.now() - startTime;
-
-    log.info(`⏱️ ATP calculation complete (${duration}ms)`, {
-      totalItems: atpResults.length,
-      allAvailable
-    });
-
-    return {
-      ...ctx.data,
-      atpResults,
-      allAvailable,
-      client
-    };
-  }))
-
-  // Step 3: Create reservations or add to waitlist
-  .then(fn('create-reservations', async ({ data, openKv, log }) => {
-    const { request, atpResults, allAvailable, expiresAt, client } = data;
-
-    log.info('📦 Creating reservations');
-
-    const kvAdapter = new VersoriKVAdapter(openKv());
-    const reservationTracker = new VersoriFileTracker(openKv(), 'pre-order-reservations');
-
-    const reservations: ReservationRecord[] = [];
-    const failedItems: any[] = [];
-
-    // Calculate priority score
-    const tierScore = request.customerTier === 'VIP' ? 100 : 50;
-    const timeScore = Date.now(); // Earlier orders get lower scores (better priority)
-    const priorityScore = tierScore * 1000000 - timeScore; // VIP orders always sort higher
-
-    for (let i = 0; i < request.items.length; i++) {
-      const item = request.items[i];
-      const atp = atpResults[i];
-
-      if (!atp.canFulfill) {
-        failedItems.push({
-          sku: item.sku,
-          quantity: item.quantity,
-          available: atp.availableToPromise,
-          reason: 'Insufficient inventory available for this ship date'
-        });
-        continue;
-      }
-
-      // Get current queue position for this SKU + ship date
-      const queueKey = ['queue', atp.sku, atp.locationRef, request.shipDate].join(':');
-      const queueData = await kvAdapter.get([queueKey]);
-      const currentQueueLength = (queueData?.value as number) || 0;
-      const queuePosition = currentQueueLength + 1;
-
-      // Update queue length
-      await kvAdapter.set([queueKey], queuePosition);
-
-      // Create reservation record
-      const reservationId = `RES-${request.orderId}-${item.sku}-${Date.now()}`;
-      const reservation: ReservationRecord = {
-        reservationId,
-        orderId: request.orderId,
-        customerId: request.customerId,
-        customerEmail: request.customerEmail,
-        sku: item.sku,
-        quantity: item.quantity,
-        locationRef: item.locationRef,
-        shipDate: request.shipDate,
-        priority: priorityScore,
-        queuePosition,
-        tier: request.customerTier || 'STANDARD',
-        status: 'RESERVED',
-        createdAt: new Date().toISOString(),
-        expiresAt
-      };
-
-      // Store reservation in KV
-      await kvAdapter.set(['reservation', reservationId], reservation);
-
-      // Track in indexed tracker for listing
-      await reservationTracker.markFileProcessed(reservationId, {
-        orderId: request.orderId,
-        sku: item.sku,
-        shipDate: request.shipDate,
-        priority: priorityScore
-      });
-
-      // Create reservation in Fluent (as custom inventory type or entity)
-      try {
-        await client.graphql({
-          query: `
-            mutation CreateReservation($input: InventoryQuantityInput!) {
-              createInventoryQuantity(input: $input) {
-                id
-                ref
-                quantity
-                status
-              }
-            }
-          `,
-          variables: {
-            input: {
-              ref: reservationId,
-              locationRef: item.locationRef,
-              skuRef: item.sku,
-              type: 'RESERVED',
-              status: 'RESERVED',
-              quantity: item.quantity,
-              expectedOn: request.shipDate,
-              attributes: [
-                { name: 'orderId', value: request.orderId },
-                { name: 'customerId', value: request.customerId },
-                { name: 'customerEmail', value: request.customerEmail },
-                { name: 'tier', value: request.customerTier || 'STANDARD' },
-                { name: 'priority', value: String(priorityScore) },
-                { name: 'queuePosition', value: String(queuePosition) },
-                { name: 'expiresAt', value: expiresAt },
-                { name: 'reservationId', value: reservationId }
-              ]
-            }
-          }
-        });
-
-        log.info('✅ Reservation created in Fluent', {
-          reservationId,
-          sku: item.sku,
-          quantity: item.quantity,
-          priority: priorityScore,
-          queuePosition
-        });
-      } catch (error) {
-        // ? Enhanced: Error logging with recommendations
-        log.error('[PreOrderAllocation] Failed to create reservation in Fluent', {
-          reservationId,
-          error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.constructor.name : 'Error',
-          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-            : error.message?.includes('mutation') || error.message?.includes('GraphQL')
-            ? 'Check GraphQL mutation syntax and reservation payload structure'
-            : error.message?.includes('inventory') || error.message?.includes('quantity')
-            ? 'Check available inventory quantity and reservation limits'
-            : error.message?.includes('connection') || error.message?.includes('timeout')
-            ? 'Check network connectivity and Fluent Commerce API availability'
-            : 'Review error details - reservation is in KV and can be retried'
-        });
-        // Continue - reservation is in KV, can be retried
-      }
-
-      reservations.push(reservation);
-    }
-
-    return {
-      success: failedItems.length === 0,
-      reservations,
-      failedItems,
-      orderId: request.orderId,
-      shipDate: request.shipDate,
-      tier: request.customerTier || 'STANDARD'
-    };
-  }))
-
-  // Step 4: Send email confirmation (placeholder)
-  .then(fn('send-confirmation', async ({ data, log }) => {
-    const { success, reservations, failedItems, orderId, shipDate, tier } = data;
-
-    log.info('📧 Sending customer notification');
-
-    // TODO: Integrate with email service (SendGrid, SES, etc.)
-    // This is a placeholder showing the data structure
-    const emailPayload = {
-      to: reservations[0]?.customerEmail,
-      subject: success
-        ? `Pre-Order Confirmed - Order ${orderId}`
-        : `Pre-Order Partially Confirmed - Order ${orderId}`,
-      body: {
-        orderId,
-        shipDate,
-        tier,
-        confirmedItems: reservations.map(r => ({
-          sku: r.sku,
-          quantity: r.quantity,
-          queuePosition: r.queuePosition,
-          expiresAt: r.expiresAt
-        })),
-        failedItems,
-        message: success
-          ? `Your pre-order has been confirmed! You are ${tier === 'VIP' ? 'priority' : 'standard'} tier.`
-          : `Some items could not be reserved. Please review below.`
-      }
-    };
-
-    log.info('✅ Email prepared', {
-      to: emailPayload.to,
-      confirmedCount: reservations.length,
-      failedCount: failedItems.length
-    });
-
-    // In production: await emailService.send(emailPayload);
-
-    return {
-      success,
-      orderId,
-      reservations: reservations.map(r => ({
-        reservationId: r.reservationId,
-        sku: r.sku,
-        quantity: r.quantity,
-        queuePosition: r.queuePosition,
-        priority: r.priority,
-        expiresAt: r.expiresAt
-      })),
-      failedItems,
-      message: success
-        ? `All items reserved successfully`
-        : `${reservations.length} items reserved, ${failedItems.length} failed`,
-      timestamp: new Date().toISOString()
-    };
-  }));
-
-// =============================================================================
-// WORKFLOW 2: SCHEDULED RELEASE (Daily at 2 AM)
-// =============================================================================
-
-/**
- * Scheduled Release Workflow - Convert reservations to allocations
- *
- * Runs daily at 2 AM to process reservations for today's ship date
- *
- * Flow:
- * 1. Query all reservations for today's ship date
- * 2. Sort by priority (VIP first, then by queue position)
- * 3. Convert to fulfillment orders
- * 4. Handle insufficient inventory (cancel lower priority)
- * 5. Send confirmation/cancellation emails
- */
-export const scheduledRelease = schedule('release-reservations', '0 2 * * *', async (ctx) => {
-  const { log, openKv } = ctx;
-  const startTime = Date.now();
-
-  return http('process-release', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { log } = ctx;
-    const client = await createClient(ctx, { validateConnection: true });
-    const kvAdapter = new VersoriKVAdapter(openKv());
-    const reservationTracker = new VersoriFileTracker(openKv(), 'pre-order-reservations');
-
-    log.info('🚀 Starting scheduled release process');
-
-    const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
-
-    try {
-      // Step 1: Query all reservations for today
-      const result = await client.graphql({
-        query: `
-          query GetTodayReservations($shipDate: String!) {
-            inventoryQuantities(
-              first: 1000
-              type: "RESERVED"
-              status: "RESERVED"
-              expectedOn: $shipDate
-            ) {
-              edges {
-                node {
-                  id
-                  ref
-                  quantity
-                  skuRef
-                  locationRef
-                  attributes {
-                    name
-                    value
-                  }
-                }
-              }
-            }
-          }
-        `,
-        variables: { shipDate: today }
-      });
-
-      const reservationEdges = result.data?.inventoryQuantities?.edges || [];
-      log.info(`📋 Found ${reservationEdges.length} reservations for ${today}`);
-
-      // Step 2: Parse and sort by priority
-      interface ReservationWithPriority {
-        id: string;
-        ref: string;
-        quantity: number;
-        sku: string;
-        locationRef: string;
-        priority: number;
-        queuePosition: number;
-        orderId: string;
-        customerId: string;
-        customerEmail: string;
-        tier: string;
-        reservationId: string;
-      }
-
-      const reservations: ReservationWithPriority[] = reservationEdges.map((edge: any) => {
-        const attrs = edge.node.attributes || [];
-        const getAttr = (name: string) => attrs.find((a: any) => a.name === name)?.value;
-
-        return {
-          id: edge.node.id,
-          ref: edge.node.ref,
-          quantity: edge.node.quantity,
-          sku: edge.node.skuRef,
-          locationRef: edge.node.locationRef,
-          priority: parseInt(getAttr('priority') || '0'),
-          queuePosition: parseInt(getAttr('queuePosition') || '999'),
-          orderId: getAttr('orderId') || '',
-          customerId: getAttr('customerId') || '',
-          customerEmail: getAttr('customerEmail') || '',
-          tier: getAttr('tier') || 'STANDARD',
-          reservationId: getAttr('reservationId') || edge.node.ref
-        };
-      });
-
-      // Sort by priority (higher priority = lower number due to negative time component)
-      reservations.sort((a, b) => b.priority - a.priority);
-
-      log.info('✅ Sorted reservations by priority', {
-        vipCount: reservations.filter(r => r.tier === 'VIP').length,
-        standardCount: reservations.filter(r => r.tier === 'STANDARD').length
-      });
-
-      // Step 3: Group by SKU and location
-      const groupedBySku = new Map<string, ReservationWithPriority[]>();
-      for (const reservation of reservations) {
-        const key = `${reservation.sku}:${reservation.locationRef}`;
-        if (!groupedBySku.has(key)) {
-          groupedBySku.set(key, []);
-        }
-        groupedBySku.get(key)!.push(reservation);
-      }
-
-      // Step 4: Process each SKU group
-      const confirmed: any[] = [];
-      const cancelled: any[] = [];
-
-      for (const [skuKey, skuReservations] of groupedBySku.entries()) {
-        const [sku, locationRef] = skuKey.split(':');
-
-        // Query current inventory
-        const invResult = await client.graphql({
-          query: `
-            query GetInventory($sku: String!, $locationRef: String!) {
-              inventoryQuantities(
-                first: 1
-                skuRef: $sku
-                locationRef: $locationRef
-                type: "LAST_ON_HAND"
-              ) {
-                edges {
-                  node {
-                    quantity
-                  }
-                }
-              }
-            }
-          `,
-          variables: { sku, locationRef }
-        });
-
-        let availableQty = invResult.data?.inventoryQuantities?.edges?.[0]?.node?.quantity || 0;
-
-        log.info(`⚙️ Processing ${skuReservations.length} reservations for ${sku}`, {
-          available: availableQty,
-          totalRequested: skuReservations.reduce((sum, r) => sum + r.quantity, 0)
-        });
-
-        // Allocate inventory by priority
-        for (const reservation of skuReservations) {
-          if (availableQty >= reservation.quantity) {
-            // Confirm reservation - create fulfillment order
-            try {
-              await client.graphql({
-                query: `
-                  mutation CreateFulfillmentOrder($input: CreateOrderInput!) {
-                    createOrder(input: $input) {
-                      id
-                      ref
-                      status
-                    }
-                  }
-                `,
-                variables: {
-                  input: {
-                    ref: `FO-${reservation.orderId}-${Date.now()}`,
-                    type: 'FULFILLMENT',
-                    retailerId: '1', // From config
-                    customer: {
-                      ref: reservation.customerId,
-                      email: reservation.customerEmail
-                    },
-                    items: [{
-                      skuRef: reservation.sku,
-                      quantity: reservation.quantity,
-                      locationRef: reservation.locationRef
-                    }],
-                    attributes: [
-                      { name: 'originalOrderId', value: reservation.orderId },
-                      { name: 'reservationId', value: reservation.reservationId },
-                      { name: 'tier', value: reservation.tier },
-                      { name: 'shipDate', value: today }
-                    ]
-                  }
-                }
-              });
-
-              // Update reservation status
-              await client.graphql({
-                query: `
-                  mutation UpdateReservation($id: ID!, $status: String!) {
-                    updateInventoryQuantity(id: $id, status: $status) {
-                      id
-                      status
-                    }
-                  }
-                `,
-                variables: {
-                  id: reservation.id,
-                  status: 'CONFIRMED'
-                }
-              });
-
-              // Update KV
-              const kvRecord = await kvAdapter.get(['reservation', reservation.reservationId]);
-              if (kvRecord?.value) {
-                const record = kvRecord.value as ReservationRecord;
-                record.status = 'CONFIRMED';
-                record.confirmedAt = new Date().toISOString();
-                await kvAdapter.set(['reservation', reservation.reservationId], record);
-              }
-
-              availableQty -= reservation.quantity;
-              confirmed.push(reservation);
-
-              log.info(`✅ Confirmed reservation: ${reservation.reservationId}`);
-            } catch (error) {
-              // ? Enhanced: Error logging with recommendations
-              log.error('[PreOrderAllocation] Failed to confirm reservation', {
-                reservationId: reservation.reservationId,
-                error: error instanceof Error ? error.message : String(error),
-                recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-                  ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-                  : error.message?.includes('mutation') || error.message?.includes('GraphQL')
-                  ? 'Check GraphQL mutation syntax and reservation confirmation payload'
-                  : error.message?.includes('inventory') || error.message?.includes('quantity')
-                  ? 'Check available inventory quantity and reservation status'
-                  : 'Review error details and check reservation confirmation logic'
-              });
-            }
-          } else {
-            // Insufficient inventory - cancel reservation
-            try {
-              await client.graphql({
-                query: `
-                  mutation UpdateReservation($id: ID!, $status: String!) {
-                    updateInventoryQuantity(id: $id, status: $status) {
-                      id
-                      status
-                    }
-                  }
-                `,
-                variables: {
-                  id: reservation.id,
-                  status: 'CANCELLED'
-                }
-              });
-
-              // Update KV
-              const kvRecord = await kvAdapter.get(['reservation', reservation.reservationId]);
-              if (kvRecord?.value) {
-                const record = kvRecord.value as ReservationRecord;
-                record.status = 'CANCELLED';
-                record.cancelledAt = new Date().toISOString();
-                await kvAdapter.set(['reservation', reservation.reservationId], record);
-              }
-
-              cancelled.push({
-                ...reservation,
-                reason: 'Insufficient inventory',
-                availableQty
-              });
-
-              log.warn(`⚠️ Cancelled reservation: ${reservation.reservationId}`, {
-                reason: 'insufficient_inventory',
-                needed: reservation.quantity,
-                available: availableQty
-              });
-            } catch (error) {
-              // ? Enhanced: Error logging with recommendations
-              log.error('[PreOrderAllocation] Failed to cancel reservation', {
-                reservationId: reservation.reservationId,
-                error: error instanceof Error ? error.message : String(error),
-                recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-                  ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-                  : error.message?.includes('mutation') || error.message?.includes('GraphQL')
-                  ? 'Check GraphQL mutation syntax and reservation cancellation payload'
-                  : error.message?.includes('not found') || error.message?.includes('missing')
-                  ? 'Reservation not found - verify reservationId and check KV store'
-                  : 'Review error details and check reservation cancellation logic'
-              });
-            }
-          }
-        }
-      }
-
-      // Step 5: Send notifications (placeholder)
-      const duration = Date.now() - startTime;
-      log.info(`📧 Sending notifications (${duration}ms total)`, {
-        confirmed: confirmed.length,
-        cancelled: cancelled.length
-      });
-
-      // TODO: Send confirmation emails to confirmed reservations
-      // TODO: Send cancellation/apology emails to cancelled reservations
-
-      return {
-        success: true,
-        date: today,
-        processed: reservations.length,
-        confirmed: confirmed.length,
-        cancelled: cancelled.length,
-        duration,
-        summary: {
-          vipConfirmed: confirmed.filter(r => r.tier === 'VIP').length,
-          standardConfirmed: confirmed.filter(r => r.tier === 'STANDARD').length,
-          vipCancelled: cancelled.filter(r => r.tier === 'VIP').length,
-          standardCancelled: cancelled.filter(r => r.tier === 'STANDARD').length
-        },
-        timestamp: new Date().toISOString()
-      };
-    } catch (error) {
-      // ? Enhanced: Error logging with recommendations
-      log.error('[PreOrderAllocation] Scheduled release failed', {
-        error: error instanceof Error ? error.message : String(error),
-        errorType: error instanceof Error ? error.constructor.name : 'Error',
-        stack: error instanceof Error ? error.stack : undefined,
-        recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-          ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-          : error.message?.includes('KV') || error.message?.includes('state')
-          ? 'Check KV store connectivity and reservation state structure'
-          : error.message?.includes('connection') || error.message?.includes('timeout')
-          ? 'Check network connectivity and Fluent Commerce API availability'
-          : 'Review error details and check scheduled release workflow configuration'
-      });
-      throw error;
-    }
-  })(ctx);
-});
-
-// =============================================================================
-// WORKFLOW 3: CANCELLATION WEBHOOK
-// =============================================================================
-
-/**
- * Cancellation Webhook - Cancel reservation and offer to next in queue
- *
- * Flow:
- * 1. Receive cancellation request
- * 2. Update reservation status
- * 3. Query next customer in queue
- * 4. Offer to next customer (if available)
- * 5. Send notifications
- */
-export const cancellationWebhook = webhook('cancel-reservation', {
-  response: { mode: 'sync' },
-  cors: true
-})
-  .then(fn('validate-cancellation', ({ data, log }) => {
-    log.info('🔍 Processing cancellation request');
-
-    if (!data.reservationId && !data.orderId) {
-      throw new Error('Either reservationId or orderId is required');
-    }
-
-    return data;
-  }))
-  .then(http('cancel-and-requeue', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { reservationId, orderId } = ctx.data;
-    const { log, openKv } = ctx;
-    const client = await createClient(ctx, { validateConnection: true });
-    const kvAdapter = new VersoriKVAdapter(openKv());
-
-    log.info('🚫 Cancelling reservation', { reservationId, orderId });
-
-    // Find reservation in KV
-    let reservation: ReservationRecord | null = null;
-
-    if (reservationId) {
-      const kvRecord = await kvAdapter.get(['reservation', reservationId]);
-      reservation = kvRecord?.value as ReservationRecord;
-    } else {
-      // Search by orderId (would need indexed tracker)
-      // Placeholder: iterate through all reservations
-      log.warn('[CANCEL] Searching by orderId - implement indexed search for production');
-    }
-
-    if (!reservation) {
-      throw new Error(`Reservation not found: ${reservationId || orderId}`);
-    }
-
-    // Update status in Fluent
-    const result = await client.graphql({
-      query: `
-        query FindReservation($ref: String!) {
-          inventoryQuantities(first: 1, ref: $ref) {
-            edges {
-              node {
-                id
-                ref
-                status
-              }
-            }
-          }
-        }
-      `,
-      variables: { ref: reservation.reservationId }
-    });
-
-    const inventoryId = result.data?.inventoryQuantities?.edges?.[0]?.node?.id;
-
-    if (inventoryId) {
-      await client.graphql({
-        query: `
-          mutation CancelReservation($id: ID!, $status: String!) {
-            updateInventoryQuantity(id: $id, status: $status) {
-              id
-              status
-            }
-          }
-        `,
-        variables: {
-          id: inventoryId,
-          status: 'CANCELLED'
-        }
-      });
-    }
-
-    // Update KV
-    reservation.status = 'CANCELLED';
-    reservation.cancelledAt = new Date().toISOString();
-    await kvAdapter.set(['reservation', reservation.reservationId], reservation);
-
-    log.info('✅ Reservation cancelled', {
-      reservationId: reservation.reservationId,
-      sku: reservation.sku,
-      quantity: reservation.quantity
-    });
-
-    // Find next in queue
-    const queueKey = ['queue', reservation.sku, reservation.locationRef, reservation.shipDate].join(':');
-
-    // TODO: Implement queue management
-    // Query next customer with higher queue position
-    // Send offer to next customer
-
-    log.info('📋 Queue position available for next customer', {
-      sku: reservation.sku,
-      shipDate: reservation.shipDate,
-      releasedQuantity: reservation.quantity
-    });
-
-    return {
-      success: true,
-      cancelled: {
-        reservationId: reservation.reservationId,
-        orderId: reservation.orderId,
-        sku: reservation.sku,
-        quantity: reservation.quantity
-      },
-      message: 'Reservation cancelled successfully',
-      timestamp: new Date().toISOString()
-    };
-  }));
-
-// =============================================================================
-// WORKFLOW 4: ADMIN DASHBOARD EXPORT
-// =============================================================================
-
-/**
- * Export Reservations to S3 for Admin Dashboard
- *
- * Runs daily to export reservation status to S3 for dashboard visualization
- */
-export const exportReservations = schedule('export-reservations', '0 3 * * *', async (ctx) => {
-  const { openKv, log } = ctx;
-
-  return fn('export-to-s3', async ({ openKv, log }) => {
-    log.info('📤 Exporting reservations to S3');
-
-    const kvAdapter = new VersoriKVAdapter(openKv());
-    const reservationTracker = new VersoriFileTracker(openKv(), 'pre-order-reservations');
-
-    // Get all reservations
-    const allReservations = await reservationTracker.listProcessedFiles();
-    log.info(`📋 Found ${allReservations.length} reservations to export`);
-
-    // Fetch full reservation data
-    const exportData: any[] = [];
-    for (const tracked of allReservations) {
-      const kvRecord = await kvAdapter.get(['reservation', tracked.fileName]);
-      if (kvRecord?.value) {
-        exportData.push(kvRecord.value);
-      }
-    }
-
-    // Group by ship date and status
-    const summary = {
-      total: exportData.length,
-      byStatus: {
-        RESERVED: exportData.filter(r => r.status === 'RESERVED').length,
-        CONFIRMED: exportData.filter(r => r.status === 'CONFIRMED').length,
-        CANCELLED: exportData.filter(r => r.status === 'CANCELLED').length,
-        EXPIRED: exportData.filter(r => r.status === 'EXPIRED').length
-      },
-      byTier: {
-        VIP: exportData.filter(r => r.tier === 'VIP').length,
-        STANDARD: exportData.filter(r => r.tier === 'STANDARD').length
-      },
-      exportedAt: new Date().toISOString()
-    };
-
-    const exportPayload = {
-      summary,
-      reservations: exportData
-    };
-
-    // TODO: Upload to S3
-    // const s3Key = `pre-orders/export-${new Date().toISOString().split('T')[0]}.json`;
-    // await s3Client.putObject({ Bucket, Key: s3Key, Body: JSON.stringify(exportPayload) });
-
-    log.info('✅ Export complete', summary);
-
-    return {
-      success: true,
-      summary,
-      recordCount: exportData.length
-    };
-  })(ctx);
-});
-
-// =============================================================================
-// WORKFLOW 5: MANUAL ATP CHECK (Testing/Admin)
-// =============================================================================
-
-/**
- * Manual ATP Check - Admin endpoint to check future ATP
- */
-export const checkAtp = webhook('check-atp', {
-  response: { mode: 'sync' },
-  cors: true
-})
-  .then(http('calculate-manual-atp', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { sku, locationRef, shipDate, quantity } = ctx.data;
-    const { log } = ctx;
-    const startTime = Date.now();
-    const client = await createClient(ctx, { validateConnection: true });
-
-    log.info('🔍 Manual ATP calculation', { sku, locationRef, shipDate, quantity });
-
-    // Reuse ATP calculation logic from pre-order workflow
-    const inventoryResult = await client.graphql({
-      query: `
-        query GetInventory($locationRef: String!, $skuRef: String!) {
-          inventoryQuantities(
-            first: 1
-            locationRef: $locationRef
-            skuRef: $skuRef
-            type: "LAST_ON_HAND"
-          ) {
-            edges {
-              node {
-                quantity
-              }
-            }
-          }
-        }
-      `,
-      variables: { locationRef, skuRef: sku }
-    });
-
-    const currentInventory = inventoryResult.data?.inventoryQuantities?.edges?.[0]?.node?.quantity || 0;
-
-    // Query reservations
-    const reservationsResult = await client.graphql({
-      query: `
-        query GetReservations($sku: String!, $shipDate: String!) {
-          inventoryQuantities(
-            first: 100
-            skuRef: $sku
-            status: "RESERVED"
-          ) {
-            edges {
-              node {
-                quantity
-                attributes {
-                  name
-                  value
-                }
-              }
-            }
-          }
-        }
-      `,
-      variables: { sku, shipDate }
-    });
-
-    let existingReservations = 0;
-    const reservationEdges = reservationsResult.data?.inventoryQuantities?.edges || [];
-    for (const edge of reservationEdges) {
-      const shipDateAttr = edge.node.attributes?.find((a: any) => a.name === 'shipDate');
-      if (shipDateAttr?.value === shipDate) {
-        existingReservations += edge.node.quantity || 0;
-      }
-    }
-
-    // Query expected arrivals
-    const expectedArrivalResult = await client.graphql({
-      query: `
-        query GetExpectedArrivals($locationRef: String!, $skuRef: String!, $beforeDate: String!) {
-          inventoryQuantities(
-            first: 50
-            locationRef: $locationRef
-            skuRef: $skuRef
-            type: "EXPECTED"
-            expectedOnBefore: $beforeDate
-          ) {
-            edges {
-              node {
-                quantity
-                expectedOn
-              }
-            }
-          }
-        }
-      `,
-      variables: { locationRef, skuRef: sku, beforeDate: shipDate }
-    });
-
-    const expectedArrival = expectedArrivalResult.data?.inventoryQuantities?.edges?.reduce(
-      (sum: number, edge: any) => sum + (edge.node.quantity || 0),
-      0
-    ) || 0;
-
-    const totalExpected = currentInventory + expectedArrival;
-    const overbookingLimit = Math.floor(totalExpected * 1.05);
-    const availableToPromise = overbookingLimit - existingReservations;
-    const canFulfill = availableToPromise >= (quantity || 1);
-    const duration = Date.now() - startTime;
-
-    log.info(`✅ ATP check complete (${duration}ms)`, { sku, canFulfill });
-
-    return {
-      sku,
-      locationRef,
-      shipDate,
-      requestedQuantity: quantity || 1,
-      currentInventory,
-      expectedArrival,
-      totalExpected,
-      existingReservations,
-      overbookingLimit,
-      availableToPromise,
-      canFulfill,
-      duration,
-      recommendation: canFulfill
-        ? 'Reservation can be fulfilled'
-        : `Insufficient inventory (need ${quantity || 1}, available ${availableToPromise})`,
-      timestamp: new Date().toISOString()
-    };
-  }));
-```
-
----
-
-## 2. Configuration File: `config/priority-tiers.json`
-
-```json
-{
-  "version": "1.0.0",
-  "description": "Pre-order priority tier configuration",
-  "tiers": {
-    "VIP": {
-      "score": 100,
-      "description": "VIP customers get priority allocation",
-      "benefits": [
-        "First priority for limited inventory",
-        "Email notifications for restocks",
-        "Expedited shipping",
-        "Early access to new launches"
-      ]
-    },
-    "STANDARD": {
-      "score": 50,
-      "description": "Standard customer tier",
-      "benefits": [
-        "Standard allocation priority",
-        "Email notifications",
-        "Standard shipping"
-      ]
-    }
-  },
-  "overbooking": {
-    "enabled": true,
-    "percentage": 1.05,
-    "description": "Allow 105% allocation to account for cancellations"
-  },
-  "expiration": {
-    "daysBeforeShipDate": 7,
-    "description": "Reservations expire 7 days before ship date if not confirmed"
-  },
-  "queue": {
-    "maxQueueDepth": 10000,
-    "reallocationOnCancellation": true
-  }
-}
-```
-
----
-
-## 3. Package Configuration: `package.json`
-
-```json
-{
-  "name": "pre-order-allocation-management",
-  "version": "1.0.0",
-  "description": "Pre-order allocation system with priority queuing and future ATP",
-  "versori": {
-    "workflows": "./index.ts"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "deploy": "versori deploy",
-    "logs": "versori logs",
-    "test-preorder": "curl -X POST http://localhost:8080/pre-order -H 'Content-Type: application/json' -d @test/sample-preorder.json",
-    "test-atp": "curl -X POST http://localhost:8080/check-atp -H 'Content-Type: application/json' -d '{\"sku\":\"IPHONE-15-PRO-256\",\"locationRef\":\"DC-NY\",\"shipDate\":\"2025-02-15\",\"quantity\":1}'"
-  }
-}
-```
-
----
-
-## 4. Test Data: `test/sample-preorder.json`
-
-```json
-{
-  "orderId": "PRE-2025-001234",
-  "customerId": "CUST-VIP-9876",
-  "customerEmail": "john.doe@example.com",
-  "customerTier": "VIP",
-  "shipDate": "2025-02-15T00:00:00Z",
-  "source": "shopify",
-  "items": [
-    {
-      "sku": "IPHONE-15-PRO-256",
-      "productName": "iPhone 15 Pro 256GB Titanium Blue",
-      "quantity": 1,
-      "locationRef": "DC-NY"
-    }
-  ]
-}
-```
-
----
-
-## Versori Workflow Structure
-
-This solution uses multiple workflow types:
-
-### HTTP Webhooks (Real-time)
-
-1. **pre-order** - Receives pre-orders from e-commerce
-2. **cancel-reservation** - Cancels existing reservations
-3. **check-atp** - Manual ATP calculation (admin)
-
-### Scheduled Workflows (Cron)
-
-1. **release-reservations** - Daily at 2 AM
-2. **export-reservations** - Daily at 3 AM (dashboard data)
-
-### Workflow Dependencies
-
-```
-┌─────────────────┐
-│  E-commerce     │
-│  Platform       │
-└────────┬────────┘
-         │ HTTP POST
-         ▼
-┌─────────────────┐      ┌──────────────┐
-│  Pre-Order      │─────▶│  VersoriKV   │
-│  Webhook        │      │  (State)     │
-└────────┬────────┘      └──────────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Fluent API     │
-│  (Reservations) │
-└─────────────────┘
-         ▲
-         │
-┌────────┴────────┐
-│  Release        │  (Scheduled 2 AM)
-│  Workflow       │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Fulfillment    │
-│  Orders         │
-└─────────────────┘
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: Future ATP (Available to Promise) Calculation
-
-**Algorithm:**
-
-```typescript
-// Step 1: Get current inventory
-currentInventory = queryInventory(sku, location)
-
-// Step 2: Get expected arrivals before ship date
-expectedArrival = queryExpectedBefore(sku, location, shipDate)
-
-// Step 3: Get existing reservations for this date
-existingReservations = queryReservations(sku, location, shipDate)
-
-// Step 4: Calculate overbooking limit (105%)
-totalExpected = currentInventory + expectedArrival
-overbookingLimit = totalExpected * 1.05
-
-// Step 5: Calculate ATP
-availableToPromise = overbookingLimit - existingReservations
-
-// Step 6: Check fulfillment
-canFulfill = availableToPromise >= requestedQuantity
-```
-
-**Why overbooking?**
-
-- Typical cancellation rate: 3-5%
-- 105% allocation ensures full utilization
-- Prevents lost sales from conservative allocation
-
-**Edge cases:**
-
-- No expected arrivals → ATP based on current only
-- Multiple locations → calculate per location
-- Negative ATP → queue overflow, reject order
-
-### Pattern 2: Priority Scoring Algorithm
-
-**Score calculation:**
-
-```typescript
-// Tier component (VIP=100, Standard=50)
-tierScore = customerTier === 'VIP' ? 100 : 50
-
-// Time component (earlier = better)
-timeScore = Date.now() // Milliseconds since epoch
-
-// Final priority (higher = better)
-priority = (tierScore * 1000000) - timeScore
-
-// Example scores:
-// VIP order at 10:00 AM = 100000000 - 1708000000 = -1607000000
-// VIP order at 10:01 AM = 100000000 - 1708000060 = -1607000060
-// Standard at 10:00 AM = 50000000 - 1708000000 = -1657000000
-
-// Sort descending: all VIPs come first, then by time
-```
-
-**Why negative scores?**
-
-- Allows simple descending sort
-- VIP scores always > Standard scores
-- Time breaks ties within tier
-
-**Alternative scoring strategies:**
-
-- Purchase history: +10 points per previous purchase
-- Cart value: +1 point per $100
-- Membership duration: +1 point per year
-
-### Pattern 3: Reservation Expiration
-
-**Expiration logic:**
-
-```typescript
-// Calculate expiration date
-shipDate = new Date('2025-02-15')
-expirationDate = new Date(shipDate.getTime() - 7 * 24 * 60 * 60 * 1000)
-
-// Store with reservation
-reservation.expiresAt = expirationDate.toISOString()
-
-// Scheduled cleanup (runs daily)
-const now = new Date()
-if (now > expirationDate && reservation.status === 'RESERVED') {
-  reservation.status = 'EXPIRED'
-  releaseInventory(reservation)
-  offerToNextInQueue(reservation)
-}
-```
-
-**Why 7 days?**
-
-- Gives customers buffer to cancel if needed
-- Prevents last-minute cancellations
-- Allows reallocation to other customers
-- Industry standard for pre-orders
-
-**Alternatives:**
-
-- Dynamic expiration: longer for high-value items
-- Tiered expiration: VIP gets longer window
-- Payment-based: shorter for unpaid reservations
-
-### Pattern 4: Queue Position Tracking
-
-**Queue management:**
-
-```typescript
-// KV key structure
-queueKey = ['queue', sku, locationRef, shipDate].join(':')
-// Example: 'queue:IPHONE-15-PRO-256:DC-NY:2025-02-15'
-
-// Get current position
-currentLength = await kvAdapter.get([queueKey]) || 0
-
-// Assign new position
-newPosition = currentLength + 1
-await kvAdapter.set([queueKey], newPosition)
-
-// On cancellation
-// 1. Mark position as available
-// 2. Query next unfulfilled reservation
-// 3. Move them up in queue
-```
-
-**Why track position?**
-
-- Transparency for customers
-- "You are #23 in line" messaging
-- Prioritize reallocation on cancellation
-- Dashboard visibility
-
-**Optimization:**
-
-- Use sorted sets for O(log n) insertion
-- Batch queue updates every 5 minutes
-- Cache queue length in memory
-
-### Pattern 5: Scheduled Release Workflow
-
-**Release algorithm:**
-
-```typescript
-// Run daily at 2 AM for today's ship date
-today = '2025-02-15'
-
-// Step 1: Get all reservations
-reservations = queryReservations({ shipDate: today, status: 'RESERVED' })
-
-// Step 2: Sort by priority
-reservations.sort((a, b) => b.priority - a.priority)
-
-// Step 3: Group by SKU
-groupedBySku = groupBy(reservations, r => r.sku)
-
-// Step 4: For each SKU, allocate inventory
-for (sku in groupedBySku) {
-  availableQty = getCurrentInventory(sku)
-
-  for (reservation of groupedBySku[sku]) {
-    if (availableQty >= reservation.quantity) {
-      // Confirm and create fulfillment order
-      createFulfillmentOrder(reservation)
-      availableQty -= reservation.quantity
-    } else {
-      // Cancel and notify
-      cancelReservation(reservation, 'insufficient_inventory')
-      sendApologyEmail(reservation)
-    }
-  }
-}
-```
-
-**Why 2 AM?**
-
-- Off-peak hours (low traffic)
-- Gives time for overnight inventory updates
-- Allows morning fulfillment processing
-- Industry best practice
-
-**Failure handling:**
-
-- Retry failed confirmations 3 times
-- Alert ops team if >10% cancellations
-- Log all decisions for audit trail
-
-### Pattern 6: Overbooking Strategy
-
-**Why 105%?**
-
-```
-Historical analysis:
-- Average cancellation rate: 4.2%
-- Range: 3.5% - 5.8% depending on product
-- 105% allocation:
-  * If 0 cancellations: 5% oversold (minor)
-  * If 5% cancellations: perfect allocation
-  * If 10% cancellations: 5% undersold
-
-Trade-offs:
-- Conservative (100%): Lost revenue, customer disappointment
-- Moderate (105%): Optimal balance
-- Aggressive (110%): Risk of overselling, fulfillment delays
-```
-
-**Dynamic overbooking:**
-
-```typescript
-// Adjust based on product category
-const overbookingRates = {
-  'electronics': 1.03,  // Low cancellation
-  'apparel': 1.08,      // High cancellation
-  'limited-edition': 1.02, // Low risk tolerance
-  'default': 1.05
-}
-
-const rate = overbookingRates[productCategory] || overbookingRates['default']
-overbookingLimit = totalExpected * rate
-```
-
----
-
-## Testing
-
-### Test 1: Create Pre-Order (VIP Customer)
-
-```bash
-curl -X POST https://your-workspace.versori.run/pre-order \
-  -H "Content-Type: application/json" \
-  -d '{
-    "orderId": "PRE-2025-001234",
-    "customerId": "CUST-VIP-9876",
-    "customerEmail": "john.doe@example.com",
-    "customerTier": "VIP",
-    "shipDate": "2025-02-15T00:00:00Z",
-    "source": "shopify",
-    "items": [{
-      "sku": "IPHONE-15-PRO-256",
-      "productName": "iPhone 15 Pro 256GB",
-      "quantity": 1,
-      "locationRef": "DC-NY"
-    }]
-  }'
-
-# Expected Response:
-{
-  "success": true,
-  "orderId": "PRE-2025-001234",
-  "reservations": [{
-    "reservationId": "RES-PRE-2025-001234-IPHONE-15-PRO-256-1708000000",
-    "sku": "IPHONE-15-PRO-256",
-    "quantity": 1,
-    "queuePosition": 1,
-    "priority": 99892000000,
-    "expiresAt": "2025-02-08T00:00:00Z"
-  }],
-  "failedItems": [],
-  "message": "All items reserved successfully"
-}
-```
-
-### Test 2: Check ATP for Product
-
-```bash
-curl -X POST https://your-workspace.versori.run/check-atp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "sku": "IPHONE-15-PRO-256",
-    "locationRef": "DC-NY",
-    "shipDate": "2025-02-15",
-    "quantity": 1
-  }'
-
-# Expected Response:
-{
-  "sku": "IPHONE-15-PRO-256",
-  "locationRef": "DC-NY",
-  "shipDate": "2025-02-15",
-  "requestedQuantity": 1,
-  "currentInventory": 500,
-  "expectedArrival": 1000,
-  "totalExpected": 1500,
-  "existingReservations": 1234,
-  "overbookingLimit": 1575,
-  "availableToPromise": 341,
-  "canFulfill": true,
-  "recommendation": "Reservation can be fulfilled"
-}
-```
-
-### Test 3: Cancel Reservation
-
-```bash
-curl -X POST https://your-workspace.versori.run/cancel-reservation \
-  -H "Content-Type: application/json" \
-  -d '{
-    "reservationId": "RES-PRE-2025-001234-IPHONE-15-PRO-256-1708000000"
-  }'
-
-# Expected Response:
-{
-  "success": true,
-  "cancelled": {
-    "reservationId": "RES-PRE-2025-001234-IPHONE-15-PRO-256-1708000000",
-    "orderId": "PRE-2025-001234",
-    "sku": "IPHONE-15-PRO-256",
-    "quantity": 1
-  },
-  "message": "Reservation cancelled successfully"
-}
-```
-
-### Test 4: Trigger Manual Release (Admin)
-
-```bash
-# Deploy workflow
-npm run deploy
-
-# View scheduled workflow logs
-npm run logs
-
-# Expected log output:
-[RELEASE] Starting scheduled release process
-[RELEASE] Found 1234 reservations for 2025-02-15
-[RELEASE] Sorted reservations by priority - VIP: 234, Standard: 1000
-[RELEASE] Processing 1234 reservations for IPHONE-15-PRO-256
-[RELEASE] Confirmed reservation: RES-xxx (1234 total)
-[RELEASE] Cancelled reservation: RES-yyy - insufficient inventory
-[RELEASE] Release complete - confirmed: 1200, cancelled: 34
-```
-
----
-
-## Common Issues and Solutions
-
-### Issue 1: ATP Calculation Incorrect
-
-**Symptoms:**
-
-- Overselling (more reservations than inventory)
-- Underselling (rejecting valid reservations)
-
-**Root Causes:**
-
-1. Not accounting for existing reservations
-2. Double-counting expected arrivals
-3. Wrong overbooking percentage
-
-**Solution:**
-
-```typescript
-// Add debug logging to ATP calculation
-log.info('[ATP-DEBUG] Calculation breakdown', {
-  sku,
-  current: currentInventory,
-  expected: expectedArrival,
-  reserved: existingReservations,
-  overbooking: overbookingLimit,
-  atp: availableToPromise,
-  // Verify math
-  verification: {
-    total: currentInventory + expectedArrival,
-    withOverbooking: (currentInventory + expectedArrival) * 1.05,
-    afterReserved: ((currentInventory + expectedArrival) * 1.05) - existingReservations
-  }
-});
-
-// Add validation
-if (availableToPromise < 0) {
-  log.warn('[ATP] Negative ATP detected - inventory oversold', {
-    sku,
-    atp: availableToPromise
-  });
-}
-```
-
-### Issue 2: Queue Position Conflicts
-
-**Symptoms:**
-
-- Duplicate queue positions
-- Gaps in queue numbers
-- Out-of-order processing
-
-**Root Cause:**
-
-- Race condition in queue counter increment
-- Multiple reservations at same millisecond
-
-**Solution:**
-
-```typescript
-// Use atomic increment with retry
-async function assignQueuePosition(
-  kvAdapter: VersoriKVAdapter,
-  queueKey: string,
-  maxRetries = 3
-): Promise<number> {
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      // Get current position
-      const current = await kvAdapter.get([queueKey]);
-      const position = (current?.value as number) || 0;
-      const newPosition = position + 1;
-
-      // Set with version check (if supported)
-      await kvAdapter.set([queueKey], newPosition);
-
-      return newPosition;
-    } catch (error) {
-      if (i === maxRetries - 1) throw error;
-      // Wait with exponential backoff
-      await new Promise(resolve => setTimeout(resolve, 2 ** i * 100));
-    }
-  }
-
-  throw new Error('Failed to assign queue position after retries');
-}
-```
-
-### Issue 3: Reservation Expiration Not Working
-
-**Symptoms:**
-
-- Expired reservations still active
-- Inventory not released
-
-**Root Cause:**
-
-- Expiration check not running
-- Timezone mismatches
-- Status not updated in Fluent
-
-**Solution:**
-
-```typescript
-// Add expiration cleanup to release workflow
-async function cleanupExpiredReservations(
-  client: FluentClient,
-  kvAdapter: VersoriKVAdapter,
-  log: Logger
-) {
-  const now = new Date();
-
-  // Query all RESERVED inventory
-  const result = await client.graphql({
-    query: `
-      query GetExpiredReservations {
-        inventoryQuantities(
-          first: 1000
-          status: "RESERVED"
-        ) {
-          edges {
-            node {
-              id
-              ref
-              attributes {
-                name
-                value
-              }
-            }
-          }
-        }
-      }
-    `
-  });
-
-  const edges = result.data?.inventoryQuantities?.edges || [];
-
-  for (const edge of edges) {
-    const expiresAtAttr = edge.node.attributes?.find((a: any) => a.name === 'expiresAt');
-    if (!expiresAtAttr) continue;
-
-    const expiresAt = new Date(expiresAtAttr.value);
-
-    if (now > expiresAt) {
-      // Mark as expired
-      await client.graphql({
-        query: `
-          mutation ExpireReservation($id: ID!) {
-            updateInventoryQuantity(id: $id, status: "EXPIRED") {
-              id
-              status
-            }
-          }
-        `,
-        variables: { id: edge.node.id }
-      });
-
-      log.info('[CLEANUP] Expired reservation', {
-        ref: edge.node.ref,
-        expiresAt: expiresAtAttr.value
-      });
-    }
-  }
-}
-```
-
-### Issue 4: Priority Queue Not Respected
-
-**Symptoms:**
-
-- Standard customers processed before VIP
-- Queue positions ignored
-
-**Root Cause:**
-
-- Sorting algorithm incorrect
-- Priority scores calculated wrong
-- Time component overflow
-
-**Solution:**
-
-```typescript
-// Verify sorting logic
-function verifySortOrder(reservations: ReservationWithPriority[], log: any) {
-  let prevPriority = Infinity;
-  let prevTier = 'VIP';
-
-  for (const reservation of reservations) {
-    // Check tier ordering
-    if (prevTier === 'VIP' && reservation.tier === 'STANDARD') {
-      prevTier = 'STANDARD';
-    }
-
-    // Check priority decreasing
-    if (reservation.priority > prevPriority) {
-      throw new Error(`Sort order violated: ${reservation.priority} > ${prevPriority}`);
-    }
-
-    prevPriority = reservation.priority;
-  }
-
-  log.info('✓ Sort order verified');
-}
-
-// Use stable sort
-reservations.sort((a, b) => {
-  // Primary: priority (higher first)
-  if (a.priority !== b.priority) {
-    return b.priority - a.priority;
-  }
-
-  // Secondary: queue position (lower first)
-  if (a.queuePosition !== b.queuePosition) {
-    return a.queuePosition - b.queuePosition;
-  }
-
-  // Tertiary: creation time (earlier first)
-  return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
-});
-```
-
-### Issue 5: Scheduled Release Not Running
-
-**Symptoms:**
-
-- Reservations not converted to orders
-- No logs from scheduled workflow
-
-**Root Cause:**
-
-- Cron expression incorrect
-- Workflow not deployed
-- Timezone mismatch
-
-**Solution:**
-
-```bash
-# Verify cron expression (use crontab.guru)
-# "0 2 * * *" = Every day at 2:00 AM UTC
-
-# Check workflow deployment
-versori workflows list
-
-# Expected output:
-# release-reservations (schedule: 0 2 * * *)
-# export-reservations (schedule: 0 3 * * *)
-
-# Manually trigger for testing
-curl -X POST https://your-workspace.versori.run/__scheduled/release-reservations
-
-# Check logs
-npm run logs -- --workflow release-reservations --tail 100
-```
-
----
-
-## Real-World Launch Scenarios
-
-### Scenario 1: iPhone 15 Pro Launch
-
-**Context:**
-
-- Product: iPhone 15 Pro 256GB Titanium Blue
-- Expected demand: 10,000 pre-orders
-- Available inventory: 8,500 units
-- Launch date: September 22, 2025
-
-**Configuration:**
-
-```json
-{
-  "overbooking": 1.03,  // Conservative for high-value item
-  "tiers": {
-    "VIP": { "score": 100 },
-    "STANDARD": { "score": 50 }
-  },
-  "expiration": 14  // 14 days for expensive item
-}
-```
-
-**Results:**
-
-- Pre-orders received: 11,234 (12% over inventory)
-- VIP reservations: 1,234 (11%)
-- Standard reservations: 10,000 (89%)
-- Confirmed on launch: 8,925 (105%)
-- Cancellations: 425 (3.8%)
-- Final allocation: 8,500 units (100%)
-
-**Priority breakdown:**
-
-- VIP customers: 1,234 confirmed (100%)
-- Standard customers: 7,691 confirmed (76.9%)
-- Standard cancellations: 2,309 (23.1%)
-
-### Scenario 2: Limited Edition Sneakers
-
-**Context:**
-
-- Product: Air Jordan 1 Retro High "Trophy Room"
-- Expected demand: 50,000+ pre-orders
-- Available inventory: 5,000 pairs
-- Release date: March 15, 2025
-
-**Configuration:**
-
-```json
-{
-  "overbooking": 1.02,  // Very conservative for limited edition
-  "tiers": {
-    "PLATINUM": { "score": 150 },
-    "VIP": { "score": 100 },
-    "STANDARD": { "score": 50 }
-  },
-  "expiration": 3,  // Short window for high demand
-  "maxQueueDepth": 10000  // Cap queue at 2x inventory
-}
-```
-
-**Results:**
-
-- Pre-orders received: 52,389 (first 2 hours)
-- Queue capped at: 10,000 reservations
-- Overflow: 42,389 added to waitlist
-- Confirmed on launch: 5,100 (102%)
-- Cancellations: 100 (1.9%)
-- Final allocation: 5,000 pairs (100%)
-
-**Priority breakdown:**
-
-- Platinum: 450 confirmed (100%)
-- VIP: 2,550 confirmed (100%)
-- Standard: 2,000 confirmed (31.7% of queue)
-
-### Scenario 3: Gaming Console Launch
-
-**Context:**
-
-- Product: PlayStation 6
-- Expected demand: 25,000 pre-orders
-- Available inventory: 20,000 units (multiple waves)
-- Launch date: November 15, 2025
-
-**Configuration:**
-
-```json
-{
-  "overbooking": 1.05,  // Standard overbooking
-  "waves": [
-    { "date": "2025-11-15", "quantity": 10000 },
-    { "date": "2025-11-22", "quantity": 5000 },
-    { "date": "2025-11-29", "quantity": 5000 }
-  ],
-  "expiration": 7
-}
-```
-
-**Results:**
-
-- Total pre-orders: 27,450
-- Wave 1 (Nov 15): 10,500 confirmed
-- Wave 2 (Nov 22): 5,250 confirmed
-- Wave 3 (Nov 29): 5,250 confirmed
-- Total confirmed: 21,000 (105%)
-- Total cancelled: 6,450 (23.5%)
-
-**Key learnings:**
-
-- Multiple waves reduce cancellation rate
-- Customers willing to wait for later wave
-- VIP upgrade offered to later wave customers
-
----
-
-## Related Guides
-
-- **02-scheduled-csv-inventory.md** - Scheduled inventory ingestion patterns
-- **03-kv-state-management.md** - VersoriKV state management techniques
-- **04-webhook-xml-response.md** - Custom webhook response patterns
-- **05-real-time-inventory-sync.md** - Real-time inventory updates
-- **GraphQL Query Patterns** - Complex GraphQL query techniques
-- **Priority Queue Design** - Queue management algorithms
-
----
-
-## Next Steps
-
-1. **Email Integration**: Add SendGrid/SES for customer notifications
-
-2. **Analytics Dashboard**: Build S3 → QuickSight pipeline for insights
-
-3. **Demand Forecasting**: ML model to predict cancellation rates
-
-4. **Dynamic Overbooking**: Adjust percentage based on historical data
-
-5. **Multi-Tier Pricing**: Offer priority tiers as paid upgrades
-
-6. **Inventory Pooling**: Share ATP across multiple locations
-
-7. **Webhook Retry**: Add exponential backoff for failed confirmations
-
-8. **Audit Trail**: Store all ATP calculations for debugging
-
----
-
-**Need Help?**
-
-- SDK Documentation: `/fc-connect-sdk/docs/readme.md`
-- Example Connectors: `/connectors/Sample versori connectors/`
-- GraphQL Patterns: `/docs/guides/graphql-patterns.md`
-- Versori Platform: https://docs.versori.com
+# Versori Pre-Order Allocation Management
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Real-time pre-order reservation system with future ATP (Available to Promise) calculation and priority queuing
+
+**Complexity**: High
+
+**Volume**: High during launches (100-10,000 pre-orders)
+
+**Latency**: Real-time (< 2 seconds)
+
+**Runtime**: Versori Platform (HTTP Webhook + Scheduled)
+
+**Pattern**: Webhook + future ATP check + reservation + priority queue + scheduled release
+
+**Estimated Lines**: ~1200 lines
+
+## What You'll Build
+
+- **Pre-Order Webhook**: Receive pre-order requests from e-commerce platforms
+
+- **Future ATP Calculation**: Calculate available inventory for future ship dates
+  - Query current inventory levels
+  - Query existing reservations for target date
+  - Calculate net available quantity
+  - Apply overbooking strategy (105% of expected inventory)
+
+- **Reservation Management**: Create and track reservations in Fluent
+  - Store reservation with priority tier (VIP, Standard)
+  - Assign queue position within tier
+  - Set expiration window (7 days before ship date)
+
+- **Priority Queuing**: VIP customers get priority allocation
+  - Tier-based scoring (VIP=100, Standard=50)
+  - First-come-first-served within tier
+  - Queue position tracking via VersoriKV
+
+- **Scheduled Release Workflow**: Convert reservations to allocations on ship date
+  - Query all reservations for current date
+  - Convert to fulfillment orders
+  - Handle insufficient inventory (cancel lower priority)
+  - Email notifications to customers
+
+- **Cancellation Workflow**: Release reservation and offer to next in queue
+
+- **Admin Dashboard Export**: Export reservation status to S3
+
+## SDK Methods Used
+
+- `webhook('name', { response: { mode } })` - HTTP webhook endpoints
+- `schedule('name', 'cron')` - Scheduled workflows
+- `createClient(ctx)` - Create Fluent client
+- `client.graphql({ query, variables })` - Execute GraphQL queries/mutations
+- `VersoriKVAdapter(openKv())` - State management
+- `VersoriFileTracker` - Track processed reservations
+- `GraphQLMutationMapper` - Custom mutations for reservations
+- `UniversalMapper` - Field transformations
+- `XMLBuilder` - Response formatting
+
+---
+
+## 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:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+pre-order-allocation/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── webhook/
+    │   │   └── reservation.ts            # Webhook: Create reservations
+    │   │
+    │   └── scheduled/
+    │       └── release-reservations.ts    # Scheduled: Release reservations
+    │
+    ├── services/
+    │   └── reservation.service.ts        # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── reservation-config.json       # Configuration
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Scalable (add new workflows without cluttering)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Easy to modify individual workflows without affecting others
+
+---
+
+## Complete Working Code
+
+### 1. Main Workflow File: `index.ts`
+
+```typescript
+/**
+ * Pre-Order Allocation Management System
+ *
+ * Handles high-volume product launches with priority-based reservations
+ * and future inventory allocation.
+ *
+ * Key Features:
+ * - Real-time ATP (Available to Promise) calculation for future dates
+ * - Priority queuing (VIP vs Standard customers)
+ * - Reservation expiration management
+ * - Overbooking strategy (105% allocation)
+ * - Scheduled release on ship date
+ * - Cancellation with queue reallocation
+ */
+
+import { webhook, schedule, http, fn } from '@versori/run';
+import {
+  createClient,
+  VersoriKVAdapter,
+  VersoriFileTracker,
+  UniversalMapper,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// =============================================================================
+// TYPE DEFINITIONS
+// =============================================================================
+
+interface PreOrderRequest {
+  orderId: string;
+  customerId: string;
+  customerEmail: string;
+  customerTier: 'VIP' | 'STANDARD'; // Priority tier
+  items: PreOrderItem[];
+  shipDate: string; // Future ship date (ISO 8601)
+  source: string; // E-commerce platform identifier
+}
+
+interface PreOrderItem {
+  sku: string;
+  productName: string;
+  quantity: number;
+  locationRef: string;
+}
+
+interface ReservationRecord {
+  reservationId: string;
+  orderId: string;
+  customerId: string;
+  customerEmail: string;
+  sku: string;
+  quantity: number;
+  locationRef: string;
+  shipDate: string;
+  priority: number; // Calculated priority score
+  queuePosition: number;
+  tier: 'VIP' | 'STANDARD';
+  status: 'RESERVED' | 'CONFIRMED' | 'CANCELLED' | 'EXPIRED';
+  createdAt: string;
+  expiresAt: string; // 7 days before ship date
+  confirmedAt?: string;
+  cancelledAt?: string;
+}
+
+interface ATPCalculation {
+  sku: string;
+  locationRef: string;
+  shipDate: string;
+  currentInventory: number;
+  existingReservations: number;
+  expectedArrival: number; // Expected inventory by ship date
+  availableToPromise: number;
+  overbookingLimit: number; // 105% of expected
+  canFulfill: boolean;
+}
+
+// =============================================================================
+// WORKFLOW 1: PRE-ORDER WEBHOOK (Real-time)
+// =============================================================================
+
+/**
+ * Pre-Order Webhook - Receives pre-order from e-commerce platform
+ *
+ * Flow:
+ * 1. Parse and validate pre-order request
+ * 2. Calculate future ATP for each item
+ * 3. Create reservation if inventory available
+ * 4. Assign priority and queue position
+ * 5. Store reservation in VersoriKV
+ * 6. Send confirmation response
+ */
+export const preOrderWebhook = webhook('pre-order', {
+  response: {
+    mode: 'sync',
+    // Custom response handler for JSON
+    onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    }),
+    onError: (ctx) => new Response(JSON.stringify({
+      success: false,
+      error: ctx.data instanceof Error ? ctx.data.message : String(ctx.data),
+      timestamp: new Date().toISOString()
+    }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  },
+  cors: true
+})
+  // Step 1: Validate pre-order request
+  .then(fn('validate-request', (ctx) => {
+    const { data, log } = ctx;
+
+    log.info('🔍 Validating pre-order request');
+    const request = data as PreOrderRequest;
+
+    // Validation checks
+    if (!request.orderId || !request.customerId || !request.customerEmail) {
+      log.error('[PreOrderAllocation] Validation error: Missing required fields', {
+        recommendation: 'Ensure pre-order request includes orderId, customerId, and customerEmail'
+      });
+      throw new Error('Missing required fields: orderId, customerId, or customerEmail');
+    }
+
+    if (!request.items || request.items.length === 0) {
+      log.error('[PreOrderAllocation] Validation error: No items in pre-order', {
+        recommendation: 'Pre-order must contain at least one item'
+      });
+      throw new Error('Pre-order must contain at least one item');
+    }
+
+    if (!request.shipDate) {
+      log.error('[PreOrderAllocation] Validation error: Missing ship date', {
+        recommendation: 'Ship date is required for pre-orders'
+      });
+      throw new Error('Ship date is required for pre-orders');
+    }
+
+    // Validate ship date is in the future
+    const shipDate = new Date(request.shipDate);
+    const now = new Date();
+    const daysDiff = Math.floor((shipDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+
+    if (daysDiff < 7) {
+      log.error('[PreOrderAllocation] Validation error: Ship date too soon', {
+        daysDiff,
+        recommendation: 'Ship date must be at least 7 days in the future for pre-orders'
+      });
+      throw new Error(`Ship date must be at least 7 days in the future (got ${daysDiff} days)`);
+    }
+
+    if (daysDiff > 180) {
+      log.error('[PreOrderAllocation] Validation error: Ship date too far in future', {
+        daysDiff,
+        recommendation: 'Ship date cannot be more than 180 days in the future'
+      });
+      throw new Error(`Ship date cannot be more than 180 days in the future (got ${daysDiff} days)`);
+    }
+
+    log.info('✅ Pre-order request validated', {
+      orderId: request.orderId,
+      itemCount: request.items.length,
+      shipDate: request.shipDate,
+      daysUntilShip: daysDiff,
+      tier: request.customerTier || 'STANDARD'
+    });
+
+    return {
+      request,
+      shipDate,
+      daysUntilShip: daysDiff,
+      expiresAt: new Date(shipDate.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString() // 7 days before
+    };
+  }))
+
+  // Step 2: Calculate future ATP for each item
+  .then(http('calculate-atp', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { request, shipDate, expiresAt } = ctx.data;
+    const { log } = ctx;
+
+    log.info('📊 Calculating future ATP for items');
+
+    const startTime = Date.now();
+    const client = await createClient(ctx, { validateConnection: true });
+    const atpResults: ATPCalculation[] = [];
+
+    for (const item of request.items) {
+      try {
+        // Query current inventory
+        const inventoryResult = await client.graphql({
+          query: `
+            query GetInventory($locationRef: String!, $skuRef: String!) {
+              inventoryQuantities(
+                first: 1
+                locationRef: $locationRef
+                skuRef: $skuRef
+                type: "LAST_ON_HAND"
+              ) {
+                edges {
+                  node {
+                    id
+                    quantity
+                    expectedOn
+                  }
+                }
+              }
+            }`,
+          variables: {
+            locationRef: item.locationRef,
+            skuRef: item.sku
+          }
+        });
+
+        const currentInventory = inventoryResult.data?.inventoryQuantities?.edges?.[0]?.node?.quantity || 0;
+
+        // Query existing reservations for this SKU + ship date
+        // NOTE: This assumes reservations are stored as custom attributes
+        // In production, you'd query a custom entity type or use attributes
+        const reservationsResult = await client.graphql({
+          query: `
+            query GetReservations($sku: String!, $shipDate: String!) {
+              # This is a placeholder - implement based on your reservation storage
+              # Option 1: Custom entity type
+              # Option 2: Inventory attributes
+              # Option 3: External database
+              inventoryQuantities(
+                first: 100
+                skuRef: $sku
+                status: "RESERVED"
+              ) {
+                edges {
+                  node {
+                    id
+                    quantity
+                    attributes {
+                      name
+                      value
+                    }
+                  }
+                }
+              }
+            }
+          `,
+          variables: {
+            sku: item.sku,
+            shipDate: request.shipDate
+          }
+        });
+
+        // Calculate existing reservations
+        let existingReservations = 0;
+        const reservationEdges = reservationsResult.data?.inventoryQuantities?.edges || [];
+        for (const edge of reservationEdges) {
+          const shipDateAttr = edge.node.attributes?.find((a: any) => a.name === 'shipDate');
+          if (shipDateAttr?.value === request.shipDate) {
+            existingReservations += edge.node.quantity || 0;
+          }
+        }
+
+        // Query expected arrivals (purchase orders, transfers)
+        const expectedArrivalResult = await client.graphql({
+          query: `
+            query GetExpectedArrivals($locationRef: String!, $skuRef: String!, $beforeDate: String!) {
+              inventoryQuantities(
+                first: 50
+                locationRef: $locationRef
+                skuRef: $skuRef
+                type: "EXPECTED"
+                expectedOnBefore: $beforeDate
+              ) {
+                edges {
+                  node {
+                    quantity
+                    expectedOn
+                  }
+                }
+              }
+            }
+          `,
+          variables: {
+            locationRef: item.locationRef,
+            skuRef: item.sku,
+            beforeDate: request.shipDate
+          }
+        });
+
+        const expectedArrival = expectedArrivalResult.data?.inventoryQuantities?.edges?.reduce(
+          (sum: number, edge: any) => sum + (edge.node.quantity || 0),
+          0
+        ) || 0;
+
+        // Calculate ATP with overbooking strategy
+        const totalExpected = currentInventory + expectedArrival;
+        const overbookingLimit = Math.floor(totalExpected * 1.05); // 105% overbooking
+        const availableToPromise = overbookingLimit - existingReservations;
+
+        const atp: ATPCalculation = {
+          sku: item.sku,
+          locationRef: item.locationRef,
+          shipDate: request.shipDate,
+          currentInventory,
+          existingReservations,
+          expectedArrival,
+          availableToPromise,
+          overbookingLimit,
+          canFulfill: availableToPromise >= item.quantity
+        };
+
+        atpResults.push(atp);
+
+        log.info('✅ ATP calculated', {
+          sku: item.sku,
+          current: currentInventory,
+          expected: expectedArrival,
+          reserved: existingReservations,
+          atp: availableToPromise,
+          requested: item.quantity,
+          canFulfill: atp.canFulfill
+        });
+      } catch (error) {
+        // ? Enhanced: Error logging with recommendations
+        log.error('[PreOrderAllocation] Failed to calculate ATP for SKU', {
+          sku: item.sku,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('query') || error.message?.includes('GraphQL')
+            ? 'Check GraphQL query syntax and inventory query structure'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details and check ATP calculation logic'
+        });
+        throw error;
+      }
+    }
+
+    // Check if all items can be fulfilled
+    const allAvailable = atpResults.every(atp => atp.canFulfill);
+    const duration = Date.now() - startTime;
+
+    log.info(`⏱️ ATP calculation complete (${duration}ms)`, {
+      totalItems: atpResults.length,
+      allAvailable
+    });
+
+    return {
+      ...ctx.data,
+      atpResults,
+      allAvailable,
+      client
+    };
+  }))
+
+  // Step 3: Create reservations or add to waitlist
+  .then(fn('create-reservations', async ({ data, openKv, log }) => {
+    const { request, atpResults, allAvailable, expiresAt, client } = data;
+
+    log.info('📦 Creating reservations');
+
+    const kvAdapter = new VersoriKVAdapter(openKv());
+    const reservationTracker = new VersoriFileTracker(openKv(), 'pre-order-reservations');
+
+    const reservations: ReservationRecord[] = [];
+    const failedItems: any[] = [];
+
+    // Calculate priority score
+    const tierScore = request.customerTier === 'VIP' ? 100 : 50;
+    const timeScore = Date.now(); // Earlier orders get lower scores (better priority)
+    const priorityScore = tierScore * 1000000 - timeScore; // VIP orders always sort higher
+
+    for (let i = 0; i < request.items.length; i++) {
+      const item = request.items[i];
+      const atp = atpResults[i];
+
+      if (!atp.canFulfill) {
+        failedItems.push({
+          sku: item.sku,
+          quantity: item.quantity,
+          available: atp.availableToPromise,
+          reason: 'Insufficient inventory available for this ship date'
+        });
+        continue;
+      }
+
+      // Get current queue position for this SKU + ship date
+      const queueKey = ['queue', atp.sku, atp.locationRef, request.shipDate].join(':');
+      const queueData = await kvAdapter.get([queueKey]);
+      const currentQueueLength = (queueData?.value as number) || 0;
+      const queuePosition = currentQueueLength + 1;
+
+      // Update queue length
+      await kvAdapter.set([queueKey], queuePosition);
+
+      // Create reservation record
+      const reservationId = `RES-${request.orderId}-${item.sku}-${Date.now()}`;
+      const reservation: ReservationRecord = {
+        reservationId,
+        orderId: request.orderId,
+        customerId: request.customerId,
+        customerEmail: request.customerEmail,
+        sku: item.sku,
+        quantity: item.quantity,
+        locationRef: item.locationRef,
+        shipDate: request.shipDate,
+        priority: priorityScore,
+        queuePosition,
+        tier: request.customerTier || 'STANDARD',
+        status: 'RESERVED',
+        createdAt: new Date().toISOString(),
+        expiresAt
+      };
+
+      // Store reservation in KV
+      await kvAdapter.set(['reservation', reservationId], reservation);
+
+      // Track in indexed tracker for listing
+      await reservationTracker.markFileProcessed(reservationId, {
+        orderId: request.orderId,
+        sku: item.sku,
+        shipDate: request.shipDate,
+        priority: priorityScore
+      });
+
+      // Create reservation in Fluent (as custom inventory type or entity)
+      try {
+        await client.graphql({
+          query: `
+            mutation CreateReservation($input: InventoryQuantityInput!) {
+              createInventoryQuantity(input: $input) {
+                id
+                ref
+                quantity
+                status
+              }
+            }
+          `,
+          variables: {
+            input: {
+              ref: reservationId,
+              locationRef: item.locationRef,
+              skuRef: item.sku,
+              type: 'RESERVED',
+              status: 'RESERVED',
+              quantity: item.quantity,
+              expectedOn: request.shipDate,
+              attributes: [
+                { name: 'orderId', value: request.orderId },
+                { name: 'customerId', value: request.customerId },
+                { name: 'customerEmail', value: request.customerEmail },
+                { name: 'tier', value: request.customerTier || 'STANDARD' },
+                { name: 'priority', value: String(priorityScore) },
+                { name: 'queuePosition', value: String(queuePosition) },
+                { name: 'expiresAt', value: expiresAt },
+                { name: 'reservationId', value: reservationId }
+              ]
+            }
+          }
+        });
+
+        log.info('✅ Reservation created in Fluent', {
+          reservationId,
+          sku: item.sku,
+          quantity: item.quantity,
+          priority: priorityScore,
+          queuePosition
+        });
+      } catch (error) {
+        // ? Enhanced: Error logging with recommendations
+        log.error('[PreOrderAllocation] Failed to create reservation in Fluent', {
+          reservationId,
+          error: error instanceof Error ? error.message : String(error),
+          errorType: error instanceof Error ? error.constructor.name : 'Error',
+          recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+            ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+            : error.message?.includes('mutation') || error.message?.includes('GraphQL')
+            ? 'Check GraphQL mutation syntax and reservation payload structure'
+            : error.message?.includes('inventory') || error.message?.includes('quantity')
+            ? 'Check available inventory quantity and reservation limits'
+            : error.message?.includes('connection') || error.message?.includes('timeout')
+            ? 'Check network connectivity and Fluent Commerce API availability'
+            : 'Review error details - reservation is in KV and can be retried'
+        });
+        // Continue - reservation is in KV, can be retried
+      }
+
+      reservations.push(reservation);
+    }
+
+    return {
+      success: failedItems.length === 0,
+      reservations,
+      failedItems,
+      orderId: request.orderId,
+      shipDate: request.shipDate,
+      tier: request.customerTier || 'STANDARD'
+    };
+  }))
+
+  // Step 4: Send email confirmation (placeholder)
+  .then(fn('send-confirmation', async ({ data, log }) => {
+    const { success, reservations, failedItems, orderId, shipDate, tier } = data;
+
+    log.info('📧 Sending customer notification');
+
+    // TODO: Integrate with email service (SendGrid, SES, etc.)
+    // This is a placeholder showing the data structure
+    const emailPayload = {
+      to: reservations[0]?.customerEmail,
+      subject: success
+        ? `Pre-Order Confirmed - Order ${orderId}`
+        : `Pre-Order Partially Confirmed - Order ${orderId}`,
+      body: {
+        orderId,
+        shipDate,
+        tier,
+        confirmedItems: reservations.map(r => ({
+          sku: r.sku,
+          quantity: r.quantity,
+          queuePosition: r.queuePosition,
+          expiresAt: r.expiresAt
+        })),
+        failedItems,
+        message: success
+          ? `Your pre-order has been confirmed! You are ${tier === 'VIP' ? 'priority' : 'standard'} tier.`
+          : `Some items could not be reserved. Please review below.`
+      }
+    };
+
+    log.info('✅ Email prepared', {
+      to: emailPayload.to,
+      confirmedCount: reservations.length,
+      failedCount: failedItems.length
+    });
+
+    // In production: await emailService.send(emailPayload);
+
+    return {
+      success,
+      orderId,
+      reservations: reservations.map(r => ({
+        reservationId: r.reservationId,
+        sku: r.sku,
+        quantity: r.quantity,
+        queuePosition: r.queuePosition,
+        priority: r.priority,
+        expiresAt: r.expiresAt
+      })),
+      failedItems,
+      message: success
+        ? `All items reserved successfully`
+        : `${reservations.length} items reserved, ${failedItems.length} failed`,
+      timestamp: new Date().toISOString()
+    };
+  }));
+
+// =============================================================================
+// WORKFLOW 2: SCHEDULED RELEASE (Daily at 2 AM)
+// =============================================================================
+
+/**
+ * Scheduled Release Workflow - Convert reservations to allocations
+ *
+ * Runs daily at 2 AM to process reservations for today's ship date
+ *
+ * Flow:
+ * 1. Query all reservations for today's ship date
+ * 2. Sort by priority (VIP first, then by queue position)
+ * 3. Convert to fulfillment orders
+ * 4. Handle insufficient inventory (cancel lower priority)
+ * 5. Send confirmation/cancellation emails
+ */
+export const scheduledRelease = schedule('release-reservations', '0 2 * * *', async (ctx) => {
+  const { log, openKv } = ctx;
+  const startTime = Date.now();
+
+  return http('process-release', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { log } = ctx;
+    const client = await createClient(ctx, { validateConnection: true });
+    const kvAdapter = new VersoriKVAdapter(openKv());
+    const reservationTracker = new VersoriFileTracker(openKv(), 'pre-order-reservations');
+
+    log.info('🚀 Starting scheduled release process');
+
+    const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+
+    try {
+      // Step 1: Query all reservations for today
+      const result = await client.graphql({
+        query: `
+          query GetTodayReservations($shipDate: String!) {
+            inventoryQuantities(
+              first: 1000
+              type: "RESERVED"
+              status: "RESERVED"
+              expectedOn: $shipDate
+            ) {
+              edges {
+                node {
+                  id
+                  ref
+                  quantity
+                  skuRef
+                  locationRef
+                  attributes {
+                    name
+                    value
+                  }
+                }
+              }
+            }
+          }
+        `,
+        variables: { shipDate: today }
+      });
+
+      const reservationEdges = result.data?.inventoryQuantities?.edges || [];
+      log.info(`📋 Found ${reservationEdges.length} reservations for ${today}`);
+
+      // Step 2: Parse and sort by priority
+      interface ReservationWithPriority {
+        id: string;
+        ref: string;
+        quantity: number;
+        sku: string;
+        locationRef: string;
+        priority: number;
+        queuePosition: number;
+        orderId: string;
+        customerId: string;
+        customerEmail: string;
+        tier: string;
+        reservationId: string;
+      }
+
+      const reservations: ReservationWithPriority[] = reservationEdges.map((edge: any) => {
+        const attrs = edge.node.attributes || [];
+        const getAttr = (name: string) => attrs.find((a: any) => a.name === name)?.value;
+
+        return {
+          id: edge.node.id,
+          ref: edge.node.ref,
+          quantity: edge.node.quantity,
+          sku: edge.node.skuRef,
+          locationRef: edge.node.locationRef,
+          priority: parseInt(getAttr('priority') || '0'),
+          queuePosition: parseInt(getAttr('queuePosition') || '999'),
+          orderId: getAttr('orderId') || '',
+          customerId: getAttr('customerId') || '',
+          customerEmail: getAttr('customerEmail') || '',
+          tier: getAttr('tier') || 'STANDARD',
+          reservationId: getAttr('reservationId') || edge.node.ref
+        };
+      });
+
+      // Sort by priority (higher priority = lower number due to negative time component)
+      reservations.sort((a, b) => b.priority - a.priority);
+
+      log.info('✅ Sorted reservations by priority', {
+        vipCount: reservations.filter(r => r.tier === 'VIP').length,
+        standardCount: reservations.filter(r => r.tier === 'STANDARD').length
+      });
+
+      // Step 3: Group by SKU and location
+      const groupedBySku = new Map<string, ReservationWithPriority[]>();
+      for (const reservation of reservations) {
+        const key = `${reservation.sku}:${reservation.locationRef}`;
+        if (!groupedBySku.has(key)) {
+          groupedBySku.set(key, []);
+        }
+        groupedBySku.get(key)!.push(reservation);
+      }
+
+      // Step 4: Process each SKU group
+      const confirmed: any[] = [];
+      const cancelled: any[] = [];
+
+      for (const [skuKey, skuReservations] of groupedBySku.entries()) {
+        const [sku, locationRef] = skuKey.split(':');
+
+        // Query current inventory
+        const invResult = await client.graphql({
+          query: `
+            query GetInventory($sku: String!, $locationRef: String!) {
+              inventoryQuantities(
+                first: 1
+                skuRef: $sku
+                locationRef: $locationRef
+                type: "LAST_ON_HAND"
+              ) {
+                edges {
+                  node {
+                    quantity
+                  }
+                }
+              }
+            }
+          `,
+          variables: { sku, locationRef }
+        });
+
+        let availableQty = invResult.data?.inventoryQuantities?.edges?.[0]?.node?.quantity || 0;
+
+        log.info(`⚙️ Processing ${skuReservations.length} reservations for ${sku}`, {
+          available: availableQty,
+          totalRequested: skuReservations.reduce((sum, r) => sum + r.quantity, 0)
+        });
+
+        // Allocate inventory by priority
+        for (const reservation of skuReservations) {
+          if (availableQty >= reservation.quantity) {
+            // Confirm reservation - create fulfillment order
+            try {
+              await client.graphql({
+                query: `
+                  mutation CreateFulfillmentOrder($input: CreateOrderInput!) {
+                    createOrder(input: $input) {
+                      id
+                      ref
+                      status
+                    }
+                  }
+                `,
+                variables: {
+                  input: {
+                    ref: `FO-${reservation.orderId}-${Date.now()}`,
+                    type: 'FULFILLMENT',
+                    retailerId: '1', // From config
+                    customer: {
+                      ref: reservation.customerId,
+                      email: reservation.customerEmail
+                    },
+                    items: [{
+                      skuRef: reservation.sku,
+                      quantity: reservation.quantity,
+                      locationRef: reservation.locationRef
+                    }],
+                    attributes: [
+                      { name: 'originalOrderId', value: reservation.orderId },
+                      { name: 'reservationId', value: reservation.reservationId },
+                      { name: 'tier', value: reservation.tier },
+                      { name: 'shipDate', value: today }
+                    ]
+                  }
+                }
+              });
+
+              // Update reservation status
+              await client.graphql({
+                query: `
+                  mutation UpdateReservation($id: ID!, $status: String!) {
+                    updateInventoryQuantity(id: $id, status: $status) {
+                      id
+                      status
+                    }
+                  }
+                `,
+                variables: {
+                  id: reservation.id,
+                  status: 'CONFIRMED'
+                }
+              });
+
+              // Update KV
+              const kvRecord = await kvAdapter.get(['reservation', reservation.reservationId]);
+              if (kvRecord?.value) {
+                const record = kvRecord.value as ReservationRecord;
+                record.status = 'CONFIRMED';
+                record.confirmedAt = new Date().toISOString();
+                await kvAdapter.set(['reservation', reservation.reservationId], record);
+              }
+
+              availableQty -= reservation.quantity;
+              confirmed.push(reservation);
+
+              log.info(`✅ Confirmed reservation: ${reservation.reservationId}`);
+            } catch (error) {
+              // ? Enhanced: Error logging with recommendations
+              log.error('[PreOrderAllocation] Failed to confirm reservation', {
+                reservationId: reservation.reservationId,
+                error: error instanceof Error ? error.message : String(error),
+                recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+                  ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+                  : error.message?.includes('mutation') || error.message?.includes('GraphQL')
+                  ? 'Check GraphQL mutation syntax and reservation confirmation payload'
+                  : error.message?.includes('inventory') || error.message?.includes('quantity')
+                  ? 'Check available inventory quantity and reservation status'
+                  : 'Review error details and check reservation confirmation logic'
+              });
+            }
+          } else {
+            // Insufficient inventory - cancel reservation
+            try {
+              await client.graphql({
+                query: `
+                  mutation UpdateReservation($id: ID!, $status: String!) {
+                    updateInventoryQuantity(id: $id, status: $status) {
+                      id
+                      status
+                    }
+                  }
+                `,
+                variables: {
+                  id: reservation.id,
+                  status: 'CANCELLED'
+                }
+              });
+
+              // Update KV
+              const kvRecord = await kvAdapter.get(['reservation', reservation.reservationId]);
+              if (kvRecord?.value) {
+                const record = kvRecord.value as ReservationRecord;
+                record.status = 'CANCELLED';
+                record.cancelledAt = new Date().toISOString();
+                await kvAdapter.set(['reservation', reservation.reservationId], record);
+              }
+
+              cancelled.push({
+                ...reservation,
+                reason: 'Insufficient inventory',
+                availableQty
+              });
+
+              log.warn(`⚠️ Cancelled reservation: ${reservation.reservationId}`, {
+                reason: 'insufficient_inventory',
+                needed: reservation.quantity,
+                available: availableQty
+              });
+            } catch (error) {
+              // ? Enhanced: Error logging with recommendations
+              log.error('[PreOrderAllocation] Failed to cancel reservation', {
+                reservationId: reservation.reservationId,
+                error: error instanceof Error ? error.message : String(error),
+                recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+                  ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+                  : error.message?.includes('mutation') || error.message?.includes('GraphQL')
+                  ? 'Check GraphQL mutation syntax and reservation cancellation payload'
+                  : error.message?.includes('not found') || error.message?.includes('missing')
+                  ? 'Reservation not found - verify reservationId and check KV store'
+                  : 'Review error details and check reservation cancellation logic'
+              });
+            }
+          }
+        }
+      }
+
+      // Step 5: Send notifications (placeholder)
+      const duration = Date.now() - startTime;
+      log.info(`📧 Sending notifications (${duration}ms total)`, {
+        confirmed: confirmed.length,
+        cancelled: cancelled.length
+      });
+
+      // TODO: Send confirmation emails to confirmed reservations
+      // TODO: Send cancellation/apology emails to cancelled reservations
+
+      return {
+        success: true,
+        date: today,
+        processed: reservations.length,
+        confirmed: confirmed.length,
+        cancelled: cancelled.length,
+        duration,
+        summary: {
+          vipConfirmed: confirmed.filter(r => r.tier === 'VIP').length,
+          standardConfirmed: confirmed.filter(r => r.tier === 'STANDARD').length,
+          vipCancelled: cancelled.filter(r => r.tier === 'VIP').length,
+          standardCancelled: cancelled.filter(r => r.tier === 'STANDARD').length
+        },
+        timestamp: new Date().toISOString()
+      };
+    } catch (error) {
+      // ? Enhanced: Error logging with recommendations
+      log.error('[PreOrderAllocation] Scheduled release failed', {
+        error: error instanceof Error ? error.message : String(error),
+        errorType: error instanceof Error ? error.constructor.name : 'Error',
+        stack: error instanceof Error ? error.stack : undefined,
+        recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+          ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+          : error.message?.includes('KV') || error.message?.includes('state')
+          ? 'Check KV store connectivity and reservation state structure'
+          : error.message?.includes('connection') || error.message?.includes('timeout')
+          ? 'Check network connectivity and Fluent Commerce API availability'
+          : 'Review error details and check scheduled release workflow configuration'
+      });
+      throw error;
+    }
+  })(ctx);
+});
+
+// =============================================================================
+// WORKFLOW 3: CANCELLATION WEBHOOK
+// =============================================================================
+
+/**
+ * Cancellation Webhook - Cancel reservation and offer to next in queue
+ *
+ * Flow:
+ * 1. Receive cancellation request
+ * 2. Update reservation status
+ * 3. Query next customer in queue
+ * 4. Offer to next customer (if available)
+ * 5. Send notifications
+ */
+export const cancellationWebhook = webhook('cancel-reservation', {
+  response: { mode: 'sync' },
+  cors: true
+})
+  .then(fn('validate-cancellation', ({ data, log }) => {
+    log.info('🔍 Processing cancellation request');
+
+    if (!data.reservationId && !data.orderId) {
+      throw new Error('Either reservationId or orderId is required');
+    }
+
+    return data;
+  }))
+  .then(http('cancel-and-requeue', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { reservationId, orderId } = ctx.data;
+    const { log, openKv } = ctx;
+    const client = await createClient(ctx, { validateConnection: true });
+    const kvAdapter = new VersoriKVAdapter(openKv());
+
+    log.info('🚫 Cancelling reservation', { reservationId, orderId });
+
+    // Find reservation in KV
+    let reservation: ReservationRecord | null = null;
+
+    if (reservationId) {
+      const kvRecord = await kvAdapter.get(['reservation', reservationId]);
+      reservation = kvRecord?.value as ReservationRecord;
+    } else {
+      // Search by orderId (would need indexed tracker)
+      // Placeholder: iterate through all reservations
+      log.warn('[CANCEL] Searching by orderId - implement indexed search for production');
+    }
+
+    if (!reservation) {
+      throw new Error(`Reservation not found: ${reservationId || orderId}`);
+    }
+
+    // Update status in Fluent
+    const result = await client.graphql({
+      query: `
+        query FindReservation($ref: String!) {
+          inventoryQuantities(first: 1, ref: $ref) {
+            edges {
+              node {
+                id
+                ref
+                status
+              }
+            }
+          }
+        }
+      `,
+      variables: { ref: reservation.reservationId }
+    });
+
+    const inventoryId = result.data?.inventoryQuantities?.edges?.[0]?.node?.id;
+
+    if (inventoryId) {
+      await client.graphql({
+        query: `
+          mutation CancelReservation($id: ID!, $status: String!) {
+            updateInventoryQuantity(id: $id, status: $status) {
+              id
+              status
+            }
+          }
+        `,
+        variables: {
+          id: inventoryId,
+          status: 'CANCELLED'
+        }
+      });
+    }
+
+    // Update KV
+    reservation.status = 'CANCELLED';
+    reservation.cancelledAt = new Date().toISOString();
+    await kvAdapter.set(['reservation', reservation.reservationId], reservation);
+
+    log.info('✅ Reservation cancelled', {
+      reservationId: reservation.reservationId,
+      sku: reservation.sku,
+      quantity: reservation.quantity
+    });
+
+    // Find next in queue
+    const queueKey = ['queue', reservation.sku, reservation.locationRef, reservation.shipDate].join(':');
+
+    // TODO: Implement queue management
+    // Query next customer with higher queue position
+    // Send offer to next customer
+
+    log.info('📋 Queue position available for next customer', {
+      sku: reservation.sku,
+      shipDate: reservation.shipDate,
+      releasedQuantity: reservation.quantity
+    });
+
+    return {
+      success: true,
+      cancelled: {
+        reservationId: reservation.reservationId,
+        orderId: reservation.orderId,
+        sku: reservation.sku,
+        quantity: reservation.quantity
+      },
+      message: 'Reservation cancelled successfully',
+      timestamp: new Date().toISOString()
+    };
+  }));
+
+// =============================================================================
+// WORKFLOW 4: ADMIN DASHBOARD EXPORT
+// =============================================================================
+
+/**
+ * Export Reservations to S3 for Admin Dashboard
+ *
+ * Runs daily to export reservation status to S3 for dashboard visualization
+ */
+export const exportReservations = schedule('export-reservations', '0 3 * * *', async (ctx) => {
+  const { openKv, log } = ctx;
+
+  return fn('export-to-s3', async ({ openKv, log }) => {
+    log.info('📤 Exporting reservations to S3');
+
+    const kvAdapter = new VersoriKVAdapter(openKv());
+    const reservationTracker = new VersoriFileTracker(openKv(), 'pre-order-reservations');
+
+    // Get all reservations
+    const allReservations = await reservationTracker.listProcessedFiles();
+    log.info(`📋 Found ${allReservations.length} reservations to export`);
+
+    // Fetch full reservation data
+    const exportData: any[] = [];
+    for (const tracked of allReservations) {
+      const kvRecord = await kvAdapter.get(['reservation', tracked.fileName]);
+      if (kvRecord?.value) {
+        exportData.push(kvRecord.value);
+      }
+    }
+
+    // Group by ship date and status
+    const summary = {
+      total: exportData.length,
+      byStatus: {
+        RESERVED: exportData.filter(r => r.status === 'RESERVED').length,
+        CONFIRMED: exportData.filter(r => r.status === 'CONFIRMED').length,
+        CANCELLED: exportData.filter(r => r.status === 'CANCELLED').length,
+        EXPIRED: exportData.filter(r => r.status === 'EXPIRED').length
+      },
+      byTier: {
+        VIP: exportData.filter(r => r.tier === 'VIP').length,
+        STANDARD: exportData.filter(r => r.tier === 'STANDARD').length
+      },
+      exportedAt: new Date().toISOString()
+    };
+
+    const exportPayload = {
+      summary,
+      reservations: exportData
+    };
+
+    // TODO: Upload to S3
+    // const s3Key = `pre-orders/export-${new Date().toISOString().split('T')[0]}.json`;
+    // await s3Client.putObject({ Bucket, Key: s3Key, Body: JSON.stringify(exportPayload) });
+
+    log.info('✅ Export complete', summary);
+
+    return {
+      success: true,
+      summary,
+      recordCount: exportData.length
+    };
+  })(ctx);
+});
+
+// =============================================================================
+// WORKFLOW 5: MANUAL ATP CHECK (Testing/Admin)
+// =============================================================================
+
+/**
+ * Manual ATP Check - Admin endpoint to check future ATP
+ */
+export const checkAtp = webhook('check-atp', {
+  response: { mode: 'sync' },
+  cors: true
+})
+  .then(http('calculate-manual-atp', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { sku, locationRef, shipDate, quantity } = ctx.data;
+    const { log } = ctx;
+    const startTime = Date.now();
+    const client = await createClient(ctx, { validateConnection: true });
+
+    log.info('🔍 Manual ATP calculation', { sku, locationRef, shipDate, quantity });
+
+    // Reuse ATP calculation logic from pre-order workflow
+    const inventoryResult = await client.graphql({
+      query: `
+        query GetInventory($locationRef: String!, $skuRef: String!) {
+          inventoryQuantities(
+            first: 1
+            locationRef: $locationRef
+            skuRef: $skuRef
+            type: "LAST_ON_HAND"
+          ) {
+            edges {
+              node {
+                quantity
+              }
+            }
+          }
+        }
+      `,
+      variables: { locationRef, skuRef: sku }
+    });
+
+    const currentInventory = inventoryResult.data?.inventoryQuantities?.edges?.[0]?.node?.quantity || 0;
+
+    // Query reservations
+    const reservationsResult = await client.graphql({
+      query: `
+        query GetReservations($sku: String!, $shipDate: String!) {
+          inventoryQuantities(
+            first: 100
+            skuRef: $sku
+            status: "RESERVED"
+          ) {
+            edges {
+              node {
+                quantity
+                attributes {
+                  name
+                  value
+                }
+              }
+            }
+          }
+        }
+      `,
+      variables: { sku, shipDate }
+    });
+
+    let existingReservations = 0;
+    const reservationEdges = reservationsResult.data?.inventoryQuantities?.edges || [];
+    for (const edge of reservationEdges) {
+      const shipDateAttr = edge.node.attributes?.find((a: any) => a.name === 'shipDate');
+      if (shipDateAttr?.value === shipDate) {
+        existingReservations += edge.node.quantity || 0;
+      }
+    }
+
+    // Query expected arrivals
+    const expectedArrivalResult = await client.graphql({
+      query: `
+        query GetExpectedArrivals($locationRef: String!, $skuRef: String!, $beforeDate: String!) {
+          inventoryQuantities(
+            first: 50
+            locationRef: $locationRef
+            skuRef: $skuRef
+            type: "EXPECTED"
+            expectedOnBefore: $beforeDate
+          ) {
+            edges {
+              node {
+                quantity
+                expectedOn
+              }
+            }
+          }
+        }
+      `,
+      variables: { locationRef, skuRef: sku, beforeDate: shipDate }
+    });
+
+    const expectedArrival = expectedArrivalResult.data?.inventoryQuantities?.edges?.reduce(
+      (sum: number, edge: any) => sum + (edge.node.quantity || 0),
+      0
+    ) || 0;
+
+    const totalExpected = currentInventory + expectedArrival;
+    const overbookingLimit = Math.floor(totalExpected * 1.05);
+    const availableToPromise = overbookingLimit - existingReservations;
+    const canFulfill = availableToPromise >= (quantity || 1);
+    const duration = Date.now() - startTime;
+
+    log.info(`✅ ATP check complete (${duration}ms)`, { sku, canFulfill });
+
+    return {
+      sku,
+      locationRef,
+      shipDate,
+      requestedQuantity: quantity || 1,
+      currentInventory,
+      expectedArrival,
+      totalExpected,
+      existingReservations,
+      overbookingLimit,
+      availableToPromise,
+      canFulfill,
+      duration,
+      recommendation: canFulfill
+        ? 'Reservation can be fulfilled'
+        : `Insufficient inventory (need ${quantity || 1}, available ${availableToPromise})`,
+      timestamp: new Date().toISOString()
+    };
+  }));
+```
+
+---
+
+## 2. Configuration File: `config/priority-tiers.json`
+
+```json
+{
+  "version": "1.0.0",
+  "description": "Pre-order priority tier configuration",
+  "tiers": {
+    "VIP": {
+      "score": 100,
+      "description": "VIP customers get priority allocation",
+      "benefits": [
+        "First priority for limited inventory",
+        "Email notifications for restocks",
+        "Expedited shipping",
+        "Early access to new launches"
+      ]
+    },
+    "STANDARD": {
+      "score": 50,
+      "description": "Standard customer tier",
+      "benefits": [
+        "Standard allocation priority",
+        "Email notifications",
+        "Standard shipping"
+      ]
+    }
+  },
+  "overbooking": {
+    "enabled": true,
+    "percentage": 1.05,
+    "description": "Allow 105% allocation to account for cancellations"
+  },
+  "expiration": {
+    "daysBeforeShipDate": 7,
+    "description": "Reservations expire 7 days before ship date if not confirmed"
+  },
+  "queue": {
+    "maxQueueDepth": 10000,
+    "reallocationOnCancellation": true
+  }
+}
+```
+
+---
+
+## 3. Package Configuration: `package.json`
+
+```json
+{
+  "name": "pre-order-allocation-management",
+  "version": "1.0.0",
+  "description": "Pre-order allocation system with priority queuing and future ATP",
+  "versori": {
+    "workflows": "./index.ts"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "deploy": "versori deploy",
+    "logs": "versori logs",
+    "test-preorder": "curl -X POST http://localhost:8080/pre-order -H 'Content-Type: application/json' -d @test/sample-preorder.json",
+    "test-atp": "curl -X POST http://localhost:8080/check-atp -H 'Content-Type: application/json' -d '{\"sku\":\"IPHONE-15-PRO-256\",\"locationRef\":\"DC-NY\",\"shipDate\":\"2025-02-15\",\"quantity\":1}'"
+  }
+}
+```
+
+---
+
+## 4. Test Data: `test/sample-preorder.json`
+
+```json
+{
+  "orderId": "PRE-2025-001234",
+  "customerId": "CUST-VIP-9876",
+  "customerEmail": "john.doe@example.com",
+  "customerTier": "VIP",
+  "shipDate": "2025-02-15T00:00:00Z",
+  "source": "shopify",
+  "items": [
+    {
+      "sku": "IPHONE-15-PRO-256",
+      "productName": "iPhone 15 Pro 256GB Titanium Blue",
+      "quantity": 1,
+      "locationRef": "DC-NY"
+    }
+  ]
+}
+```
+
+---
+
+## Versori Workflow Structure
+
+This solution uses multiple workflow types:
+
+### HTTP Webhooks (Real-time)
+
+1. **pre-order** - Receives pre-orders from e-commerce
+2. **cancel-reservation** - Cancels existing reservations
+3. **check-atp** - Manual ATP calculation (admin)
+
+### Scheduled Workflows (Cron)
+
+1. **release-reservations** - Daily at 2 AM
+2. **export-reservations** - Daily at 3 AM (dashboard data)
+
+### Workflow Dependencies
+
+```
+┌─────────────────┐
+│  E-commerce     │
+│  Platform       │
+└────────┬────────┘
+         │ HTTP POST
+         ▼
+┌─────────────────┐      ┌──────────────┐
+│  Pre-Order      │─────▶│  VersoriKV   │
+│  Webhook        │      │  (State)     │
+└────────┬────────┘      └──────────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Fluent API     │
+│  (Reservations) │
+└─────────────────┘
+         ▲
+         │
+┌────────┴────────┐
+│  Release        │  (Scheduled 2 AM)
+│  Workflow       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Fulfillment    │
+│  Orders         │
+└─────────────────┘
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: Future ATP (Available to Promise) Calculation
+
+**Algorithm:**
+
+```typescript
+// Step 1: Get current inventory
+currentInventory = queryInventory(sku, location)
+
+// Step 2: Get expected arrivals before ship date
+expectedArrival = queryExpectedBefore(sku, location, shipDate)
+
+// Step 3: Get existing reservations for this date
+existingReservations = queryReservations(sku, location, shipDate)
+
+// Step 4: Calculate overbooking limit (105%)
+totalExpected = currentInventory + expectedArrival
+overbookingLimit = totalExpected * 1.05
+
+// Step 5: Calculate ATP
+availableToPromise = overbookingLimit - existingReservations
+
+// Step 6: Check fulfillment
+canFulfill = availableToPromise >= requestedQuantity
+```
+
+**Why overbooking?**
+
+- Typical cancellation rate: 3-5%
+- 105% allocation ensures full utilization
+- Prevents lost sales from conservative allocation
+
+**Edge cases:**
+
+- No expected arrivals → ATP based on current only
+- Multiple locations → calculate per location
+- Negative ATP → queue overflow, reject order
+
+### Pattern 2: Priority Scoring Algorithm
+
+**Score calculation:**
+
+```typescript
+// Tier component (VIP=100, Standard=50)
+tierScore = customerTier === 'VIP' ? 100 : 50
+
+// Time component (earlier = better)
+timeScore = Date.now() // Milliseconds since epoch
+
+// Final priority (higher = better)
+priority = (tierScore * 1000000) - timeScore
+
+// Example scores:
+// VIP order at 10:00 AM = 100000000 - 1708000000 = -1607000000
+// VIP order at 10:01 AM = 100000000 - 1708000060 = -1607000060
+// Standard at 10:00 AM = 50000000 - 1708000000 = -1657000000
+
+// Sort descending: all VIPs come first, then by time
+```
+
+**Why negative scores?**
+
+- Allows simple descending sort
+- VIP scores always > Standard scores
+- Time breaks ties within tier
+
+**Alternative scoring strategies:**
+
+- Purchase history: +10 points per previous purchase
+- Cart value: +1 point per $100
+- Membership duration: +1 point per year
+
+### Pattern 3: Reservation Expiration
+
+**Expiration logic:**
+
+```typescript
+// Calculate expiration date
+shipDate = new Date('2025-02-15')
+expirationDate = new Date(shipDate.getTime() - 7 * 24 * 60 * 60 * 1000)
+
+// Store with reservation
+reservation.expiresAt = expirationDate.toISOString()
+
+// Scheduled cleanup (runs daily)
+const now = new Date()
+if (now > expirationDate && reservation.status === 'RESERVED') {
+  reservation.status = 'EXPIRED'
+  releaseInventory(reservation)
+  offerToNextInQueue(reservation)
+}
+```
+
+**Why 7 days?**
+
+- Gives customers buffer to cancel if needed
+- Prevents last-minute cancellations
+- Allows reallocation to other customers
+- Industry standard for pre-orders
+
+**Alternatives:**
+
+- Dynamic expiration: longer for high-value items
+- Tiered expiration: VIP gets longer window
+- Payment-based: shorter for unpaid reservations
+
+### Pattern 4: Queue Position Tracking
+
+**Queue management:**
+
+```typescript
+// KV key structure
+queueKey = ['queue', sku, locationRef, shipDate].join(':')
+// Example: 'queue:IPHONE-15-PRO-256:DC-NY:2025-02-15'
+
+// Get current position
+currentLength = await kvAdapter.get([queueKey]) || 0
+
+// Assign new position
+newPosition = currentLength + 1
+await kvAdapter.set([queueKey], newPosition)
+
+// On cancellation
+// 1. Mark position as available
+// 2. Query next unfulfilled reservation
+// 3. Move them up in queue
+```
+
+**Why track position?**
+
+- Transparency for customers
+- "You are #23 in line" messaging
+- Prioritize reallocation on cancellation
+- Dashboard visibility
+
+**Optimization:**
+
+- Use sorted sets for O(log n) insertion
+- Batch queue updates every 5 minutes
+- Cache queue length in memory
+
+### Pattern 5: Scheduled Release Workflow
+
+**Release algorithm:**
+
+```typescript
+// Run daily at 2 AM for today's ship date
+today = '2025-02-15'
+
+// Step 1: Get all reservations
+reservations = queryReservations({ shipDate: today, status: 'RESERVED' })
+
+// Step 2: Sort by priority
+reservations.sort((a, b) => b.priority - a.priority)
+
+// Step 3: Group by SKU
+groupedBySku = groupBy(reservations, r => r.sku)
+
+// Step 4: For each SKU, allocate inventory
+for (sku in groupedBySku) {
+  availableQty = getCurrentInventory(sku)
+
+  for (reservation of groupedBySku[sku]) {
+    if (availableQty >= reservation.quantity) {
+      // Confirm and create fulfillment order
+      createFulfillmentOrder(reservation)
+      availableQty -= reservation.quantity
+    } else {
+      // Cancel and notify
+      cancelReservation(reservation, 'insufficient_inventory')
+      sendApologyEmail(reservation)
+    }
+  }
+}
+```
+
+**Why 2 AM?**
+
+- Off-peak hours (low traffic)
+- Gives time for overnight inventory updates
+- Allows morning fulfillment processing
+- Industry best practice
+
+**Failure handling:**
+
+- Retry failed confirmations 3 times
+- Alert ops team if >10% cancellations
+- Log all decisions for audit trail
+
+### Pattern 6: Overbooking Strategy
+
+**Why 105%?**
+
+```
+Historical analysis:
+- Average cancellation rate: 4.2%
+- Range: 3.5% - 5.8% depending on product
+- 105% allocation:
+  * If 0 cancellations: 5% oversold (minor)
+  * If 5% cancellations: perfect allocation
+  * If 10% cancellations: 5% undersold
+
+Trade-offs:
+- Conservative (100%): Lost revenue, customer disappointment
+- Moderate (105%): Optimal balance
+- Aggressive (110%): Risk of overselling, fulfillment delays
+```
+
+**Dynamic overbooking:**
+
+```typescript
+// Adjust based on product category
+const overbookingRates = {
+  'electronics': 1.03,  // Low cancellation
+  'apparel': 1.08,      // High cancellation
+  'limited-edition': 1.02, // Low risk tolerance
+  'default': 1.05
+}
+
+const rate = overbookingRates[productCategory] || overbookingRates['default']
+overbookingLimit = totalExpected * rate
+```
+
+---
+
+## Testing
+
+### Test 1: Create Pre-Order (VIP Customer)
+
+```bash
+curl -X POST https://your-workspace.versori.run/pre-order \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "PRE-2025-001234",
+    "customerId": "CUST-VIP-9876",
+    "customerEmail": "john.doe@example.com",
+    "customerTier": "VIP",
+    "shipDate": "2025-02-15T00:00:00Z",
+    "source": "shopify",
+    "items": [{
+      "sku": "IPHONE-15-PRO-256",
+      "productName": "iPhone 15 Pro 256GB",
+      "quantity": 1,
+      "locationRef": "DC-NY"
+    }]
+  }'
+
+# Expected Response:
+{
+  "success": true,
+  "orderId": "PRE-2025-001234",
+  "reservations": [{
+    "reservationId": "RES-PRE-2025-001234-IPHONE-15-PRO-256-1708000000",
+    "sku": "IPHONE-15-PRO-256",
+    "quantity": 1,
+    "queuePosition": 1,
+    "priority": 99892000000,
+    "expiresAt": "2025-02-08T00:00:00Z"
+  }],
+  "failedItems": [],
+  "message": "All items reserved successfully"
+}
+```
+
+### Test 2: Check ATP for Product
+
+```bash
+curl -X POST https://your-workspace.versori.run/check-atp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sku": "IPHONE-15-PRO-256",
+    "locationRef": "DC-NY",
+    "shipDate": "2025-02-15",
+    "quantity": 1
+  }'
+
+# Expected Response:
+{
+  "sku": "IPHONE-15-PRO-256",
+  "locationRef": "DC-NY",
+  "shipDate": "2025-02-15",
+  "requestedQuantity": 1,
+  "currentInventory": 500,
+  "expectedArrival": 1000,
+  "totalExpected": 1500,
+  "existingReservations": 1234,
+  "overbookingLimit": 1575,
+  "availableToPromise": 341,
+  "canFulfill": true,
+  "recommendation": "Reservation can be fulfilled"
+}
+```
+
+### Test 3: Cancel Reservation
+
+```bash
+curl -X POST https://your-workspace.versori.run/cancel-reservation \
+  -H "Content-Type: application/json" \
+  -d '{
+    "reservationId": "RES-PRE-2025-001234-IPHONE-15-PRO-256-1708000000"
+  }'
+
+# Expected Response:
+{
+  "success": true,
+  "cancelled": {
+    "reservationId": "RES-PRE-2025-001234-IPHONE-15-PRO-256-1708000000",
+    "orderId": "PRE-2025-001234",
+    "sku": "IPHONE-15-PRO-256",
+    "quantity": 1
+  },
+  "message": "Reservation cancelled successfully"
+}
+```
+
+### Test 4: Trigger Manual Release (Admin)
+
+```bash
+# Deploy workflow
+npm run deploy
+
+# View scheduled workflow logs
+npm run logs
+
+# Expected log output:
+[RELEASE] Starting scheduled release process
+[RELEASE] Found 1234 reservations for 2025-02-15
+[RELEASE] Sorted reservations by priority - VIP: 234, Standard: 1000
+[RELEASE] Processing 1234 reservations for IPHONE-15-PRO-256
+[RELEASE] Confirmed reservation: RES-xxx (1234 total)
+[RELEASE] Cancelled reservation: RES-yyy - insufficient inventory
+[RELEASE] Release complete - confirmed: 1200, cancelled: 34
+```
+
+---
+
+## Common Issues and Solutions
+
+### Issue 1: ATP Calculation Incorrect
+
+**Symptoms:**
+
+- Overselling (more reservations than inventory)
+- Underselling (rejecting valid reservations)
+
+**Root Causes:**
+
+1. Not accounting for existing reservations
+2. Double-counting expected arrivals
+3. Wrong overbooking percentage
+
+**Solution:**
+
+```typescript
+// Add debug logging to ATP calculation
+log.info('[ATP-DEBUG] Calculation breakdown', {
+  sku,
+  current: currentInventory,
+  expected: expectedArrival,
+  reserved: existingReservations,
+  overbooking: overbookingLimit,
+  atp: availableToPromise,
+  // Verify math
+  verification: {
+    total: currentInventory + expectedArrival,
+    withOverbooking: (currentInventory + expectedArrival) * 1.05,
+    afterReserved: ((currentInventory + expectedArrival) * 1.05) - existingReservations
+  }
+});
+
+// Add validation
+if (availableToPromise < 0) {
+  log.warn('[ATP] Negative ATP detected - inventory oversold', {
+    sku,
+    atp: availableToPromise
+  });
+}
+```
+
+### Issue 2: Queue Position Conflicts
+
+**Symptoms:**
+
+- Duplicate queue positions
+- Gaps in queue numbers
+- Out-of-order processing
+
+**Root Cause:**
+
+- Race condition in queue counter increment
+- Multiple reservations at same millisecond
+
+**Solution:**
+
+```typescript
+// Use atomic increment with retry
+async function assignQueuePosition(
+  kvAdapter: VersoriKVAdapter,
+  queueKey: string,
+  maxRetries = 3
+): Promise<number> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      // Get current position
+      const current = await kvAdapter.get([queueKey]);
+      const position = (current?.value as number) || 0;
+      const newPosition = position + 1;
+
+      // Set with version check (if supported)
+      await kvAdapter.set([queueKey], newPosition);
+
+      return newPosition;
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      // Wait with exponential backoff
+      await new Promise(resolve => setTimeout(resolve, 2 ** i * 100));
+    }
+  }
+
+  throw new Error('Failed to assign queue position after retries');
+}
+```
+
+### Issue 3: Reservation Expiration Not Working
+
+**Symptoms:**
+
+- Expired reservations still active
+- Inventory not released
+
+**Root Cause:**
+
+- Expiration check not running
+- Timezone mismatches
+- Status not updated in Fluent
+
+**Solution:**
+
+```typescript
+// Add expiration cleanup to release workflow
+async function cleanupExpiredReservations(
+  client: FluentClient,
+  kvAdapter: VersoriKVAdapter,
+  log: Logger
+) {
+  const now = new Date();
+
+  // Query all RESERVED inventory
+  const result = await client.graphql({
+    query: `
+      query GetExpiredReservations {
+        inventoryQuantities(
+          first: 1000
+          status: "RESERVED"
+        ) {
+          edges {
+            node {
+              id
+              ref
+              attributes {
+                name
+                value
+              }
+            }
+          }
+        }
+      }
+    `
+  });
+
+  const edges = result.data?.inventoryQuantities?.edges || [];
+
+  for (const edge of edges) {
+    const expiresAtAttr = edge.node.attributes?.find((a: any) => a.name === 'expiresAt');
+    if (!expiresAtAttr) continue;
+
+    const expiresAt = new Date(expiresAtAttr.value);
+
+    if (now > expiresAt) {
+      // Mark as expired
+      await client.graphql({
+        query: `
+          mutation ExpireReservation($id: ID!) {
+            updateInventoryQuantity(id: $id, status: "EXPIRED") {
+              id
+              status
+            }
+          }
+        `,
+        variables: { id: edge.node.id }
+      });
+
+      log.info('[CLEANUP] Expired reservation', {
+        ref: edge.node.ref,
+        expiresAt: expiresAtAttr.value
+      });
+    }
+  }
+}
+```
+
+### Issue 4: Priority Queue Not Respected
+
+**Symptoms:**
+
+- Standard customers processed before VIP
+- Queue positions ignored
+
+**Root Cause:**
+
+- Sorting algorithm incorrect
+- Priority scores calculated wrong
+- Time component overflow
+
+**Solution:**
+
+```typescript
+// Verify sorting logic
+function verifySortOrder(reservations: ReservationWithPriority[], log: any) {
+  let prevPriority = Infinity;
+  let prevTier = 'VIP';
+
+  for (const reservation of reservations) {
+    // Check tier ordering
+    if (prevTier === 'VIP' && reservation.tier === 'STANDARD') {
+      prevTier = 'STANDARD';
+    }
+
+    // Check priority decreasing
+    if (reservation.priority > prevPriority) {
+      throw new Error(`Sort order violated: ${reservation.priority} > ${prevPriority}`);
+    }
+
+    prevPriority = reservation.priority;
+  }
+
+  log.info('✓ Sort order verified');
+}
+
+// Use stable sort
+reservations.sort((a, b) => {
+  // Primary: priority (higher first)
+  if (a.priority !== b.priority) {
+    return b.priority - a.priority;
+  }
+
+  // Secondary: queue position (lower first)
+  if (a.queuePosition !== b.queuePosition) {
+    return a.queuePosition - b.queuePosition;
+  }
+
+  // Tertiary: creation time (earlier first)
+  return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+});
+```
+
+### Issue 5: Scheduled Release Not Running
+
+**Symptoms:**
+
+- Reservations not converted to orders
+- No logs from scheduled workflow
+
+**Root Cause:**
+
+- Cron expression incorrect
+- Workflow not deployed
+- Timezone mismatch
+
+**Solution:**
+
+```bash
+# Verify cron expression (use crontab.guru)
+# "0 2 * * *" = Every day at 2:00 AM UTC
+
+# Check workflow deployment
+versori workflows list
+
+# Expected output:
+# release-reservations (schedule: 0 2 * * *)
+# export-reservations (schedule: 0 3 * * *)
+
+# Manually trigger for testing
+curl -X POST https://your-workspace.versori.run/__scheduled/release-reservations
+
+# Check logs
+npm run logs -- --workflow release-reservations --tail 100
+```
+
+---
+
+## Real-World Launch Scenarios
+
+### Scenario 1: iPhone 15 Pro Launch
+
+**Context:**
+
+- Product: iPhone 15 Pro 256GB Titanium Blue
+- Expected demand: 10,000 pre-orders
+- Available inventory: 8,500 units
+- Launch date: September 22, 2025
+
+**Configuration:**
+
+```json
+{
+  "overbooking": 1.03,  // Conservative for high-value item
+  "tiers": {
+    "VIP": { "score": 100 },
+    "STANDARD": { "score": 50 }
+  },
+  "expiration": 14  // 14 days for expensive item
+}
+```
+
+**Results:**
+
+- Pre-orders received: 11,234 (12% over inventory)
+- VIP reservations: 1,234 (11%)
+- Standard reservations: 10,000 (89%)
+- Confirmed on launch: 8,925 (105%)
+- Cancellations: 425 (3.8%)
+- Final allocation: 8,500 units (100%)
+
+**Priority breakdown:**
+
+- VIP customers: 1,234 confirmed (100%)
+- Standard customers: 7,691 confirmed (76.9%)
+- Standard cancellations: 2,309 (23.1%)
+
+### Scenario 2: Limited Edition Sneakers
+
+**Context:**
+
+- Product: Air Jordan 1 Retro High "Trophy Room"
+- Expected demand: 50,000+ pre-orders
+- Available inventory: 5,000 pairs
+- Release date: March 15, 2025
+
+**Configuration:**
+
+```json
+{
+  "overbooking": 1.02,  // Very conservative for limited edition
+  "tiers": {
+    "PLATINUM": { "score": 150 },
+    "VIP": { "score": 100 },
+    "STANDARD": { "score": 50 }
+  },
+  "expiration": 3,  // Short window for high demand
+  "maxQueueDepth": 10000  // Cap queue at 2x inventory
+}
+```
+
+**Results:**
+
+- Pre-orders received: 52,389 (first 2 hours)
+- Queue capped at: 10,000 reservations
+- Overflow: 42,389 added to waitlist
+- Confirmed on launch: 5,100 (102%)
+- Cancellations: 100 (1.9%)
+- Final allocation: 5,000 pairs (100%)
+
+**Priority breakdown:**
+
+- Platinum: 450 confirmed (100%)
+- VIP: 2,550 confirmed (100%)
+- Standard: 2,000 confirmed (31.7% of queue)
+
+### Scenario 3: Gaming Console Launch
+
+**Context:**
+
+- Product: PlayStation 6
+- Expected demand: 25,000 pre-orders
+- Available inventory: 20,000 units (multiple waves)
+- Launch date: November 15, 2025
+
+**Configuration:**
+
+```json
+{
+  "overbooking": 1.05,  // Standard overbooking
+  "waves": [
+    { "date": "2025-11-15", "quantity": 10000 },
+    { "date": "2025-11-22", "quantity": 5000 },
+    { "date": "2025-11-29", "quantity": 5000 }
+  ],
+  "expiration": 7
+}
+```
+
+**Results:**
+
+- Total pre-orders: 27,450
+- Wave 1 (Nov 15): 10,500 confirmed
+- Wave 2 (Nov 22): 5,250 confirmed
+- Wave 3 (Nov 29): 5,250 confirmed
+- Total confirmed: 21,000 (105%)
+- Total cancelled: 6,450 (23.5%)
+
+**Key learnings:**
+
+- Multiple waves reduce cancellation rate
+- Customers willing to wait for later wave
+- VIP upgrade offered to later wave customers
+
+---
+
+## Related Guides
+
+- **02-scheduled-csv-inventory.md** - Scheduled inventory ingestion patterns
+- **03-kv-state-management.md** - VersoriKV state management techniques
+- **04-webhook-xml-response.md** - Custom webhook response patterns
+- **05-real-time-inventory-sync.md** - Real-time inventory updates
+- **GraphQL Query Patterns** - Complex GraphQL query techniques
+- **Priority Queue Design** - Queue management algorithms
+
+---
+
+## Next Steps
+
+1. **Email Integration**: Add SendGrid/SES for customer notifications
+
+2. **Analytics Dashboard**: Build S3 → QuickSight pipeline for insights
+
+3. **Demand Forecasting**: ML model to predict cancellation rates
+
+4. **Dynamic Overbooking**: Adjust percentage based on historical data
+
+5. **Multi-Tier Pricing**: Offer priority tiers as paid upgrades
+
+6. **Inventory Pooling**: Share ATP across multiple locations
+
+7. **Webhook Retry**: Add exponential backoff for failed confirmations
+
+8. **Audit Trail**: Store all ATP calculations for debugging
+
+---
+
+**Need Help?**
+
+- SDK Documentation: `/fc-connect-sdk/docs/readme.md`
+- Example Connectors: `/connectors/Sample versori connectors/`
+- GraphQL Patterns: `/docs/guides/graphql-patterns.md`
+- Versori Platform: https://docs.versori.com