agentic-qe 2.7.4 → 2.8.0

package/dist/edge/p2p/crdt/CRDTStore.js

@@ -0,0 +1,839 @@
+"use strict";
+/**
+ * CRDT Store - Storage and Management for Multiple CRDTs
+ *
+ * Provides a centralized store for managing multiple CRDT instances,
+ * applying remote updates, generating deltas for synchronization,
+ * and garbage collecting tombstones.
+ *
+ * @module edge/p2p/crdt/CRDTStore
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CRDTStore = void 0;
+const types_1 = require("./types");
+const VectorClock_1 = require("./VectorClock");
+const GCounter_1 = require("./GCounter");
+const LWWRegister_1 = require("./LWWRegister");
+const ORSet_1 = require("./ORSet");
+const PatternCRDT_1 = require("./PatternCRDT");
+// ============================================
+// CRDTStore Class
+// ============================================
+/**
+ * Store for managing multiple CRDT instances.
+ *
+ * Features:
+ * - Create and retrieve CRDTs by ID
+ * - Apply remote updates and merge states
+ * - Generate delta updates for synchronization
+ * - Automatic garbage collection of tombstones
+ * - Event emission for monitoring
+ * - Conflict tracking
+ *
+ * @example
+ * ```typescript
+ * const store = new CRDTStore({
+ *   replicaId: 'replica-1',
+ *   autoGC: true,
+ * });
+ *
+ * // Create CRDTs
+ * const counter = store.createGCounter('page-views');
+ * const tags = store.createORSet<string>('user-tags');
+ * const pattern = store.createPattern({
+ *   id: 'pattern-1',
+ *   content: '...',
+ *   type: 'test',
+ *   category: 'unit',
+ *   domain: 'api',
+ * });
+ *
+ * // Apply remote state
+ * store.applyState(remoteState);
+ *
+ * // Generate deltas for sync
+ * const deltas = store.generateDeltas(lastSyncClock);
+ *
+ * // Get stats
+ * const stats = store.getStats();
+ * ```
+ */
+class CRDTStore {
+    /**
+     * Create a new CRDT store
+     *
+     * @param config - Store configuration
+     */
+    constructor(config = {}) {
+        this.config = { ...types_1.DEFAULT_STORE_CONFIG, ...config };
+        if (!this.config.replicaId) {
+            throw new types_1.CRDTError('Replica ID is required for CRDTStore', types_1.CRDTErrorCode.InvalidState);
+        }
+        this.instances = new Map();
+        this.types = new Map();
+        this.vectorClock = new VectorClock_1.VectorClock(this.config.replicaId);
+        this.deltaBuffer = new Map();
+        this.conflicts = [];
+        this.eventHandlers = new Set();
+        // Start auto GC if enabled
+        if (this.config.autoGC) {
+            this.startAutoGC();
+        }
+    }
+    // ============================================
+    // CRDT Creation
+    // ============================================
+    /**
+     * Create a new G-Counter
+     *
+     * @param id - Counter identifier
+     * @param initialValue - Initial value
+     * @returns Created counter
+     */
+    createGCounter(id, initialValue = 0) {
+        this.checkCapacity();
+        this.checkIdAvailable(id);
+        const counter = new GCounter_1.GCounter(this.config.replicaId, id, initialValue);
+        this.instances.set(id, counter);
+        this.types.set(id, types_1.CRDTType.GCounter);
+        this.vectorClock.increment();
+        this.emit({
+            type: types_1.CRDTEventType.Created,
+            crdtId: id,
+            crdtType: types_1.CRDTType.GCounter,
+            timestamp: Date.now(),
+            details: { initialValue },
+        });
+        return counter;
+    }
+    /**
+     * Create a new LWW-Register
+     *
+     * @param id - Register identifier
+     * @param initialValue - Initial value
+     * @returns Created register
+     */
+    createLWWRegister(id, initialValue) {
+        this.checkCapacity();
+        this.checkIdAvailable(id);
+        const register = new LWWRegister_1.LWWRegister(this.config.replicaId, id, initialValue);
+        this.instances.set(id, register);
+        this.types.set(id, types_1.CRDTType.LWWRegister);
+        this.vectorClock.increment();
+        this.emit({
+            type: types_1.CRDTEventType.Created,
+            crdtId: id,
+            crdtType: types_1.CRDTType.LWWRegister,
+            timestamp: Date.now(),
+            details: { hasInitialValue: initialValue !== undefined },
+        });
+        return register;
+    }
+    /**
+     * Create a new OR-Set
+     *
+     * @param id - Set identifier
+     * @returns Created set
+     */
+    createORSet(id) {
+        this.checkCapacity();
+        this.checkIdAvailable(id);
+        const set = new ORSet_1.ORSet(this.config.replicaId, id, {
+            tombstoneTtl: this.config.tombstoneTtl,
+        });
+        this.instances.set(id, set);
+        this.types.set(id, types_1.CRDTType.ORSet);
+        this.vectorClock.increment();
+        this.emit({
+            type: types_1.CRDTEventType.Created,
+            crdtId: id,
+            crdtType: types_1.CRDTType.ORSet,
+            timestamp: Date.now(),
+            details: {},
+        });
+        return set;
+    }
+    /**
+     * Create a new Pattern CRDT
+     *
+     * @param input - Pattern input data
+     * @returns Created PatternCRDT
+     */
+    createPattern(input) {
+        this.checkCapacity();
+        this.checkIdAvailable(input.id);
+        const pattern = new PatternCRDT_1.PatternCRDT(this.config.replicaId, input);
+        this.instances.set(input.id, pattern);
+        this.types.set(input.id, types_1.CRDTType.PatternCRDT);
+        this.vectorClock.increment();
+        this.emit({
+            type: types_1.CRDTEventType.Created,
+            crdtId: input.id,
+            crdtType: types_1.CRDTType.PatternCRDT,
+            timestamp: Date.now(),
+            details: { type: input.type, category: input.category },
+        });
+        return pattern;
+    }
+    // ============================================
+    // CRDT Retrieval
+    // ============================================
+    /**
+     * Get a CRDT by ID
+     *
+     * @param id - CRDT identifier
+     * @returns CRDT instance or undefined
+     */
+    get(id) {
+        return this.instances.get(id);
+    }
+    /**
+     * Get a G-Counter by ID
+     *
+     * @param id - Counter identifier
+     * @returns Counter or undefined
+     */
+    getGCounter(id) {
+        const instance = this.instances.get(id);
+        if (instance && this.types.get(id) === types_1.CRDTType.GCounter) {
+            return instance;
+        }
+        return undefined;
+    }
+    /**
+     * Get an LWW-Register by ID
+     *
+     * @param id - Register identifier
+     * @returns Register or undefined
+     */
+    getLWWRegister(id) {
+        const instance = this.instances.get(id);
+        if (instance && this.types.get(id) === types_1.CRDTType.LWWRegister) {
+            return instance;
+        }
+        return undefined;
+    }
+    /**
+     * Get an OR-Set by ID
+     *
+     * @param id - Set identifier
+     * @returns Set or undefined
+     */
+    getORSet(id) {
+        const instance = this.instances.get(id);
+        if (instance && this.types.get(id) === types_1.CRDTType.ORSet) {
+            return instance;
+        }
+        return undefined;
+    }
+    /**
+     * Get a PatternCRDT by ID
+     *
+     * @param id - Pattern identifier
+     * @returns Pattern or undefined
+     */
+    getPattern(id) {
+        const instance = this.instances.get(id);
+        if (instance && this.types.get(id) === types_1.CRDTType.PatternCRDT) {
+            return instance;
+        }
+        return undefined;
+    }
+    /**
+     * Check if a CRDT exists
+     *
+     * @param id - CRDT identifier
+     * @returns True if exists
+     */
+    has(id) {
+        return this.instances.has(id);
+    }
+    /**
+     * Get all CRDT IDs
+     *
+     * @returns Array of IDs
+     */
+    getIds() {
+        return Array.from(this.instances.keys());
+    }
+    /**
+     * Get IDs by type
+     *
+     * @param type - CRDT type to filter by
+     * @returns Array of matching IDs
+     */
+    getIdsByType(type) {
+        const ids = [];
+        for (const [id, t] of this.types) {
+            if (t === type) {
+                ids.push(id);
+            }
+        }
+        return ids;
+    }
+    /**
+     * Get the type of a CRDT
+     *
+     * @param id - CRDT identifier
+     * @returns CRDT type or undefined
+     */
+    getType(id) {
+        return this.types.get(id);
+    }
+    // ============================================
+    // State Application
+    // ============================================
+    /**
+     * Apply a remote CRDT state
+     *
+     * If the CRDT doesn't exist locally, it will be created.
+     * If it exists, the states will be merged.
+     *
+     * @param state - Remote CRDT state
+     * @returns Merge result
+     */
+    applyState(state) {
+        const startTime = Date.now();
+        let result;
+        const existing = this.instances.get(state.id);
+        if (existing) {
+            // Merge with existing
+            result = this.mergeExisting(state);
+        }
+        else {
+            // Create new from state
+            result = this.createFromState(state);
+        }
+        // Track conflicts
+        if (this.config.trackConflicts) {
+            this.addConflicts(result.conflicts);
+        }
+        // Emit event
+        if (result.localChanged) {
+            this.emit({
+                type: types_1.CRDTEventType.Merge,
+                crdtId: state.id,
+                crdtType: state.type,
+                timestamp: Date.now(),
+                details: {
+                    origin: state.origin,
+                    conflicts: result.conflicts.length,
+                    duration: Date.now() - startTime,
+                },
+            });
+        }
+        this.vectorClock.increment();
+        return result;
+    }
+    /**
+     * Merge state with existing CRDT
+     */
+    mergeExisting(state) {
+        const instance = this.instances.get(state.id);
+        const type = this.types.get(state.id);
+        if (type !== state.type) {
+            throw new types_1.CRDTError(`Type mismatch: local is ${type}, remote is ${state.type}`, types_1.CRDTErrorCode.InvalidType, state.id);
+        }
+        switch (type) {
+            case types_1.CRDTType.GCounter:
+                return instance.merge(state);
+            case types_1.CRDTType.LWWRegister:
+                return instance.merge(state);
+            case types_1.CRDTType.ORSet:
+                return instance.merge(state);
+            case types_1.CRDTType.PatternCRDT:
+                return instance.merge(state);
+            default:
+                throw new types_1.CRDTError(`Unknown CRDT type: ${type}`, types_1.CRDTErrorCode.InvalidType, state.id);
+        }
+    }
+    /**
+     * Create a new CRDT from remote state
+     */
+    createFromState(state) {
+        this.checkCapacity();
+        let instance;
+        switch (state.type) {
+            case types_1.CRDTType.GCounter:
+                instance = GCounter_1.GCounter.fromState(state, this.config.replicaId);
+                break;
+            case types_1.CRDTType.LWWRegister:
+                instance = LWWRegister_1.LWWRegister.fromState(state, this.config.replicaId);
+                break;
+            case types_1.CRDTType.ORSet:
+                instance = ORSet_1.ORSet.fromState(state, this.config.replicaId);
+                break;
+            case types_1.CRDTType.PatternCRDT:
+                instance = PatternCRDT_1.PatternCRDT.fromState(state, this.config.replicaId);
+                break;
+            default:
+                throw new types_1.CRDTError(`Unknown CRDT type: ${state.type}`, types_1.CRDTErrorCode.InvalidType, state.id);
+        }
+        this.instances.set(state.id, instance);
+        this.types.set(state.id, state.type);
+        this.emit({
+            type: types_1.CRDTEventType.Created,
+            crdtId: state.id,
+            crdtType: state.type,
+            timestamp: Date.now(),
+            details: { fromRemote: true, origin: state.origin },
+        });
+        return {
+            success: true,
+            mergedState: state,
+            localChanged: true,
+            conflicts: [],
+            stats: {
+                duration: 0,
+                entriesMerged: 1,
+                autoResolved: 0,
+                tombstonesProcessed: 0,
+                memoryDelta: 0,
+            },
+        };
+    }
+    /**
+     * Apply a delta update
+     *
+     * @param delta - Delta to apply
+     * @returns True if applied successfully
+     */
+    applyDelta(delta) {
+        const instance = this.instances.get(delta.crdtId);
+        if (!instance) {
+            // Buffer delta for later if CRDT doesn't exist yet
+            if (this.config.enableDeltas) {
+                this.bufferDelta(delta);
+            }
+            return false;
+        }
+        const type = this.types.get(delta.crdtId);
+        if (type !== delta.type) {
+            return false;
+        }
+        let applied = false;
+        switch (type) {
+            case types_1.CRDTType.GCounter:
+                applied = instance.applyDelta(delta);
+                break;
+            case types_1.CRDTType.LWWRegister:
+                applied = instance.applyDelta(delta);
+                break;
+            case types_1.CRDTType.ORSet:
+                applied = instance.applyDelta(delta);
+                break;
+            case types_1.CRDTType.PatternCRDT:
+                applied = instance.applyDelta(delta);
+                break;
+        }
+        if (applied) {
+            this.vectorClock.increment();
+            this.emit({
+                type: types_1.CRDTEventType.Update,
+                crdtId: delta.crdtId,
+                crdtType: delta.type,
+                timestamp: Date.now(),
+                details: { deltaOrigin: delta.origin },
+            });
+        }
+        return applied;
+    }
+    // ============================================
+    // Delta Generation
+    // ============================================
+    /**
+     * Generate deltas for all CRDTs since a given clock
+     *
+     * @param since - Vector clock of last sync
+     * @returns Array of deltas
+     */
+    generateDeltas(since) {
+        const deltas = [];
+        for (const [id, instance] of this.instances) {
+            const type = this.types.get(id);
+            let delta = null;
+            switch (type) {
+                case types_1.CRDTType.GCounter:
+                    delta = instance.generateDelta(since);
+                    break;
+                case types_1.CRDTType.LWWRegister:
+                    delta = instance.generateDelta(since);
+                    break;
+                case types_1.CRDTType.ORSet:
+                    delta = instance.generateDelta(since);
+                    break;
+                case types_1.CRDTType.PatternCRDT:
+                    delta = instance.generateDelta(since);
+                    break;
+            }
+            if (delta) {
+                deltas.push(delta);
+                this.emit({
+                    type: types_1.CRDTEventType.DeltaGenerated,
+                    crdtId: id,
+                    crdtType: type,
+                    timestamp: Date.now(),
+                    details: { sequenceNumber: delta.sequenceNumber },
+                });
+            }
+        }
+        this.lastSync = Date.now();
+        return deltas;
+    }
+    /**
+     * Get all states for full sync
+     *
+     * @returns Array of all CRDT states
+     */
+    getAllStates() {
+        const states = [];
+        for (const [id, instance] of this.instances) {
+            const type = this.types.get(id);
+            switch (type) {
+                case types_1.CRDTType.GCounter:
+                    states.push(instance.state());
+                    break;
+                case types_1.CRDTType.LWWRegister:
+                    states.push(instance.state());
+                    break;
+                case types_1.CRDTType.ORSet:
+                    states.push(instance.state());
+                    break;
+                case types_1.CRDTType.PatternCRDT:
+                    states.push(instance.state());
+                    break;
+            }
+        }
+        return states;
+    }
+    // ============================================
+    // Delta Buffering
+    // ============================================
+    /**
+     * Buffer a delta for later application
+     */
+    bufferDelta(delta) {
+        if (!this.deltaBuffer.has(delta.crdtId)) {
+            this.deltaBuffer.set(delta.crdtId, []);
+        }
+        const buffer = this.deltaBuffer.get(delta.crdtId);
+        // Check buffer size limit
+        if (buffer.length >= this.config.maxDeltaBuffer) {
+            buffer.shift(); // Remove oldest
+        }
+        buffer.push({
+            delta,
+            timestamp: Date.now(),
+            applied: false,
+        });
+    }
+    /**
+     * Apply buffered deltas for a CRDT
+     *
+     * @param id - CRDT identifier
+     * @returns Number of deltas applied
+     */
+    applyBufferedDeltas(id) {
+        const buffer = this.deltaBuffer.get(id);
+        if (!buffer || buffer.length === 0) {
+            return 0;
+        }
+        let applied = 0;
+        for (const entry of buffer) {
+            if (!entry.applied && this.applyDelta(entry.delta)) {
+                entry.applied = true;
+                applied++;
+            }
+        }
+        // Clean up applied deltas
+        this.deltaBuffer.set(id, buffer.filter(e => !e.applied));
+        return applied;
+    }
+    // ============================================
+    // Garbage Collection
+    // ============================================
+    /**
+     * Run garbage collection on all ORSets
+     *
+     * @returns GC result
+     */
+    gc() {
+        const startTime = Date.now();
+        let totalCollected = 0;
+        let totalRetained = 0;
+        for (const [id, instance] of this.instances) {
+            if (this.types.get(id) === types_1.CRDTType.ORSet) {
+                const orset = instance;
+                const collected = orset.gcTombstones();
+                totalCollected += collected;
+                totalRetained += orset.getTombstoneCount();
+            }
+        }
+        // Clean up old conflicts
+        const conflictCutoff = Date.now() - this.config.tombstoneTtl;
+        this.conflicts = this.conflicts.filter(c => c.detectedAt > conflictCutoff);
+        // Clean up old buffered deltas
+        for (const [id, buffer] of this.deltaBuffer) {
+            const freshDeltas = buffer.filter(e => e.timestamp > conflictCutoff);
+            if (freshDeltas.length !== buffer.length) {
+                this.deltaBuffer.set(id, freshDeltas);
+            }
+        }
+        this.lastGC = Date.now();
+        const result = {
+            collected: totalCollected,
+            retained: totalRetained,
+            memoryFreed: totalCollected * 64, // Approximate
+            duration: Date.now() - startTime,
+        };
+        this.emit({
+            type: types_1.CRDTEventType.GarbageCollected,
+            crdtId: '*',
+            crdtType: types_1.CRDTType.ORSet,
+            timestamp: Date.now(),
+            details: result,
+        });
+        return result;
+    }
+    /**
+     * Start automatic garbage collection
+     */
+    startAutoGC() {
+        if (this.gcIntervalHandle) {
+            return;
+        }
+        this.gcIntervalHandle = setInterval(() => {
+            this.gc();
+        }, this.config.gcInterval);
+    }
+    /**
+     * Stop automatic garbage collection
+     */
+    stopAutoGC() {
+        if (this.gcIntervalHandle) {
+            clearInterval(this.gcIntervalHandle);
+            this.gcIntervalHandle = undefined;
+        }
+    }
+    // ============================================
+    // Conflict Tracking
+    // ============================================
+    /**
+     * Add conflicts to history
+     */
+    addConflicts(conflicts) {
+        for (const conflict of conflicts) {
+            this.conflicts.push(conflict);
+            // Trim if too many
+            if (this.conflicts.length > this.config.maxConflicts) {
+                this.conflicts.shift();
+            }
+            this.emit({
+                type: types_1.CRDTEventType.Conflict,
+                crdtId: conflict.crdtId,
+                crdtType: types_1.CRDTType.LWWRegister, // Generic
+                timestamp: Date.now(),
+                details: conflict,
+            });
+        }
+    }
+    /**
+     * Get recent conflicts
+     *
+     * @param limit - Maximum conflicts to return
+     * @returns Array of conflicts
+     */
+    getConflicts(limit) {
+        const l = limit ?? this.conflicts.length;
+        return this.conflicts.slice(-l);
+    }
+    /**
+     * Clear conflict history
+     */
+    clearConflicts() {
+        this.conflicts = [];
+    }
+    // ============================================
+    // CRDT Deletion
+    // ============================================
+    /**
+     * Delete a CRDT from the store
+     *
+     * @param id - CRDT identifier
+     * @returns True if deleted
+     */
+    delete(id) {
+        const instance = this.instances.get(id);
+        if (!instance) {
+            return false;
+        }
+        const type = this.types.get(id);
+        this.instances.delete(id);
+        this.types.delete(id);
+        this.deltaBuffer.delete(id);
+        this.vectorClock.increment();
+        this.emit({
+            type: types_1.CRDTEventType.Deleted,
+            crdtId: id,
+            crdtType: type,
+            timestamp: Date.now(),
+            details: {},
+        });
+        return true;
+    }
+    /**
+     * Clear all CRDTs from the store
+     */
+    clear() {
+        const ids = Array.from(this.instances.keys());
+        for (const id of ids) {
+            this.delete(id);
+        }
+    }
+    // ============================================
+    // Events
+    // ============================================
+    /**
+     * Add an event handler
+     *
+     * @param handler - Event handler function
+     */
+    on(handler) {
+        this.eventHandlers.add(handler);
+    }
+    /**
+     * Remove an event handler
+     *
+     * @param handler - Handler to remove
+     */
+    off(handler) {
+        this.eventHandlers.delete(handler);
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                console.error('CRDT event handler error:', error);
+            }
+        }
+    }
+    // ============================================
+    // Validation
+    // ============================================
+    /**
+     * Check if store has capacity for new CRDT
+     */
+    checkCapacity() {
+        if (this.instances.size >= this.config.maxInstances) {
+            throw new types_1.CRDTError(`Store is full (max ${this.config.maxInstances} instances)`, types_1.CRDTErrorCode.StoreFull);
+        }
+    }
+    /**
+     * Check if ID is available
+     */
+    checkIdAvailable(id) {
+        if (this.instances.has(id)) {
+            throw new types_1.CRDTError(`CRDT with ID '${id}' already exists`, types_1.CRDTErrorCode.InvalidState, id);
+        }
+    }
+    // ============================================
+    // Statistics
+    // ============================================
+    /**
+     * Get store statistics
+     *
+     * @returns Store stats
+     */
+    getStats() {
+        const byType = {
+            [types_1.CRDTType.GCounter]: 0,
+            [types_1.CRDTType.PNCounter]: 0,
+            [types_1.CRDTType.LWWRegister]: 0,
+            [types_1.CRDTType.ORSet]: 0,
+            [types_1.CRDTType.MVRegister]: 0,
+            [types_1.CRDTType.LWWMap]: 0,
+            [types_1.CRDTType.PatternCRDT]: 0,
+        };
+        let totalTombstones = 0;
+        let pendingDeltas = 0;
+        for (const [id, instance] of this.instances) {
+            const type = this.types.get(id);
+            byType[type]++;
+            if (type === types_1.CRDTType.ORSet) {
+                totalTombstones += instance.getTombstoneCount();
+            }
+        }
+        for (const buffer of this.deltaBuffer.values()) {
+            pendingDeltas += buffer.filter(e => !e.applied).length;
+        }
+        return {
+            totalInstances: this.instances.size,
+            byType,
+            totalTombstones,
+            pendingDeltas,
+            totalConflicts: this.conflicts.length,
+            memoryUsage: this.estimateMemoryUsage(),
+            lastGC: this.lastGC,
+            lastSync: this.lastSync,
+        };
+    }
+    /**
+     * Estimate memory usage in bytes
+     */
+    estimateMemoryUsage() {
+        let total = 0;
+        for (const [id, instance] of this.instances) {
+            const type = this.types.get(id);
+            switch (type) {
+                case types_1.CRDTType.GCounter:
+                    total += 64 * instance.getReplicas().length;
+                    break;
+                case types_1.CRDTType.LWWRegister:
+                    total += 128; // Base + value estimate
+                    break;
+                case types_1.CRDTType.ORSet:
+                    total += 64 * instance.size();
+                    total += 32 * instance.getTombstoneCount();
+                    break;
+                case types_1.CRDTType.PatternCRDT:
+                    total += 1024; // Rough estimate
+                    break;
+            }
+        }
+        return total;
+    }
+    /**
+     * Get the replica ID
+     *
+     * @returns Replica ID
+     */
+    getReplicaId() {
+        return this.config.replicaId;
+    }
+    /**
+     * Get the vector clock
+     *
+     * @returns Vector clock copy
+     */
+    getVectorClock() {
+        return this.vectorClock.clone();
+    }
+    /**
+     * Dispose the store
+     */
+    dispose() {
+        this.stopAutoGC();
+        this.clear();
+        this.eventHandlers.clear();
+        this.conflicts = [];
+        this.deltaBuffer.clear();
+    }
+}
+exports.CRDTStore = CRDTStore;
+//# sourceMappingURL=CRDTStore.js.map