@unrdf/knowledge-engine 5.0.1

package/src/canonicalize.mjs

@@ -0,0 +1,414 @@
+/**
+ * @file Canonicalization and isomorphism checks for RDF graphs.
+ * @module canonicalize
+ */
+
+import rdfCanonize from 'rdf-canonize';
+
+/**
+ * Canonicalize a store into URDNA2015 canonical N-Quads.
+ * @param {import('n3').Store} store - The store to canonicalize
+ * @param {Object} [options] - Canonicalization options
+ * @param {string} [options.algorithm='URDNA2015'] - Canonicalization algorithm
+ * @param {boolean} [options.produceGeneralizedRdf=false] - Produce generalized RDF
+ * @param {number} [options.timeoutMs=30000] - Timeout in milliseconds
+ * @returns {Promise<string>} Promise resolving to canonical N-Quads string
+ *
+ * @throws {Error} If canonicalization fails
+ *
+ * @example
+ * const store = new Store();
+ * // ... add quads to store
+ *
+ * const canonical = await canonicalize(store);
+ * console.log('Canonical N-Quads:', canonical);
+ */
+export async function canonicalize(store, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('canonicalize: store must be a valid Store instance');
+  }
+
+  const { algorithm = 'URDNA2015', produceGeneralizedRdf = false, timeoutMs = 30000 } = options;
+
+  try {
+    // Get quads from store and validate
+    const quads = store.getQuads();
+    if (!Array.isArray(quads)) {
+      throw new TypeError('store.getQuads() must return an array');
+    }
+
+    // If store is empty, return empty canonical form
+    if (quads.length === 0) {
+      return '';
+    }
+
+    // Convert store to N-Quads format using Oxigraph dump
+    const nquads = store.dump({ format: 'application/n-quads' });
+
+    // Validate nquads output
+    if (typeof nquads !== 'string' || nquads.trim().length === 0) {
+      throw new TypeError('Serialization produced empty or invalid N-Quads');
+    }
+
+    // Parse N-Quads string to RDF.js dataset format
+    // rdf-canonize expects an array of quad objects, not a string
+    const parsedDataset = rdfCanonize.NQuads.parse(nquads);
+
+    // Set up timeout
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error('Canonicalization timeout')), timeoutMs);
+    });
+
+    // Perform canonicalization with parsed dataset
+    const canonicalPromise = rdfCanonize.canonize(parsedDataset, {
+      algorithm,
+      produceGeneralizedRdf,
+    });
+
+    return await Promise.race([canonicalPromise, timeoutPromise]);
+  } catch (error) {
+    throw new Error(`Canonicalization failed: ${error.message}`);
+  }
+}
+
+/**
+ * Check if two stores are isomorphic (logically equivalent).
+ * @param {import('n3').Store} storeA - First store to compare
+ * @param {import('n3').Store} storeB - Second store to compare
+ * @param {Object} [options] - Comparison options
+ * @param {string} [options.algorithm='URDNA2015'] - Canonicalization algorithm
+ * @param {number} [options.timeoutMs=30000] - Timeout in milliseconds
+ * @returns {Promise<boolean>} Promise resolving to true if stores are isomorphic
+ *
+ * @throws {Error} If comparison fails
+ *
+ * @example
+ * const store1 = new Store();
+ * const store2 = new Store();
+ * // ... add quads to both stores
+ *
+ * const isomorphic = await isIsomorphic(store1, store2);
+ * console.log('Stores are isomorphic:', isomorphic);
+ */
+export async function isIsomorphic(storeA, storeB, options = {}) {
+  if (!storeA || typeof storeA.getQuads !== 'function') {
+    throw new TypeError('isIsomorphic: storeA must be a valid Store instance');
+  }
+  if (!storeB || typeof storeB.getQuads !== 'function') {
+    throw new TypeError('isIsomorphic: storeB must be a valid Store instance');
+  }
+
+  try {
+    // Quick size check first
+    if (storeA.size !== storeB.size) {
+      return false;
+    }
+
+    // If both stores are empty, they are isomorphic
+    if (storeA.size === 0) {
+      return true;
+    }
+
+    // Canonicalize both stores and compare
+    const [canonicalA, canonicalB] = await Promise.all([
+      canonicalize(storeA, options),
+      canonicalize(storeB, options),
+    ]);
+
+    return canonicalA === canonicalB;
+  } catch (error) {
+    throw new Error(`Isomorphism check failed: ${error.message}`);
+  }
+}
+
+/**
+ * Get canonical hash of a store.
+ * @param {import('n3').Store} store - The store to hash
+ * @param {Object} [options] - Hashing options
+ * @param {string} [options.hashAlgorithm='SHA-256'] - Hash algorithm
+ * @param {string} [options.algorithm='URDNA2015'] - Canonicalization algorithm
+ * @returns {Promise<string>} Promise resolving to hexadecimal hash string
+ *
+ * @throws {Error} If hashing fails
+ *
+ * @example
+ * const store = new Store();
+ * // ... add quads to store
+ *
+ * const hash = await getCanonicalHash(store);
+ * console.log('Canonical hash:', hash);
+ */
+export async function getCanonicalHash(store, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('getCanonicalHash: store must be a valid Store instance');
+  }
+
+  const { hashAlgorithm = 'SHA-256', algorithm = 'URDNA2015' } = options;
+
+  // Normalize hash algorithm name for Web Crypto API
+  const normalizeHashAlgorithm = alg => {
+    const normalized = alg.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const map = {
+      sha1: 'SHA-1',
+      sha256: 'SHA-256',
+      sha384: 'SHA-384',
+      sha512: 'SHA-512',
+    };
+    return map[normalized] || alg;
+  };
+
+  try {
+    const canonical = await canonicalize(store, { algorithm });
+
+    // Use Web Crypto API if available, otherwise fall back to Node.js crypto
+    if (typeof crypto !== 'undefined' && crypto.subtle) {
+      const encoder = new TextEncoder();
+      const data = encoder.encode(canonical);
+      const webCryptoAlg = normalizeHashAlgorithm(hashAlgorithm);
+      const hashBuffer = await crypto.subtle.digest(webCryptoAlg, data);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    } else {
+      // Node.js fallback
+      const crypto = await import('node:crypto');
+      const nodeCryptoAlg = hashAlgorithm.toLowerCase().replace('-', '');
+      const hash = crypto.createHash(nodeCryptoAlg);
+      hash.update(canonical);
+      return hash.digest('hex');
+    }
+  } catch (error) {
+    throw new Error(`Canonical hashing failed: ${error.message}`);
+  }
+}
+
+/**
+ * Compare multiple stores and group them by isomorphism.
+ * @param {Array<import('n3').Store>} stores - Array of stores to compare
+ * @param {Object} [options] - Comparison options
+ * @returns {Promise<Array<Object>>} Promise resolving to array of group objects with stores property
+ *
+ * @throws {Error} If comparison fails
+ *
+ * @example
+ * const stores = [store1, store2, store3, store4];
+ * const groups = await groupByIsomorphism(stores);
+ * console.log('Isomorphic groups:', groups);
+ * // Output: [{stores: [store1, store3]}, {stores: [store2]}, {stores: [store4]}]
+ */
+export async function groupByIsomorphism(stores, options = {}) {
+  if (!Array.isArray(stores)) {
+    return [];
+  }
+
+  if (stores.length === 0) {
+    return [];
+  }
+
+  // Validate all stores are valid before processing
+  for (let i = 0; i < stores.length; i++) {
+    if (!stores[i] || typeof stores[i].getQuads !== 'function') {
+      throw new TypeError(`groupByIsomorphism: store at index ${i} must be a valid Store instance`);
+    }
+  }
+
+  try {
+    const groups = [];
+    const processed = new Set();
+
+    for (let i = 0; i < stores.length; i++) {
+      if (processed.has(i)) {
+        continue;
+      }
+
+      const currentGroupStores = [stores[i]];
+      processed.add(i);
+
+      for (let j = i + 1; j < stores.length; j++) {
+        if (processed.has(j)) {
+          continue;
+        }
+
+        try {
+          const isomorphic = await isIsomorphic(stores[i], stores[j], options);
+          if (isomorphic) {
+            currentGroupStores.push(stores[j]);
+            processed.add(j);
+          }
+        } catch (error) {
+          // If comparison fails, treat as non-isomorphic
+          console.warn(`Failed to compare stores ${i} and ${j}: ${error.message}`);
+        }
+      }
+
+      groups.push({ stores: currentGroupStores });
+    }
+
+    return groups;
+  } catch (error) {
+    throw new Error(`Isomorphism grouping failed: ${error.message}`);
+  }
+}
+
+/**
+ * Find duplicate stores in an array.
+ * @param {Array<import('n3').Store>} stores - Array of stores to check
+ * @param {Object} [options] - Comparison options
+ * @returns {Promise<Array<Object>>} Promise resolving to array of duplicate objects with stores and canonicalHash
+ *
+ * @throws {Error} If comparison fails
+ *
+ * @example
+ * const stores = [store1, store2, store3];
+ * const duplicates = await findDuplicates(stores);
+ * if (duplicates.length > 0) {
+ *   console.log('Found duplicate stores:', duplicates);
+ * }
+ */
+export async function findDuplicates(stores, options = {}) {
+  const groups = await groupByIsomorphism(stores, options);
+  const duplicates = [];
+
+  for (const group of groups) {
+    if (group.stores.length > 1) {
+      // Get canonical hash for the group
+      const hash = await getCanonicalHash(group.stores[0], options);
+      duplicates.push({
+        stores: group.stores,
+        canonicalHash: hash,
+      });
+    }
+  }
+
+  return duplicates;
+}
+
+/**
+ * Get canonicalization statistics.
+ * @param {import('n3').Store} store - The store to analyze
+ * @param {Object} [options] - Analysis options
+ * @returns {Promise<Object>} Promise resolving to canonicalization statistics
+ *
+ * @example
+ * const stats = await getCanonicalizationStats(store);
+ * console.log('Store size:', stats.quads);
+ * console.log('Canonical size:', stats.canonicalLength);
+ * console.log('Time:', stats.canonicalizationTime);
+ */
+export async function getCanonicalizationStats(store, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('getCanonicalizationStats: store must be a valid Store instance');
+  }
+
+  const { algorithm = 'URDNA2015' } = options;
+
+  try {
+    const startTime = performance.now();
+    const canonical = await canonicalize(store, { algorithm });
+    const endTime = performance.now();
+
+    return {
+      quads: store.size,
+      canonicalLength: canonical.length,
+      canonicalizationTime: Math.max(endTime - startTime, 0.01), // Ensure non-zero time
+      algorithm,
+    };
+  } catch (error) {
+    throw new Error(`Canonicalization statistics failed: ${error.message}`);
+  }
+}
+
+/**
+ * Create a canonicalization session for batch operations.
+ * @param {Object} [options] - Session options
+ * @returns {Promise<Object>} Canonicalization session
+ *
+ * @example
+ * const session = await createCanonicalizationSession();
+ *
+ * // Direct canonicalization
+ * const canonical = await session.canonicalize(store);
+ *
+ * // Isomorphism check
+ * const isomorphic = await session.isIsomorphic(store1, store2);
+ *
+ * // Get canonical hash
+ * const hash = await session.getCanonicalHash(store);
+ *
+ * // Get session statistics
+ * const stats = session.getStats();
+ */
+export async function createCanonicalizationSession(options = {}) {
+  const sessionOptions = options;
+  let canonicalizationCount = 0;
+  let isomorphismCheckCount = 0;
+  let totalTime = 0;
+
+  return {
+    /**
+     * Canonicalize a store.
+     * @param {import('n3').Store} store - Store to canonicalize
+     * @returns {Promise<string>} Canonical N-Quads
+     */
+    async canonicalize(store) {
+      const startTime = Date.now();
+      try {
+        const result = await canonicalize(store, sessionOptions);
+        canonicalizationCount++;
+        totalTime += Date.now() - startTime;
+        return result;
+      } catch (error) {
+        totalTime += Date.now() - startTime;
+        throw error;
+      }
+    },
+
+    /**
+     * Check if two stores are isomorphic.
+     * @param {import('n3').Store} storeA - First store
+     * @param {import('n3').Store} storeB - Second store
+     * @returns {Promise<boolean>} True if isomorphic
+     */
+    async isIsomorphic(storeA, storeB) {
+      const startTime = Date.now();
+      try {
+        const result = await isIsomorphic(storeA, storeB, sessionOptions);
+        isomorphismCheckCount++;
+        totalTime += Date.now() - startTime;
+        return result;
+      } catch (error) {
+        totalTime += Date.now() - startTime;
+        throw error;
+      }
+    },
+
+    /**
+     * Get canonical hash of a store.
+     * @param {import('n3').Store} store - Store to hash
+     * @returns {Promise<string>} Canonical hash
+     */
+    async getCanonicalHash(store) {
+      const startTime = Date.now();
+      try {
+        const result = await getCanonicalHash(store, sessionOptions);
+        canonicalizationCount++;
+        totalTime += Date.now() - startTime;
+        return result;
+      } catch (error) {
+        totalTime += Date.now() - startTime;
+        throw error;
+      }
+    },
+
+    /**
+     * Get session statistics.
+     * @returns {Object} Session statistics
+     */
+    getStats() {
+      return {
+        canonicalizations: canonicalizationCount,
+        isomorphismChecks: isomorphismCheckCount,
+        totalTime,
+      };
+    },
+  };
+}

package/src/condition-cache.mjs

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Condition Cache - Eliminates duplicate condition evaluation
+ *
+ * @description
+ * Caches SPARQL-ASK condition evaluation results by (hookId, storeVersion)
+ * to eliminate redundant re-evaluation of the same condition.
+ *
+ * Cache Strategy:
+ * - Key: `${hookId}-${storeVersion}`
+ * - Value: boolean (condition satisfied)
+ * - TTL: 60s default (invalidates on store version change)
+ * - Invalidation: Manual clear on store version change
+ *
+ * Expected Impact: 40-50% latency reduction
+ *
+ * @module knowledge-engine/condition-cache
+ */
+
+/**
+ * Condition Cache - Caches SPARQL condition evaluation results
+ *
+ * @class ConditionCache
+ */
+export class ConditionCache {
+  /**
+   * Create a new condition cache
+   * @param {object} options - Configuration options
+   * @param {number} options.ttl - Time-to-live in milliseconds (default: 60000)
+   */
+  constructor(options = {}) {
+    this.cache = new Map(); // `${hookId}-${storeVersion}` → { value, timestamp }
+    this.ttl = options.ttl || 60000; // 60 seconds default
+  }
+
+  /**
+   * Get cached condition result
+   *
+   * Returns undefined if:
+   * - Entry doesn't exist
+   * - Entry has expired (TTL exceeded)
+   *
+   * @param {string} hookId - Hook identifier
+   * @param {string} storeVersion - Store version hash
+   * @returns {boolean|undefined} Cached result or undefined
+   */
+  get(hookId, storeVersion) {
+    if (!hookId || !storeVersion) {
+      return undefined;
+    }
+
+    const key = `${hookId}-${storeVersion}`;
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    // TTL check - if expired, remove and return undefined
+    if (Date.now() - entry.timestamp > this.ttl) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Store condition result in cache
+   *
+   * @param {string} hookId - Hook identifier
+   * @param {string} storeVersion - Store version hash
+   * @param {boolean} value - Evaluation result (true/false)
+   */
+  set(hookId, storeVersion, value) {
+    if (!hookId || !storeVersion) {
+      return;
+    }
+
+    const key = `${hookId}-${storeVersion}`;
+    this.cache.set(key, {
+      value: Boolean(value),
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Clear entire cache (call on store version change)
+   *
+   * This should be called whenever the store is modified
+   * (delta applied, new transaction, etc.)
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {object} Cache stats (size, ttl, entries)
+   */
+  stats() {
+    return {
+      size: this.cache.size,
+      ttl: this.ttl,
+      entries: Array.from(this.cache.keys()),
+    };
+  }
+}
+
+export default ConditionCache;