#Sync Manager (@xtnd/vantage-sync-manager)

Package: @xtnd/vantage-sync-manager
Source Directory: xtnd-vantage/packages/sync-manager/

#1. Overview

@xtnd/vantage-sync-manager is the operational nerve center of XTND Vantage. It orchestrates:

• Non-blocking writes into local storage adapters.
• Dynamic urgency evaluation via the VantageUrgencyEngine.
• Immediate out-of-band dispatch of P0 Critical events.
• Autonomous background batch syncing of P1–P3 events with exponential backoff and network retry logic.

#2. Storage Manager (VantageStorageManager)

export interface StorageManagerOptions {
  storageAdapter?: IStorageAdapter;      // Defaults to MemoryStorageAdapter
  urgencyEvaluator?: IUrgencyEvaluator;  // Defaults to VantageUrgencyEngine
  transport?: ISyncTransport;            // E.g. VantageHttpTransport
  batchSize?: number;                    // Defaults to 50
  syncIntervalMs?: number;               // Defaults to 10,000ms (10s)
  autoStartSync?: boolean;               // Defaults to true
}

#2.1 The Write Cycle (writeEvent)

When an application logs an event:

1. Urgency is evaluated: urgencyEvaluator.evaluate(type, payload).
2. A VantageEvent object is stamped with a UUID, timestamp, priority, and synced: false.
3. The event is written into the local IStorageAdapter.
4. If priority is P0_CRITICAL, dispatchImmediateEvent(event) is triggered out-of-band:
   • Dispatches via transport.sendImmediate(event).
   • On confirmation, calls storage.markSynced([event.id]).
5. The method resolves immediately, ensuring non-blocking execution for callers.

#2.2 The Batch Sync Loop (startSyncLoop)

• Initiates an interval timer (default 10s) with syncTimer.unref() to avoid keeping Node.js process loops open.
• In browsers, coordinates with window.requestIdleCallback() to execute batch flushes only when the browser main thread is idle.
• Concurrency lock: isSyncing prevents overlapping flush executions.

#3. Urgency Evaluation Engine (VantageUrgencyEngine)

The Urgency Engine assigns one of four operational priorities:

#4. HTTP Edge Transport (VantageHttpTransport)

The HTTP transport layer handles resilient communication with Cloudflare Workers:

#Features

• Exponential Backoff: Up to 3 retries for HTTP 5xx errors or network drops with exponential backoff delay (1s, 2s, 4s, capped at 5s).
• Timeout Protection: Employs AbortController with a configurable timeout (default 5000ms).
• Tab Close Delivery (keepalive: true): Uses the browser fetch keepalive flag so events are successfully delivered even if a user navigates away or closes their tab.
• Client Identity: Sends X-Vantage-Client: xtnd-vantage-sdk/1.0 and optional Authorization: Bearer <token>.

#5. Usage Example

import { MemoryStorageAdapter } from '@xtnd/vantage-storage-local';
import { VantageStorageManager, VantageHttpTransport } from '@xtnd/vantage-sync-manager';

const storageAdapter = new MemoryStorageAdapter();
const transport = new VantageHttpTransport({
  endpoint: 'https://api.vantage.xgi.io',
  apiKey: 'secret_vantage_key'
});

const storageManager = new VantageStorageManager({
  storageAdapter,
  transport,
  batchSize: 50,
  syncIntervalMs: 5000,
  autoStartSync: true
});

// Log normal event (batched)
await storageManager.writeEvent('page:init', { route: '/dashboard' });

// Log critical event (immediately sent to api.vantage.xgi.io/v1/events/urgent)
await storageManager.writeEvent('ai:quota:exhausted', {
  provider: 'openai',
  remainingCreditsUsd: 0,
  isCritical: true
});