@revealui/ai 0.1.0

package/dist/memory/crdt/lww-register.js

@@ -0,0 +1,169 @@
+/**
+ * Last-Writer-Wins Register (LWW-Register)
+ *
+ * A CRDT that stores a single value where the most recent write wins.
+ * Uses timestamps and node IDs to determine ordering when timestamps are equal.
+ *
+ * IMPORTANT: This register deep clones object/array values to prevent external mutations.
+ * Primitives (strings, numbers, booleans, null) are stored as-is for performance.
+ *
+ * Use cases:
+ * - User preferences
+ * - Agent configurations
+ * - Any single-valued state
+ *
+ * @example
+ * ```typescript
+ * const reg1 = new LWWRegister<string>('node-a', 'initial')
+ * const reg2 = new LWWRegister<string>('node-b', 'initial')
+ *
+ * reg1.set('value-from-a')
+ * reg2.set('value-from-b')
+ *
+ * // Merge resolves to most recent write
+ * const merged = reg1.merge(reg2)
+ * const value = merged.get() // 'value-from-b' (if reg2 was set later)
+ * ```
+ */
+import { randomUUID } from 'node:crypto';
+import { deepClone } from '../utils/deep-clone.js';
+export class LWWRegister {
+    value;
+    timestamp;
+    nodeId;
+    version;
+    /**
+     * Creates a new LWW-Register.
+     * @param nodeId - Unique identifier for this node
+     * @param initialValue - The initial value
+     * @param timestamp - Optional initial timestamp (defaults to now)
+     */
+    constructor(nodeId, initialValue, timestamp) {
+        this.nodeId = nodeId;
+        // Deep clone object/array values to prevent external mutations
+        this.value = this.shouldClone(initialValue) ? deepClone(initialValue) : initialValue;
+        this.timestamp = timestamp ?? Date.now();
+        this.version = 1;
+    }
+    /**
+     * Determines if a value should be deep cloned.
+     * Only objects and arrays need cloning; primitives are safe to store directly.
+     */
+    shouldClone(value) {
+        return value !== null && typeof value === 'object';
+    }
+    /**
+     * Sets a new value with the current timestamp.
+     * Deep clones object/array values to prevent external mutations.
+     * @param value - The new value to set
+     * @param timestamp - Optional explicit timestamp (defaults to now)
+     */
+    set(value, timestamp) {
+        const newTimestamp = timestamp ?? Date.now();
+        // For local sets, always update (increment timestamp if necessary)
+        // This ensures local writes always succeed
+        if (newTimestamp <= this.timestamp) {
+            this.timestamp = this.timestamp + 1;
+        }
+        else {
+            this.timestamp = newTimestamp;
+        }
+        // Deep clone object/array values to prevent external mutations
+        this.value = this.shouldClone(value) ? deepClone(value) : value;
+        this.version++;
+    }
+    /**
+     * Gets the current value.
+     * Returns a deep clone of object/array values to prevent external mutations.
+     * @returns The current value stored in the register (cloned if object/array)
+     */
+    get() {
+        // Deep clone object/array values before returning to prevent external mutations
+        return this.shouldClone(this.value) ? deepClone(this.value) : this.value;
+    }
+    /**
+     * Gets the timestamp of the last update.
+     * @returns The timestamp when the value was last set
+     */
+    getTimestamp() {
+        return this.timestamp;
+    }
+    /**
+     * Gets the current version number.
+     * @returns The number of times this register has been updated
+     */
+    getVersion() {
+        return this.version;
+    }
+    /**
+     * Merges another LWW-Register into this one.
+     * The value with the most recent timestamp wins.
+     * @param other - The register to merge
+     * @returns A new merged LWWRegister
+     */
+    merge(other) {
+        const merged = this.clone();
+        if (other.timestamp > merged.timestamp) {
+            // Deep clone the winning value to prevent mutations
+            merged.value = this.shouldClone(other.value) ? deepClone(other.value) : other.value;
+            merged.timestamp = other.timestamp;
+            merged.version = Math.max(merged.version, other.version) + 1;
+        }
+        else if (other.timestamp === merged.timestamp && other.nodeId > merged.nodeId) {
+            // Tie-break: lexicographically greater node ID wins
+            // Deep clone the winning value to prevent mutations
+            merged.value = this.shouldClone(other.value) ? deepClone(other.value) : other.value;
+            merged.nodeId = other.nodeId;
+            merged.version = Math.max(merged.version, other.version) + 1;
+        }
+        return merged;
+    }
+    /**
+     * Creates a deep copy of this register.
+     * @returns A new LWWRegister with the same state
+     */
+    clone() {
+        const cloned = new LWWRegister(this.nodeId, this.value, this.timestamp);
+        cloned.version = this.version;
+        return cloned;
+    }
+    /**
+     * Serializes the register to a plain object.
+     * @returns A serializable representation
+     */
+    toData() {
+        // Deep clone the value to prevent external mutations of serialized data
+        // This ensures the returned data structure is safe to modify without affecting internal state
+        return {
+            value: this.shouldClone(this.value) ? deepClone(this.value) : this.value,
+            timestamp: this.timestamp,
+            nodeId: this.nodeId,
+            version: this.version,
+        };
+    }
+    /**
+     * Deserializes a register from serialized data.
+     * @param data - The serialized register data
+     * @returns A new LWWRegister instance
+     */
+    static fromData(data) {
+        // Constructor will deep clone object/array values automatically
+        const register = new LWWRegister(data.nodeId, data.value, data.timestamp);
+        register.version = data.version;
+        return register;
+    }
+    /**
+     * Creates a new register with a generated node ID.
+     * @param initialValue - The initial value
+     * @returns A new LWWRegister with a UUID node ID
+     */
+    static create(initialValue) {
+        return new LWWRegister(randomUUID(), initialValue);
+    }
+    /**
+     * Returns a string representation for debugging.
+     */
+    toString() {
+        return `LWWRegister(value=${JSON.stringify(this.value)}, ts=${this.timestamp}, node=${this.nodeId.slice(0, 8)})`;
+    }
+}

package/dist/memory/crdt/or-set.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Observed-Removed Set (OR-Set)
+ *
+ * A CRDT that supports both add and remove operations on a set.
+ * Uses unique tags for each element addition to handle concurrent operations.
+ *
+ * Use cases:
+ * - Collections of memories
+ * - Tags and categories
+ * - Active agent lists
+ * - User sessions
+ *
+ * @example
+ * ```typescript
+ * const set1 = new ORSet<string>('node-a')
+ * const set2 = new ORSet<string>('node-b')
+ *
+ * set1.add('item1')
+ * set2.add('item2')
+ * set1.remove('item1')
+ *
+ * const merged = set1.merge(set2)
+ * merged.values() // ['item2']
+ * ```
+ */
+import { type VectorClockData } from './vector-clock.js';
+export interface ORSetEntry<T> {
+    value: T;
+    tag: string;
+    clock: VectorClockData;
+}
+export interface ORSetData<T> {
+    nodeId: string;
+    added: Record<string, ORSetEntry<T>>;
+    removed: string[];
+}
+export declare class ORSet<T> {
+    private nodeId;
+    private added;
+    private removed;
+    private clock;
+    /**
+     * Creates a new OR-Set.
+     * @param nodeId - Unique identifier for this node
+     */
+    constructor(nodeId: string);
+    /**
+     * Adds an element to the set.
+     * @param element - The element to add
+     * @returns The unique tag for this addition
+     */
+    add(element: T): string;
+    /**
+     * Removes an element by its tag.
+     * @param tag - The unique tag of the element to remove
+     * @returns true if the element was removed
+     */
+    remove(tag: string): boolean;
+    /**
+     * Removes an element by value (removes all instances).
+     * @param element - The element value to remove
+     * @returns Number of instances removed
+     */
+    removeByValue(element: T): number;
+    /**
+     * Checks if a tag is in the set.
+     * @param tag - The unique tag to check
+     * @returns true if the tag exists and hasn't been removed
+     */
+    has(tag: string): boolean;
+    /**
+     * Checks if a value exists in the set.
+     * @param element - The element value to check
+     * @returns true if the value exists
+     */
+    hasValue(element: T): boolean;
+    /**
+     * Gets all tags for a given value.
+     * @param element - The element value to find tags for
+     * @returns Array of tags for the value
+     */
+    getTags(element: T): string[];
+    /**
+     * Gets all current values in the set.
+     * @returns Array of all non-removed values
+     */
+    values(): T[];
+    /**
+     * Gets all entries (with tags) in the set.
+     * @returns Array of [tag, value] tuples
+     */
+    entries(): Array<[string, T]>;
+    /**
+     * Gets the number of elements in the set.
+     */
+    get size(): number;
+    /**
+     * Checks if the set is empty.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Merges another OR-Set into this one.
+     * @param other - The set to merge
+     * @returns A new merged ORSet
+     */
+    merge(other: ORSet<T>): ORSet<T>;
+    /**
+     * Clears all elements from the set.
+     */
+    clear(): void;
+    /**
+     * Creates a copy of this set.
+     * @returns A new ORSet with the same state
+     */
+    clone(): ORSet<T>;
+    /**
+     * Serializes the set to a plain object.
+     * @returns A serializable representation
+     */
+    toData(): ORSetData<T>;
+    /**
+     * Deserializes a set from serialized data.
+     * @param data - The serialized set data
+     * @returns A new ORSet instance
+     */
+    static fromData<T>(data: ORSetData<T>): ORSet<T>;
+    /**
+     * Creates a new OR-Set with a generated node ID.
+     * @returns A new ORSet with a UUID node ID
+     */
+    static create<T>(): ORSet<T>;
+    /**
+     * Deep equality check for complex objects.
+     */
+    private deepEquals;
+    /**
+     * Returns a string representation for debugging.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=or-set.d.ts.map

package/dist/memory/crdt/or-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"or-set.d.ts","sourceRoot":"","sources":["../../../src/memory/crdt/or-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAErE,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAA;IACR,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,eAAe,CAAA;CACvB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;IACpC,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,qBAAa,KAAK,CAAC,CAAC;IAClB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,KAAK,CAAa;IAE1B;;;OAGG;gBACS,MAAM,EAAE,MAAM;IAO1B;;;;OAIG;IACH,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM;IAUvB;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAS5B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM;IAcjC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO;IAS7B;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM,EAAE;IAU7B;;;OAGG;IACH,MAAM,IAAI,CAAC,EAAE;IAUb;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAU7B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAQjB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAkChC;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;OAGG;IACH,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC;IAkBjB;;;OAGG;IACH,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC;IAkBtB;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAiBhD;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;IAI5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAInB"}

package/dist/memory/crdt/or-set.js

@@ -0,0 +1,291 @@
+/**
+ * Observed-Removed Set (OR-Set)
+ *
+ * A CRDT that supports both add and remove operations on a set.
+ * Uses unique tags for each element addition to handle concurrent operations.
+ *
+ * Use cases:
+ * - Collections of memories
+ * - Tags and categories
+ * - Active agent lists
+ * - User sessions
+ *
+ * @example
+ * ```typescript
+ * const set1 = new ORSet<string>('node-a')
+ * const set2 = new ORSet<string>('node-b')
+ *
+ * set1.add('item1')
+ * set2.add('item2')
+ * set1.remove('item1')
+ *
+ * const merged = set1.merge(set2)
+ * merged.values() // ['item2']
+ * ```
+ */
+import { randomUUID } from 'node:crypto';
+import { VectorClock } from './vector-clock.js';
+export class ORSet {
+    nodeId;
+    added;
+    removed;
+    clock;
+    /**
+     * Creates a new OR-Set.
+     * @param nodeId - Unique identifier for this node
+     */
+    constructor(nodeId) {
+        this.nodeId = nodeId;
+        this.added = new Map();
+        this.removed = new Set();
+        this.clock = new VectorClock(nodeId);
+    }
+    /**
+     * Adds an element to the set.
+     * @param element - The element to add
+     * @returns The unique tag for this addition
+     */
+    add(element) {
+        const tag = `${this.nodeId}:${randomUUID()}`;
+        this.clock.tick();
+        this.added.set(tag, {
+            value: element,
+            clock: this.clock.clone(),
+        });
+        return tag;
+    }
+    /**
+     * Removes an element by its tag.
+     * @param tag - The unique tag of the element to remove
+     * @returns true if the element was removed
+     */
+    remove(tag) {
+        if (this.added.has(tag) && !this.removed.has(tag)) {
+            this.removed.add(tag);
+            this.clock.tick();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Removes an element by value (removes all instances).
+     * @param element - The element value to remove
+     * @returns Number of instances removed
+     */
+    removeByValue(element) {
+        let count = 0;
+        for (const [tag, entry] of this.added) {
+            if (this.deepEquals(entry.value, element) && !this.removed.has(tag)) {
+                this.removed.add(tag);
+                count++;
+            }
+        }
+        if (count > 0) {
+            this.clock.tick();
+        }
+        return count;
+    }
+    /**
+     * Checks if a tag is in the set.
+     * @param tag - The unique tag to check
+     * @returns true if the tag exists and hasn't been removed
+     */
+    has(tag) {
+        return this.added.has(tag) && !this.removed.has(tag);
+    }
+    /**
+     * Checks if a value exists in the set.
+     * @param element - The element value to check
+     * @returns true if the value exists
+     */
+    hasValue(element) {
+        for (const [tag, entry] of this.added) {
+            if (this.deepEquals(entry.value, element) && !this.removed.has(tag)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Gets all tags for a given value.
+     * @param element - The element value to find tags for
+     * @returns Array of tags for the value
+     */
+    getTags(element) {
+        const tags = [];
+        for (const [tag, entry] of this.added) {
+            if (this.deepEquals(entry.value, element) && !this.removed.has(tag)) {
+                tags.push(tag);
+            }
+        }
+        return tags;
+    }
+    /**
+     * Gets all current values in the set.
+     * @returns Array of all non-removed values
+     */
+    values() {
+        const values = [];
+        for (const [tag, entry] of this.added) {
+            if (!this.removed.has(tag)) {
+                values.push(entry.value);
+            }
+        }
+        return values;
+    }
+    /**
+     * Gets all entries (with tags) in the set.
+     * @returns Array of [tag, value] tuples
+     */
+    entries() {
+        const entries = [];
+        for (const [tag, entry] of this.added) {
+            if (!this.removed.has(tag)) {
+                entries.push([tag, entry.value]);
+            }
+        }
+        return entries;
+    }
+    /**
+     * Gets the number of elements in the set.
+     */
+    get size() {
+        let count = 0;
+        for (const tag of this.added.keys()) {
+            if (!this.removed.has(tag)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Checks if the set is empty.
+     */
+    get isEmpty() {
+        return this.size === 0;
+    }
+    /**
+     * Merges another OR-Set into this one.
+     * @param other - The set to merge
+     * @returns A new merged ORSet
+     */
+    merge(other) {
+        const merged = new ORSet(this.nodeId);
+        // Merge clocks
+        merged.clock = this.clock.clone();
+        merged.clock.merge(other.clock);
+        // Union of added elements
+        for (const [tag, entry] of this.added) {
+            merged.added.set(tag, {
+                value: entry.value,
+                clock: entry.clock.clone(),
+            });
+        }
+        for (const [tag, entry] of other.added) {
+            if (!merged.added.has(tag)) {
+                merged.added.set(tag, {
+                    value: entry.value,
+                    clock: entry.clock.clone(),
+                });
+            }
+        }
+        // Union of removed tags
+        for (const tag of this.removed) {
+            merged.removed.add(tag);
+        }
+        for (const tag of other.removed) {
+            merged.removed.add(tag);
+        }
+        return merged;
+    }
+    /**
+     * Clears all elements from the set.
+     */
+    clear() {
+        for (const tag of this.added.keys()) {
+            this.removed.add(tag);
+        }
+        this.clock.tick();
+    }
+    /**
+     * Creates a copy of this set.
+     * @returns A new ORSet with the same state
+     */
+    clone() {
+        const cloned = new ORSet(this.nodeId);
+        cloned.clock = this.clock.clone();
+        for (const [tag, entry] of this.added) {
+            cloned.added.set(tag, {
+                value: entry.value,
+                clock: entry.clock.clone(),
+            });
+        }
+        for (const tag of this.removed) {
+            cloned.removed.add(tag);
+        }
+        return cloned;
+    }
+    /**
+     * Serializes the set to a plain object.
+     * @returns A serializable representation
+     */
+    toData() {
+        const added = {};
+        for (const [tag, entry] of this.added) {
+            added[tag] = {
+                value: entry.value,
+                tag,
+                clock: entry.clock.toData(),
+            };
+        }
+        return {
+            nodeId: this.nodeId,
+            added,
+            removed: Array.from(this.removed),
+        };
+    }
+    /**
+     * Deserializes a set from serialized data.
+     * @param data - The serialized set data
+     * @returns A new ORSet instance
+     */
+    static fromData(data) {
+        const set = new ORSet(data.nodeId);
+        for (const [tag, entry] of Object.entries(data.added)) {
+            set.added.set(tag, {
+                value: entry.value,
+                clock: VectorClock.fromData(entry.clock, data.nodeId),
+            });
+        }
+        for (const tag of data.removed) {
+            set.removed.add(tag);
+        }
+        return set;
+    }
+    /**
+     * Creates a new OR-Set with a generated node ID.
+     * @returns A new ORSet with a UUID node ID
+     */
+    static create() {
+        return new ORSet(randomUUID());
+    }
+    /**
+     * Deep equality check for complex objects.
+     */
+    deepEquals(a, b) {
+        if (a === b)
+            return true;
+        if (typeof a !== typeof b)
+            return false;
+        if (typeof a !== 'object' || a === null)
+            return false;
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    /**
+     * Returns a string representation for debugging.
+     */
+    toString() {
+        const values = this.values();
+        return `ORSet(size=${this.size}, values=[${values.map((v) => JSON.stringify(v)).join(', ')}])`;
+    }
+}