@unrdf/knowledge-engine 5.0.1 → 26.4.3

package/src/store-cache.mjs

@@ -1,137 +0,0 @@
-/**
- * @fileoverview Store Cache - Eliminates N×M store conversions
- *
- * @description
- * Caches Oxigraph store instances by version hash to eliminate redundant
- * N3 Store → Oxigraph Store conversions on every SPARQL query.
- *
- * Cache Strategy:
- * - Key: Store version hash (quad count + sampled quad hashes)
- * - Value: Oxigraph store instance
- * - Invalidation: On any delta application
- * - LRU eviction: Maximum 10 entries
- *
- * Expected Impact: 50-70% latency reduction
- *
- * @module knowledge-engine/store-cache
- */
-
-import crypto from 'node:crypto';
-
-/**
- * Simple fast hash function for quad sampling
- * @param {string} text - Text to hash
- * @returns {string} Hex digest
- */
-function quickHash(text) {
-  return crypto.createHash('md5').update(text).digest('hex').slice(0, 8);
-}
-
-/**
- * Store Cache - Oxigraph instance caching by store version
- *
- * @class StoreCache
- */
-export class StoreCache {
-  /**
-   * Create a new store cache
-   * @param {object} options - Configuration options
-   * @param {number} options.maxSize - Maximum cache entries (default: 10)
-   */
-  constructor(options = {}) {
-    this.cache = new Map(); // storeVersion → Oxigraph Store
-    this.currentVersion = null;
-    this.maxSize = options.maxSize || 10;
-  }
-
-  /**
-   * Get store version hash (fast fingerprint)
-   *
-   * Computes a version hash based on:
-   * - Total quad count (main cache key differentiator)
-   * - Hash of first 100 quads + last 100 quads (quick validation)
-   *
-   * @param {Store} store - N3 Store instance
-   * @returns {string} Version hash (format: "count-hash")
-   */
-  getVersion(store) {
-    // Get all quads (this is unavoidable)
-    const quads = store.getQuads();
-    const count = quads.length;
-
-    if (count === 0) {
-      return '0-empty';
-    }
-
-    // Sample quads: first 100 + last 100 for quick validation
-    const sampleStart = Math.min(100, count);
-    const sampleEnd = Math.max(count - 100, sampleStart);
-
-    const sample = [...quads.slice(0, sampleStart), ...quads.slice(sampleEnd)];
-
-    // Hash the string representation of sampled quads
-    const sampleStr = sample
-      .map(q => `${q.subject.value}|${q.predicate.value}|${q.object.value}`)
-      .join('\n');
-
-    const sampleHash = quickHash(sampleStr);
-
-    return `${count}-${sampleHash}`;
-  }
-
-  /**
-   * Get cached Oxigraph store or create new one
-   *
-   * @param {Store} store - N3 Store instance
-   * @param {Function} createStore - Factory function to create Oxigraph store
-   * @returns {object} Oxigraph Store instance
-   */
-  getOrCreate(store, createStore) {
-    const version = this.getVersion(store);
-
-    // Cache hit - return cached Oxigraph store
-    if (this.cache.has(version)) {
-      return this.cache.get(version);
-    }
-
-    // Cache miss - convert ONCE
-    const quads = store.getQuads();
-    const oxStore = createStore(Array.from(quads));
-
-    // Store in cache
-    this.cache.set(version, oxStore);
-    this.currentVersion = version;
-
-    // LRU eviction - remove oldest entry if over capacity
-    if (this.cache.size > this.maxSize) {
-      const firstKey = this.cache.keys().next().value;
-      this.cache.delete(firstKey);
-    }
-
-    return oxStore;
-  }
-
-  /**
-   * Invalidate entire cache
-   * Call this when the store version changes (delta applied)
-   */
-  clear() {
-    this.cache.clear();
-    this.currentVersion = null;
-  }
-
-  /**
-   * Get cache statistics
-   * @returns {object} Cache stats (size, maxSize, currentVersion)
-   */
-  stats() {
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      currentVersion: this.currentVersion,
-      entries: Array.from(this.cache.keys()),
-    };
-  }
-}
-
-export default StoreCache;

package/src/telemetry.mjs

@@ -1,167 +0,0 @@
-/**
- * @fileoverview Batched OTEL Telemetry - Reduces span overhead
- *
- * @description
- * Optimizes OpenTelemetry instrumentation to reduce span creation overhead:
- * - Single parent span per transaction (not per hook)
- * - Async attribute setting (non-blocking)
- * - Conditional instrumentation (disable in production)
- * - Batch flush for pending attributes
- *
- * Expected Impact: 10-15% latency reduction
- *
- * @module knowledge-engine/telemetry
- */
-
-/**
- * Batched OTEL Telemetry for Knowledge Hooks
- *
- * @class BatchedTelemetry
- */
-export class BatchedTelemetry {
-  /**
-   * Create a new batched telemetry instance
-   * @param {object} tracer - OpenTelemetry tracer instance
-   * @param {object} options - Configuration options
-   * @param {boolean} options.enabled - Enable telemetry (default: true if not in production)
-   * @param {number} options.flushInterval - Batch flush interval in ms (default: 10ms)
-   */
-  constructor(tracer, options = {}) {
-    this.tracer = tracer;
-    this.enabled = options.enabled ?? process.env.NODE_ENV !== 'production';
-    this.flushInterval = options.flushInterval ?? 10;
-    this.pendingAttributes = [];
-    this.flushTimeout = null;
-  }
-
-  /**
-   * Start parent span for entire transaction (not per hook)
-   *
-   * @param {string} name - Span name
-   * @param {object} attributes - Initial attributes
-   * @returns {object|null} Span instance or null if disabled
-   */
-  startTransactionSpan(name, attributes = {}) {
-    if (!this.enabled || !this.tracer) {
-      return null;
-    }
-
-    try {
-      return this.tracer.startSpan(name, {
-        attributes: {
-          'hook.transaction': true,
-          ...attributes,
-        },
-      });
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Queue attribute update for batch flush (async, non-blocking)
-   *
-   * Attributes are queued and flushed in batch after flushInterval
-   * to avoid blocking the hot path with span attribute mutations.
-   *
-   * @param {object} span - Span instance
-   * @param {string} key - Attribute key
-   * @param {*} value - Attribute value
-   */
-  setAttribute(span, key, value) {
-    if (!this.enabled || !span) {
-      return;
-    }
-
-    // Queue attribute update
-    this.pendingAttributes.push({ span, key, value });
-
-    // Schedule batch flush if not already scheduled
-    if (!this.flushTimeout) {
-      this.flushTimeout = setTimeout(() => this.flush(), this.flushInterval);
-    }
-  }
-
-  /**
-   * Flush pending attributes in batch
-   *
-   * This reduces the number of span attribute mutations
-   * by batching them together rather than setting each individually.
-   */
-  flush() {
-    try {
-      for (const { span, key, value } of this.pendingAttributes) {
-        try {
-          span.setAttribute(key, value);
-        } catch {
-          // Ignore individual attribute errors
-        }
-      }
-    } finally {
-      this.pendingAttributes = [];
-      this.flushTimeout = null;
-    }
-  }
-
-  /**
-   * Record span event (batched)
-   *
-   * @param {object} span - Span instance
-   * @param {string} name - Event name
-   * @param {object} attributes - Event attributes
-   */
-  recordEvent(span, name, attributes = {}) {
-    if (!this.enabled || !span) {
-      return;
-    }
-
-    try {
-      span.recordEvent(name, attributes);
-    } catch {
-      // Ignore recording errors
-    }
-  }
-
-  /**
-   * End span with status
-   *
-   * @param {object} span - Span instance
-   * @param {string} status - Status code ('ok', 'error', 'unset')
-   * @param {string} message - Status message (optional)
-   */
-  endSpan(span, status = 'ok', message = '') {
-    if (!this.enabled || !span) {
-      return;
-    }
-
-    try {
-      // Flush any pending attributes first
-      if (this.pendingAttributes.length > 0) {
-        this.flush();
-      }
-
-      // End span with status
-      span.setStatus({ code: status, message });
-      span.end();
-    } catch {
-      // Ignore end errors
-    }
-  }
-
-  /**
-   * Disable telemetry (for production or testing)
-   */
-  disable() {
-    this.enabled = false;
-    this.flush();
-  }
-
-  /**
-   * Enable telemetry
-   */
-  enable() {
-    this.enabled = true;
-  }
-}
-
-export default BatchedTelemetry;