#Event-Driven Pipeline & Urgency Engine

XTND Vantage • Local-First Telemetry Ingestion, Urgency Classification & Synchronization

#1. The Core Invariant: "Listeners Only Write to Storage"

A central architectural pattern of XTND Vantage is the decoupling of event generation from event transmission.

In typical software systems, when an event occurs (e.g. an API call completes or a user clicks a button), an HTTP request is made directly to a telemetry endpoint. This introduces:

• Latency and CPU thread contention.
• Fragility: network disconnects cause silent event loss.
• Main-thread blocking: analytics libraries compete with UI rendering frames.

In XTND Vantage:

[Application Code]
       │
       ▼
[EventBus / Subsystem]
       │
       ▼
[VantageStorageManager.writeEvent()]  <── Strict non-blocking boundary
       │
       ├──> [Local Storage Adapter] (Memory / IndexedDB)
       │
       └──> [VantageUrgencyEngine]
                  │
                  ├── P0_CRITICAL  ──> Immediate HTTP transport (fetch with keepalive)
                  └── P1 - P3      ──> Enqueue in local buffer for periodic batch sync

#2. The VantageEvent Schema

Every event passing through Vantage conforms to the strict TypeScript contract defined in @xtnd/vantage-core:

export type EventPriority = 'P0_CRITICAL' | 'P1_HIGH' | 'P2_NORMAL' | 'P3_DEFERRED';

export interface VantageEvent<T = any> {
  /** Unique UUIDv4 identifier generated locally */
  id: string;

  /** Dot- or colon-namespaced event key (e.g. 'page:init', 'ai:quota:exhausted') */
  type: string;

  /** Origin identifier (e.g. 'laogpt.com', 'api.sonar.vantage.xgi.io') */
  source: string;

  /** Priority classification determined by UrgencyEngine */
  priority: EventPriority;

  /** Unix epoch timestamp in milliseconds */
  timestamp: number;

  /** Generic typed payload object containing event-specific data */
  payload: T;

  /** Contextual metadata (tenantId, environment, correlationId, release version) */
  meta?: {
    tenantId?: string;
    environment?: 'production' | 'staging' | 'development';
    version?: string;
    correlationId?: string;
    [key: string]: any;
  };

  /** Flag indicating whether the event has been confirmed acknowledged upstream */
  synced?: boolean;
}

#3. The Urgency Engine (VantageUrgencyEngine)

The Urgency Engine inspects every incoming event's type and payload to assign one of four execution tiers:

graph TD
    subgraph P0["P0_CRITICAL (Immediate Dispatch)"]
        P0_1["ai:quota:exhausted (< 1% balance)"]
        P0_2["circuit:trip (Runaway loop / 5xx spike)"]
        P0_3["outage:declared (System incident)"]
        P0_4["HTTP 500+ Origin Errors"]
    end

    subgraph P1["P1_HIGH (Top-Tier Sync)"]
        P1_1["ai:stream:completed"]
        P1_2["ai:generation:complete"]
        P1_3["ai:quota:warning (< 20% balance)"]
        P1_4["user:conversion / payment:success"]
    end

    subgraph P2["P2_NORMAL (Standard Batching)"]
        P2_1["page:init (Browser arrival)"]
        P2_2["ai:chunk (Intermediate stream chunks)"]
        P2_3["web_vitals (LCP, FID, CLS)"]
        P2_4["edge:request:completed"]
    end

    subgraph P3["P3_DEFERRED (Idle Sync)"]
        P3_1["status:heartbeat"]
        P3_2["debug:trace / cache:hit"]
        P3_3["heartbeat:idle"]
    end

#Urgency Classification Rules

// Default evaluation logic in VantageUrgencyEngine:
if (
  lowerType.includes('quota:exhausted') ||
  lowerType.includes('circuit:trip') ||
  lowerType.includes('outage:declared') ||
  (payload?.status >= 500) ||
  (payload?.isCritical === true)
) {
  return 'P0_CRITICAL';
}

if (
  lowerType.includes('ai:stream:completed') ||
  lowerType.includes('user:conversion') ||
  lowerType.includes('quota:warning')
) {
  return 'P1_HIGH';
}

if (
  lowerType.includes('debug') ||
  lowerType.includes('cache:hit') ||
  lowerType.includes('status:heartbeat')
) {
  return 'P3_DEFERRED';
}

return 'P2_NORMAL'; // Default fallback

#Custom Rule Extension

Developers can register custom priority rules dynamically:

const engine = new VantageUrgencyEngine();
engine.registerRule((type, payload) => {
  if (type === 'fraud:detected') return 'P0_CRITICAL';
  if (payload?.isVIPCustomer) return 'P1_HIGH';
  return null; // Fallback to downstream rules
});

#4. Dual-Path Synchronization Architecture

#Path 1: P0 Critical Immediate Dispatch

When an event receives a P0_CRITICAL tag:

1. It is written to local storage with synced: false.
2. Out-of-band execution calls transport.sendImmediate(event) without blocking the originating thread.
3. In browser environments, HTTP requests use fetch(..., { keepalive: true }) to guarantee delivery even if the user closes the tab immediately.
4. Upon HTTP 200/202 confirmation, the local storage entry is updated to synced: true via markSynced([event.id]).

#Path 2: P1–P3 Idle Batch Synchronization

For non-critical events:

1. Events accumulate in the local storage buffer.
2. A background timer runs every 10,000ms (10 seconds).
3. If running in a browser that supports window.requestIdleCallback, the flush is scheduled during the browser's idle periods to guarantee 60 FPS UI rendering.
4. Up to 50 events (batchSize) are read via readUnsynced(50).
5. Events are posted as a JSON payload to /v1/events/batch or /v1/events/web.
6. Successful acknowledgments mark events as synced, and synced records are periodically pruned to prevent memory growth.

#5. Storage Adapters (IStorageAdapter)

Vantage provides two production storage adapters:

1. MemoryStorageAdapter:
   • Zero dependencies.
   • High-throughput in-memory array with array bounds capping.
   • Ideal for Cloudflare Workers, Node.js servers, and automated unit testing.
2. IndexedDBStorageAdapter:
   • Built on native browser window.indexedDB.
   • Durable persistence across page refreshes, browser restarts, and tab closures.
   • Offline-resilient: events generated while a user is offline will automatically sync once network connectivity resumes.