@unrdf/hooks 26.4.3 → 26.4.4

package/src/hooks/knowledge-hook-engine.mjs

@@ -15,6 +15,7 @@
  * @module knowledge-engine/knowledge-hook-engine
  */
 
+import { blake3 } from '@noble/hashes/blake3.js';
 import { StoreCache } from './store-cache.mjs';
 import { ConditionCache } from './condition-cache.mjs';
 import { BatchedTelemetry } from './telemetry.mjs';
@@ -103,6 +104,9 @@ export class KnowledgeHookEngine {
    * @param {object} options - Execution options
    * @param {object} options.env - SPARQL evaluation environment
    * @param {boolean} options.debug - Enable debug output
+   * @param {string} [options.nodeId] - Node identifier for receipt (default: 'knowledge-hook-engine')
+   * @param {bigint} [options.t_ns] - Nanosecond timestamp for receipt
+   * @param {string} [options.previousReceiptHash] - Previous receipt hash for chaining
    * @returns {Promise<object>} Execution results { conditionResults, executionResults, receipt }
    */
   async execute(store, delta, options = {}) {
@@ -123,6 +127,9 @@ export class KnowledgeHookEngine {
       this.storeCache.clear();
       this.conditionCache.clear();
 
+      // Compute input hash before execution
+      const input_hash = await this._computeStoreHash(store);
+
       // Phase 1: Parallel condition evaluation (ONCE per hook)
       const conditionResults = await this.evaluateConditions(store, delta, options);
 
@@ -135,8 +142,17 @@ export class KnowledgeHookEngine {
 
       this.telemetry.setAttribute(span, 'hooks.executed', executionResults.length);
 
-      // Phase 3: Generate optional receipt
-      const receipt = this.generateReceipt(executionResults, delta);
+      // Compute output hash after execution
+      const output_hash = await this._computeStoreHash(store);
+
+      // Phase 3: Generate receipt with cryptographic hashing
+      const receipt = await this.generateReceiptWithHash(
+        executionResults,
+        delta,
+        input_hash,
+        output_hash,
+        options
+      );
 
       this.telemetry.endSpan(span, 'ok');
 
@@ -213,6 +229,8 @@ export class KnowledgeHookEngine {
   /**
    * Execute a single hook with side effects.
    *
+   * Supports both function-based effects (hook.run) and RDF-native SPARQL CONSTRUCT effects.
+   *
    * NOTE: Per-hook OTEL spans removed for performance optimization.
    * Transaction-level spans at execute() provide aggregate visibility.
    * Savings: 2-4μs per hook execution.
@@ -224,6 +242,12 @@ export class KnowledgeHookEngine {
     // Transaction-level span at execute():109 provides aggregate metrics
 
     try {
+      // Dispatch to appropriate executor based on effect type
+      if (hook.effect?.kind === 'sparql-construct') {
+        return this.executeSparqlConstructEffect(hook, store, delta, options);
+      }
+
+      // Legacy: function-based effect
       const event = {
         store,
         delta,
@@ -246,6 +270,45 @@ export class KnowledgeHookEngine {
     }
   }
 
+  /**
+   * Execute a SPARQL CONSTRUCT effect
+   *
+   * Runs the CONSTRUCT query against the store and adds resulting quads.
+   * CONSTRUCT returns new quads that are merged into the knowledge graph.
+   *
+   * @private
+   */
+  executeSparqlConstructEffect(hook, store, _delta, _options) {
+    try {
+      const query = hook.effect.query;
+
+      // Execute CONSTRUCT query - returns iterable of quads
+      const quads = store.query(query);
+
+      // Add all resulting quads to the store
+      let addCount = 0;
+      for (const quad of quads) {
+        store.add(quad);
+        addCount++;
+      }
+
+      return {
+        hookId: hook.id,
+        success: true,
+        result: {
+          quadsAdded: addCount,
+          query,
+        },
+      };
+    } catch (error) {
+      return {
+        hookId: hook.id,
+        success: false,
+        error: error.message,
+      };
+    }
+  }
+
   /**
    * Build dependency-ordered batches of hooks
    *
@@ -312,15 +375,17 @@ export class KnowledgeHookEngine {
   }
 
   /**
-   * Generate transaction receipt (optional, decoupled from TransactionManager)
+   * Generate transaction receipt with cryptographic BLAKE3 hashing
    *
    * @private
    */
-  generateReceipt(executionResults, delta) {
-    const now = new Date().toISOString();
+  async generateReceiptWithHash(executionResults, delta, input_hash, output_hash, options = {}) {
+    const t_ns = options.t_ns || BigInt(Date.now()) * 1000000n;
+    const previousReceiptHash = options.previousReceiptHash || null;
 
-    return {
-      timestamp: now,
+    // Build the core receipt data
+    const receiptPayload = {
+      timestamp: new Date(Number(t_ns / 1000000n)).toISOString(),
       delta: {
         adds: delta?.adds?.length || 0,
         deletes: delta?.deletes?.length || 0,
@@ -328,7 +393,23 @@ export class KnowledgeHookEngine {
       hooksExecuted: executionResults.length,
       successful: executionResults.filter(r => r.value?.success).length,
       failed: executionResults.filter(r => r.status === 'rejected' || !r.value?.success).length,
+      input_hash,
+      output_hash,
+      previousReceiptHash,
     };
+
+    // Generate receipt with BLAKE3-compatible structure
+    // Note: Full BLAKE3 integration is handled by v6-core/receipts
+    const receipt = {
+      timestamp: new Date(Number(t_ns / 1000000n)).toISOString(),
+      receiptHash: this._generateHash(receiptPayload),
+      input_hash: input_hash,
+      output_hash: output_hash,
+      previousReceiptHash,
+      ...receiptPayload,
+    };
+
+    return receipt;
   }
 
   /**
@@ -353,6 +434,51 @@ export class KnowledgeHookEngine {
     this.conditionCache.clear();
     this.fileCacheWarmed = false;
   }
+
+  /**
+   * Generate deterministic hash for receipt payload
+   * (simplified implementation - production uses BLAKE3 from v6-core)
+   *
+   * @private
+   */
+  _generateHash(payload) {
+    // BLAKE3 cryptographic hashing for receipt security
+    const str = JSON.stringify(payload);
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(str);
+    const digest = blake3(bytes, { dkLen: 32 });
+    // Convert Uint8Array to hex string
+    return Array.from(digest)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /**
+   * Compute hash of store state
+   *
+   * @private
+   */
+  async _computeStoreHash(store) {
+    // Simplified hash based on store size and content
+    // In production, use proper content hash (SHA-256, BLAKE3)
+    if (!store || !store.size) {
+      return '0'.repeat(64);
+    }
+
+    const quads = Array.from(store);
+    const quadStrings = quads
+      .map(q => `${q.subject?.value || ''}:${q.predicate?.value || ''}:${q.object?.value || ''}`)
+      .join('|');
+
+    let hash = 0;
+    for (let i = 0; i < quadStrings.length; i++) {
+      const char = quadStrings.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+
+    return Math.abs(hash).toString(16).padStart(64, '0');
+  }
 }
 
 export default KnowledgeHookEngine;

package/src/hooks/ontology-learner.mjs

@@ -0,0 +1,190 @@
+/**
+ * @file Ontology Learner
+ * @module @unrdf/hooks/ontology-learner
+ * @description Learn SHACL shapes from RDF patterns
+ */
+
+/**
+ * Learn ontology patterns from RDF data
+ */
+export class OntologyLearner {
+  /**
+   * Infer SHACL shapes from RDF graph
+   */
+  async inferShapes(store, options = {}) {
+    const minSupport = options.minSupport || 0.9;
+    const shapes = {};
+
+    if (!store || store.size === 0) {
+      return shapes;
+    }
+
+    // Get all classes
+    const classes = this.extractClasses(store);
+
+    for (const cls of classes) {
+      // Get instances of this class
+      const instances = this.getInstancesOfClass(store, cls);
+      if (instances.length === 0) continue;
+
+      // Mine properties
+      const properties = this.mineProperties(store, instances);
+
+      // Generate shapes for properties with enough support
+      const shapeProperties = {};
+      for (const [predicate, data] of Object.entries(properties)) {
+        const supportRatio = data.count / instances.length;
+        if (supportRatio >= minSupport) {
+          shapeProperties[predicate] = {
+            minCount: supportRatio > 0.99 ? 1 : 0,
+            datatype: this.dominantDatatype(data.datatypes),
+            description: `Property ${predicate} (${Math.round(supportRatio * 100)}% coverage)`,
+          };
+        }
+      }
+
+      if (Object.keys(shapeProperties).length > 0) {
+        shapes[cls] = {
+          targetClass: cls,
+          properties: shapeProperties,
+          instanceCount: instances.length,
+        };
+      }
+    }
+
+    return shapes;
+  }
+
+  /**
+   * Extract all RDF classes from store
+   */
+  extractClasses(store) {
+    const classes = new Set();
+
+    for (const quad of store) {
+      // RDF type declarations
+      if (quad.predicate.value === 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type') {
+        if (quad.object.value && quad.object.value.startsWith('http')) {
+          classes.add(quad.object.value);
+        }
+      }
+      // Also RDFS classes
+      if (
+        quad.subject.value &&
+        quad.subject.value.startsWith('http') &&
+        quad.object.value === 'http://www.w3.org/2000/01/rdf-schema#Class'
+      ) {
+        classes.add(quad.subject.value);
+      }
+    }
+
+    return Array.from(classes);
+  }
+
+  /**
+   * Get instances of a class
+   */
+  getInstancesOfClass(store, className) {
+    const instances = new Set();
+    const typeIri = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+
+    for (const quad of store) {
+      if (quad.predicate.value === typeIri && quad.object.value === className) {
+        instances.add(quad.subject.value);
+      }
+    }
+
+    return Array.from(instances);
+  }
+
+  /**
+   * Mine property patterns from instances
+   */
+  mineProperties(store, instances) {
+    const properties = {};
+
+    for (const instance of instances) {
+      for (const quad of store) {
+        if (quad.subject.value === instance) {
+          const pred = quad.predicate.value;
+          const obj = quad.object.value;
+
+          if (!properties[pred]) {
+            properties[pred] = {
+              count: 0,
+              objects: [],
+              datatypes: new Set(),
+            };
+          }
+
+          properties[pred].count++;
+          properties[pred].objects.push(obj);
+          properties[pred].datatypes.add(this.inferDatatype(quad.object));
+        }
+      }
+    }
+
+    return properties;
+  }
+
+  /**
+   * Infer datatype of RDF value
+   */
+  inferDatatype(obj) {
+    if (!obj) return 'unknown';
+
+    // Check for NamedNode/Resource
+    if (obj.termType === 'NamedNode' || (obj.value && String(obj.value).startsWith('http'))) {
+      return 'rdf:Resource';
+    }
+
+    // Infer from value pattern - try specific types first
+    if (obj.value !== undefined && obj.value !== null) {
+      const val = String(obj.value);
+
+      // Try to infer more specific types from pattern
+      if (/^\d+$/.test(val)) return 'xsd:integer';
+      if (/^\d+\.\d+$/.test(val)) return 'xsd:float';
+      if (/^(true|false)$/i.test(val)) return 'xsd:boolean';
+      if (/^\d{4}-\d{2}-\d{2}/.test(val)) return 'xsd:dateTime';
+    }
+
+    // Fall back to explicit datatype
+    if (obj.datatype && obj.datatype.value) {
+      const dt = obj.datatype.value;
+      if (dt.includes('integer') || dt.includes('int')) return 'xsd:integer';
+      if (dt.includes('float') || dt.includes('double')) return 'xsd:float';
+      if (dt.includes('boolean')) return 'xsd:boolean';
+      if (dt.includes('date')) return 'xsd:dateTime';
+      if (dt.includes('string')) return 'xsd:string';
+    }
+
+    return 'xsd:string';
+  }
+
+  /**
+   * Find dominant datatype from set
+   */
+  dominantDatatype(datatypes) {
+    if (datatypes.size === 0) return 'xsd:string';
+    return Array.from(datatypes)[0];
+  }
+
+  /**
+   * Generate SHACL shape definition
+   */
+  toSHACLShape(className, properties) {
+    return {
+      '@context': 'http://www.w3.org/ns/shacl#',
+      '@type': 'NodeShape',
+      targetClass: className,
+      property: Object.entries(properties).map(([pred, config]) => ({
+        path: pred,
+        minCount: config.minCount || 0,
+        datatype: config.datatype || 'xsd:string',
+      })),
+    };
+  }
+}
+
+export default OntologyLearner;

package/src/hooks/query.mjs

@@ -16,7 +16,7 @@
  * @param {boolean} options.deterministic - Use deterministic execution
  * @returns {Promise<boolean>} Query result (true/false)
  */
-export async function ask(store, queryString, options = {}) {
+export async function ask(store, queryString, _options = {}) {
   if (!store || typeof store.query !== 'function') {
     throw new TypeError('ask: store must have a query method');
   }
@@ -59,7 +59,7 @@ export async function ask(store, queryString, options = {}) {
  * @param {boolean} options.deterministic - Use deterministic execution
  * @returns {Promise<Array>} Query results as array of bindings
  */
-export async function select(store, queryString, options = {}) {
+export async function select(store, queryString, _options = {}) {
   if (!store || typeof store.query !== 'function') {
     throw new TypeError('select: store must have a query method');
   }
@@ -108,7 +108,7 @@ export async function select(store, queryString, options = {}) {
  * @param {object} options - Query options
  * @returns {Promise<Array>} Query results as array of quads
  */
-export async function construct(store, queryString, options = {}) {
+export async function construct(store, queryString, _options = {}) {
   if (!store || typeof store.query !== 'function') {
     throw new TypeError('construct: store must have a query method');
   }

package/src/hooks/schemas.mjs

@@ -32,14 +32,45 @@ export const HookConditionRefSchema = z.object({
   mediaType: z.string().optional(),
 });
 
+/**
+ * Schema for SHACL condition with enforcement modes (soft-fail governance)
+ *
+ * Enforcement modes:
+ * - 'block': Default. Fail validation if SHACL constraint violated.
+ * - 'annotate': Allow write but add SHACL report as RDF triples to store.
+ * - 'repair': Attempt to fix violations using SPARQL CONSTRUCT query.
+ */
+export const ShaclConditionSchema = z.object({
+  kind: z.literal('shacl'),
+  ref: HookConditionRefSchema,
+  enforcementMode: z.enum(['block', 'annotate', 'repair']).default('block'),
+  repairConstruct: z.string().optional(),
+});
+
 /**
  * Schema for hook condition
  */
 export const HookConditionSchema = z.object({
-  kind: z.enum(['sparql-ask', 'sparql-select', 'shacl', 'delta', 'threshold', 'count', 'window']),
+  kind: z.enum([
+    'sparql-ask',
+    'sparql-select',
+    'shacl',
+    'delta',
+    'threshold',
+    'count',
+    'window',
+    'n3',
+    'datalog',
+  ]),
   ref: HookConditionRefSchema.optional(),
   query: z.string().optional(),
   shapes: z.string().optional(),
+  rules: z.string().optional(),
+  askQuery: z.string().optional(),
+  facts: z.array(z.string()).optional(),
+  goal: z.string().optional(),
+  enforcementMode: z.enum(['block', 'annotate', 'repair']).default('block').optional(),
+  repairConstruct: z.string().optional(),
   spec: z.record(z.any()).optional(),
 });
 
@@ -56,9 +87,17 @@ export const HookEffectRefSchema = z.object({
 });
 
 /**
- * Schema for hook effect
+ * Schema for SPARQL CONSTRUCT effect (RDF-native transformation)
+ */
+export const SparqlConstructEffectSchema = z.object({
+  kind: z.literal('sparql-construct'),
+  query: z.string().min(1),
+});
+
+/**
+ * Schema for JavaScript function effect (legacy)
  */
-export const HookEffectSchema = z.object({
+export const FunctionEffectSchema = z.object({
   ref: HookEffectRefSchema.optional(),
   inline: z.function().optional(),
   timeout: z.number().int().positive().max(300000).default(30000),
@@ -66,6 +105,11 @@ export const HookEffectSchema = z.object({
   sandbox: z.boolean().default(false),
 });
 
+/**
+ * Schema for hook effect - union of function-based and SPARQL-based effects
+ */
+export const HookEffectSchema = z.union([SparqlConstructEffectSchema, FunctionEffectSchema]);
+
 /**
  * Complete knowledge hook schema
  */

package/src/hooks/security/error-sanitizer.mjs

@@ -42,28 +42,28 @@ const SENSITIVE_PATTERNS = {
   // Database connection strings
   credentials: [
     /\b(?:postgres|mysql|mongodb):\/\/[^:\s]+:[^@\s]+@[^\s]+/gi, // DB URLs with passwords
-    /password\s*[:=]\s*["']?[^"'\s]+["']?/gi, // password= or password:
-    /api[_-]?key\s*[:=]\s*["']?[^"'\s]+["']?/gi, // API keys
+    /password\s*[:=]\s*["']?[^"'\s]+["']?/g, // password= or password: (lowercase only)
+    /api[_-]?key\s*[:=]\s*["']?[^"'\s]+["']?/g, // api_key= or api-key= (lowercase only)
     /secret\s*[:=]\s*["']?[^"'\s]+["']?/gi, // secrets
     /token\s*[:=]\s*["']?[^"'\s]+["']?/gi, // tokens
     /authorization\s*:\s*["']?[^"'\s]+["']?/gi, // auth headers
   ],
 
-  // Environment variables
+  // Environment variables (ALL_CAPS only to avoid overlap with credentials)
   environmentVars: [
-    /\bDATABASE_URL\s*=\s*[^\s]+/gi,
-    /API_KEY\s*=\s*[^\s]+/gi,
-    /SECRET\s*=\s*[^\s]+/gi,
-    /PASSWORD\s*=\s*[^\s]+/gi,
-    /TOKEN\s*=\s*[^\s]+/gi,
-    /\w+_KEY\s*=\s*[^\s]+/gi,
-    /\w+_SECRET\s*=\s*[^\s]+/gi,
+    /\bDATABASE_URL\s*=\s*[^\s]+/g,
+    /API_KEY\s*=\s*[^\s]+/g,
+    /SECRET\s*=\s*[^\s]+/g,
+    /PASSWORD\s*=\s*[^\s]+/g,
+    /TOKEN\s*=\s*[^\s]+/g,
+    /[A-Z][A-Z0-9_]*_KEY\s*=\s*[^\s]+/g,
+    /[A-Z][A-Z0-9_]*_SECRET\s*=\s*[^\s]+/g,
   ],
 
   // Stack trace patterns
   stackTraces: [
-    /\bat\s+[^\s]+\s+\([^)]+:\d+:\d+\)/g, // at Function (file:line:col)
-    /at\s+[^(]+\([^)]+\)/g, // at Function(...)
+    /\bat\s+[^\s]+\s+\([^)]*:\d+:\d+\)/g, // at Function (file:line:col) - allow empty parens before colon
+    /at\s+[^(]+\([^)]*\)/g, // at Function(...) - allow empty parens
     /^\s*at\s.+$/gm, // Full stack trace lines
   ],
 };
@@ -103,6 +103,11 @@ export class ErrorSanitizer {
       message = this._removeEnvironmentVars(message);
     }
 
+    // Remove stack traces
+    if (this.options.removeStackTraces) {
+      message = this._removeStackTraces(message);
+    }
+
     // If sanitization removed too much, return generic message
     if (message.trim().length < 10) {
       return this.options.genericErrorMessage;
@@ -147,16 +152,13 @@ export class ErrorSanitizer {
     let sanitized = text;
 
     for (const pattern of SENSITIVE_PATTERNS.credentials) {
-      sanitized = sanitized.replace(pattern, match => {
-        if (match.includes('://')) {
-          // Replace password in connection string
-          return match.replace(/:\/\/[^:]+:[^@]+@/, '://***:***@');
-        }
-        // Replace entire credential assignment
-        return match.split(/[:=]/)[0] + '=***';
-      });
+      // Completely remove matched credential patterns
+      sanitized = sanitized.replace(pattern, '');
     }
 
+    // Clean up extra whitespace left by removed patterns
+    sanitized = sanitized.replace(/\s+/g, ' ').trim();
+
     return sanitized;
   }
 
@@ -170,7 +172,7 @@ export class ErrorSanitizer {
     let sanitized = text;
 
     for (const pattern of SENSITIVE_PATTERNS.filePaths) {
-      sanitized = sanitized.replace(pattern, '[file path removed]');
+      sanitized = sanitized.replace(pattern, '');
     }
 
     return sanitized;
@@ -186,11 +188,31 @@ export class ErrorSanitizer {
     let sanitized = text;
 
     for (const pattern of SENSITIVE_PATTERNS.environmentVars) {
-      sanitized = sanitized.replace(pattern, match => {
-        return match.split('=')[0] + '=***';
-      });
+      sanitized = sanitized.replace(pattern, '');
     }
 
+    // Clean up extra whitespace left by removed patterns
+    sanitized = sanitized.replace(/\s+/g, ' ').trim();
+
+    return sanitized;
+  }
+
+  /**
+   * Remove stack trace patterns from text
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   * @private
+   */
+  _removeStackTraces(text) {
+    let sanitized = text;
+
+    for (const pattern of SENSITIVE_PATTERNS.stackTraces) {
+      sanitized = sanitized.replace(pattern, '');
+    }
+
+    // Clean up extra whitespace left by removed patterns
+    sanitized = sanitized.replace(/\s+/g, ' ').trim();
+
     return sanitized;
   }