@topgunbuild/core 0.1.0 → 0.2.0-alpha

package/dist/index.js

@@ -32,8 +32,19 @@ __export(index_exports, {
   MerkleTree: () => MerkleTree,
   MessageSchema: () => MessageSchema,
   ORMap: () => ORMap,
+  ORMapDiffRequestSchema: () => ORMapDiffRequestSchema,
+  ORMapDiffResponseSchema: () => ORMapDiffResponseSchema,
+  ORMapMerkleReqBucketSchema: () => ORMapMerkleReqBucketSchema,
+  ORMapMerkleTree: () => ORMapMerkleTree,
+  ORMapPushDiffSchema: () => ORMapPushDiffSchema,
   ORMapRecordSchema: () => ORMapRecordSchema,
+  ORMapSyncInitSchema: () => ORMapSyncInitSchema,
+  ORMapSyncRespBucketsSchema: () => ORMapSyncRespBucketsSchema,
+  ORMapSyncRespLeafSchema: () => ORMapSyncRespLeafSchema,
+  ORMapSyncRespRootSchema: () => ORMapSyncRespRootSchema,
   OpBatchMessageSchema: () => OpBatchMessageSchema,
+  PingMessageSchema: () => PingMessageSchema,
+  PongMessageSchema: () => PongMessageSchema,
   PredicateNodeSchema: () => PredicateNodeSchema,
   PredicateOpSchema: () => PredicateOpSchema,
   Predicates: () => Predicates,
@@ -50,10 +61,14 @@ __export(index_exports, {
   TopicSubSchema: () => TopicSubSchema,
   TopicUnsubSchema: () => TopicUnsubSchema,
   combineHashes: () => combineHashes,
+  compareTimestamps: () => compareTimestamps,
   deserialize: () => deserialize,
   evaluatePredicate: () => evaluatePredicate,
+  hashORMapEntry: () => hashORMapEntry,
+  hashORMapRecord: () => hashORMapRecord,
   hashString: () => hashString,
-  serialize: () => serialize
+  serialize: () => serialize,
+  timestampToString: () => timestampToString
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -433,6 +448,225 @@ var LWWMap = class {
   }
 };
 
+// src/ORMapMerkle.ts
+function timestampToString(ts) {
+  return `${ts.millis}:${ts.counter}:${ts.nodeId}`;
+}
+function stringifyValue(value) {
+  if (value === null || value === void 0) {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value, Object.keys(value).sort());
+  }
+  return String(value);
+}
+function hashORMapEntry(key, records) {
+  const sortedTags = Array.from(records.keys()).sort();
+  const parts = [`key:${key}`];
+  for (const tag of sortedTags) {
+    const record = records.get(tag);
+    const valuePart = stringifyValue(record.value);
+    let recordStr = `${tag}:${valuePart}:${timestampToString(record.timestamp)}`;
+    if (record.ttlMs !== void 0) {
+      recordStr += `:ttl=${record.ttlMs}`;
+    }
+    parts.push(recordStr);
+  }
+  return hashString(parts.join("|"));
+}
+function hashORMapRecord(record) {
+  const valuePart = stringifyValue(record.value);
+  let str = `${record.tag}:${valuePart}:${timestampToString(record.timestamp)}`;
+  if (record.ttlMs !== void 0) {
+    str += `:ttl=${record.ttlMs}`;
+  }
+  return hashString(str);
+}
+function compareTimestamps(a, b) {
+  if (a.millis !== b.millis) {
+    return a.millis - b.millis;
+  }
+  if (a.counter !== b.counter) {
+    return a.counter - b.counter;
+  }
+  return a.nodeId.localeCompare(b.nodeId);
+}
+
+// src/ORMapMerkleTree.ts
+var ORMapMerkleTree = class {
+  constructor(depth = 3) {
+    this.depth = depth;
+    this.root = { hash: 0, children: {} };
+  }
+  /**
+   * Update tree from ORMap data.
+   * Rebuilds hashes for all entries in the map.
+   */
+  updateFromORMap(map) {
+    this.root = { hash: 0, children: {} };
+    const snapshot = map.getSnapshot();
+    for (const [key, records] of snapshot.items) {
+      if (records.size > 0) {
+        const keyStr = String(key);
+        const entryHash = hashORMapEntry(keyStr, records);
+        const pathHash = hashString(keyStr).toString(16).padStart(8, "0");
+        this.updateNode(this.root, keyStr, entryHash, pathHash, 0);
+      }
+    }
+  }
+  /**
+   * Incrementally update a single key's hash.
+   * Call this when records for a key change.
+   */
+  update(key, records) {
+    const pathHash = hashString(key).toString(16).padStart(8, "0");
+    if (records.size === 0) {
+      this.removeNode(this.root, key, pathHash, 0);
+    } else {
+      const entryHash = hashORMapEntry(key, records);
+      this.updateNode(this.root, key, entryHash, pathHash, 0);
+    }
+  }
+  /**
+   * Remove a key from the tree.
+   * Called when all records for a key are removed.
+   */
+  remove(key) {
+    const pathHash = hashString(key).toString(16).padStart(8, "0");
+    this.removeNode(this.root, key, pathHash, 0);
+  }
+  updateNode(node, key, entryHash, pathHash, level) {
+    if (level >= this.depth) {
+      if (!node.entries) node.entries = /* @__PURE__ */ new Map();
+      node.entries.set(key, entryHash);
+      let h2 = 0;
+      for (const val of node.entries.values()) {
+        h2 = h2 + val | 0;
+      }
+      node.hash = h2 >>> 0;
+      return node.hash;
+    }
+    const bucketChar = pathHash[level];
+    if (!node.children) node.children = {};
+    if (!node.children[bucketChar]) {
+      node.children[bucketChar] = { hash: 0 };
+    }
+    this.updateNode(node.children[bucketChar], key, entryHash, pathHash, level + 1);
+    let h = 0;
+    for (const child of Object.values(node.children)) {
+      h = h + child.hash | 0;
+    }
+    node.hash = h >>> 0;
+    return node.hash;
+  }
+  removeNode(node, key, pathHash, level) {
+    if (level >= this.depth) {
+      if (node.entries) {
+        node.entries.delete(key);
+        let h2 = 0;
+        for (const val of node.entries.values()) {
+          h2 = h2 + val | 0;
+        }
+        node.hash = h2 >>> 0;
+      }
+      return node.hash;
+    }
+    const bucketChar = pathHash[level];
+    if (node.children && node.children[bucketChar]) {
+      this.removeNode(node.children[bucketChar], key, pathHash, level + 1);
+    }
+    let h = 0;
+    if (node.children) {
+      for (const child of Object.values(node.children)) {
+        h = h + child.hash | 0;
+      }
+    }
+    node.hash = h >>> 0;
+    return node.hash;
+  }
+  /**
+   * Get the root hash for quick comparison.
+   */
+  getRootHash() {
+    return this.root.hash;
+  }
+  /**
+   * Get node at a specific path.
+   */
+  getNode(path) {
+    let current = this.root;
+    for (const char of path) {
+      if (!current.children || !current.children[char]) {
+        return void 0;
+      }
+      current = current.children[char];
+    }
+    return current;
+  }
+  /**
+   * Returns the hashes of the children at the given path.
+   * Used by the client/server to compare buckets.
+   */
+  getBuckets(path) {
+    const node = this.getNode(path);
+    if (!node || !node.children) return {};
+    const result = {};
+    for (const [key, child] of Object.entries(node.children)) {
+      result[key] = child.hash;
+    }
+    return result;
+  }
+  /**
+   * For a leaf node (bucket), returns the actual keys it contains.
+   * Used to request specific keys when a bucket differs.
+   */
+  getKeysInBucket(path) {
+    const node = this.getNode(path);
+    if (!node || !node.entries) return [];
+    return Array.from(node.entries.keys());
+  }
+  /**
+   * Find keys that differ between this tree and bucket info from remote.
+   * Returns keys that:
+   * - Exist locally but have different hash on remote
+   * - Exist on remote but not locally
+   * - Exist locally but not on remote
+   */
+  findDiffKeys(path, remoteEntries) {
+    const diffKeys = /* @__PURE__ */ new Set();
+    const node = this.getNode(path);
+    const localEntries = node?.entries || /* @__PURE__ */ new Map();
+    for (const [key, hash] of localEntries) {
+      const remoteHash = remoteEntries.get(key);
+      if (remoteHash === void 0 || remoteHash !== hash) {
+        diffKeys.add(key);
+      }
+    }
+    for (const key of remoteEntries.keys()) {
+      if (!localEntries.has(key)) {
+        diffKeys.add(key);
+      }
+    }
+    return diffKeys;
+  }
+  /**
+   * Get all entry hashes at a leaf path.
+   * Used when sending bucket details to remote.
+   */
+  getEntryHashes(path) {
+    const node = this.getNode(path);
+    return node?.entries || /* @__PURE__ */ new Map();
+  }
+  /**
+   * Check if a path leads to a leaf node.
+   */
+  isLeaf(path) {
+    const node = this.getNode(path);
+    return node !== void 0 && node.entries !== void 0 && node.entries.size > 0;
+  }
+};
+
 // src/ORMap.ts
 var ORMap = class {
   constructor(hlc) {
@@ -440,6 +674,7 @@ var ORMap = class {
     this.hlc = hlc;
     this.items = /* @__PURE__ */ new Map();
     this.tombstones = /* @__PURE__ */ new Set();
+    this.merkleTree = new ORMapMerkleTree();
   }
   onChange(callback) {
     this.listeners.push(callback);
@@ -484,6 +719,7 @@ var ORMap = class {
       this.items.set(key, keyMap);
     }
     keyMap.set(tag, record);
+    this.updateMerkleTree(key);
     this.notify();
     return record;
   }
@@ -508,6 +744,7 @@ var ORMap = class {
     if (keyMap.size === 0) {
       this.items.delete(key);
     }
+    this.updateMerkleTree(key);
     this.notify();
     return tagsToRemove;
   }
@@ -517,6 +754,7 @@ var ORMap = class {
   clear() {
     this.items.clear();
     this.tombstones.clear();
+    this.merkleTree = new ORMapMerkleTree();
     this.notify();
   }
   /**
@@ -566,9 +804,10 @@ var ORMap = class {
   }
   /**
    * Applies a record from a remote source (Sync).
+   * Returns true if the record was applied (not tombstoned).
    */
   apply(key, record) {
-    if (this.tombstones.has(record.tag)) return;
+    if (this.tombstones.has(record.tag)) return false;
     let keyMap = this.items.get(key);
     if (!keyMap) {
       keyMap = /* @__PURE__ */ new Map();
@@ -576,7 +815,9 @@ var ORMap = class {
     }
     keyMap.set(record.tag, record);
     this.hlc.update(record.timestamp);
+    this.updateMerkleTree(key);
     this.notify();
+    return true;
   }
   /**
    * Applies a tombstone (deletion) from a remote source.
@@ -587,6 +828,7 @@ var ORMap = class {
       if (keyMap.has(tag)) {
         keyMap.delete(tag);
         if (keyMap.size === 0) this.items.delete(key);
+        this.updateMerkleTree(key);
         break;
       }
     }
@@ -599,6 +841,7 @@ var ORMap = class {
    * - Updates HLC with observed timestamps.
    */
   merge(other) {
+    const changedKeys = /* @__PURE__ */ new Set();
     for (const tag of other.tombstones) {
       this.tombstones.add(tag);
     }
@@ -612,6 +855,7 @@ var ORMap = class {
         if (!this.tombstones.has(tag)) {
           if (!localKeyMap.has(tag)) {
             localKeyMap.set(tag, record);
+            changedKeys.add(key);
           }
           this.hlc.update(record.timestamp);
         }
@@ -621,12 +865,16 @@ var ORMap = class {
       for (const tag of localKeyMap.keys()) {
         if (this.tombstones.has(tag)) {
           localKeyMap.delete(tag);
+          changedKeys.add(key);
         }
       }
       if (localKeyMap.size === 0) {
         this.items.delete(key);
       }
     }
+    for (const key of changedKeys) {
+      this.updateMerkleTree(key);
+    }
     this.notify();
   }
   /**
@@ -646,6 +894,108 @@ var ORMap = class {
     }
     return removedTags;
   }
+  // ============ Merkle Sync Methods ============
+  /**
+   * Get the Merkle Tree for this ORMap.
+   * Used for efficient synchronization.
+   */
+  getMerkleTree() {
+    return this.merkleTree;
+  }
+  /**
+   * Get a snapshot of internal state for Merkle Tree synchronization.
+   * Returns references to internal structures - do not modify!
+   */
+  getSnapshot() {
+    return {
+      items: this.items,
+      tombstones: this.tombstones
+    };
+  }
+  /**
+   * Get all keys in this ORMap.
+   */
+  allKeys() {
+    return Array.from(this.items.keys());
+  }
+  /**
+   * Get the internal records map for a key.
+   * Returns Map<tag, record> or undefined if key doesn't exist.
+   * Used for Merkle sync.
+   */
+  getRecordsMap(key) {
+    return this.items.get(key);
+  }
+  /**
+   * Merge remote records for a specific key into local state.
+   * Implements Observed-Remove CRDT semantics.
+   * Used during Merkle Tree synchronization.
+   *
+   * @param key The key to merge
+   * @param remoteRecords Array of records from remote
+   * @param remoteTombstones Array of tombstone tags from remote
+   * @returns Result with count of added and updated records
+   */
+  mergeKey(key, remoteRecords, remoteTombstones = []) {
+    let added = 0;
+    let updated = 0;
+    for (const tag of remoteTombstones) {
+      if (!this.tombstones.has(tag)) {
+        this.tombstones.add(tag);
+      }
+    }
+    let localKeyMap = this.items.get(key);
+    if (!localKeyMap) {
+      localKeyMap = /* @__PURE__ */ new Map();
+      this.items.set(key, localKeyMap);
+    }
+    for (const tag of localKeyMap.keys()) {
+      if (this.tombstones.has(tag)) {
+        localKeyMap.delete(tag);
+      }
+    }
+    for (const remoteRecord of remoteRecords) {
+      if (this.tombstones.has(remoteRecord.tag)) {
+        continue;
+      }
+      const localRecord = localKeyMap.get(remoteRecord.tag);
+      if (!localRecord) {
+        localKeyMap.set(remoteRecord.tag, remoteRecord);
+        added++;
+      } else if (compareTimestamps(remoteRecord.timestamp, localRecord.timestamp) > 0) {
+        localKeyMap.set(remoteRecord.tag, remoteRecord);
+        updated++;
+      }
+      this.hlc.update(remoteRecord.timestamp);
+    }
+    if (localKeyMap.size === 0) {
+      this.items.delete(key);
+    }
+    this.updateMerkleTree(key);
+    if (added > 0 || updated > 0) {
+      this.notify();
+    }
+    return { added, updated };
+  }
+  /**
+   * Check if a tag is tombstoned.
+   */
+  isTombstoned(tag) {
+    return this.tombstones.has(tag);
+  }
+  /**
+   * Update the Merkle Tree for a specific key.
+   * Called internally after any modification.
+   */
+  updateMerkleTree(key) {
+    const keyStr = String(key);
+    const keyMap = this.items.get(key);
+    if (!keyMap || keyMap.size === 0) {
+      this.merkleTree.remove(keyStr);
+    } else {
+      this.merkleTree.update(keyStr, keyMap);
+    }
+  }
 };
 
 // src/serializer.ts
@@ -909,6 +1259,91 @@ var TopicMessageEventSchema = import_zod.z.object({
     timestamp: import_zod.z.number()
   })
 });
+var PingMessageSchema = import_zod.z.object({
+  type: import_zod.z.literal("PING"),
+  timestamp: import_zod.z.number()
+  // Client's Date.now()
+});
+var PongMessageSchema = import_zod.z.object({
+  type: import_zod.z.literal("PONG"),
+  timestamp: import_zod.z.number(),
+  // Echo back client's timestamp
+  serverTime: import_zod.z.number()
+  // Server's Date.now() (for clock skew detection)
+});
+var ORMapSyncInitSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_SYNC_INIT"),
+  mapName: import_zod.z.string(),
+  rootHash: import_zod.z.number(),
+  bucketHashes: import_zod.z.record(import_zod.z.string(), import_zod.z.number()),
+  // path -> hash
+  lastSyncTimestamp: import_zod.z.number().optional()
+});
+var ORMapSyncRespRootSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_SYNC_RESP_ROOT"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    rootHash: import_zod.z.number(),
+    timestamp: TimestampSchema
+  })
+});
+var ORMapSyncRespBucketsSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_SYNC_RESP_BUCKETS"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    path: import_zod.z.string(),
+    buckets: import_zod.z.record(import_zod.z.string(), import_zod.z.number())
+  })
+});
+var ORMapMerkleReqBucketSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_MERKLE_REQ_BUCKET"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    path: import_zod.z.string()
+  })
+});
+var ORMapSyncRespLeafSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_SYNC_RESP_LEAF"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    path: import_zod.z.string(),
+    entries: import_zod.z.array(import_zod.z.object({
+      key: import_zod.z.string(),
+      records: import_zod.z.array(ORMapRecordSchema),
+      tombstones: import_zod.z.array(import_zod.z.string())
+      // Tombstone tags for this key's records
+    }))
+  })
+});
+var ORMapDiffRequestSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_DIFF_REQUEST"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    keys: import_zod.z.array(import_zod.z.string())
+  })
+});
+var ORMapDiffResponseSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_DIFF_RESPONSE"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    entries: import_zod.z.array(import_zod.z.object({
+      key: import_zod.z.string(),
+      records: import_zod.z.array(ORMapRecordSchema),
+      tombstones: import_zod.z.array(import_zod.z.string())
+    }))
+  })
+});
+var ORMapPushDiffSchema = import_zod.z.object({
+  type: import_zod.z.literal("ORMAP_PUSH_DIFF"),
+  payload: import_zod.z.object({
+    mapName: import_zod.z.string(),
+    entries: import_zod.z.array(import_zod.z.object({
+      key: import_zod.z.string(),
+      records: import_zod.z.array(ORMapRecordSchema),
+      tombstones: import_zod.z.array(import_zod.z.string())
+    }))
+  })
+});
 var MessageSchema = import_zod.z.discriminatedUnion("type", [
   AuthMessageSchema,
   QuerySubMessageSchema,
@@ -924,7 +1359,18 @@ var MessageSchema = import_zod.z.discriminatedUnion("type", [
   LockReleaseSchema,
   TopicSubSchema,
   TopicUnsubSchema,
-  TopicPubSchema
+  TopicPubSchema,
+  PingMessageSchema,
+  PongMessageSchema,
+  // ORMap Sync Messages
+  ORMapSyncInitSchema,
+  ORMapSyncRespRootSchema,
+  ORMapSyncRespBucketsSchema,
+  ORMapMerkleReqBucketSchema,
+  ORMapSyncRespLeafSchema,
+  ORMapDiffRequestSchema,
+  ORMapDiffResponseSchema,
+  ORMapPushDiffSchema
 ]);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -940,8 +1386,19 @@ var MessageSchema = import_zod.z.discriminatedUnion("type", [
   MerkleTree,
   MessageSchema,
   ORMap,
+  ORMapDiffRequestSchema,
+  ORMapDiffResponseSchema,
+  ORMapMerkleReqBucketSchema,
+  ORMapMerkleTree,
+  ORMapPushDiffSchema,
   ORMapRecordSchema,
+  ORMapSyncInitSchema,
+  ORMapSyncRespBucketsSchema,
+  ORMapSyncRespLeafSchema,
+  ORMapSyncRespRootSchema,
   OpBatchMessageSchema,
+  PingMessageSchema,
+  PongMessageSchema,
   PredicateNodeSchema,
   PredicateOpSchema,
   Predicates,
@@ -958,9 +1415,13 @@ var MessageSchema = import_zod.z.discriminatedUnion("type", [
   TopicSubSchema,
   TopicUnsubSchema,
   combineHashes,
+  compareTimestamps,
   deserialize,
   evaluatePredicate,
+  hashORMapEntry,
+  hashORMapRecord,
   hashString,
-  serialize
+  serialize,
+  timestampToString
 });
 //# sourceMappingURL=index.js.map