cozo-memory 1.1.4 → 1.1.6

package/dist/temporal-conflict-resolution.js

@@ -0,0 +1,386 @@
+"use strict";
+/**
+ * Temporal Conflict Resolution Service
+ *
+ * Inspired by T-GRAG (Li et al., 2025) - Dynamic GraphRAG Framework
+ *
+ * Detects and resolves temporal conflicts in observations:
+ * - Semantic contradictions across time periods
+ * - Redundant information with temporal evolution
+ * - Outdated facts superseded by newer information
+ *
+ * Key Features:
+ * - Embedding-based semantic similarity detection
+ * - Keyword-based contradiction patterns
+ * - Automatic conflict resolution via Validity retraction
+ * - Audit trail preservation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemporalConflictResolutionService = exports.ConflictConfidence = exports.ConflictType = void 0;
+/**
+ * Conflict types
+ */
+var ConflictType;
+(function (ConflictType) {
+    ConflictType["SEMANTIC_CONTRADICTION"] = "semantic_contradiction";
+    ConflictType["TEMPORAL_REDUNDANCY"] = "temporal_redundancy";
+    ConflictType["SUPERSEDED_FACT"] = "superseded_fact";
+})(ConflictType || (exports.ConflictType = ConflictType = {}));
+/**
+ * Confidence level for conflict detection
+ */
+var ConflictConfidence;
+(function (ConflictConfidence) {
+    ConflictConfidence["HIGH"] = "high";
+    ConflictConfidence["MEDIUM"] = "medium";
+    ConflictConfidence["LOW"] = "low";
+})(ConflictConfidence || (exports.ConflictConfidence = ConflictConfidence = {}));
+/**
+ * Contradiction patterns for keyword-based detection
+ */
+const CONTRADICTION_PATTERNS = [
+    // Status contradictions
+    { positive: ['active', 'running', 'ongoing', 'operational', 'continued'],
+        negative: ['inactive', 'discontinued', 'cancelled', 'stopped', 'shut down', 'closed', 'deprecated', 'archived', 'ended', 'abandoned'] },
+    // Boolean contradictions
+    { positive: ['yes', 'true', 'confirmed', 'approved', 'accepted', 'enabled'],
+        negative: ['no', 'false', 'denied', 'rejected', 'refused', 'disabled'] },
+    // Existence contradictions
+    { positive: ['exists', 'present', 'available', 'found', 'located'],
+        negative: ['missing', 'absent', 'unavailable', 'not found', 'removed', 'deleted'] },
+    // Quantity contradictions (detected via numeric comparison)
+    { positive: ['increased', 'grew', 'rose', 'higher', 'more', 'expanded'],
+        negative: ['decreased', 'fell', 'dropped', 'lower', 'less', 'reduced', 'shrunk'] },
+];
+/**
+ * Temporal Conflict Resolution Service
+ */
+class TemporalConflictResolutionService {
+    db;
+    embeddings;
+    config;
+    constructor(db, embeddings, config = {}) {
+        this.db = db;
+        this.embeddings = embeddings;
+        this.config = {
+            similarityThreshold: config.similarityThreshold ?? 0.85,
+            contradictionThreshold: config.contradictionThreshold ?? 0.3,
+            timeWindowDays: config.timeWindowDays ?? 365,
+            autoResolve: config.autoResolve ?? false,
+            preserveAuditTrail: config.preserveAuditTrail ?? true,
+        };
+    }
+    /**
+     * Detect temporal conflicts for an entity
+     */
+    async detectConflicts(entityId) {
+        try {
+            // Get all observations for the entity, ordered by time
+            // Query WITHOUT @ "NOW" to access created_at, then filter manually for valid rows
+            const datalog = `
+        ?[id, text, created_at_ms, embedding] := 
+          *observation{
+            id,
+            created_at,
+            entity_id,
+            text,
+            embedding
+          },
+          entity_id = $entity_id,
+          to_bool(created_at),
+          created_at_ms = to_int(created_at) / 1000
+        
+        :order created_at_ms
+      `;
+            const result = await this.db.run(datalog, { entity_id: entityId });
+            if (result.rows.length < 2) {
+                return []; // Need at least 2 observations to have conflicts
+            }
+            const observations = result.rows.map((row) => ({
+                id: row[0],
+                text: row[1],
+                created_at: row[2], // Now in milliseconds
+                embedding: row[3],
+            }));
+            // Get entity name (query without @ "NOW" and filter manually)
+            const entityResult = await this.db.run(`?[name] := *entity{id, created_at, name}, id = $id, to_bool(created_at)`, { id: entityId });
+            const entityName = entityResult.rows[0]?.[0] || 'Unknown';
+            const conflicts = [];
+            // Compare each pair of observations
+            for (let i = 0; i < observations.length; i++) {
+                for (let j = i + 1; j < observations.length; j++) {
+                    const older = observations[i];
+                    const newer = observations[j];
+                    // Check time window
+                    const timeDiffDays = (newer.created_at - older.created_at) / (1000 * 60 * 60 * 24);
+                    if (timeDiffDays > this.config.timeWindowDays) {
+                        continue; // Outside time window
+                    }
+                    // Calculate semantic similarity
+                    const similarity = this.cosineSimilarity(older.embedding, newer.embedding);
+                    // Detect conflict type
+                    const conflict = this.detectConflictType(older, newer, similarity, entityId, entityName);
+                    if (conflict) {
+                        conflicts.push(conflict);
+                    }
+                }
+            }
+            return conflicts;
+        }
+        catch (error) {
+            console.error('[TemporalConflict] Error detecting conflicts:', error);
+            return [];
+        }
+    }
+    /**
+     * Detect conflict type between two observations
+     */
+    detectConflictType(older, newer, similarity, entityId, entityName) {
+        // Type 1: Temporal Redundancy (very similar, likely duplicate)
+        // Check this FIRST to avoid false contradiction detection
+        if (similarity >= this.config.similarityThreshold) {
+            return {
+                older_observation_id: older.id,
+                newer_observation_id: newer.id,
+                older_text: older.text,
+                newer_text: newer.text,
+                older_time: older.created_at,
+                newer_time: newer.created_at,
+                conflict_type: ConflictType.TEMPORAL_REDUNDANCY,
+                confidence: similarity,
+                confidence_level: this.getConfidenceLevel(similarity),
+                reason: `Highly similar observations (${(similarity * 100).toFixed(1)}% similarity) - likely redundant`,
+                entity_id: entityId,
+                entity_name: entityName,
+            };
+        }
+        // Type 2: Semantic Contradiction (contradiction keywords detected)
+        // Only check if NOT redundant (similarity < threshold)
+        const contradictionScore = this.detectContradictionKeywords(older.text, newer.text);
+        if (contradictionScore > 0.25) { // Lowered threshold from 0.5 to 0.25
+            return {
+                older_observation_id: older.id,
+                newer_observation_id: newer.id,
+                older_text: older.text,
+                newer_text: newer.text,
+                older_time: older.created_at,
+                newer_time: newer.created_at,
+                conflict_type: ConflictType.SEMANTIC_CONTRADICTION,
+                confidence: contradictionScore,
+                confidence_level: this.getConfidenceLevel(contradictionScore),
+                reason: `Contradictory statements detected via keyword analysis`,
+                entity_id: entityId,
+                entity_name: entityName,
+            };
+        }
+        // Type 3: Superseded Fact (moderate similarity, newer info updates older)
+        if (similarity > 0.4 && similarity < 0.85) {
+            // Check if newer observation explicitly supersedes older
+            const supersessionScore = this.detectSupersession(older.text, newer.text);
+            if (supersessionScore > 0.6) {
+                return {
+                    older_observation_id: older.id,
+                    newer_observation_id: newer.id,
+                    older_text: older.text,
+                    newer_text: newer.text,
+                    older_time: older.created_at,
+                    newer_time: newer.created_at,
+                    conflict_type: ConflictType.SUPERSEDED_FACT,
+                    confidence: supersessionScore,
+                    confidence_level: this.getConfidenceLevel(supersessionScore),
+                    reason: `Newer observation updates or supersedes older information`,
+                    entity_id: entityId,
+                    entity_name: entityName,
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Detect contradiction keywords
+     */
+    detectContradictionKeywords(text1, text2) {
+        const lower1 = text1.toLowerCase();
+        const lower2 = text2.toLowerCase();
+        let contradictionCount = 0;
+        let totalChecks = 0;
+        for (const pattern of CONTRADICTION_PATTERNS) {
+            const hasPositive1 = pattern.positive.some(kw => lower1.includes(kw));
+            const hasNegative1 = pattern.negative.some(kw => lower1.includes(kw));
+            const hasPositive2 = pattern.positive.some(kw => lower2.includes(kw));
+            const hasNegative2 = pattern.negative.some(kw => lower2.includes(kw));
+            // Only count if at least one text has a keyword from this pattern
+            if (hasPositive1 || hasNegative1 || hasPositive2 || hasNegative2) {
+                totalChecks++;
+                // Contradiction: one has positive, other has negative
+                if ((hasPositive1 && hasNegative2) || (hasNegative1 && hasPositive2)) {
+                    contradictionCount++;
+                }
+            }
+        }
+        // Return 0 if no patterns were checked, otherwise return ratio
+        return totalChecks === 0 ? 0 : contradictionCount / totalChecks;
+    }
+    /**
+     * Detect if newer observation supersedes older
+     */
+    detectSupersession(olderText, newerText) {
+        const supersessionKeywords = [
+            'updated', 'revised', 'changed', 'modified', 'corrected',
+            'now', 'currently', 'as of', 'latest', 'recent',
+            'replaced', 'superseded', 'obsolete', 'outdated'
+        ];
+        const lowerNewer = newerText.toLowerCase();
+        const matchCount = supersessionKeywords.filter(kw => lowerNewer.includes(kw)).length;
+        return Math.min(matchCount / 3, 1.0); // Normalize to 0-1
+    }
+    /**
+     * Resolve conflicts by invalidating older observations
+     */
+    async resolveConflicts(entityId, conflicts) {
+        try {
+            // Detect conflicts if not provided
+            if (!conflicts) {
+                conflicts = await this.detectConflicts(entityId);
+            }
+            if (conflicts.length === 0) {
+                return {
+                    resolved_conflicts: 0,
+                    invalidated_observations: [],
+                    audit_observations: [],
+                    conflicts: [],
+                };
+            }
+            const invalidatedObservations = [];
+            const auditObservations = [];
+            // Resolve each conflict
+            for (const conflict of conflicts) {
+                // Invalidate older observation
+                await this.invalidateObservation(conflict.older_observation_id);
+                invalidatedObservations.push(conflict.older_observation_id);
+                // Create audit trail if enabled
+                if (this.config.preserveAuditTrail) {
+                    const auditId = await this.createAuditObservation(conflict);
+                    auditObservations.push(auditId);
+                }
+            }
+            console.log(`[TemporalConflict] Resolved ${conflicts.length} conflicts for entity ${entityId}`);
+            return {
+                resolved_conflicts: conflicts.length,
+                invalidated_observations: invalidatedObservations,
+                audit_observations: auditObservations,
+                conflicts,
+            };
+        }
+        catch (error) {
+            console.error('[TemporalConflict] Error resolving conflicts:', error);
+            throw error;
+        }
+    }
+    /**
+     * Invalidate an observation using Validity retraction
+     */
+    async invalidateObservation(observationId) {
+        // Delete the observation (query without @ "NOW" and filter manually)
+        const datalog = `
+      ?[id, created_at, entity_id, text, embedding, metadata] := 
+        *observation{
+          id,
+          created_at,
+          entity_id,
+          text,
+          embedding,
+          metadata
+        },
+        id = $id,
+        to_bool(created_at)
+      
+      :delete observation {
+        id, created_at, entity_id, text, embedding, metadata
+      }
+    `;
+        await this.db.run(datalog, { id: observationId });
+    }
+    /**
+     * Create audit observation for conflict resolution
+     */
+    async createAuditObservation(conflict) {
+        const { v4: uuidv4 } = await import('uuid');
+        const auditId = uuidv4();
+        const now = Date.now() * 1000; // Convert to microseconds
+        const auditText = `[CONFLICT RESOLVED] ${conflict.conflict_type}: Observation superseded by newer information (confidence: ${(conflict.confidence * 100).toFixed(1)}%)`;
+        const embedding = await this.embeddings.embed(auditText);
+        const datalog = `
+      ?[id, created_at, entity_id, text, embedding, metadata] := 
+        id = $id,
+        created_at = $created_at,
+        entity_id = $entity_id,
+        text = $text,
+        embedding = $embedding,
+        metadata = $metadata
+      
+      :put observation {
+        id, created_at => entity_id, text, embedding, metadata
+      }
+    `;
+        await this.db.run(datalog, {
+            id: auditId,
+            created_at: [now, true],
+            entity_id: conflict.entity_id,
+            text: auditText,
+            embedding,
+            metadata: {
+                conflict_resolution: true,
+                conflict_type: conflict.conflict_type,
+                superseded_by: conflict.newer_observation_id,
+                original_observation: conflict.older_observation_id,
+                original_time: conflict.older_time,
+                resolution_time: now / 1000, // Store as milliseconds in metadata
+                confidence: conflict.confidence,
+                reason: conflict.reason,
+            },
+        });
+        return auditId;
+    }
+    /**
+     * Get confidence level from numeric confidence
+     */
+    getConfidenceLevel(confidence) {
+        if (confidence >= 0.8)
+            return ConflictConfidence.HIGH;
+        if (confidence >= 0.5)
+            return ConflictConfidence.MEDIUM;
+        return ConflictConfidence.LOW;
+    }
+    /**
+     * Calculate cosine similarity between two embeddings
+     */
+    cosineSimilarity(vec1, vec2) {
+        if (vec1.length !== vec2.length) {
+            throw new Error('Vectors must have same length');
+        }
+        let dotProduct = 0;
+        let norm1 = 0;
+        let norm2 = 0;
+        for (let i = 0; i < vec1.length; i++) {
+            dotProduct += vec1[i] * vec2[i];
+            norm1 += vec1[i] * vec1[i];
+            norm2 += vec2[i] * vec2[i];
+        }
+        const magnitude = Math.sqrt(norm1) * Math.sqrt(norm2);
+        return magnitude === 0 ? 0 : dotProduct / magnitude;
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.TemporalConflictResolutionService = TemporalConflictResolutionService;