@ninebix/nmt-system 1.0.0

package/dist/src/sync/state-sync.js

@@ -0,0 +1,396 @@
+/**
+ * State Sync Manager - Distributed state synchronization
+ *
+ * Manages state synchronization between nodes using vector clocks
+ * for causality tracking and conflict resolution.
+ *
+ * @module sync/state-sync
+ */
+import { createEvent } from '../events/event-bus.js';
+import { VectorClock } from './vector-clock.js';
+/**
+ * StateSyncManager - Coordinates state synchronization
+ *
+ * Features:
+ * - Vector clock-based causality tracking
+ * - Change journal for durability
+ * - Configurable conflict resolution
+ * - Event-based notifications
+ *
+ * @example
+ * ```typescript
+ * const sync = new StateSyncManager({
+ *   nodeId: 'node-1',
+ *   journal: changeJournal,
+ *   merkleEngine: merkleEngine,
+ *   eventBus: eventBus
+ * });
+ *
+ * await sync.init();
+ *
+ * // Record local changes
+ * await sync.recordChange({
+ *   type: 'neuron',
+ *   operation: 'create',
+ *   entityId: 'neuron-123',
+ *   data: { content: 'Hello' }
+ * });
+ *
+ * // Compute diff with remote
+ * const diff = await sync.computeStateDiff(remoteState);
+ *
+ * // Apply remote changes
+ * const result = await sync.applyRemoteChanges(remoteChanges);
+ * ```
+ */
+export class StateSyncManager {
+    nodeId;
+    journal;
+    merkleEngine;
+    eventBus;
+    conflictResolution;
+    vectorClock;
+    merkleRoot = null;
+    initialized = false;
+    initPromise = null;
+    peers = new Map();
+    conflictHandlers = [];
+    constructor(options) {
+        this.nodeId = options.nodeId;
+        this.journal = options.journal;
+        this.merkleEngine = options.merkleEngine;
+        this.eventBus = options.eventBus ?? null;
+        this.conflictResolution = options.conflictResolution ?? {
+            strategy: 'last-write-wins',
+        };
+        this.vectorClock = new VectorClock(this.nodeId);
+    }
+    /**
+     * Initialize the sync manager
+     * Thread-safe: concurrent calls will wait for the same initialization
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        // If initialization is already in progress, wait for it
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        // Start initialization
+        this.initPromise = this._doInit();
+        await this.initPromise;
+    }
+    /**
+     * Internal initialization logic
+     */
+    async _doInit() {
+        try {
+            await this.journal.init();
+            // Restore vector clock from journal
+            const latestSeq = await this.journal.getLatestSequence();
+            if (latestSeq > 0) {
+                const latestEntry = await this.journal.get(latestSeq);
+                if (latestEntry) {
+                    this.vectorClock = VectorClock.fromJSON(latestEntry.vectorClock, this.nodeId);
+                }
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            // Reset promise so init can be retried
+            this.initPromise = null;
+            throw error;
+        }
+    }
+    /**
+     * Record a local change
+     */
+    async recordChange(change) {
+        if (!this.initialized) {
+            await this.init();
+        }
+        // Increment vector clock
+        this.vectorClock.tick(this.nodeId);
+        const entry = {
+            type: change.type,
+            operation: change.operation,
+            entityId: change.entityId,
+            data: change.data,
+            vectorClock: this.vectorClock.toJSON(),
+            timestamp: new Date().toISOString(),
+            nodeId: this.nodeId,
+            metadata: change.metadata,
+        };
+        const sequence = await this.journal.append(entry);
+        // Emit event
+        if (this.eventBus) {
+            this.eventBus.publish(createEvent('sync:state_changed', 'state-sync', { sequence, entry }));
+        }
+        return sequence;
+    }
+    /**
+     * Record multiple changes atomically
+     */
+    async recordChanges(changes) {
+        if (!this.initialized) {
+            await this.init();
+        }
+        const entries = [];
+        for (const change of changes) {
+            this.vectorClock.tick(this.nodeId);
+            entries.push({
+                type: change.type,
+                operation: change.operation,
+                entityId: change.entityId,
+                data: change.data,
+                vectorClock: this.vectorClock.toJSON(),
+                timestamp: new Date().toISOString(),
+                nodeId: this.nodeId,
+                metadata: change.metadata,
+            });
+        }
+        return this.journal.appendBatch(entries);
+    }
+    /**
+     * Compute diff between local and remote state
+     */
+    async computeStateDiff(remoteState) {
+        const localSequence = await this.journal.getLatestSequence();
+        const result = {
+            needsSync: false,
+            localAhead: [],
+            remoteAhead: [],
+            conflicts: [],
+        };
+        // Compare vector clocks
+        const comparison = this.vectorClock.compare(remoteState.vectorClock);
+        switch (comparison) {
+            case 'equal':
+                // States are in sync
+                return result;
+            case 'after':
+                // Local is ahead - send local changes
+                result.needsSync = true;
+                if (remoteState.sequence < localSequence) {
+                    result.localAhead = await this.journal.getAfterSequence(remoteState.sequence);
+                }
+                break;
+            case 'before':
+                // Remote is ahead - request remote changes
+                result.needsSync = true;
+                for (let seq = localSequence + 1; seq <= remoteState.sequence; seq++) {
+                    result.remoteAhead.push(seq);
+                }
+                break;
+            case 'concurrent':
+                // Concurrent changes - potential conflicts
+                result.needsSync = true;
+                if (remoteState.sequence < localSequence) {
+                    result.localAhead = await this.journal.getAfterSequence(remoteState.sequence);
+                }
+                for (let seq = localSequence + 1; seq <= remoteState.sequence; seq++) {
+                    result.remoteAhead.push(seq);
+                }
+                break;
+        }
+        return result;
+    }
+    /**
+     * Apply remote changes
+     */
+    async applyRemoteChanges(changes) {
+        const result = {
+            applied: 0,
+            conflicts: 0,
+            resolved: [],
+            skipped: 0,
+        };
+        for (const remoteEntry of changes) {
+            // Check for conflicts
+            const localEntries = await this.journal.getByEntity(remoteEntry.entityId);
+            const conflictingEntry = localEntries.find(local => {
+                const localClock = VectorClock.fromJSON(local.vectorClock);
+                const remoteClock = VectorClock.fromJSON(remoteEntry.vectorClock);
+                return localClock.isConcurrentWith(remoteClock);
+            });
+            if (conflictingEntry) {
+                result.conflicts++;
+                // Emit conflict event
+                if (this.eventBus) {
+                    this.eventBus.publish(createEvent('sync:conflict', 'state-sync', { local: conflictingEntry, remote: remoteEntry }));
+                }
+                // Notify handlers
+                for (const handler of this.conflictHandlers) {
+                    handler(conflictingEntry, remoteEntry);
+                }
+                // Resolve conflict
+                const resolved = this.resolveConflict(conflictingEntry, remoteEntry);
+                if (resolved) {
+                    // Apply resolved change
+                    await this.recordChange({
+                        type: resolved.type,
+                        operation: resolved.operation,
+                        entityId: resolved.entityId,
+                        data: resolved.data,
+                        metadata: { resolvedConflict: true },
+                    });
+                    result.resolved.push(resolved);
+                    if (this.eventBus) {
+                        this.eventBus.publish(createEvent('sync:resolved', 'state-sync', { resolved }));
+                    }
+                }
+            }
+            else {
+                // No conflict - apply directly
+                // Merge vector clocks
+                const remoteClock = VectorClock.fromJSON(remoteEntry.vectorClock);
+                this.vectorClock.update(remoteClock);
+                // Record in local journal
+                await this.journal.append({
+                    type: remoteEntry.type,
+                    operation: remoteEntry.operation,
+                    entityId: remoteEntry.entityId,
+                    data: remoteEntry.data,
+                    vectorClock: this.vectorClock.toJSON(),
+                    timestamp: new Date().toISOString(),
+                    nodeId: remoteEntry.nodeId,
+                    metadata: { ...remoteEntry.metadata, synced: true },
+                });
+                result.applied++;
+            }
+        }
+        return result;
+    }
+    /**
+     * Get current local state
+     */
+    getLocalState() {
+        return {
+            nodeId: this.nodeId,
+            merkleRoot: this.merkleRoot,
+            vectorClock: this.vectorClock.clone(),
+            sequence: 0, // Will be updated by getLatestSequence
+            lastSync: null,
+        };
+    }
+    /**
+     * Get local state with current sequence
+     */
+    async getLocalStateAsync() {
+        const sequence = await this.journal.getLatestSequence();
+        return {
+            nodeId: this.nodeId,
+            merkleRoot: this.merkleRoot,
+            vectorClock: this.vectorClock.clone(),
+            sequence,
+            lastSync: new Date().toISOString(),
+        };
+    }
+    /**
+     * Register conflict handler
+     */
+    onConflict(handler) {
+        this.conflictHandlers.push(handler);
+        return () => {
+            const index = this.conflictHandlers.indexOf(handler);
+            if (index >= 0) {
+                this.conflictHandlers.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Add a peer
+     */
+    addPeer(peer) {
+        this.peers.set(peer.peerId, peer);
+    }
+    /**
+     * Remove a peer
+     */
+    removePeer(peerId) {
+        this.peers.delete(peerId);
+    }
+    /**
+     * Get all peers
+     */
+    getPeers() {
+        return Array.from(this.peers.values());
+    }
+    /**
+     * Get a specific peer
+     */
+    getPeer(peerId) {
+        return this.peers.get(peerId);
+    }
+    /**
+     * Update peer state
+     */
+    updatePeer(peerId, update) {
+        const peer = this.peers.get(peerId);
+        if (peer) {
+            Object.assign(peer, update);
+        }
+    }
+    /**
+     * Set the Merkle root for state hashing
+     */
+    setMerkleRoot(root) {
+        this.merkleRoot = root;
+    }
+    /**
+     * Get current vector clock
+     */
+    getVectorClock() {
+        return this.vectorClock.clone();
+    }
+    /**
+     * Get changes since a sequence
+     */
+    async getChangesSince(sequence) {
+        return this.journal.getAfterSequence(sequence);
+    }
+    /**
+     * Resolve conflict based on strategy
+     */
+    resolveConflict(local, remote) {
+        switch (this.conflictResolution.strategy) {
+            case 'last-write-wins':
+                // Compare timestamps
+                const localTime = new Date(local.timestamp).getTime();
+                const remoteTime = new Date(remote.timestamp).getTime();
+                return localTime >= remoteTime ? local : remote;
+            case 'vector-clock':
+                // Use vector clock dominance
+                const localClock = VectorClock.fromJSON(local.vectorClock);
+                const remoteClock = VectorClock.fromJSON(remote.vectorClock);
+                if (localClock.dominates(remoteClock)) {
+                    return local;
+                }
+                else if (remoteClock.dominates(localClock)) {
+                    return remote;
+                }
+                // If neither dominates, fall back to timestamp
+                return new Date(local.timestamp) >= new Date(remote.timestamp)
+                    ? local
+                    : remote;
+            case 'merge':
+            case 'manual':
+                if (this.conflictResolution.resolver) {
+                    return this.conflictResolution.resolver(local, remote);
+                }
+                // No resolver provided, fall back to last-write-wins
+                return new Date(local.timestamp) >= new Date(remote.timestamp)
+                    ? local
+                    : remote;
+            default:
+                return local;
+        }
+    }
+}
+/**
+ * Create a StateSyncManager instance
+ */
+export function createStateSyncManager(options) {
+    return new StateSyncManager(options);
+}
+//# sourceMappingURL=state-sync.js.map

package/dist/src/sync/state-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-sync.js","sourceRoot":"","sources":["../../../src/sync/state-sync.ts"],"names":[],"mappings":"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"}

package/dist/src/sync/vector-clock.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Vector Clock - Logical clock for distributed systems
+ *
+ * Provides causal ordering for events across multiple nodes.
+ * Used for conflict detection and resolution in state synchronization.
+ *
+ * @module sync/vector-clock
+ */
+/**
+ * Comparison result between two vector clocks
+ */
+export type ClockComparison = 'before' | 'after' | 'concurrent' | 'equal';
+/**
+ * Serialized vector clock format
+ */
+export type SerializedClock = Record<string, number>;
+/**
+ * VectorClock - Lamport-style vector clock implementation
+ *
+ * Vector clocks track causality in distributed systems:
+ * - If clock A happened-before clock B, compare returns 'before'
+ * - If clock B happened-before clock A, compare returns 'after'
+ * - If neither happened-before the other, they are 'concurrent'
+ *
+ * @example
+ * ```typescript
+ * const clockA = new VectorClock('node-a');
+ * clockA.increment('node-a');
+ * clockA.increment('node-a');
+ *
+ * const clockB = new VectorClock('node-b');
+ * clockB.increment('node-b');
+ *
+ * // Clocks are concurrent (no causal relationship)
+ * console.log(clockA.compare(clockB)); // 'concurrent'
+ *
+ * // Merge creates a clock that dominates both
+ * const merged = clockA.merge(clockB);
+ * console.log(merged.compare(clockA)); // 'after'
+ * ```
+ */
+export declare class VectorClock {
+    private clock;
+    private nodeId;
+    constructor(nodeId?: string, initial?: SerializedClock);
+    /**
+     * Increment the clock for a specific node
+     * Returns a new VectorClock (immutable operation)
+     */
+    increment(nodeId?: string): VectorClock;
+    /**
+     * Increment in place (mutable operation)
+     */
+    tick(nodeId?: string): void;
+    /**
+     * Get the timestamp for a specific node
+     */
+    get(nodeId: string): number;
+    /**
+     * Set the timestamp for a specific node
+     * @throws {Error} If value is negative or not an integer
+     */
+    set(nodeId: string, value: number): void;
+    /**
+     * Merge with another vector clock
+     * Returns a new clock with max values from both (immutable)
+     */
+    merge(other: VectorClock): VectorClock;
+    /**
+     * Merge in place (mutable operation)
+     */
+    update(other: VectorClock): void;
+    /**
+     * Compare this clock with another
+     *
+     * @returns
+     * - 'before': this happened before other
+     * - 'after': this happened after other
+     * - 'concurrent': neither happened before the other
+     * - 'equal': clocks are identical
+     */
+    compare(other: VectorClock): ClockComparison;
+    /**
+     * Check if this clock happened before or concurrent with other
+     */
+    happenedBefore(other: VectorClock): boolean;
+    /**
+     * Check if this clock happened after or concurrent with other
+     */
+    happenedAfter(other: VectorClock): boolean;
+    /**
+     * Check if two events are concurrent (no causal relationship)
+     */
+    isConcurrentWith(other: VectorClock): boolean;
+    /**
+     * Check if this clock dominates (is >= in all dimensions)
+     */
+    dominates(other: VectorClock): boolean;
+    /**
+     * Get all node IDs in this clock
+     */
+    getNodes(): string[];
+    /**
+     * Get the total sum of all timestamps (for debugging)
+     */
+    sum(): number;
+    /**
+     * Get the size (number of nodes)
+     */
+    size(): number;
+    /**
+     * Check if clock is empty (all zeros or no entries)
+     */
+    isEmpty(): boolean;
+    /**
+     * Create a copy of this clock
+     */
+    clone(): VectorClock;
+    /**
+     * Serialize to JSON-friendly format
+     */
+    toJSON(): SerializedClock;
+    /**
+     * Create from serialized format
+     */
+    static fromJSON(data: SerializedClock, nodeId?: string): VectorClock;
+    /**
+     * Create an empty clock for a node
+     */
+    static create(nodeId: string): VectorClock;
+    /**
+     * String representation for debugging
+     */
+    toString(): string;
+    /**
+     * Check equality with another clock
+     */
+    equals(other: VectorClock): boolean;
+}
+/**
+ * Create a new VectorClock instance
+ */
+export declare function createVectorClock(nodeId?: string): VectorClock;
+//# sourceMappingURL=vector-clock.d.ts.map

package/dist/src/sync/vector-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-clock.d.ts","sourceRoot":"","sources":["../../../src/sync/vector-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe;IAWtD;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW;IAWvC;;OAEG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ3B;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAI3B;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAUxC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW;IAiBtC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAOhC;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe;IAmC5C;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAI3C;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAI1C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAI7C;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAKtC;;OAEG;IACH,QAAQ,IAAI,MAAM,EAAE;IAIpB;;OAEG;IACH,GAAG,IAAI,MAAM;IAQb;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,OAAO,IAAI,OAAO;IAQlB;;OAEG;IACH,KAAK,IAAI,WAAW;IAIpB;;OAEG;IACH,MAAM,IAAI,eAAe;IAQzB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW;IAIpE;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW;IAI1C;;OAEG;IACH,QAAQ,IAAI,MAAM;IASlB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;CAGpC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAE9D"}