@revealui/ai 0.1.0

package/dist/memory/preferences/user-preferences-manager.js

@@ -0,0 +1,342 @@
+/**
+ * User Preferences Manager
+ *
+ * Manages user preferences with CRDT support for conflict-free updates
+ * from multiple devices. Uses LWWRegister for last-writer-wins semantics.
+ */
+import { UserPreferencesSchema } from '@revealui/contracts/entities';
+import { eq, users } from '@revealui/db/schema';
+import { LWWRegister } from '../crdt/lww-register.js';
+import { DatabaseConnectionError, DatabaseConstraintError, DatabaseOperationError, NotFoundError, ValidationError, } from '../errors/index.js';
+import { deepClone } from '../utils/deep-clone.js';
+import { createLogger } from '../utils/logger.js';
+import { findUserById } from '../utils/sql-helpers.js';
+// =============================================================================
+// User Preferences Manager
+// =============================================================================
+/**
+ * Manages user preferences with CRDT support.
+ *
+ * Note: This implementation stores CRDT state directly in users.preferences JSONB field.
+ * All preferences must be in CRDT format - legacy format is not supported.
+ *
+ * @example
+ * ```typescript
+ * const manager = new UserPreferencesManager('user-123', 'node-abc', db)
+ * await manager.load()
+ *
+ * await manager.updatePreferences({ theme: 'dark' })
+ * const prefs = manager.getPreferences()
+ *
+ * await manager.save()
+ * ```
+ */
+export class UserPreferencesManager {
+    preferences;
+    userId;
+    nodeId;
+    db;
+    logger = createLogger('[UserPreferences]');
+    /**
+     * Creates a new UserPreferencesManager.
+     *
+     * @param userId - User identifier
+     * @param nodeId - Node identifier (for CRDT operations)
+     * @param db - Database client
+     */
+    constructor(userId, nodeId, db) {
+        this.userId = userId;
+        this.nodeId = nodeId;
+        this.db = db;
+        // Initialize with default preferences
+        const defaultPrefs = {
+            theme: 'system',
+            language: 'en',
+            timezone: 'UTC',
+        };
+        this.preferences = new LWWRegister(nodeId, defaultPrefs);
+    }
+    /**
+     * Gets the current preferences.
+     *
+     * @returns Current user preferences
+     */
+    getPreferences() {
+        return this.preferences.get();
+    }
+    /**
+     * Updates preferences with partial data.
+     * Merges with existing preferences.
+     *
+     * @param updates - Partial preferences updates
+     */
+    updatePreferences(updates) {
+        const current = this.preferences.get();
+        const merged = {
+            ...current,
+            ...updates,
+            // Deep merge for nested objects
+            notifications: updates.notifications
+                ? { ...current.notifications, ...updates.notifications }
+                : current.notifications,
+            editor: updates.editor ? { ...current.editor, ...updates.editor } : current.editor,
+            ai: updates.ai ? { ...current.ai, ...updates.ai } : current.ai,
+        };
+        // Validate before setting
+        const validationResult = UserPreferencesSchema.safeParse(merged);
+        if (!validationResult.success) {
+            throw new ValidationError(`Invalid preferences: ${validationResult.error.message}`);
+        }
+        this.preferences.set(validationResult.data);
+    }
+    /**
+     * Sets entire preferences object.
+     *
+     * @param preferences - Complete preferences object
+     */
+    setPreferences(preferences) {
+        // Validate before setting
+        const validationResult = UserPreferencesSchema.safeParse(preferences);
+        if (!validationResult.success) {
+            throw new ValidationError(`Invalid preferences: ${validationResult.error.message}`);
+        }
+        this.preferences.set(validationResult.data);
+    }
+    /**
+     * Gets a specific preference value.
+     *
+     * @param key - Preference key (supports dot notation for nested keys)
+     * @returns Preference value or undefined
+     */
+    getPreference(key) {
+        const prefs = this.preferences.get();
+        const keys = key.split('.');
+        let value = prefs;
+        for (const k of keys) {
+            if (value && typeof value === 'object' && k in value) {
+                value = value[k];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return value;
+    }
+    /**
+     * Sets a specific preference value.
+     *
+     * @param key - Preference key (supports dot notation for nested keys)
+     * @param value - Preference value
+     */
+    setPreference(key, value) {
+        // Deep clone to avoid mutations
+        const prefs = deepClone(this.preferences.get());
+        const keys = key.split('.');
+        const lastKey = keys[keys.length - 1];
+        if (!lastKey) {
+            throw new ValidationError(`Invalid preference key: "${key}"`);
+        }
+        const parentKeys = keys.slice(0, -1);
+        // Navigate to parent object in cloned structure
+        let parent = prefs;
+        for (const k of parentKeys) {
+            if (!(k in parent) || typeof parent[k] !== 'object' || parent[k] === null) {
+                parent[k] = {};
+            }
+            parent = parent[k];
+        }
+        // Set the value in cloned structure
+        parent[lastKey] = value;
+        // Validate and set
+        const validationResult = UserPreferencesSchema.safeParse(prefs);
+        if (!validationResult.success) {
+            throw new ValidationError(`Invalid preferences after update: ${validationResult.error.message}`);
+        }
+        this.preferences.set(validationResult.data);
+    }
+    /**
+     * Merges another UserPreferencesManager into this one.
+     * Uses CRDT merge for conflict resolution.
+     *
+     * @param other - UserPreferencesManager to merge
+     * @returns New merged UserPreferencesManager
+     */
+    merge(other) {
+        const merged = new UserPreferencesManager(this.userId, this.nodeId, this.db);
+        merged.preferences = this.preferences.merge(other.preferences);
+        return merged;
+    }
+    /**
+     * Loads preferences from database.
+     * Stores CRDT state directly in users.preferences JSONB field.
+     * Requires preferences to be in CRDT format.
+     *
+     * @throws DatabaseConnectionError if database connection fails
+     * @throws DatabaseOperationError if database operation fails
+     * @throws ValidationError if preferences are not in CRDT format
+     */
+    async load() {
+        try {
+            // Load user record (using raw SQL for Neon HTTP compatibility)
+            const user = await findUserById(this.db, this.userId);
+            if (!user) {
+                // User doesn't exist, use defaults
+                return;
+            }
+            // Check if preferences exist
+            if (user.preferences && typeof user.preferences === 'object' && user.preferences !== null) {
+                const prefsRecord = user.preferences;
+                // Check for CRDT state in _crdt field
+                if (prefsRecord._crdt && typeof prefsRecord._crdt === 'object') {
+                    const crdtData = prefsRecord._crdt;
+                    const lwwData = crdtData.lww_register;
+                    if (lwwData && 'value' in lwwData) {
+                        const validationResult = UserPreferencesSchema.safeParse(lwwData.value);
+                        if (validationResult.success) {
+                            this.preferences = LWWRegister.fromData(lwwData);
+                            return;
+                        }
+                    }
+                }
+                // Preferences exist but are not in CRDT format
+                // Per legacy code removal policy, we do not support legacy format
+                throw new ValidationError(`User preferences for ${this.userId} are not in valid CRDT format. ` +
+                    `Expected CRDT structure with _crdt.lww_register.value, but got: ${JSON.stringify(user.preferences).substring(0, 100)}. ` +
+                    `All preferences must be stored in CRDT format.`);
+            }
+        }
+        catch (error) {
+            // Handle specific error types
+            if (error instanceof ValidationError) {
+                throw error;
+            }
+            // Database errors
+            if (error instanceof Error) {
+                const errorMessage = error.message.toLowerCase();
+                if (errorMessage.includes('connection') ||
+                    errorMessage.includes('timeout') ||
+                    errorMessage.includes('econnrefused') ||
+                    errorMessage.includes('connect econnrefused')) {
+                    this.logger.error(`Database connection error loading preferences for user ${this.userId}:`, error);
+                    throw new DatabaseConnectionError('Failed to load user preferences', error);
+                }
+                if (errorMessage.includes('violates') ||
+                    errorMessage.includes('constraint') ||
+                    errorMessage.includes('foreign key')) {
+                    this.logger.error(`Database constraint error loading preferences for user ${this.userId}:`, error);
+                    throw new DatabaseConstraintError('Failed to load user preferences', error);
+                }
+            }
+            // Generic database operation error
+            this.logger.error(`Failed to load preferences for user ${this.userId}:`, error);
+            throw new DatabaseOperationError('Failed to load user preferences', error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Saves preferences to database.
+     * Stores CRDT state directly in users.preferences JSONB field.
+     *
+     * @throws NotFoundError if user does not exist
+     * @throws DatabaseConnectionError if database connection fails
+     * @throws DatabaseConstraintError if database constraint violation occurs
+     * @throws DatabaseOperationError if database operation fails
+     */
+    async save() {
+        try {
+            // Store CRDT state in users.preferences JSONB field
+            // Structure: { _crdt: { lww_register: {...} } }
+            const crdtData = this.preferences.toData();
+            const preferencesValue = {
+                // biome-ignore lint/style/useNamingConvention: _crdt is the CRDT state storage key — internal convention that must not be renamed
+                _crdt: {
+                    lww_register: crdtData,
+                },
+            };
+            // Check if user exists (using raw SQL for Neon HTTP compatibility)
+            const existingUser = await findUserById(this.db, this.userId);
+            if (!existingUser) {
+                throw new NotFoundError(`User ${this.userId}`);
+            }
+            // Update users table with CRDT state in preferences JSONB
+            await this.db
+                .update(users)
+                .set({
+                preferences: preferencesValue,
+                updatedAt: new Date(),
+            })
+                .where(eq(users.id, this.userId));
+        }
+        catch (error) {
+            // Handle specific error types (re-throw as-is)
+            if (error instanceof NotFoundError ||
+                error instanceof DatabaseConnectionError ||
+                error instanceof DatabaseConstraintError ||
+                error instanceof DatabaseOperationError) {
+                throw error;
+            }
+            // Handle database errors
+            if (error instanceof Error) {
+                const errorMessage = error.message.toLowerCase();
+                if (errorMessage.includes('connection') ||
+                    errorMessage.includes('timeout') ||
+                    errorMessage.includes('econnrefused') ||
+                    errorMessage.includes('connect econnrefused')) {
+                    this.logger.error(`Database connection error saving preferences for user ${this.userId}:`, error);
+                    throw new DatabaseConnectionError('Failed to save user preferences', error);
+                }
+                if (errorMessage.includes('violates') ||
+                    errorMessage.includes('constraint') ||
+                    errorMessage.includes('foreign key') ||
+                    errorMessage.includes('duplicate')) {
+                    this.logger.error(`Database constraint error saving preferences for user ${this.userId}:`, error);
+                    throw new DatabaseConstraintError('Failed to save user preferences', error);
+                }
+            }
+            // Generic database operation error
+            this.logger.error(`Failed to save preferences for user ${this.userId}:`, error);
+            throw new DatabaseOperationError('Failed to save user preferences', error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Serializes preferences to plain object.
+     *
+     * @returns Serialized data
+     */
+    toData() {
+        return this.preferences.toData();
+    }
+    /**
+     * Deserializes preferences from plain object.
+     *
+     * @param data - Serialized data
+     * @param userId - User identifier
+     * @param nodeId - Node identifier
+     * @param db - Database client
+     * @returns New UserPreferencesManager instance
+     */
+    static fromData(data, userId, nodeId, db) {
+        const manager = new UserPreferencesManager(userId, nodeId, db);
+        manager.preferences = LWWRegister.fromData(data);
+        return manager;
+    }
+    /**
+     * Creates a copy of this UserPreferencesManager.
+     *
+     * @returns New UserPreferencesManager with same state
+     */
+    clone() {
+        return UserPreferencesManager.fromData(this.toData(), this.userId, this.nodeId, this.db);
+    }
+    /**
+     * Gets the user ID.
+     */
+    getUserId() {
+        return this.userId;
+    }
+    /**
+     * Gets the node ID.
+     */
+    getNodeId() {
+        return this.nodeId;
+    }
+}

package/dist/memory/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Services
+ *
+ * Business logic services for memory operations.
+ */
+export type { EntityType } from './node-id-service.js';
+export { NodeIdService } from './node-id-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/memory/services/index.js

@@ -0,0 +1,6 @@
+/**
+ * Services
+ *
+ * Business logic services for memory operations.
+ */
+export { NodeIdService } from './node-id-service.js';

package/dist/memory/services/node-id-service.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Node ID Service
+ *
+ * Provides deterministic node IDs for CRDT operations using a hybrid approach:
+ * - Primary: SHA-256 hash of entity ID (fast, deterministic, no DB lookup)
+ * - Fallback: Database table for collision resolution and manual management
+ *
+ * This ensures:
+ * - Same entity always gets same node ID (deterministic)
+ * - Collision-resistant (SHA-256 + DB fallback)
+ * - Fast (hash is primary, DB only on collision)
+ */
+import type { Database } from '@revealui/db/client';
+export type EntityType = 'session' | 'user';
+/**
+ * Node ID Service
+ */
+export declare class NodeIdService {
+    private db;
+    constructor(db: Database);
+    /**
+     * Gets or creates a node ID for an entity.
+     *
+     * Strategy:
+     * 1. Generate SHA-256 hash of entityId
+     * 2. Check database for existing mapping
+     * 3. If exists, return stored nodeId
+     * 4. If not, create new mapping with UUID
+     * 5. Handle collisions (same hash, different entityId)
+     *
+     * @param entityType - Type of entity ('session' or 'user')
+     * @param entityId - Entity identifier (sessionId or userId)
+     * @returns Node ID (UUID string)
+     */
+    getNodeId(entityType: EntityType, entityId: string): Promise<string>;
+    /**
+     * Resolves a hash collision (same hash, different entityId).
+     *
+     * Strategy: Generate a new hash using entityType + entityId to ensure uniqueness.
+     *
+     * @param hash - Original hash that collided
+     * @param entityType - Type of entity
+     * @param entityId - Entity identifier
+     * @param attempt - Current collision resolution attempt (default: 1)
+     * @returns Node ID (UUID string)
+     * @throws Error if max collision attempts exceeded
+     */
+    private resolveCollision;
+    /**
+     * Generates SHA-256 hash of entity ID.
+     *
+     * @param entityId - Entity identifier
+     * @returns Hexadecimal hash string (64 characters)
+     */
+    private hashEntityId;
+    /**
+     * Validates input parameters.
+     *
+     * @param entityType - Type of entity
+     * @param entityId - Entity identifier
+     * @throws Error if inputs are invalid
+     */
+    private validateInputs;
+    /**
+     * Retry wrapper for database operations with exponential backoff.
+     *
+     * @param operation - Async operation to retry
+     * @param maxRetries - Maximum number of retry attempts (default: 3)
+     * @param baseDelay - Base delay in milliseconds for exponential backoff (default: 100)
+     * @returns Result of the operation
+     * @throws Error if all retries fail
+     */
+    private withRetry;
+}
+//# sourceMappingURL=node-id-service.d.ts.map

package/dist/memory/services/node-id-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-id-service.d.ts","sourceRoot":"","sources":["../../../src/memory/services/node-id-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAInD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,CAAA;AAE3C;;GAEG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ;IAEhC;;;;;;;;;;;;;OAaG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoC1E;;;;;;;;;;;OAWG;YACW,gBAAgB;IAsD9B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;;;;OAQG;YACW,SAAS;CAuCxB"}

package/dist/memory/services/node-id-service.js

@@ -0,0 +1,190 @@
+/**
+ * Node ID Service
+ *
+ * Provides deterministic node IDs for CRDT operations using a hybrid approach:
+ * - Primary: SHA-256 hash of entity ID (fast, deterministic, no DB lookup)
+ * - Fallback: Database table for collision resolution and manual management
+ *
+ * This ensures:
+ * - Same entity always gets same node ID (deterministic)
+ * - Collision-resistant (SHA-256 + DB fallback)
+ * - Fast (hash is primary, DB only on collision)
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { logger } from '@revealui/core/utils/logger';
+import { nodeIdMappings } from '@revealui/db/schema';
+import { findNodeIdMappingByHash } from '../utils/sql-helpers.js';
+/**
+ * Node ID Service
+ */
+export class NodeIdService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Gets or creates a node ID for an entity.
+     *
+     * Strategy:
+     * 1. Generate SHA-256 hash of entityId
+     * 2. Check database for existing mapping
+     * 3. If exists, return stored nodeId
+     * 4. If not, create new mapping with UUID
+     * 5. Handle collisions (same hash, different entityId)
+     *
+     * @param entityType - Type of entity ('session' or 'user')
+     * @param entityId - Entity identifier (sessionId or userId)
+     * @returns Node ID (UUID string)
+     */
+    async getNodeId(entityType, entityId) {
+        return this.withRetry(async () => {
+            // Validate inputs
+            this.validateInputs(entityType, entityId);
+            // Generate SHA-256 hash
+            const hash = this.hashEntityId(entityId);
+            // Check database for existing mapping (using raw SQL for Neon HTTP compatibility)
+            const existing = await findNodeIdMappingByHash(this.db, hash);
+            if (existing) {
+                // Verify entityId matches (collision detection)
+                if (existing.entityId !== entityId || existing.entityType !== entityType) {
+                    // Collision detected - resolve it
+                    return this.resolveCollision(hash, entityType, entityId, 1);
+                }
+                // Return existing node ID
+                return existing.nodeId;
+            }
+            // No existing mapping - create new one
+            const newNodeId = randomUUID();
+            await this.db.insert(nodeIdMappings).values({
+                id: hash,
+                entityType,
+                entityId,
+                nodeId: newNodeId,
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+            return newNodeId;
+        });
+    }
+    /**
+     * Resolves a hash collision (same hash, different entityId).
+     *
+     * Strategy: Generate a new hash using entityType + entityId to ensure uniqueness.
+     *
+     * @param hash - Original hash that collided
+     * @param entityType - Type of entity
+     * @param entityId - Entity identifier
+     * @param attempt - Current collision resolution attempt (default: 1)
+     * @returns Node ID (UUID string)
+     * @throws Error if max collision attempts exceeded
+     */
+    async resolveCollision(hash, entityType, entityId, attempt = 1) {
+        const MaxCollisionAttempts = 10;
+        if (attempt > MaxCollisionAttempts) {
+            throw new Error(`Failed to resolve node ID collision after ${MaxCollisionAttempts} attempts. ` +
+                `This is extremely rare. Please contact support.`);
+        }
+        // Log collision for monitoring
+        logger.warn('Node ID collision detected', {
+            attempt,
+            maxAttempts: MaxCollisionAttempts,
+            hash,
+            entityType,
+            entityId,
+        });
+        // Generate collision-resistant hash using entityType + entityId
+        const collisionHash = this.hashEntityId(`${entityType}:${entityId}:${attempt}`);
+        // Check if collision hash already exists (using raw SQL for Neon HTTP compatibility)
+        const existing = await findNodeIdMappingByHash(this.db, collisionHash);
+        if (existing) {
+            // Verify this is actually our entity (not another collision)
+            if (existing.entityId === entityId && existing.entityType === entityType) {
+                // This is our mapping - use it
+                return existing.nodeId;
+            }
+            // Another collision - recurse with incremented attempt
+            return this.resolveCollision(collisionHash, entityType, entityId, attempt + 1);
+        }
+        // Create new mapping with collision hash
+        const newNodeId = randomUUID();
+        await this.db.insert(nodeIdMappings).values({
+            id: collisionHash,
+            entityType,
+            entityId,
+            nodeId: newNodeId,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        });
+        return newNodeId;
+    }
+    /**
+     * Generates SHA-256 hash of entity ID.
+     *
+     * @param entityId - Entity identifier
+     * @returns Hexadecimal hash string (64 characters)
+     */
+    hashEntityId(entityId) {
+        return createHash('sha256').update(entityId).digest('hex');
+    }
+    /**
+     * Validates input parameters.
+     *
+     * @param entityType - Type of entity
+     * @param entityId - Entity identifier
+     * @throws Error if inputs are invalid
+     */
+    validateInputs(entityType, entityId) {
+        if (entityType !== 'session' && entityType !== 'user') {
+            throw new Error(`Invalid entityType: ${entityType}. Must be 'session' or 'user'`);
+        }
+        if (!entityId || typeof entityId !== 'string' || entityId.trim().length === 0) {
+            throw new Error(`Invalid entityId: must be a non-empty string`);
+        }
+        // Additional validation: entityId should be reasonable length
+        // Very long entityIds might indicate an attack or data corruption
+        const MaxEntityIdLength = 1000;
+        if (entityId.length > MaxEntityIdLength) {
+            throw new Error(`Invalid entityId: length ${entityId.length} exceeds maximum of ${MaxEntityIdLength} characters`);
+        }
+    }
+    /**
+     * Retry wrapper for database operations with exponential backoff.
+     *
+     * @param operation - Async operation to retry
+     * @param maxRetries - Maximum number of retry attempts (default: 3)
+     * @param baseDelay - Base delay in milliseconds for exponential backoff (default: 100)
+     * @returns Result of the operation
+     * @throws Error if all retries fail
+     */
+    async withRetry(operation, maxRetries = 3, baseDelay = 100) {
+        let lastError = null;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on validation errors
+                if (lastError.message.includes('Invalid')) {
+                    throw lastError;
+                }
+                // Don't retry on collision resolution limit exceeded
+                if (lastError.message.includes('Failed to resolve node ID collision')) {
+                    throw lastError;
+                }
+                // Exponential backoff: 100ms, 200ms, 400ms
+                if (attempt < maxRetries - 1) {
+                    const delay = baseDelay * 2 ** attempt;
+                    logger.warn('Database operation failed, retrying', {
+                        attempt: attempt + 1,
+                        maxRetries,
+                        delay,
+                        error: lastError.message,
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw new Error(`Database operation failed after ${maxRetries} attempts: ${lastError?.message}`);
+    }
+}