@topgunbuild/core 0.10.1 → 0.11.0

package/dist/index.mjs

@@ -21,6 +21,7 @@ var HLC = class {
     this.nodeId = nodeId;
     this.strictMode = options.strictMode ?? false;
     this.maxDriftMs = options.maxDriftMs ?? 6e4;
+    this.clockSource = options.clockSource ?? { now: () => Date.now() };
     this.lastMillis = 0;
     this.lastCounter = 0;
   }
@@ -33,12 +34,19 @@ var HLC = class {
   get getMaxDriftMs() {
     return this.maxDriftMs;
   }
+  /**
+   * Returns the clock source used by this HLC instance.
+   * Useful for LWWMap/ORMap to access the same clock for TTL checks.
+   */
+  getClockSource() {
+    return this.clockSource;
+  }
   /**
    * Generates a new unique timestamp for a local event.
    * Ensures monotonicity: always greater than any previously generated or received timestamp.
    */
   now() {
-    const systemTime = Date.now();
+    const systemTime = this.clockSource.now();
     if (systemTime > this.lastMillis) {
       this.lastMillis = systemTime;
       this.lastCounter = 0;
@@ -56,7 +64,7 @@ var HLC = class {
    * Must be called whenever a message/event is received from another node.
    */
   update(remote) {
-    const systemTime = Date.now();
+    const systemTime = this.clockSource.now();
     const drift = remote.millis - systemTime;
     if (drift > this.maxDriftMs) {
       if (this.strictMode) {
@@ -340,7 +348,7 @@ var LWWMap = class {
       return void 0;
     }
     if (record.ttlMs) {
-      const now = Date.now();
+      const now = this.hlc.getClockSource().now();
       if (record.timestamp.millis + record.ttlMs < now) {
         return void 0;
       }
@@ -417,7 +425,7 @@ var LWWMap = class {
    */
   entries() {
     const iterator = this.data.entries();
-    const now = Date.now();
+    const clockSource = this.hlc.getClockSource();
     return {
       [Symbol.iterator]() {
         return this;
@@ -427,7 +435,7 @@ var LWWMap = class {
         while (!result.done) {
           const [key, record] = result.value;
           if (record.value !== null) {
-            if (record.ttlMs && record.timestamp.millis + record.ttlMs < now) {
+            if (record.ttlMs && record.timestamp.millis + record.ttlMs < clockSource.now()) {
               result = iterator.next();
               continue;
             }
@@ -764,7 +772,7 @@ var ORMap = class {
     const keyMap = this.items.get(key);
     if (!keyMap) return [];
     const values = [];
-    const now = Date.now();
+    const now = this.hlc.getClockSource().now();
     for (const [tag, record] of keyMap.entries()) {
       if (!this.tombstones.has(tag)) {
         if (record.ttlMs && record.timestamp.millis + record.ttlMs < now) {
@@ -784,7 +792,7 @@ var ORMap = class {
     const keyMap = this.items.get(key);
     if (!keyMap) return [];
     const records = [];
-    const now = Date.now();
+    const now = this.hlc.getClockSource().now();
     for (const [tag, record] of keyMap.entries()) {
       if (!this.tombstones.has(tag)) {
         if (record.ttlMs && record.timestamp.millis + record.ttlMs < now) {
@@ -2886,9 +2894,86 @@ var SyncResetRequiredPayloadSchema = z9.object({
   reason: z9.string()
 });
 
-// src/schemas/index.ts
+// src/schemas/http-sync-schemas.ts
 import { z as z10 } from "zod";
-var MessageSchema = z10.discriminatedUnion("type", [
+var SyncMapEntrySchema = z10.object({
+  mapName: z10.string(),
+  lastSyncTimestamp: TimestampSchema
+});
+var HttpQueryRequestSchema = z10.object({
+  queryId: z10.string(),
+  mapName: z10.string(),
+  filter: z10.any(),
+  limit: z10.number().optional(),
+  offset: z10.number().optional()
+});
+var HttpSearchRequestSchema = z10.object({
+  searchId: z10.string(),
+  mapName: z10.string(),
+  query: z10.string(),
+  options: z10.any().optional()
+});
+var HttpSyncRequestSchema = z10.object({
+  // Client identification
+  clientId: z10.string(),
+  // Client's current HLC for causality tracking
+  clientHlc: TimestampSchema,
+  // Batch of operations to push (optional)
+  operations: z10.array(ClientOpSchema).optional(),
+  // Maps the client wants deltas for, with their last known sync HLC timestamp
+  syncMaps: z10.array(SyncMapEntrySchema).optional(),
+  // One-shot queries to execute (optional)
+  queries: z10.array(HttpQueryRequestSchema).optional(),
+  // One-shot search requests (optional)
+  searches: z10.array(HttpSearchRequestSchema).optional()
+});
+var DeltaRecordSchema = z10.object({
+  key: z10.string(),
+  record: LWWRecordSchema,
+  eventType: z10.enum(["PUT", "REMOVE"])
+});
+var MapDeltaSchema = z10.object({
+  mapName: z10.string(),
+  records: z10.array(DeltaRecordSchema),
+  serverSyncTimestamp: TimestampSchema
+});
+var HttpQueryResultSchema = z10.object({
+  queryId: z10.string(),
+  results: z10.array(z10.any()),
+  hasMore: z10.boolean().optional(),
+  nextCursor: z10.string().optional()
+});
+var HttpSearchResultSchema = z10.object({
+  searchId: z10.string(),
+  results: z10.array(z10.any()),
+  totalCount: z10.number().optional()
+});
+var HttpSyncErrorSchema = z10.object({
+  code: z10.number(),
+  message: z10.string(),
+  context: z10.string().optional()
+});
+var HttpSyncResponseSchema = z10.object({
+  // Server's current HLC
+  serverHlc: TimestampSchema,
+  // Acknowledgment of received operations
+  ack: z10.object({
+    lastId: z10.string(),
+    results: z10.array(OpResultSchema).optional()
+  }).optional(),
+  // Delta records for requested maps (new/changed since lastSyncTimestamp)
+  deltas: z10.array(MapDeltaSchema).optional(),
+  // Query results
+  queryResults: z10.array(HttpQueryResultSchema).optional(),
+  // Search results
+  searchResults: z10.array(HttpSearchResultSchema).optional(),
+  // Errors for individual operations
+  errors: z10.array(HttpSyncErrorSchema).optional()
+});
+
+// src/schemas/index.ts
+import { z as z11 } from "zod";
+var MessageSchema = z11.discriminatedUnion("type", [
   AuthMessageSchema,
   QuerySubMessageSchema,
   QueryUnsubMessageSchema,
@@ -3901,6 +3986,18 @@ function createPredicateMatcher(getAttribute) {
 }
 
 // src/query/QueryTypes.ts
+var COST_WEIGHTS = {
+  CPU: 1,
+  NETWORK: 10,
+  // Network is expensive (latency, bandwidth)
+  IO: 5,
+  // Disk I/O is moderately expensive
+  ROWS: 1e-3
+  // Row count factor
+};
+function calculateTotalCost(cost) {
+  return cost.rows * COST_WEIGHTS.ROWS + cost.cpu * COST_WEIGHTS.CPU + cost.network * COST_WEIGHTS.NETWORK + cost.io * COST_WEIGHTS.IO;
+}
 function isSimpleQuery(query) {
   return [
     "eq",
@@ -6222,13 +6319,22 @@ var QueryOptimizer = class {
    * Optimize a query and return an execution plan.
    *
    * Optimization order (by cost):
-   * 1. StandingQueryIndex (cost: 10) - pre-computed results
-   * 2. Other indexes via optimizeNode
+   * 1. Point lookup (cost: 1) - direct primary key access
+   * 2. StandingQueryIndex (cost: 10) - pre-computed results
+   * 3. Other indexes via optimizeNode
    *
    * @param query - Query to optimize
    * @returns Query execution plan
    */
   optimize(query) {
+    const pointLookupStep = this.tryPointLookup(query);
+    if (pointLookupStep) {
+      return {
+        root: pointLookupStep,
+        estimatedCost: this.estimateCost(pointLookupStep),
+        usesIndexes: this.usesIndexes(pointLookupStep)
+      };
+    }
     if (this.standingQueryRegistry) {
       const standingIndex = this.standingQueryRegistry.getIndex(query);
       if (standingIndex) {
@@ -6252,16 +6358,68 @@ var QueryOptimizer = class {
     };
   }
   /**
-   * Optimize a query with sort/limit/offset options.
+   * Optimize a query with sort/limit/offset options and index hints.
+   *
+   * Hint precedence: disableOptimization > useIndex > forceIndexScan.
    *
    * @param query - Query to optimize
-   * @param options - Query options (sort, limit, offset)
+   * @param options - Query options (sort, limit, cursor, hints)
    * @returns Query execution plan with options
    */
   optimizeWithOptions(query, options) {
+    if (options.disableOptimization) {
+      return {
+        root: { type: "full-scan", predicate: query },
+        estimatedCost: Number.MAX_SAFE_INTEGER,
+        usesIndexes: false
+      };
+    }
+    if (options.useIndex) {
+      const indexes = this.indexRegistry.getIndexes(options.useIndex);
+      if (indexes.length === 0) {
+        throw new Error(
+          `Index hint: no index found for attribute "${options.useIndex}"`
+        );
+      }
+      let best = indexes[0];
+      for (let i = 1; i < indexes.length; i++) {
+        if (indexes[i].getRetrievalCost() < best.getRetrievalCost()) {
+          best = indexes[i];
+        }
+      }
+      const step = {
+        type: "index-scan",
+        index: best,
+        query: this.buildHintedIndexQuery(query, options.useIndex)
+      };
+      return this.applyPlanOptions(
+        {
+          root: step,
+          estimatedCost: best.getRetrievalCost(),
+          usesIndexes: true,
+          hint: options.useIndex
+        },
+        options
+      );
+    }
     const basePlan = this.optimize(query);
+    if (options.forceIndexScan && !basePlan.usesIndexes) {
+      throw new Error(
+        "No suitable index found and forceIndexScan is enabled"
+      );
+    }
+    return this.applyPlanOptions(basePlan, options);
+  }
+  /**
+   * Apply sort/limit/cursor options to a query plan.
+   *
+   * @param plan - Base query plan
+   * @param options - Query options with sort/limit/cursor
+   * @returns Plan with options applied
+   */
+  applyPlanOptions(plan, options) {
     if (!options.sort && options.limit === void 0 && options.cursor === void 0) {
-      return basePlan;
+      return plan;
     }
     let indexedSort = false;
     let sortField;
@@ -6278,14 +6436,73 @@ var QueryOptimizer = class {
       }
     }
     return {
-      ...basePlan,
+      ...plan,
       indexedSort,
       sort: sortField && sortDirection ? { field: sortField, direction: sortDirection } : void 0,
       limit: options.limit,
       cursor: options.cursor
-      // replaces offset
     };
   }
+  /**
+   * Extract the relevant index query for a hinted attribute from the query tree.
+   * If the query directly references the attribute, build an index query from it.
+   * For compound (logical) queries, extract the matching child predicate.
+   * Falls back to { type: 'has' } when no matching predicate is found,
+   * retrieving all entries from the index for post-filtering.
+   * FTS query nodes also fall back to { type: 'has' } since full-text search
+   * queries are not compatible with regular index lookups.
+   *
+   * @param query - Original query tree
+   * @param attributeName - Hinted attribute name
+   * @returns Index query for the hinted attribute
+   */
+  buildHintedIndexQuery(query, attributeName) {
+    if (isSimpleQuery(query) && query.attribute === attributeName) {
+      return this.buildIndexQuery(query);
+    }
+    if (isFTSQuery(query)) {
+      return { type: "has" };
+    }
+    if (isLogicalQuery(query) && query.children) {
+      for (const child of query.children) {
+        if (isSimpleQuery(child) && child.attribute === attributeName) {
+          return this.buildIndexQuery(child);
+        }
+      }
+    }
+    return { type: "has" };
+  }
+  /**
+   * Try to optimize query as a point lookup.
+   * Returns a point lookup step if query is an equality or IN query on primary key.
+   *
+   * @param query - Query to check
+   * @returns Point lookup step or null
+   */
+  tryPointLookup(query) {
+    if (!isSimpleQuery(query)) {
+      return null;
+    }
+    const primaryKeyFields = ["_key", "key", "id"];
+    if (!primaryKeyFields.includes(query.attribute)) {
+      return null;
+    }
+    if (query.type === "eq") {
+      return {
+        type: "point-lookup",
+        key: query.value,
+        cost: 1
+      };
+    }
+    if (query.type === "in" && query.values) {
+      return {
+        type: "multi-point-lookup",
+        keys: query.values,
+        cost: query.values.length
+      };
+    }
+    return null;
+  }
   /**
    * Optimize a single query node.
    */
@@ -6674,6 +6891,9 @@ var QueryOptimizer = class {
    */
   estimateCost(step) {
     switch (step.type) {
+      case "point-lookup":
+      case "multi-point-lookup":
+        return step.cost;
       case "index-scan":
         return step.index.getRetrievalCost();
       case "full-scan":
@@ -6708,11 +6928,89 @@ var QueryOptimizer = class {
         return Number.MAX_SAFE_INTEGER;
     }
   }
+  /**
+   * Estimate distributed cost including network overhead.
+   *
+   * Network cost is assigned based on step type:
+   * - full-scan: broadcast to all nodes (highest cost)
+   * - index-scan: 0 if local partition, 5 if remote
+   * - point-lookup: 0 if local key, 5 if remote
+   * - intersection/union: aggregating results from multiple sources
+   *
+   * @param step - Plan step to estimate
+   * @param context - Distributed query context (optional)
+   * @returns Distributed cost breakdown
+   */
+  estimateDistributedCost(step, context) {
+    const baseCost = this.estimateCost(step);
+    if (!context?.isDistributed || context.nodeCount <= 1) {
+      return {
+        rows: baseCost,
+        cpu: baseCost,
+        network: 0,
+        io: 0
+      };
+    }
+    let networkCost = 0;
+    switch (step.type) {
+      case "full-scan":
+        networkCost = context.nodeCount * 10;
+        break;
+      case "index-scan":
+        networkCost = 5;
+        break;
+      case "point-lookup":
+        networkCost = 5;
+        break;
+      case "multi-point-lookup":
+        networkCost = Math.min(step.keys.length, context.nodeCount) * 5;
+        break;
+      case "intersection":
+      case "union":
+        networkCost = step.steps.length * 5;
+        break;
+      case "filter":
+        return this.estimateDistributedCost(step.source, context);
+      case "not":
+        networkCost = context.nodeCount * 5;
+        break;
+      case "fts-scan":
+        networkCost = Math.ceil(context.nodeCount / 2) * 5;
+        break;
+      case "fusion":
+        networkCost = step.steps.reduce(
+          (sum, s) => sum + this.estimateDistributedCost(s, context).network,
+          0
+        );
+        break;
+    }
+    return {
+      rows: baseCost,
+      cpu: baseCost,
+      network: networkCost,
+      io: context.usesStorage ? baseCost * 0.5 : 0
+    };
+  }
+  /**
+   * Get total distributed cost for a plan step.
+   * Convenience method combining estimateDistributedCost and calculateTotalCost.
+   *
+   * @param step - Plan step to estimate
+   * @param context - Distributed query context (optional)
+   * @returns Weighted total cost
+   */
+  getTotalDistributedCost(step, context) {
+    const distributedCost = this.estimateDistributedCost(step, context);
+    return calculateTotalCost(distributedCost);
+  }
   /**
    * Check if a plan step uses any indexes.
    */
   usesIndexes(step) {
     switch (step.type) {
+      case "point-lookup":
+      case "multi-point-lookup":
+        return true;
       case "index-scan":
         return true;
       case "full-scan":
@@ -8893,6 +9191,24 @@ var IndexedLWWMap = class extends LWWMap {
    */
   executePlan(step) {
     switch (step.type) {
+      case "point-lookup": {
+        const key = step.key;
+        const result = /* @__PURE__ */ new Set();
+        if (this.get(key) !== void 0) {
+          result.add(key);
+        }
+        return new SetResultSet(result, 1);
+      }
+      case "multi-point-lookup": {
+        const result = /* @__PURE__ */ new Set();
+        for (const key of step.keys) {
+          const k = key;
+          if (this.get(k) !== void 0) {
+            result.add(k);
+          }
+        }
+        return new SetResultSet(result, step.keys.length);
+      }
       case "index-scan":
         return step.index.retrieve(step.query);
       case "full-scan": {
@@ -11951,6 +12267,504 @@ function getSearchDebugger() {
 function resetSearchDebugger() {
   globalSearchDebugger = null;
 }
+
+// src/testing/VirtualClock.ts
+var RealClock = {
+  now: () => Date.now()
+};
+var VirtualClock = class {
+  /**
+   * @param initialTime Starting timestamp in milliseconds (default: 0)
+   */
+  constructor(initialTime = 0) {
+    if (!Number.isFinite(initialTime) || initialTime < 0) {
+      throw new Error("Initial time must be a non-negative finite number");
+    }
+    this.currentTime = initialTime;
+  }
+  /**
+   * Returns the current virtual time.
+   * Time remains frozen until advance() or set() is called.
+   */
+  now() {
+    return this.currentTime;
+  }
+  /**
+   * Advances time forward by the specified milliseconds.
+   * @param ms Milliseconds to advance (must be non-negative)
+   */
+  advance(ms) {
+    if (!Number.isFinite(ms) || ms < 0) {
+      throw new Error("Advance amount must be a non-negative finite number");
+    }
+    this.currentTime += ms;
+  }
+  /**
+   * Sets the clock to a specific time.
+   * Allows moving time forward or backward (useful for testing).
+   * @param time Absolute timestamp in milliseconds
+   */
+  set(time) {
+    if (!Number.isFinite(time) || time < 0) {
+      throw new Error("Time must be a non-negative finite number");
+    }
+    this.currentTime = time;
+  }
+  /**
+   * Resets the clock to zero.
+   */
+  reset() {
+    this.currentTime = 0;
+  }
+};
+
+// src/testing/SeededRNG.ts
+var SeededRNG = class {
+  /**
+   * @param seed Integer seed value. Same seed = same sequence.
+   */
+  constructor(seed) {
+    if (!Number.isInteger(seed)) {
+      throw new Error("Seed must be an integer");
+    }
+    this.state = seed >>> 0;
+    this.originalSeed = this.state;
+  }
+  /**
+   * Returns the original seed used to construct this RNG.
+   */
+  getSeed() {
+    return this.originalSeed;
+  }
+  /**
+   * Generates the next random number in [0, 1).
+   * Uses mulberry32 algorithm for deterministic, high-quality randomness.
+   */
+  random() {
+    let t = this.state += 1831565813;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    this.state = t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  }
+  /**
+   * Generates a random integer in [min, max] (inclusive).
+   * @param min Minimum value (inclusive)
+   * @param max Maximum value (inclusive)
+   */
+  randomInt(min, max) {
+    if (!Number.isInteger(min) || !Number.isInteger(max)) {
+      throw new Error("Min and max must be integers");
+    }
+    if (min > max) {
+      throw new Error("Min must be less than or equal to max");
+    }
+    const range = max - min + 1;
+    return Math.floor(this.random() * range) + min;
+  }
+  /**
+   * Generates a random boolean value.
+   * @param probability Probability of returning true (default: 0.5)
+   */
+  randomBool(probability = 0.5) {
+    if (probability < 0 || probability > 1) {
+      throw new Error("Probability must be between 0 and 1");
+    }
+    return this.random() < probability;
+  }
+  /**
+   * Shuffles an array in place using Fisher-Yates algorithm.
+   * Returns the shuffled array.
+   * @param array Array to shuffle
+   */
+  shuffle(array) {
+    for (let i = array.length - 1; i > 0; i--) {
+      const j = this.randomInt(0, i);
+      [array[i], array[j]] = [array[j], array[i]];
+    }
+    return array;
+  }
+  /**
+   * Picks a random element from an array.
+   * @param array Array to pick from
+   * @returns Random element, or undefined if array is empty
+   */
+  pick(array) {
+    if (array.length === 0) return void 0;
+    return array[this.randomInt(0, array.length - 1)];
+  }
+  /**
+   * Resets the RNG to its original seed.
+   * Useful for reproducing a sequence from the start.
+   */
+  reset() {
+    this.state = this.originalSeed;
+  }
+};
+
+// src/testing/VirtualNetwork.ts
+var VirtualNetwork = class {
+  constructor(rng, clock) {
+    this.pendingMessages = [];
+    this.rng = rng;
+    this.clock = clock;
+    this.config = {
+      latencyMs: { min: 0, max: 0 },
+      packetLossRate: 0,
+      partitions: []
+    };
+  }
+  /**
+   * Updates network configuration.
+   * Partially updates existing config with provided values.
+   */
+  configure(config) {
+    if (config.latencyMs !== void 0) {
+      const { min, max } = config.latencyMs;
+      if (min < 0 || max < 0 || min > max) {
+        throw new Error("Invalid latency range");
+      }
+      this.config.latencyMs = config.latencyMs;
+    }
+    if (config.packetLossRate !== void 0) {
+      if (config.packetLossRate < 0 || config.packetLossRate > 1) {
+        throw new Error("Packet loss rate must be between 0 and 1");
+      }
+      this.config.packetLossRate = config.packetLossRate;
+    }
+    if (config.partitions !== void 0) {
+      this.config.partitions = config.partitions;
+    }
+  }
+  /**
+   * Sends a message through the network.
+   * Subject to packet loss, latency, and partition rules.
+   */
+  send(from, to, payload) {
+    if (this.rng.random() < this.config.packetLossRate) {
+      return;
+    }
+    if (this.isPartitioned(from, to)) {
+      return;
+    }
+    const latency = this.rng.randomInt(
+      this.config.latencyMs.min,
+      this.config.latencyMs.max
+    );
+    const scheduledTime = this.clock.now() + latency;
+    this.pendingMessages.push({
+      from,
+      to,
+      payload,
+      scheduledTime
+    });
+  }
+  /**
+   * Creates a network partition between two groups.
+   * Nodes in groupA cannot communicate with nodes in groupB.
+   */
+  partition(groupA, groupB) {
+    this.config.partitions.push(groupA, groupB);
+  }
+  /**
+   * Removes all network partitions.
+   */
+  heal() {
+    this.config.partitions = [];
+  }
+  /**
+   * Delivers all messages scheduled at or before the current time.
+   * @returns Array of delivered messages
+   */
+  tick() {
+    const currentTime = this.clock.now();
+    const delivered = [];
+    const remaining = [];
+    for (const msg of this.pendingMessages) {
+      if (msg.scheduledTime <= currentTime) {
+        delivered.push(msg);
+      } else {
+        remaining.push(msg);
+      }
+    }
+    this.pendingMessages = remaining;
+    return delivered;
+  }
+  /**
+   * Returns the number of messages currently in flight.
+   */
+  getPendingCount() {
+    return this.pendingMessages.length;
+  }
+  /**
+   * Clears all pending messages.
+   */
+  clear() {
+    this.pendingMessages = [];
+  }
+  /**
+   * Checks if two nodes are partitioned from each other.
+   */
+  isPartitioned(from, to) {
+    for (let i = 0; i < this.config.partitions.length; i += 2) {
+      const groupA = this.config.partitions[i];
+      const groupB = this.config.partitions[i + 1];
+      if (groupA.includes(from) && groupB.includes(to) || groupB.includes(from) && groupA.includes(to)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Returns all pending messages (useful for debugging).
+   */
+  getPendingMessages() {
+    return [...this.pendingMessages];
+  }
+};
+
+// src/testing/InvariantChecker.ts
+var InvariantChecker = class {
+  constructor() {
+    this.invariants = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Adds an invariant to be checked.
+   * @param name Unique name for this invariant
+   * @param check Function that returns true if invariant holds
+   */
+  addInvariant(name, check) {
+    if (this.invariants.has(name)) {
+      throw new Error(`Invariant '${name}' already exists`);
+    }
+    this.invariants.set(name, check);
+  }
+  /**
+   * Removes an invariant by name.
+   */
+  removeInvariant(name) {
+    return this.invariants.delete(name);
+  }
+  /**
+   * Verifies all invariants against the provided state.
+   * @returns Result with pass/fail status and list of failed invariants
+   */
+  verify(state) {
+    const failures = [];
+    for (const [name, check] of this.invariants.entries()) {
+      try {
+        if (!check(state)) {
+          failures.push(name);
+        }
+      } catch (error) {
+        failures.push(`${name} (exception: ${error instanceof Error ? error.message : String(error)})`);
+      }
+    }
+    return {
+      passed: failures.length === 0,
+      failures
+    };
+  }
+  /**
+   * Returns the number of registered invariants.
+   */
+  get count() {
+    return this.invariants.size;
+  }
+  /**
+   * Clears all invariants.
+   */
+  clear() {
+    this.invariants.clear();
+  }
+};
+var CRDTInvariants = {
+  /**
+   * Verifies LWW-Map convergence: all maps contain the same values for same keys.
+   */
+  lwwConvergence: (maps) => {
+    if (maps.length < 2) return true;
+    const reference = maps[0];
+    const refKeys = new Set(reference.allKeys());
+    for (let i = 1; i < maps.length; i++) {
+      const other = maps[i];
+      const otherKeys = new Set(other.allKeys());
+      if (refKeys.size !== otherKeys.size) return false;
+      for (const key of refKeys) {
+        if (!otherKeys.has(key)) return false;
+      }
+      for (const key of refKeys) {
+        const refRecord = reference.getRecord(key);
+        const otherRecord = other.getRecord(key);
+        if (!refRecord || !otherRecord) {
+          if (refRecord !== otherRecord) return false;
+          continue;
+        }
+        if (refRecord.value !== otherRecord.value) return false;
+        if (HLC.compare(refRecord.timestamp, otherRecord.timestamp) !== 0) {
+          return false;
+        }
+      }
+    }
+    return true;
+  },
+  /**
+   * Verifies OR-Map convergence: all maps contain the same values for same keys.
+   */
+  orMapConvergence: (maps) => {
+    if (maps.length < 2) return true;
+    const reference = maps[0];
+    const refKeys = reference.allKeys();
+    for (let i = 1; i < maps.length; i++) {
+      const other = maps[i];
+      const otherKeys = new Set(other.allKeys());
+      if (refKeys.length !== otherKeys.size) return false;
+      for (const key of refKeys) {
+        if (!otherKeys.has(key)) return false;
+      }
+      for (const key of refKeys) {
+        const refRecords = reference.getRecords(key);
+        const otherRecords = other.getRecords(key);
+        if (refRecords.length !== otherRecords.length) return false;
+        const refSorted = [...refRecords].sort((a, b) => a.tag.localeCompare(b.tag));
+        const otherSorted = [...otherRecords].sort((a, b) => a.tag.localeCompare(b.tag));
+        for (let j = 0; j < refSorted.length; j++) {
+          if (refSorted[j].tag !== otherSorted[j].tag) return false;
+          if (refSorted[j].value !== otherSorted[j].value) return false;
+          if (HLC.compare(refSorted[j].timestamp, otherSorted[j].timestamp) !== 0) {
+            return false;
+          }
+        }
+      }
+      const refTombstones = new Set(reference.getTombstones());
+      const otherTombstones = new Set(other.getTombstones());
+      if (refTombstones.size !== otherTombstones.size) return false;
+      for (const tag of refTombstones) {
+        if (!otherTombstones.has(tag)) return false;
+      }
+    }
+    return true;
+  },
+  /**
+   * Verifies HLC monotonicity: timestamps are strictly increasing.
+   */
+  hlcMonotonicity: (timestamps) => {
+    for (let i = 1; i < timestamps.length; i++) {
+      if (HLC.compare(timestamps[i - 1], timestamps[i]) >= 0) {
+        return false;
+      }
+    }
+    return true;
+  },
+  /**
+   * Verifies Merkle tree consistency: trees with same data have same root hash.
+   */
+  merkleConsistency: (trees) => {
+    if (trees.length < 2) return true;
+    const referenceHash = trees[0].getRootHash();
+    for (let i = 1; i < trees.length; i++) {
+      if (trees[i].getRootHash() !== referenceHash) {
+        return false;
+      }
+    }
+    return true;
+  }
+};
+
+// src/testing/ScenarioRunner.ts
+var ScenarioRunner = class {
+  constructor(config) {
+    if (!config.nodes || config.nodes.length === 0) {
+      throw new Error("Scenario must have at least one node");
+    }
+    if (config.duration <= 0) {
+      throw new Error("Duration must be positive");
+    }
+    this.seed = config.seed ?? Math.floor(Math.random() * 2147483647);
+    this.config = {
+      ...config,
+      seed: this.seed,
+      tickInterval: config.tickInterval ?? 1
+    };
+    this.clock = new VirtualClock(0);
+    this.rng = new SeededRNG(this.seed);
+    this.network = new VirtualNetwork(this.rng, this.clock);
+  }
+  /**
+   * Returns the seed used for this scenario.
+   */
+  getSeed() {
+    return this.seed;
+  }
+  /**
+   * Returns the virtual clock instance.
+   */
+  getClock() {
+    return this.clock;
+  }
+  /**
+   * Returns the seeded RNG instance.
+   */
+  getRNG() {
+    return this.rng;
+  }
+  /**
+   * Returns the virtual network instance.
+   */
+  getNetwork() {
+    return this.network;
+  }
+  /**
+   * Returns the list of nodes in this scenario.
+   */
+  getNodes() {
+    return [...this.config.nodes];
+  }
+  /**
+   * Executes the simulation scenario.
+   *
+   * @param setup Called once before simulation starts. Initialize state here.
+   * @param step Called on each tick. Perform operations and message delivery.
+   * @param invariants Checker for verifying correctness throughout execution.
+   * @returns Result with pass/fail status and captured state
+   */
+  run(setup, step, invariants) {
+    const finalStates = /* @__PURE__ */ new Map();
+    const invariantFailures = [];
+    setup(this);
+    let tickCount = 0;
+    const tickInterval = this.config.tickInterval;
+    const endTime = this.config.duration;
+    while (this.clock.now() < endTime) {
+      this.clock.advance(tickInterval);
+      tickCount++;
+      step(this, tickCount);
+      const delivered = this.network.tick();
+      if (delivered.length > 0) {
+        finalStates.set(`_tick_${tickCount}_delivered`, delivered.length);
+      }
+    }
+    const result = invariants.verify(null);
+    if (!result.passed) {
+      invariantFailures.push(...result.failures);
+    }
+    return {
+      seed: this.seed,
+      passed: invariantFailures.length === 0,
+      ticks: tickCount,
+      invariantFailures,
+      finalStates
+    };
+  }
+  /**
+   * Stores state for a node (useful for capturing final state).
+   */
+  setState(nodeId, state) {
+    if (!this.config.nodes.includes(nodeId)) {
+      throw new Error(`Unknown node: ${nodeId}`);
+    }
+  }
+};
 export {
   AuthFailMessageSchema,
   AuthMessageSchema,
@@ -11958,7 +12772,9 @@ export {
   BatchMessageSchema,
   BuiltInProcessors,
   BuiltInResolvers,
+  COST_WEIGHTS,
   CRDTDebugger,
+  CRDTInvariants,
   ClientOpMessageSchema,
   ClientOpSchema,
   ClusterSearchReqMessageSchema,
@@ -12000,6 +12816,7 @@ export {
   DEFAULT_RESOLVER_RATE_LIMITS,
   DEFAULT_STOP_WORDS,
   DEFAULT_WRITE_CONCERN_TIMEOUT,
+  DeltaRecordSchema,
   ENGLISH_STOPWORDS,
   EntryProcessBatchRequestSchema,
   EntryProcessBatchResponseSchema,
@@ -12019,12 +12836,20 @@ export {
   GcPrunePayloadSchema,
   HLC,
   HashIndex,
+  HttpQueryRequestSchema,
+  HttpQueryResultSchema,
+  HttpSearchRequestSchema,
+  HttpSearchResultSchema,
+  HttpSyncErrorSchema,
+  HttpSyncRequestSchema,
+  HttpSyncResponseSchema,
   HybridQueryDeltaPayloadSchema,
   HybridQueryRespPayloadSchema,
   IndexRegistry,
   IndexedLWWMap,
   IndexedORMap,
   IntersectionResultSet,
+  InvariantChecker,
   InvertedIndex,
   JournalEventDataSchema,
   JournalEventMessageSchema,
@@ -12045,6 +12870,7 @@ export {
   LockReleasedPayloadSchema,
   LockRequestSchema,
   LowercaseFilter,
+  MapDeltaSchema,
   MaxLengthFilter,
   MergeRejectedMessageSchema,
   MerkleReqBucketMessageSchema,
@@ -12089,10 +12915,12 @@ export {
   QueryUpdateMessageSchema,
   QueryUpdatePayloadSchema,
   RESOLVER_FORBIDDEN_PATTERNS,
+  RealClock,
   ReciprocalRankFusion,
   RegisterResolverRequestSchema,
   RegisterResolverResponseSchema,
   Ringbuffer,
+  ScenarioRunner,
   SearchCursor,
   SearchDebugger,
   SearchMessageSchema,
@@ -12107,6 +12935,7 @@ export {
   SearchUpdateMessageSchema,
   SearchUpdatePayloadSchema,
   SearchUpdateTypeSchema,
+  SeededRNG,
   ServerBatchEventMessageSchema,
   ServerEventMessageSchema,
   ServerEventPayloadSchema,
@@ -12118,6 +12947,7 @@ export {
   StandingQueryRegistry,
   StopWordFilter,
   SyncInitMessageSchema,
+  SyncMapEntrySchema,
   SyncResetRequiredPayloadSchema,
   SyncRespBucketsMessageSchema,
   SyncRespLeafMessageSchema,
@@ -12133,11 +12963,14 @@ export {
   UniqueFilter,
   UnregisterResolverRequestSchema,
   UnregisterResolverResponseSchema,
+  VirtualClock,
+  VirtualNetwork,
   WRITE_CONCERN_ORDER,
   WhitespaceTokenizer,
   WordBoundaryTokenizer,
   WriteConcern,
   WriteConcernSchema,
+  calculateTotalCost,
   combineHashes,
   compareHLCTimestamps,
   compareTimestamps,