@unrdf/hooks 26.4.8 → 26.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unrdf/hooks",
-  "version": "26.4.8",
+  "version": "26.5.5",
   "description": "UNRDF Knowledge Hooks - Policy Definition and Execution Framework",
   "type": "module",
   "bin": {
@@ -10,7 +10,10 @@
   "exports": {
     ".": "./src/index.mjs",
     "./define": "./src/define.mjs",
-    "./executor": "./src/executor.mjs"
+    "./executor": "./src/executor.mjs",
+    "./parallel-executor": "./src/hooks/parallel-executor.mjs",
+    "./dependency-graph": "./src/hooks/dependency-graph.mjs",
+    "./worker-pool": "./src/hooks/worker-pool.mjs"
   },
   "sideEffects": false,
   "files": [
@@ -48,12 +51,14 @@
   ],
   "dependencies": {
     "@noble/hashes": "^1.4.0",
-    "@unrdf/core": "26.4.4",
-    "@unrdf/oxigraph": "26.4.4",
+    "@opentelemetry/api": "^1.7.0",
+    "@unrdf/core": "workspace:*",
+    "@unrdf/otel": "workspace:*",
+    "@unrdf/oxigraph": "workspace:*",
     "citty": "^0.1.6",
     "eyereasoner": "^10",
     "sparqljs": "^3.7.3",
-    "zod": "^4.1.13"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",

package/src/define.mjs

@@ -48,6 +48,9 @@ export const THRESHOLD = 'threshold';
 /** @type {'count'} Count-based condition */
 export const COUNT = 'count';
 
+/** @type {'semantic-inference'} Open Ontologies reasoning query */
+export const SEMANTIC_INFERENCE = 'semantic-inference';
+
 /** @type {'window'} Sliding window temporal condition */
 export const WINDOW = 'window';
 

package/src/hooks/condition-evaluator.mjs

@@ -403,6 +403,8 @@ export async function evaluateCondition(condition, graph, options = {}) {
         return await evaluateWindow(condition, graph, resolver, env, options);
       case 'n3':
         return await evaluateN3(condition, graph, resolver, env);
+      case 'semantic-inference':
+        return await evaluateSemanticInference(condition, graph, resolver, env);
       default:
         throw new Error(`Unsupported condition kind: ${condition.kind}`);
     }

package/src/hooks/dependency-graph.mjs

@@ -0,0 +1,388 @@
+/**
+ * @file Dependency Graph - Topological sort with cycle detection for parallel hook execution
+ * @module hooks/dependency-graph
+ */
+
+import { z } from 'zod';
+
+/* ========================================================================= */
+/* Zod Schemas                                                              */
+/* ========================================================================= */
+
+export const HookDependencySchema = z.object({
+  hookId: z.string(),
+  dependsOn: z.array(z.string()).optional().default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+/* ========================================================================= */
+/* Dependency Graph Class                                                     */
+/* ========================================================================= */
+
+/**
+ * Dependency graph for topological sorting and cycle detection.
+ *
+ * @class DependencyGraph
+ */
+export class DependencyGraph {
+  /**
+   * Create a new dependency graph.
+   */
+  constructor() {
+    /** @type {Map<string, Set<string>>} - hookId → set of dependencies */
+    this.dependencies = new Map();
+
+    /** @type {Map<string, Set<string>>} - hookId → set of dependents (reverse graph) */
+    this.dependents = new Map();
+
+    /** @type {Set<string>} - all registered hook IDs */
+    this.nodes = new Set();
+  }
+
+  /**
+   * Add a node (hook) to the graph.
+   *
+   * @param {string} hookId - Hook identifier
+   * @param {string[]} [dependencies=[]] - List of hook IDs this hook depends on
+   */
+  addNode(hookId, dependencies = []) {
+    const nodeExists = this.nodes.has(hookId);
+
+    // Initialize dependency and dependent sets
+    this.dependencies.set(hookId, new Set(dependencies));
+    this.dependents.set(hookId, new Set());
+    this.nodes.add(hookId);
+
+    // Update reverse graph (dependents)
+    for (const depId of dependencies) {
+      // Add the dependency as a node if it doesn't exist
+      if (!this.nodes.has(depId)) {
+        this.nodes.add(depId);
+        this.dependencies.set(depId, new Set());
+        this.dependents.set(depId, new Set());
+      }
+
+      // Add current hook as dependent of the dependency
+      this.dependents.get(depId).add(hookId);
+
+      // If node already existed, remove old dependency relationships
+      if (nodeExists) {
+        // Note: We're keeping the new dependencies, so old ones are effectively replaced
+        // The dependents sets are updated above
+      }
+    }
+  }
+
+  /**
+   * Add multiple nodes to the graph.
+   *
+   * @param {Array<{hookId: string, dependsOn?: string[]}>} nodes - Nodes to add
+   */
+  addNodes(nodes) {
+    for (const node of nodes) {
+      this.addNode(node.hookId, node.dependsOn || []);
+    }
+  }
+
+  /**
+   * Remove a node from the graph.
+   *
+   * @param {string} hookId - Hook identifier to remove
+   * @returns {boolean} True if node was removed
+   */
+  removeNode(hookId) {
+    if (!this.nodes.has(hookId)) {
+      return false;
+    }
+
+    // Remove from dependency sets of dependent nodes
+    const dependents = this.dependents.get(hookId) || new Set();
+    for (const dependentId of dependents) {
+      this.dependencies.get(dependentId)?.delete(hookId);
+    }
+
+    // Remove from dependent sets of dependency nodes
+    const dependencies = this.dependencies.get(hookId) || new Set();
+    for (const depId of dependencies) {
+      this.dependents.get(depId)?.delete(hookId);
+    }
+
+    // Clean up maps
+    this.dependencies.delete(hookId);
+    this.dependents.delete(hookId);
+    this.nodes.delete(hookId);
+
+    return true;
+  }
+
+  /**
+   * Check if the graph contains a cycle.
+   *
+   * Uses depth-first search with coloring (white/gray/black) to detect back edges.
+   *
+   * @returns {{hasCycle: boolean, cycle?: string[]}} - Cycle detection result
+   */
+  detectCycle() {
+    const WHITE = 0; // Unvisited
+    const GRAY = 1; // Visiting (in current path)
+    const BLACK = 2; // Visited (not in current path)
+
+    /** @type {Map<string, number>} */
+    const color = new Map();
+
+    // Initialize all nodes as white
+    for (const node of this.nodes) {
+      color.set(node, WHITE);
+    }
+
+    /** @type {string[]} */
+    const cycle = [];
+
+    /**
+     * Depth-first search to detect back edges.
+     *
+     * @param {string} node - Current node
+     * @returns {boolean} - True if cycle found
+     */
+    const dfs = (node) => {
+      color.set(node, GRAY);
+
+      const dependencies = this.dependencies.get(node) || new Set();
+      for (const dep of dependencies) {
+        const depColor = color.get(dep);
+
+        if (depColor === GRAY) {
+          // Back edge found - cycle detected
+          cycle.push(node, dep);
+          return true;
+        }
+
+        if (depColor === WHITE) {
+          if (dfs(dep)) {
+            cycle.push(node);
+            return true;
+          }
+        }
+      }
+
+      color.set(node, BLACK);
+      return false;
+    };
+
+    // Run DFS from each white node
+    for (const node of this.nodes) {
+      if (color.get(node) === WHITE) {
+        if (dfs(node)) {
+          // Reverse to get correct order
+          cycle.reverse();
+          return { hasCycle: true, cycle };
+        }
+      }
+    }
+
+    return { hasCycle: false };
+  }
+
+  /**
+   * Perform topological sort (Kahn's algorithm).
+   *
+   * Returns an array of layers, where each layer contains hooks that can be
+   * executed in parallel. Hooks in layer N depend only on hooks in layers < N.
+   *
+   * @returns {{layers: string[][], hasCycle: boolean, cycle?: string[]}} - Topological sort result
+   */
+  topologicalSort() {
+    // First check for cycles
+    const cycleDetection = this.detectCycle();
+    if (cycleDetection.hasCycle) {
+      return {
+        layers: [],
+        hasCycle: true,
+        cycle: cycleDetection.cycle,
+      };
+    }
+
+    /** @type {Map<string, number>} - hookId → in-degree (number of unmet dependencies) */
+    const inDegree = new Map();
+
+    // Initialize in-degrees
+    for (const node of this.nodes) {
+      const deps = this.dependencies.get(node) || new Set();
+      // Only count dependencies that are actually registered nodes
+      inDegree.set(node, [...deps].filter(dep => this.nodes.has(dep)).length);
+    }
+
+    /** @type {string[]} - Queue of nodes with in-degree 0 */
+    const queue = [];
+
+    // Find all nodes with in-degree 0
+    for (const [node, degree] of inDegree) {
+      if (degree === 0) {
+        queue.push(node);
+      }
+    }
+
+    /** @type {string[][]} - Result layers */
+    const layers = [];
+
+    // Process nodes in batches (layers)
+    while (queue.length > 0) {
+      // Current layer: all nodes currently in queue can execute in parallel
+      layers.push([...queue]);
+
+      // Process all nodes in current layer
+      /** @type {string[]} */
+      const currentLayer = [...queue];
+      queue.length = 0; // Clear queue
+
+      // For each node in current layer, reduce in-degree of its dependents
+      for (const node of currentLayer) {
+        const dependents = this.dependents.get(node) || new Set();
+        for (const dependent of dependents) {
+          const newDegree = (inDegree.get(dependent) || 0) - 1;
+          inDegree.set(dependent, newDegree);
+
+          // If in-degree becomes 0, add to next layer
+          if (newDegree === 0) {
+            queue.push(dependent);
+          }
+        }
+      }
+    }
+
+    // Check if all nodes were processed (should be true if no cycles)
+    const processedCount = layers.reduce((sum, layer) => sum + layer.length, 0);
+    const hasCycle = processedCount !== this.nodes.size;
+
+    return {
+      layers,
+      hasCycle,
+      cycle: hasCycle ? [] : undefined,
+    };
+  }
+
+  /**
+   * Get all dependencies for a hook (transitive closure).
+   *
+   * @param {string} hookId - Hook identifier
+   * @returns {Set<string>} - Set of all transitive dependencies
+   */
+  getTransitiveDependencies(hookId) {
+    const visited = new Set();
+    const result = new Set();
+
+    const dfs = (node) => {
+      if (visited.has(node)) {
+        return;
+      }
+
+      visited.add(node);
+      const deps = this.dependencies.get(node) || new Set();
+      for (const dep of deps) {
+        result.add(dep);
+        dfs(dep);
+      }
+    };
+
+    dfs(hookId);
+    return result;
+  }
+
+  /**
+   * Get all dependents for a hook (transitive closure).
+   *
+   * @param {string} hookId - Hook identifier
+   * @returns {Set<string>} - Set of all transitive dependents
+   */
+  getTransitiveDependents(hookId) {
+    const visited = new Set();
+    const result = new Set();
+
+    const dfs = (node) => {
+      if (visited.has(node)) {
+        return;
+      }
+
+      visited.add(node);
+      const deps = this.dependents.get(node) || new Set();
+      for (const dep of deps) {
+        result.add(dep);
+        dfs(dep);
+      }
+    };
+
+    dfs(hookId);
+    return result;
+  }
+
+  /**
+   * Get statistics about the dependency graph.
+   *
+   * @returns {{nodeCount: number, edgeCount: number, maxDepth: number, avgBranchingFactor: number}}
+   */
+  getStats() {
+    const nodeCount = this.nodes.size;
+    let edgeCount = 0;
+
+    for (const [, deps] of this.dependencies) {
+      edgeCount += deps.size;
+    }
+
+    // Calculate max depth (longest path)
+    const { layers } = this.topologicalSort();
+    const maxDepth = layers.length;
+
+    // Calculate average branching factor (avg dependents per node)
+    const avgBranchingFactor =
+      nodeCount > 0
+        ? [...this.dependents.values()].reduce((sum, deps) => sum + deps.size, 0) / nodeCount
+        : 0;
+
+    return {
+      nodeCount,
+      edgeCount,
+      maxDepth,
+      avgBranchingFactor: parseFloat(avgBranchingFactor.toFixed(2)),
+    };
+  }
+
+  /**
+   * Clear all nodes from the graph.
+   */
+  clear() {
+    this.dependencies.clear();
+    this.dependents.clear();
+    this.nodes.clear();
+  }
+}
+
+/* ========================================================================= */
+/* Factory Functions                                                          */
+/* ========================================================================= */
+
+/**
+ * Create a dependency graph from hook definitions.
+ *
+ * @param {Array<{id: string, dependsOn?: string[]}>} hooks - Hook definitions
+ * @returns {DependencyGraph} - Populated dependency graph
+ */
+export function createDependencyGraph(hooks) {
+  const graph = new DependencyGraph();
+
+  for (const hook of hooks) {
+    graph.addNode(hook.id, hook.dependsOn || []);
+  }
+
+  return graph;
+}
+
+/**
+ * Build execution layers from hooks (convenience function).
+ *
+ * @param {Array<{id: string, dependsOn?: string[]}>} hooks - Hook definitions
+ * @returns {{layers: any[][], hasCycle: boolean, cycle?: string[]}} - Topological sort result
+ */
+export function buildExecutionLayers(hooks) {
+  const graph = createDependencyGraph(hooks);
+  return graph.topologicalSort();
+}

package/src/hooks/observability.mjs

@@ -4,8 +4,7 @@
  *
  * @description
  * Implements comprehensive observability with OpenTelemetry traces, metrics,
- * and logging for the UNRDF Knowledge Engine. Provides backpressure monitoring,
- * error isolation, and performance tracking.
+ * and logging for the UNRDF Knowledge Engine. Uses daemon SDK as single source of truth.
  */
 
 import { _randomUUID } from 'crypto';
@@ -13,6 +12,35 @@ import { _z } from 'zod';
 import { ObservabilityConfigSchema, PerformanceMetricsSchema } from './schemas.mjs';
 import { getRuntimeConfig } from '../context/config.mjs';
 
+// Import daemon SDK functions (single source of truth)
+let getTracer, getMeter;
+try {
+  const daemonSdk = await import('@unrdf/daemon/integrations/otel-sdk.mjs');
+  getTracer = daemonSdk.getTracer;
+  getMeter = daemonSdk.getMeter;
+} catch {
+  // Daemon SDK not available (e.g., in standalone hooks usage)
+  console.warn('[Observability] Daemon SDK not available - will use fallback mode');
+}
+
+// Import generated semantic convention constants
+import {
+  ATTR_UNRDF_HOOK_ID,
+  ATTR_UNRDF_HOOK_NAME,
+  ATTR_UNRDF_HOOK_CONDITION_KIND,
+  ATTR_UNRDF_HOOK_EFFECT_KIND,
+  ATTR_UNRDF_HOOK_ENABLED,
+  ATTR_UNRDF_HOOK_SATISFIED,
+  ATTR_UNRDF_HOOK_PRIORITY,
+  ATTR_UNRDF_HOOK_QUADS_ADDED,
+  ATTR_UNRDF_HOOK_HOOKS_SATISFIED,
+  ATTR_UNRDF_HOOK_HOOKS_TOTAL,
+  ATTR_UNRDF_TRANSACTION_ID,
+  ATTR_UNRDF_TRANSACTION_ISOLATION_LEVEL,
+  ATTR_UNRDF_TRANSACTION_OPERATION_COUNT,
+  ATTR_UNRDF_TRANSACTION_RESULT,
+} from '@unrdf/otel/generated';
+
 /**
  * OpenTelemetry observability manager
  */
@@ -48,63 +76,29 @@ export class ObservabilityManager {
     if (this.initialized) return;
 
     try {
-      // Dynamic import of OpenTelemetry packages
-      const { NodeSDK } = await import('@opentelemetry/sdk-node');
-      const { getNodeAutoInstrumentations } =
-        await import('@opentelemetry/auto-instrumentations-node');
-      const { Resource } = await import('@opentelemetry/resources');
-      const { SemanticResourceAttributes } = await import('@opentelemetry/semantic-conventions');
-      const { OTLPTraceExporter } = await import('@opentelemetry/exporter-otlp-http');
-      const { OTLPMetricExporter } = await import('@opentelemetry/exporter-otlp-http');
-      const { PeriodicExportingMetricReader } = await import('@opentelemetry/sdk-metrics');
-      const { trace, metrics } = await import('@opentelemetry/api');
-
-      // Create resource
-      const resource = new Resource({
-        [SemanticResourceAttributes.SERVICE_NAME]: this.config.serviceName,
-        [SemanticResourceAttributes.SERVICE_VERSION]: this.config.serviceVersion,
-        ...this.config.resourceAttributes,
-      });
-
-      // Create exporters
-      const traceExporter = new OTLPTraceExporter({
-        url: this.config.endpoint ? `${this.config.endpoint}/v1/traces` : undefined,
-        headers: this.config.headers,
-      });
-
-      const metricExporter = new OTLPMetricExporter({
-        url: this.config.endpoint ? `${this.config.endpoint}/v1/metrics` : undefined,
-        headers: this.config.headers,
-      });
-
-      // Create metric reader
-      const metricReader = new PeriodicExportingMetricReader({
-        exporter: metricExporter,
-        exportIntervalMillis: this.config.scheduledDelayMillis,
-        exportTimeoutMillis: this.config.exportTimeoutMillis,
-      });
-
-      // Initialize SDK
-      const sdk = new NodeSDK({
-        resource,
-        traceExporter: this.config.enableTracing ? traceExporter : undefined,
-        metricReader: this.config.enableMetrics ? metricReader : undefined,
-        instrumentations: this.config.enableTracing ? [getNodeAutoInstrumentations()] : [],
-      });
-
-      await sdk.start();
-
-      // Get tracer and meter
-      this.tracer = trace.getTracer(this.config.serviceName, this.config.serviceVersion);
-      this.meter = metrics.getMeter(this.config.serviceName, this.config.serviceVersion);
-
-      // Create custom metrics
-      this._createCustomMetrics();
-
-      this.initialized = true;
-      console.log(`[Observability] Initialized with service: ${this.config.serviceName}`);
+      // Use daemon SDK as single source of truth
+      if (typeof getTracer === 'function' && typeof getMeter === 'function') {
+        this.tracer = getTracer();
+        this.meter = getMeter();
+
+        if (!this.tracer || !this.meter) {
+          console.warn('[Observability] Daemon SDK not initialized - using fallback');
+          this._initializeFallback();
+          return;
+        }
+
+        // Create custom metrics using daemon's meter
+        this._createCustomMetrics();
+
+        this.initialized = true;
+        console.log(`[Observability] Initialized with daemon SDK for service: ${this.config.serviceName}`);
+      } else {
+        // Daemon SDK not available - use fallback
+        console.warn('[Observability] Daemon SDK not available - using fallback mode');
+        this._initializeFallback();
+      }
     } catch (error) {
-      console.warn(`[Observability] Failed to initialize OpenTelemetry: ${error.message}`);
+      console.warn(`[Observability] Failed to initialize with daemon SDK: ${error.message}`);
       // Fallback to console logging
       this._initializeFallback();
     }
@@ -117,42 +111,42 @@ export class ObservabilityManager {
   _createCustomMetrics() {
     if (!this.meter) return;
 
-    // Transaction metrics
-    this.transactionCounter = this.meter.createCounter('kgc_transactions_total', {
+    // Transaction metrics (using unrdf.* prefix from registry)
+    this.transactionCounter = this.meter.createCounter('unrdf_transactions_total', {
       description: 'Total number of transactions processed',
     });
 
-    this.transactionDuration = this.meter.createHistogram('kgc_transaction_duration_ms', {
+    this.transactionDuration = this.meter.createHistogram('unrdf_transaction_duration_ms', {
       description: 'Transaction processing duration in milliseconds',
       unit: 'ms',
     });
 
-    this.hookExecutionCounter = this.meter.createCounter('kgc_hooks_executed_total', {
+    this.hookExecutionCounter = this.meter.createCounter('unrdf_hooks_executed_total', {
       description: 'Total number of hooks executed',
     });
 
-    this.hookDuration = this.meter.createHistogram('kgc_hook_duration_ms', {
+    this.hookDuration = this.meter.createHistogram('unrdf_hook_duration_ms', {
       description: 'Hook execution duration in milliseconds',
       unit: 'ms',
     });
 
-    this.errorCounter = this.meter.createCounter('kgc_errors_total', {
+    this.errorCounter = this.meter.createCounter('unrdf_errors_total', {
       description: 'Total number of errors',
     });
 
-    this.memoryGauge = this.meter.createUpDownCounter('kgc_memory_usage_bytes', {
+    this.memoryGauge = this.meter.createUpDownCounter('unrdf_memory_usage_bytes', {
       description: 'Memory usage in bytes',
     });
 
-    this.cacheHitCounter = this.meter.createCounter('kgc_cache_hits_total', {
+    this.cacheHitCounter = this.meter.createCounter('unrdf_cache_hits_total', {
       description: 'Total cache hits',
     });
 
-    this.cacheMissCounter = this.meter.createCounter('kgc_cache_misses_total', {
+    this.cacheMissCounter = this.meter.createCounter('unrdf_cache_misses_total', {
       description: 'Total cache misses',
     });
 
-    this.queueDepthGauge = this.meter.createUpDownCounter('kgc_queue_depth', {
+    this.queueDepthGauge = this.meter.createUpDownCounter('unrdf_queue_depth', {
       description: 'Current queue depth',
     });
   }
@@ -177,10 +171,9 @@ export class ObservabilityManager {
       return { transactionId, startTime: Date.now() };
     }
 
-    const span = this.tracer.startSpan('kgc.transaction', {
+    const span = this.tracer.startSpan('unrdf.transaction', {
       attributes: {
-        'kgc.transaction.id': transactionId,
-        'kgc.service.name': this.config.serviceName,
+        [ATTR_UNRDF_TRANSACTION_ID]: transactionId,
         ...attributes,
       },
     });
@@ -239,11 +232,11 @@ export class ObservabilityManager {
     }
 
     const parentSpan = this.activeSpans.get(transactionId)?.span;
-    const span = this.tracer.startSpan('kgc.hook', {
+    const span = this.tracer.startSpan('unrdf.hook', {
       parent: parentSpan,
       attributes: {
-        'kgc.hook.id': hookId,
-        'kgc.transaction.id': transactionId,
+        [ATTR_UNRDF_HOOK_ID]: hookId,
+        [ATTR_UNRDF_TRANSACTION_ID]: transactionId,
         ...attributes,
       },
     });