@unrdf/hooks 26.4.2 → 26.4.4

package/src/hooks/self-play-autonomics.mjs

@@ -0,0 +1,423 @@
+/**
+ * @file Knowledge Hooks Self-Play Autonomics
+ * @module @unrdf/hooks/self-play-autonomics
+ * @description Autonomous feedback loops where hook conditions trigger effects which mutate the RDF store
+ *
+ * Enables closed-loop knowledge engineering:
+ * 1. Evaluate conditions (SPARQL ASK/SELECT, SHACL, delta, threshold, ...)
+ * 2. Execute satisfied effects (SPARQL CONSTRUCT mutations)
+ * 3. Store changes produce receipt (BLAKE3 hash, linked chain)
+ * 4. Re-evaluate conditions until goal or no-op
+ */
+
+import { randomUUID } from 'crypto';
+import { evaluateCondition } from './condition-evaluator.mjs';
+import { KnowledgeHookEngine } from './knowledge-hook-engine.mjs';
+import { ask, select, construct } from './query.mjs';
+
+/**
+ * Build a self-play toolRegistry from knowledge hooks
+ * Returns structured ChainResult objects instead of CLI strings
+ *
+ * @param {Object} store - RDF store (N3 or Oxigraph)
+ * @param {Array} hooks - Array of KnowledgeHook definitions
+ * @returns {Object} toolRegistry { toolName: { handler, schema } }
+ */
+export function buildHooksToolRegistry(store, _hooks = []) {
+  const engine = new KnowledgeHookEngine(store);
+
+  return {
+    hooks_evaluate_conditions: {
+      handler: async ({ store: evalStore, hooks: evalHooks }) => {
+        // Evaluate all conditions and collect results
+        const conditionResults = [];
+        const satisfied = [];
+
+        for (const hook of evalHooks) {
+          try {
+            const result = await evaluateCondition(hook.condition, evalStore);
+            conditionResults.push({
+              hookName: hook.name,
+              condition: hook.condition,
+              satisfied: result,
+            });
+
+            if (result) {
+              satisfied.push(hook);
+            }
+          } catch (err) {
+            conditionResults.push({
+              hookName: hook.name,
+              condition: hook.condition,
+              satisfied: false,
+              error: err.message,
+            });
+          }
+        }
+
+        const successRate = evalHooks.length > 0 ? satisfied.length / evalHooks.length : 0;
+
+        return {
+          conditionResults,
+          satisfied,
+          successRate,
+        };
+      },
+    },
+
+    hooks_execute_effects: {
+      handler: async ({ store: _execStore, hooks: execHooks, delta: _delta }) => {
+        // Execute hooks with receipt chaining
+        const context = {
+          nodeId: 'self-play-autonomics',
+          t_ns: BigInt(Date.now() * 1000000),
+        };
+
+        try {
+          const result = await engine.execute(context, execHooks);
+
+          return {
+            executionResults: execHooks.map(h => ({
+              hookName: h.name,
+              status: 'executed',
+            })),
+            receipt: {
+              receiptHash: result.receipt.receiptHash,
+              input_hash: result.receipt.input_hash,
+              output_hash: result.receipt.output_hash,
+              previousReceiptHash: result.receipt.previousReceiptHash || null,
+              hooksExecuted: result.successful + result.failed,
+              successful: result.successful,
+              failed: result.failed,
+              delta: result.receipt.delta,
+              timestamp: result.receipt.timestamp,
+            },
+          };
+        } catch (err) {
+          return {
+            executionResults: execHooks.map(h => ({
+              hookName: h.name,
+              status: 'failed',
+              error: err.message,
+            })),
+            receipt: null,
+            error: err.message,
+          };
+        }
+      },
+    },
+
+    hooks_query: {
+      handler: async ({ store: queryStore, query: sparqlQuery, kind = 'sparql-ask' }) => {
+        // Execute SPARQL query based on kind
+        try {
+          let result;
+
+          switch (kind.toLowerCase()) {
+            case 'sparql-ask':
+            case 'ask':
+              result = await ask(queryStore, sparqlQuery);
+              break;
+
+            case 'sparql-select':
+            case 'select':
+              result = await select(queryStore, sparqlQuery);
+              break;
+
+            case 'sparql-construct':
+            case 'construct':
+              result = await construct(queryStore, sparqlQuery);
+              break;
+
+            default:
+              // Default to ASK
+              result = await ask(queryStore, sparqlQuery);
+          }
+
+          return {
+            result,
+            kind,
+            success: true,
+          };
+        } catch (err) {
+          return {
+            result: null,
+            kind,
+            success: false,
+            error: err.message,
+          };
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Create a decision policy that reads hook results and branches intelligently
+ *
+ * @param {Function} goalCondition - async (store, previousResult) => boolean
+ * @returns {Function} decisionFn(episode, previousResult) => { toolName, input } | null
+ */
+export function createHooksAwarePolicy(goalCondition = async () => false) {
+  return async (episode, previousResult) => {
+    const stepCount = episode.steps.length;
+    const { store, hooks } = episode.context;
+
+    // Step 0: always evaluate conditions first
+    if (stepCount === 0) {
+      return {
+        toolName: 'hooks_evaluate_conditions',
+        input: { store, hooks },
+      };
+    }
+
+    // Step 1: if conditions satisfied, execute effects; else terminate
+    if (stepCount === 1) {
+      const { satisfied } = previousResult || {};
+      if (!satisfied || satisfied.length === 0) {
+        return null; // No conditions to satisfy
+      }
+
+      return {
+        toolName: 'hooks_execute_effects',
+        input: { store, hooks, delta: { adds: 0, deletes: 0 } },
+      };
+    }
+
+    // Step 2+: check goal condition
+    if (stepCount >= 2) {
+      if (await goalCondition(store, previousResult)) {
+        episode.recordFeedback(1.0, 'goal condition satisfied');
+        return null; // Success
+      }
+
+      // Re-evaluate to see if more conditions fire
+      return {
+        toolName: 'hooks_evaluate_conditions',
+        input: { store, hooks },
+      };
+    }
+
+    return null;
+  };
+}
+
+/**
+ * Compute feedback signal based on hook execution outcome
+ *
+ * @param {Object} executionResult - from hooks_execute_effects
+ * @param {Object} previousResult - from hooks_evaluate_conditions
+ * @returns {number} feedback signal (-1 to 1)
+ */
+export function computeHooksFeedback(executionResult, _previousResult) {
+  if (!executionResult) return -0.5; // Execution failed
+
+  const { receipt } = executionResult;
+  if (!receipt) return 0; // No-op
+
+  const { hooksExecuted, successful, failed } = receipt;
+
+  if (failed > 0) return -0.3; // Some failures
+  if (successful === 0) return 0; // No hooks ran (no-op)
+  if (hooksExecuted > 0) return 0.1 + 0.1 * Math.min(successful / hooksExecuted, 1); // Pro-rata success
+
+  return 0;
+}
+
+/**
+ * Receipt chain node
+ */
+class ReceiptChainNode {
+  constructor(receipt, previousNode = null) {
+    this.receiptHash = receipt.receiptHash;
+    this.input_hash = receipt.input_hash;
+    this.output_hash = receipt.output_hash;
+    this.previousReceiptHash = previousNode?.receiptHash || receipt.previousReceiptHash || null;
+    this.timestamp = receipt.timestamp || new Date().toISOString();
+    this.delta = receipt.delta;
+    this.hooksExecuted = receipt.hooksExecuted;
+  }
+
+  toJSON() {
+    return {
+      receiptHash: this.receiptHash,
+      input_hash: this.input_hash,
+      output_hash: this.output_hash,
+      previousReceiptHash: this.previousReceiptHash,
+      timestamp: this.timestamp,
+      delta: this.delta,
+      hooksExecuted: this.hooksExecuted,
+    };
+  }
+}
+
+/**
+ * Run full autonomous hooks loop across multiple episodes
+ *
+ * @param {Object} store - RDF store (shared across episodes)
+ * @param {Array} hookDefinitions - KnowledgeHook array
+ * @param {Object} options - { goalCondition, episodeCount, maxStepsPerEpisode, onEpisodeEnd }
+ * @returns {Promise<Object>} { episodes, finalStore, receiptChain, stats }
+ */
+export async function runHooksAutonomics(store, hookDefinitions = [], options = {}) {
+  const {
+    goalCondition = async () => false,
+    episodeCount = 3,
+    maxStepsPerEpisode = 10,
+    onEpisodeEnd = () => {},
+  } = options;
+
+  // Build tool registry
+  const toolRegistry = buildHooksToolRegistry(store, hookDefinitions);
+
+  // Create decision policy
+  const decisionFn = createHooksAwarePolicy(goalCondition);
+
+  // Track receipt chain
+  const receiptChain = [];
+  let previousReceiptNode = null;
+
+  const episodes = [];
+
+  for (let e = 0; e < episodeCount; e++) {
+    const episode = {
+      episodeId: randomUUID(),
+      stepCount: 0,
+      stepResults: [],
+      feedback: [],
+      terminated: false,
+      terminationReason: null,
+      timestamp: new Date().toISOString(),
+    };
+
+    const context = {
+      store,
+      hooks: hookDefinitions,
+    };
+
+    let previousResult = null;
+
+    for (let step = 0; step < maxStepsPerEpisode; step++) {
+      if (episode.terminated) break;
+
+      // Decide next tool
+      const decision = await decisionFn(
+        {
+          steps: episode.stepResults,
+          context,
+          recordFeedback: (s, r) => episode.feedback.push({ signal: s, reason: r }),
+        },
+        previousResult
+      );
+
+      if (!decision) {
+        episode.terminated = true;
+        episode.terminationReason = 'no more decisions';
+        episode.feedback.push({ signal: 0, reason: 'terminated: no more decisions' });
+        break;
+      }
+
+      const { toolName, input } = decision;
+
+      // Execute tool
+      const stepStartTime = Date.now();
+      try {
+        const tool = toolRegistry[toolName];
+        if (!tool) {
+          episode.terminated = true;
+          episode.terminationReason = `unknown tool: ${toolName}`;
+          episode.feedback.push({ signal: -1, reason: `unknown tool: ${toolName}` });
+          break;
+        }
+
+        const result = await tool.handler(input);
+        const duration = Date.now() - stepStartTime;
+
+        episode.stepResults.push({
+          stepId: randomUUID(),
+          toolName,
+          input,
+          output: result,
+          duration,
+          timestamp: new Date().toISOString(),
+          success: true,
+        });
+
+        previousResult = result;
+
+        // Record receipt if present
+        if (result?.receipt) {
+          const receiptNode = new ReceiptChainNode(result.receipt, previousReceiptNode);
+          receiptChain.push(receiptNode.toJSON());
+          previousReceiptNode = receiptNode;
+        }
+
+        // Compute feedback
+        const feedback = computeHooksFeedback(result, previousResult);
+        episode.feedback.push({
+          signal: feedback,
+          reason: `${toolName} succeeded`,
+        });
+      } catch (err) {
+        const duration = Date.now() - stepStartTime;
+
+        episode.stepResults.push({
+          stepId: randomUUID(),
+          toolName,
+          input,
+          output: null,
+          duration,
+          timestamp: new Date().toISOString(),
+          success: false,
+          error: err.message,
+        });
+
+        episode.terminated = true;
+        episode.terminationReason = `tool failed: ${toolName}`;
+        episode.feedback.push({ signal: -0.5, reason: `${toolName} failed: ${err.message}` });
+      }
+
+      episode.stepCount++;
+    }
+
+    if (!episode.terminated && episode.stepCount >= maxStepsPerEpisode) {
+      episode.terminated = true;
+      episode.terminationReason = 'max steps reached';
+      episode.feedback.push({ signal: 0, reason: 'max steps reached' });
+    }
+
+    // Calculate metrics
+    const totalFeedback = episode.feedback.reduce((sum, f) => sum + f.signal, 0);
+    const avgFeedback = episode.feedback.length > 0 ? totalFeedback / episode.feedback.length : 0;
+
+    episode.metrics = {
+      stepCount: episode.stepCount,
+      feedbackCount: episode.feedback.length,
+      totalFeedback,
+      avgFeedback,
+    };
+
+    episodes.push(episode);
+    await onEpisodeEnd(episode);
+  }
+
+  // Calculate stats
+  const totalFeedback = episodes.reduce((sum, ep) => sum + ep.metrics.totalFeedback, 0);
+  const successCount = episodes.filter(ep => ep.metrics.totalFeedback > 0).length;
+
+  const stats = {
+    totalEpisodes: episodes.length,
+    successCount,
+    successRate: episodes.length > 0 ? successCount / episodes.length : 0,
+    totalFeedback,
+    avgFeedback: episodes.length > 0 ? totalFeedback / episodes.length : 0,
+    receiptChainLength: receiptChain.length,
+  };
+
+  return {
+    episodes,
+    finalStore: store,
+    receiptChain,
+    stats,
+  };
+}

package/src/hooks/telemetry.mjs

@@ -48,10 +48,7 @@ export class BatchedTelemetry {
 
     try {
       return this.tracer.startSpan(name, {
-        attributes: {
-          'hook.transaction': true,
-          ...attributes,
-        },
+        attributes,
       });
     } catch {
       return null;
@@ -68,7 +65,7 @@ export class BatchedTelemetry {
    * @param {string} key - Attribute key
    * @param {*} value - Attribute value
    */
-  setAttribute(span, key, value) {
+  addPendingAttribute(span, key, value) {
     if (!this.enabled || !span) {
       return;
     }
@@ -78,7 +75,7 @@ export class BatchedTelemetry {
 
     // Schedule batch flush if not already scheduled
     if (!this.flushTimeout) {
-      this.flushTimeout = setTimeout(() => this.flush(), this.flushInterval);
+      this.flushTimeout = setTimeout(() => this.flushPendingAttributes(), this.flushInterval);
     }
   }
 
@@ -88,7 +85,7 @@ export class BatchedTelemetry {
    * This reduces the number of span attribute mutations
    * by batching them together rather than setting each individually.
    */
-  flush() {
+  flushPendingAttributes() {
     try {
       for (const { span, key, value } of this.pendingAttributes) {
         try {
@@ -137,7 +134,7 @@ export class BatchedTelemetry {
     try {
       // Flush any pending attributes first
       if (this.pendingAttributes.length > 0) {
-        this.flush();
+        this.flushPendingAttributes();
       }
 
       // End span with status
@@ -148,12 +145,24 @@ export class BatchedTelemetry {
     }
   }
 
+  /**
+   * Cleanup telemetry (flush and clear state)
+   */
+  cleanup() {
+    if (this.flushTimeout) {
+      clearTimeout(this.flushTimeout);
+      this.flushTimeout = null;
+    }
+    this.flushPendingAttributes();
+    this.pendingAttributes = [];
+  }
+
   /**
    * Disable telemetry (for production or testing)
    */
   disable() {
     this.enabled = false;
-    this.flush();
+    this.cleanup();
   }
 
   /**
@@ -162,6 +171,20 @@ export class BatchedTelemetry {
   enable() {
     this.enabled = true;
   }
+
+  /**
+   * Alias for addPendingAttribute (backward compatibility)
+   */
+  setAttribute(span, key, value) {
+    return this.addPendingAttribute(span, key, value);
+  }
+
+  /**
+   * Alias for flushPendingAttributes (backward compatibility)
+   */
+  flush() {
+    return this.flushPendingAttributes();
+  }
 }
 
 export default BatchedTelemetry;

package/src/hooks/validate.mjs

@@ -3,56 +3,104 @@
  * @module hooks/validate
  *
  * @description
- * Provides SHACL validation against RDF stores.
- * This is a simplified implementation - full SHACL validation would require a dedicated library.
+ * Full SHACL validation using rdf-validate-shacl against Oxigraph-backed RDF stores.
+ * Supports minCount, maxCount, datatype, and other SHACL Core constraints.
+ * Caches parsed shape validators for performance.
  */
 
+import SHACLValidator from 'rdf-validate-shacl';
+import oxigraph from 'oxigraph';
+
+const SHACL_NS = 'http://www.w3.org/ns/shacl#';
+
+// Severity URI to short string mapping
+const SEVERITY_MAP = {
+  [`${SHACL_NS}Violation`]: 'violation',
+  [`${SHACL_NS}Warning`]: 'warning',
+  [`${SHACL_NS}Info`]: 'info',
+};
+
+// Cache parsed SHACLValidator instances keyed by shapes string
+const validatorCache = new Map();
+const CACHE_MAX_SIZE = 50;
+
 /**
- * Validate RDF data against SHACL shapes
+ * Get or create a cached SHACLValidator for the given shapes Turtle string.
  *
- * @param {object} dataStore - RDF store containing data to validate
+ * @param {string} shapesString - SHACL shapes as Turtle
+ * @returns {SHACLValidator} Cached validator instance
+ */
+function getValidator(shapesString) {
+  let validator = validatorCache.get(shapesString);
+  if (validator) {
+    return validator;
+  }
+
+  const shapesStore = new oxigraph.Store();
+  shapesStore.load(shapesString, { format: 'text/turtle' });
+  const shapesQuads = shapesStore.match(null, null, null, null);
+
+  validator = new SHACLValidator(shapesQuads);
+
+  // Evict oldest entry if cache is full
+  if (validatorCache.size >= CACHE_MAX_SIZE) {
+    const firstKey = validatorCache.keys().next().value;
+    validatorCache.delete(firstKey);
+  }
+  validatorCache.set(shapesString, validator);
+
+  return validator;
+}
+
+/**
+ * Validate RDF data against SHACL shapes.
+ *
+ * @param {object} dataStore - RDF store containing data to validate (OxigraphStore or raw oxigraph.Store)
  * @param {string} shapesString - SHACL shapes as Turtle string
  * @param {object} options - Validation options
  * @param {boolean} options.strict - Enable strict validation mode
  * @param {boolean} options.includeDetails - Include validation details in report
- * @returns {object} SHACL validation report
+ * @returns {Promise<object>} SHACL validation report
  */
-export function validateShacl(dataStore, shapesString, options = {}) {
-  const { strict = false, includeDetails = true } = options;
-
-  // Simplified SHACL validation
-  // In production, use a full SHACL validator like rdf-validate-shacl
-
-  const report = {
-    conforms: true,
-    results: [],
-    timestamp: new Date().toISOString(),
-  };
+export async function validateShacl(dataStore, shapesString, options = {}) {
+  const { includeDetails = true } = options;
 
   try {
-    // Basic validation: check if data store is valid
     if (!dataStore || typeof dataStore.size !== 'number') {
       throw new Error('Invalid data store');
     }
-
-    // Check if shapes string is valid
     if (!shapesString || typeof shapesString !== 'string') {
       throw new Error('Invalid shapes string');
     }
 
-    // In a full implementation, this would:
-    // 1. Parse SHACL shapes from shapesString
-    // 2. Iterate through each shape
-    // 3. Apply constraints to data
-    // 4. Collect validation results
+    const validator = getValidator(shapesString);
+
+    // Use the raw oxigraph.Store for validation (unwrap OxigraphStore wrapper if needed)
+    const rawStore = dataStore.store || dataStore;
+
+    const shaclReport = await validator.validate(rawStore);
 
-    // For now, return conforming result
-    // This should be replaced with actual SHACL validation logic
+    const results = (shaclReport.results || []).map(result => ({
+      severity: SEVERITY_MAP[result.severity?.value] || 'violation',
+      message: result.message?.map(m => m.value).join('; ') || null,
+      focusNode: result.focusNode?.value || null,
+      resultPath: result.path?.value || null,
+      resultMessage: result.message?.map(m => m.value).join('; ') || null,
+      value: result.value?.value || null,
+      sourceConstraintComponent: result.sourceConstraintComponent?.value || null,
+      sourceShape: result.sourceShape?.value || null,
+    }));
+
+    const report = {
+      conforms: shaclReport.conforms,
+      results,
+      timestamp: new Date().toISOString(),
+    };
 
     if (includeDetails) {
       report.details = {
-        shapesCount: 0,
-        constraintsChecked: 0,
+        shapesCount: countShapes(shapesString),
+        constraintsChecked: results.length,
         validationTime: 0,
       };
     }
@@ -65,7 +113,9 @@ export function validateShacl(dataStore, shapesString, options = {}) {
         {
           severity: 'violation',
           message: `SHACL validation error: ${error.message}`,
-          path: null,
+          focusNode: null,
+          resultPath: null,
+          resultMessage: `SHACL validation error: ${error.message}`,
           value: null,
         },
       ],
@@ -75,6 +125,17 @@ export function validateShacl(dataStore, shapesString, options = {}) {
   }
 }
 
+/**
+ * Count the number of sh:NodeShape declarations in a shapes string.
+ *
+ * @param {string} shapesString - Turtle shapes string
+ * @returns {number} Approximate number of shapes
+ */
+function countShapes(shapesString) {
+  const matches = shapesString.match(/sh:NodeShape/g);
+  return matches ? matches.length : 0;
+}
+
 /**
  * Validate a single node against SHACL shapes
  *
@@ -82,11 +143,10 @@ export function validateShacl(dataStore, shapesString, options = {}) {
  * @param {object} node - Node to validate
  * @param {string} shapesString - SHACL shapes
  * @param {object} options - Validation options
- * @returns {object} Validation report for the node
+ * @returns {Promise<object>} Validation report for the node
  */
-export function validateNode(store, node, shapesString, options = {}) {
-  // Simplified node validation
-  const report = validateShacl(store, shapesString, options);
+export async function validateNode(store, node, shapesString, options = {}) {
+  const report = await validateShacl(store, shapesString, options);
 
   return {
     ...report,
@@ -131,3 +191,10 @@ export function getWarnings(report) {
 
   return report.results.filter(result => result.severity === 'warning');
 }
+
+/**
+ * Clear the validator cache. Useful in tests or when shapes change frequently.
+ */
+export function clearValidatorCache() {
+  validatorCache.clear();
+}

package/src/index.mjs

@@ -116,6 +116,8 @@ export {
   evaluateCondition,
   createConditionEvaluator,
   validateCondition,
+  serializeShaclReport,
+  SlidingWindow,
 } from './hooks/condition-evaluator.mjs';
 
 // File Resolver (Content-addressed file loading)