@topgunbuild/core 0.1.0 → 0.2.0-alpha

package/dist/index.d.mts

@@ -156,6 +156,86 @@ declare class LWWMap<K, V> {
     allKeys(): IterableIterator<K>;
 }
 
+/**
+ * Merkle Node for ORMap.
+ * Uses a prefix trie structure based on key hash (similar to LWWMap MerkleTree).
+ */
+interface ORMapMerkleNode {
+    hash: number;
+    children?: {
+        [key: string]: ORMapMerkleNode;
+    };
+    entries?: Map<string, number>;
+}
+/**
+ * A Merkle Tree implementation specifically for ORMap synchronization.
+ * Uses a Prefix Trie structure based on the hash of the Record Key.
+ *
+ * Structure:
+ * - Level 0: Root
+ * - Level 1..N: Buckets based on hex digits of Key Hash.
+ *
+ * Key difference from LWWMap MerkleTree:
+ * - Each key can have multiple records (tags), so the entry hash includes all records for that key.
+ */
+declare class ORMapMerkleTree {
+    private root;
+    private readonly depth;
+    constructor(depth?: number);
+    /**
+     * Update tree from ORMap data.
+     * Rebuilds hashes for all entries in the map.
+     */
+    updateFromORMap<K, V>(map: ORMap<K, V>): void;
+    /**
+     * Incrementally update a single key's hash.
+     * Call this when records for a key change.
+     */
+    update<V>(key: string, records: Map<string, ORMapRecord<V>>): void;
+    /**
+     * Remove a key from the tree.
+     * Called when all records for a key are removed.
+     */
+    remove(key: string): void;
+    private updateNode;
+    private removeNode;
+    /**
+     * Get the root hash for quick comparison.
+     */
+    getRootHash(): number;
+    /**
+     * Get node at a specific path.
+     */
+    getNode(path: string): ORMapMerkleNode | undefined;
+    /**
+     * Returns the hashes of the children at the given path.
+     * Used by the client/server to compare buckets.
+     */
+    getBuckets(path: string): Record<string, number>;
+    /**
+     * For a leaf node (bucket), returns the actual keys it contains.
+     * Used to request specific keys when a bucket differs.
+     */
+    getKeysInBucket(path: string): string[];
+    /**
+     * 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: string, remoteEntries: Map<string, number>): Set<string>;
+    /**
+     * Get all entry hashes at a leaf path.
+     * Used when sending bucket details to remote.
+     */
+    getEntryHashes(path: string): Map<string, number>;
+    /**
+     * Check if a path leads to a leaf node.
+     */
+    isLeaf(path: string): boolean;
+}
+
 /**
  * A record in the OR-Map (Observed-Remove Map).
  * Represents a single value instance with a unique tag.
@@ -166,6 +246,20 @@ interface ORMapRecord<V> {
     tag: string;
     ttlMs?: number;
 }
+/**
+ * Result of merging records for a key.
+ */
+interface MergeKeyResult {
+    added: number;
+    updated: number;
+}
+/**
+ * Snapshot of ORMap internal state for Merkle Tree synchronization.
+ */
+interface ORMapSnapshot<K, V> {
+    items: Map<K, Map<string, ORMapRecord<V>>>;
+    tombstones: Set<string>;
+}
 /**
  * OR-Map (Observed-Remove Map) Implementation.
  *
@@ -181,6 +275,7 @@ declare class ORMap<K, V> {
     private items;
     private tombstones;
     private readonly hlc;
+    private merkleTree;
     constructor(hlc: HLC);
     private listeners;
     onChange(callback: () => void): () => void;
@@ -219,8 +314,9 @@ declare class ORMap<K, V> {
     getTombstones(): string[];
     /**
      * Applies a record from a remote source (Sync).
+     * Returns true if the record was applied (not tombstoned).
      */
-    apply(key: K, record: ORMapRecord<V>): void;
+    apply(key: K, record: ORMapRecord<V>): boolean;
     /**
      * Applies a tombstone (deletion) from a remote source.
      */
@@ -236,8 +332,76 @@ declare class ORMap<K, V> {
      * Garbage Collection: Prunes tombstones older than the specified timestamp.
      */
     prune(olderThan: Timestamp): string[];
+    /**
+     * Get the Merkle Tree for this ORMap.
+     * Used for efficient synchronization.
+     */
+    getMerkleTree(): ORMapMerkleTree;
+    /**
+     * Get a snapshot of internal state for Merkle Tree synchronization.
+     * Returns references to internal structures - do not modify!
+     */
+    getSnapshot(): ORMapSnapshot<K, V>;
+    /**
+     * Get all keys in this ORMap.
+     */
+    allKeys(): K[];
+    /**
+     * 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: K): Map<string, ORMapRecord<V>> | undefined;
+    /**
+     * 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: K, remoteRecords: ORMapRecord<V>[], remoteTombstones?: string[]): MergeKeyResult;
+    /**
+     * Check if a tag is tombstoned.
+     */
+    isTombstoned(tag: string): boolean;
+    /**
+     * Update the Merkle Tree for a specific key.
+     * Called internally after any modification.
+     */
+    private updateMerkleTree;
 }
 
+/**
+ * Convert Timestamp to deterministic string for hashing.
+ * Format: millis:counter:nodeId
+ */
+declare function timestampToString(ts: Timestamp): string;
+/**
+ * Hash an ORMap entry (key + all its records).
+ * Must be deterministic regardless of insertion order.
+ *
+ * @param key The key of the entry
+ * @param records Map of tag -> record for this key
+ * @returns Hash as a number (FNV-1a hash)
+ */
+declare function hashORMapEntry<V>(key: string, records: Map<string, ORMapRecord<V>>): number;
+/**
+ * Hash a single ORMapRecord for comparison.
+ * Used when comparing individual records during merge.
+ */
+declare function hashORMapRecord<V>(record: ORMapRecord<V>): number;
+/**
+ * Compare two timestamps.
+ * Returns:
+ *   < 0 if a < b
+ *   > 0 if a > b
+ *   = 0 if a == b
+ */
+declare function compareTimestamps(a: Timestamp, b: Timestamp): number;
+
 /**
  * FNV-1a Hash implementation for strings.
  * Fast, non-cryptographic, synchronous.
@@ -559,6 +723,142 @@ declare const TopicMessageEventSchema: z.ZodObject<{
         timestamp: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>;
+declare const PingMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"PING">;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+declare const PongMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"PONG">;
+    timestamp: z.ZodNumber;
+    serverTime: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * ORMAP_SYNC_INIT: Client initiates ORMap sync
+ * Sends root hash and bucket hashes to server
+ */
+declare const ORMapSyncInitSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_INIT">;
+    mapName: z.ZodString;
+    rootHash: z.ZodNumber;
+    bucketHashes: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    lastSyncTimestamp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * ORMAP_SYNC_RESP_ROOT: Server responds with its root hash
+ */
+declare const ORMapSyncRespRootSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_RESP_ROOT">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        rootHash: z.ZodNumber;
+        timestamp: z.ZodObject<{
+            millis: z.ZodNumber;
+            counter: z.ZodNumber;
+            nodeId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * ORMAP_SYNC_RESP_BUCKETS: Server sends bucket hashes for comparison
+ */
+declare const ORMapSyncRespBucketsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_RESP_BUCKETS">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        path: z.ZodString;
+        buckets: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * ORMAP_MERKLE_REQ_BUCKET: Client requests bucket details
+ */
+declare const ORMapMerkleReqBucketSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_MERKLE_REQ_BUCKET">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * ORMAP_SYNC_RESP_LEAF: Server sends actual records for differing keys
+ */
+declare const ORMapSyncRespLeafSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_RESP_LEAF">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        path: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            records: z.ZodArray<z.ZodObject<{
+                value: z.ZodAny;
+                timestamp: z.ZodObject<{
+                    millis: z.ZodNumber;
+                    counter: z.ZodNumber;
+                    nodeId: z.ZodString;
+                }, z.core.$strip>;
+                tag: z.ZodString;
+                ttlMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tombstones: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * ORMAP_DIFF_REQUEST: Client requests data for specific keys
+ */
+declare const ORMapDiffRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_DIFF_REQUEST">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        keys: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * ORMAP_DIFF_RESPONSE: Server responds with data for requested keys
+ */
+declare const ORMapDiffResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_DIFF_RESPONSE">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            records: z.ZodArray<z.ZodObject<{
+                value: z.ZodAny;
+                timestamp: z.ZodObject<{
+                    millis: z.ZodNumber;
+                    counter: z.ZodNumber;
+                    nodeId: z.ZodString;
+                }, z.core.$strip>;
+                tag: z.ZodString;
+                ttlMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tombstones: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * ORMAP_PUSH_DIFF: Client pushes local diffs to server
+ */
+declare const ORMapPushDiffSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_PUSH_DIFF">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            records: z.ZodArray<z.ZodObject<{
+                value: z.ZodAny;
+                timestamp: z.ZodObject<{
+                    millis: z.ZodNumber;
+                    counter: z.ZodNumber;
+                    nodeId: z.ZodString;
+                }, z.core.$strip>;
+                tag: z.ZodString;
+                ttlMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tombstones: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 declare const MessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"AUTH">;
     token: z.ZodString;
@@ -717,9 +1017,112 @@ declare const MessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         topic: z.ZodString;
         data: z.ZodAny;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"PING">;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"PONG">;
+    timestamp: z.ZodNumber;
+    serverTime: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_INIT">;
+    mapName: z.ZodString;
+    rootHash: z.ZodNumber;
+    bucketHashes: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    lastSyncTimestamp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_RESP_ROOT">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        rootHash: z.ZodNumber;
+        timestamp: z.ZodObject<{
+            millis: z.ZodNumber;
+            counter: z.ZodNumber;
+            nodeId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_RESP_BUCKETS">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        path: z.ZodString;
+        buckets: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_MERKLE_REQ_BUCKET">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_SYNC_RESP_LEAF">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        path: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            records: z.ZodArray<z.ZodObject<{
+                value: z.ZodAny;
+                timestamp: z.ZodObject<{
+                    millis: z.ZodNumber;
+                    counter: z.ZodNumber;
+                    nodeId: z.ZodString;
+                }, z.core.$strip>;
+                tag: z.ZodString;
+                ttlMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tombstones: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_DIFF_REQUEST">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        keys: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_DIFF_RESPONSE">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            records: z.ZodArray<z.ZodObject<{
+                value: z.ZodAny;
+                timestamp: z.ZodObject<{
+                    millis: z.ZodNumber;
+                    counter: z.ZodNumber;
+                    nodeId: z.ZodString;
+                }, z.core.$strip>;
+                tag: z.ZodString;
+                ttlMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tombstones: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ORMAP_PUSH_DIFF">;
+    payload: z.ZodObject<{
+        mapName: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            records: z.ZodArray<z.ZodObject<{
+                value: z.ZodAny;
+                timestamp: z.ZodObject<{
+                    millis: z.ZodNumber;
+                    counter: z.ZodNumber;
+                    nodeId: z.ZodString;
+                }, z.core.$strip>;
+                tag: z.ZodString;
+                ttlMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            tombstones: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
 }, z.core.$strip>], "type">;
 type Query = z.infer<typeof QuerySchema>;
 type ClientOp = z.infer<typeof ClientOpSchema>;
 type Message = z.infer<typeof MessageSchema>;
+type PingMessage = z.infer<typeof PingMessageSchema>;
+type PongMessage = z.infer<typeof PongMessageSchema>;
 
-export { AuthMessageSchema, type ClientOp, ClientOpMessageSchema, ClientOpSchema, HLC, LWWMap, type LWWRecord, LWWRecordSchema, LockReleaseSchema, LockRequestSchema, MerkleReqBucketMessageSchema, MerkleTree, type Message, MessageSchema, ORMap, type ORMapRecord, ORMapRecordSchema, OpBatchMessageSchema, type PermissionPolicy, type PermissionType, type PredicateNode, PredicateNodeSchema, type PredicateOp, PredicateOpSchema, Predicates, type Principal, type Query, QuerySchema, QuerySubMessageSchema, QueryUnsubMessageSchema, SyncInitMessageSchema, SyncRespBucketsMessageSchema, SyncRespLeafMessageSchema, SyncRespRootMessageSchema, type Timestamp, TimestampSchema, TopicMessageEventSchema, TopicPubSchema, TopicSubSchema, TopicUnsubSchema, combineHashes, deserialize, evaluatePredicate, hashString, serialize };
+export { AuthMessageSchema, type ClientOp, ClientOpMessageSchema, ClientOpSchema, HLC, LWWMap, type LWWRecord, LWWRecordSchema, LockReleaseSchema, LockRequestSchema, type MergeKeyResult, MerkleReqBucketMessageSchema, MerkleTree, type Message, MessageSchema, ORMap, ORMapDiffRequestSchema, ORMapDiffResponseSchema, type ORMapMerkleNode, ORMapMerkleReqBucketSchema, ORMapMerkleTree, ORMapPushDiffSchema, type ORMapRecord, ORMapRecordSchema, type ORMapSnapshot, ORMapSyncInitSchema, ORMapSyncRespBucketsSchema, ORMapSyncRespLeafSchema, ORMapSyncRespRootSchema, OpBatchMessageSchema, type PermissionPolicy, type PermissionType, type PingMessage, PingMessageSchema, type PongMessage, PongMessageSchema, type PredicateNode, PredicateNodeSchema, type PredicateOp, PredicateOpSchema, Predicates, type Principal, type Query, QuerySchema, QuerySubMessageSchema, QueryUnsubMessageSchema, SyncInitMessageSchema, SyncRespBucketsMessageSchema, SyncRespLeafMessageSchema, SyncRespRootMessageSchema, type Timestamp, TimestampSchema, TopicMessageEventSchema, TopicPubSchema, TopicSubSchema, TopicUnsubSchema, combineHashes, compareTimestamps, deserialize, evaluatePredicate, hashORMapEntry, hashORMapRecord, hashString, serialize, timestampToString };