@unrdf/knowledge-engine 5.0.1

package/src/define-hook.mjs

@@ -0,0 +1,213 @@
+/**
+ * @file 80/20 Knowledge Hook definition contract for autonomic systems.
+ * @module newco/defineHook
+ *
+ * @description
+ * This module provides the `defineHook` function, the sole entry point for
+ * defining a Knowledge Hook. The contract enforces critical principles for
+ * autonomic, deterministic, and provable systems:
+ *
+ * 1.  **Conditions are Addressed, Not Embedded**: The `when` clause MUST
+ * reference an external, content-addressed SPARQL or SHACL file.
+ * This forbids inline query strings, ensuring that governance logic is
+ * a verifiable, standalone artifact.
+ *
+ * 2.  **Reflex Arc Lifecycle**: The `before`, `run`, and `after` functions
+ * provide a minimal, complete lifecycle for autonomic reflexes:
+ * - `before`: A pre-condition gate for payload normalization or cancellation.
+ * - `run`: The core effect or analysis.
+ * - `after`: A post-execution step for auditing and cleanup.
+ *
+ * 3.  **Declarative Configuration**: Determinism and receipting strategies
+ * are declared as metadata, not implemented imperatively within the hook.
+ *
+ * 4.  **Comprehensive Validation**: Uses Zod schemas for complete type safety
+ * and validation of all hook components.
+ *
+ * This API is designed to feel familiar to users of Nitro's `defineTask`
+ * while being fundamentally adapted for a knowledge-native, policy-first runtime.
+ */
+
+/**
+ * A content-addressed file reference. This is the only way to specify a
+ * condition, ensuring that governance logic is a verifiable artifact and
+ * not an inline string.
+ *
+ * @typedef {Object} Ref
+ * @property {string} uri - The URI of the resource, typically a file path like "file://hooks/compliance/largeTx.ask.rq".
+ * @property {string} sha256 - The SHA-256 hash of the file's content, for integrity and provenance.
+ * @property {'application/sparql-query'|'text/shacl'|'text/turtle'} mediaType - The MIME type of the resource.
+ */
+
+/**
+ * Descriptive metadata for cataloging, discovery, and tooling.
+ *
+ * @typedef {Object} HookMeta
+ * @property {string} name - A unique, human-readable name for the hook (e.g., "compliance:largeTx").
+ * @property {string} [description] - A brief explanation of the hook's purpose.
+ * @property {string[]} [ontology] - A list of ontology prefixes this hook relates to (e.g., ["fibo", "prov"]).
+ */
+
+/**
+ * Defines the knowledge surface the hook observes during its condition evaluation.
+ *
+ * @typedef {Object} HookChannel
+ * @property {string[]} [graphs] - An array of named graph IRIs or labels to scope the query.
+ * @property {'before'|'after'|'delta'} [view] - The state of the graph to evaluate against. 'before' is the state before the delta is applied, 'after' is the state after, and 'delta' is a graph containing only the additions and removals.
+ */
+
+/**
+ * The declarative trigger condition for the hook, based on a content-addressed reference.
+ *
+ * @typedef {Object} HookCondition
+ * @property {'sparql-ask'|'sparql-select'|'shacl'} kind - The type of evaluation to perform.
+ * @property {Ref} ref - The content-addressed reference to the SPARQL or SHACL file.
+ */
+
+/**
+ * The execution context passed to all lifecycle functions, providing access
+ * to the graph and environment.
+ *
+ * @typedef {Object} HookContext
+ * @property {any} [graph] - The active RDF/JS Store or Dataset instance.
+ * @property {Object.<string, unknown>} [env] - Environment variables or runtime configuration.
+ */
+
+/**
+ * The data payload for a hook event.
+ *
+ * @typedef {Object.<string, unknown>} HookPayload
+ */
+
+/**
+ * The event object passed to each lifecycle function of a hook.
+ *
+ * @typedef {Object} HookEvent
+ * @property {string} name - The name of the hook being executed.
+ * @property {HookPayload} payload - The input data for the event.
+ * @property {HookContext} context - The execution context.
+ */
+
+/**
+ * The standardized result of a hook's `run` or `after` function.
+ *
+ * @typedef {Object} HookResult
+ * @property {any} [result] - The primary output or return value of the hook.
+ * @property {any} [assertions] - Optional RDF quads to be added to the graph as a result of the hook's execution.
+ * @property {any} [deltas] - An optional, more complex delta (additions/removals) to be applied.
+ * @property {boolean} [cancelled] - Indicates if the hook was cancelled during the `before` phase.
+ * @property {string} [reason] - The reason for cancellation.
+ */
+
+/**
+ * The complete, 80/20 contract for a Knowledge Hook. This object defines
+ * the hook's identity, its trigger condition, its autonomic behavior, and
+ * its operational guarantees.
+ *
+ * @typedef {Object} KnowledgeHook
+ * @property {HookMeta} meta - Essential metadata for the hook.
+ * @property {HookChannel} [channel] - The observation channel for the condition.
+ * @property {HookCondition} when - The declarative, file-based trigger condition.
+ * @property {{ seed?: number }} [determinism] - Configuration for deterministic operations. Defaults to a fixed seed of 42.
+ * @property {{ anchor?: ('git-notes'|'none') }} [receipt] - Strategy for anchoring the transaction receipt. Defaults to 'none'.
+ * @property {(e: HookEvent) => Promise<Partial<HookPayload>|{cancel:true,reason?:string}> | Partial<HookPayload>|{cancel:true,reason?:string}} [before] - A function that runs before the condition is checked. It can modify the payload or cancel the execution.
+ * @property {(e: HookEvent) => Promise<HookResult> | HookResult} run - The main execution body of the hook.
+ * @property {(e: HookEvent & { result?: any, cancelled?: boolean, reason?: string }) => Promise<HookResult> | HookResult} [after] - A function that runs after the `run` phase, for cleanup or auditing.
+ */
+
+/**
+ * Defines a Knowledge Hook, validating its structure and enforcing the
+ * 80/20 contract for autonomic systems using comprehensive Zod validation.
+ *
+ * @template T
+ * @param {KnowledgeHook} def - The hook definition object.
+ * @returns {KnowledgeHook} The validated and normalized hook definition.
+ */
+import { createKnowledgeHook } from './schemas.mjs';
+import { defaultSecurityValidator } from './security-validator.mjs';
+
+/**
+ *
+ */
+export function defineHook(def) {
+  // Use comprehensive Zod validation
+  const validatedHook = createKnowledgeHook(def);
+
+  // Apply security validation (warn only, don't block)
+  // Security will be enforced at execution time via sandbox
+  const securityValidation = defaultSecurityValidator.validateKnowledgeHook(validatedHook);
+  if (!securityValidation.valid) {
+    // Log warning in development (can't modify frozen object, so just log)
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(
+        `[Security Warning] Hook "${validatedHook.meta.name}": ${securityValidation.blockReason}`
+      );
+    }
+  }
+
+  return validatedHook;
+}
+
+/* ------------------------- Example (Happy Path) ------------------------- */
+
+/**
+ * This is an example of how to use `defineHook` to create a compliance gate.
+ * It demonstrates all the core features of the 80/20 contract.
+ */
+export const exampleComplianceHook = defineHook({
+  meta: {
+    name: 'compliance:largeTx',
+    description:
+      'Alerts and creates an audit trail when a financial transaction exceeds a certain threshold.',
+    ontology: ['fibo'],
+  },
+  channel: {
+    graphs: ['urn:graph:fibo:prod'],
+    view: 'delta',
+  },
+  when: {
+    kind: 'sparql-ask',
+    ref: {
+      uri: 'file://hooks/compliance/largeTx.ask.rq',
+      sha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', // Example hash
+      mediaType: 'application/sparql-query',
+    },
+  },
+  determinism: { seed: 42 },
+  receipt: { anchor: 'git-notes' },
+
+  async before({ payload }) {
+    if (!payload || typeof payload.amount !== 'number' || payload.amount <= 0) {
+      return {
+        cancel: true,
+        reason: 'Invalid or non-positive transaction amount.',
+      };
+    }
+    // Normalize payload for the `run` step
+    return { ...payload, validatedAt: new Date().toISOString() };
+  },
+
+  async run({ payload }) {
+    console.log(
+      `[RUN] Processing large transaction of ${payload.amount} validated at ${payload.validatedAt}`
+    );
+    // The main result could be an alert object, an event to be emitted, etc.
+    return {
+      result: { status: 'alert-dispatched', amount: payload.amount },
+      // This hook also generates a new piece of knowledge (an audit triple).
+      assertions: [
+        /* an RDF quad like: [ a:tx, prov:wasGeneratedBy, this:hook ] */
+      ],
+    };
+  },
+
+  async after({ result, cancelled, reason }) {
+    if (cancelled) {
+      console.log(`[AFTER] Hook execution was cancelled. Reason: ${reason}`);
+    } else {
+      console.log(`[AFTER] Hook successfully completed with status: ${result?.result?.status}`);
+    }
+    // The 'after' hook always returns a result for logging/receipt purposes.
+    return { result: { finalStatus: cancelled ? 'cancelled' : 'completed' } };
+  },
+});

package/src/effect-sandbox-browser.mjs

@@ -0,0 +1,283 @@
+/**
+ * @file Browser-compatible Effect Sandbox
+ * @module effect-sandbox-browser
+ *
+ * @description
+ * Browser-compatible version of the effect sandbox that uses Web Workers
+ * instead of Node.js worker threads for secure hook execution.
+ */
+
+import { randomUUID, Worker } from './browser-shims.mjs';
+import { z } from 'zod';
+
+/**
+ * Schema for sandbox configuration
+ */
+const SandboxConfigSchema = z.object({
+  type: z.enum(['worker', 'global']).default('worker'), // Only worker mode in browser
+  timeout: z.number().int().positive().max(30000).default(5000), // Shorter timeout for browser
+  memoryLimit: z
+    .number()
+    .int()
+    .positive()
+    .max(100 * 1024 * 1024)
+    .default(10 * 1024 * 1024), // 10MB default
+  allowedGlobals: z
+    .array(z.string())
+    .default(['console', 'Date', 'Math', 'JSON', 'Array', 'Object']),
+  enableNetwork: z.boolean().default(false),
+  enableFileSystem: z.boolean().default(false),
+  strictMode: z.boolean().default(true),
+});
+
+/**
+ * Schema for sandbox execution context
+ */
+const SandboxContextSchema = z.object({
+  event: z.any(),
+  store: z.any(),
+  delta: z.any(),
+  metadata: z.record(z.any()).optional(),
+});
+
+/**
+ * Schema for sandbox execution result
+ */
+const SandboxResultSchema = z.object({
+  success: z.boolean(),
+  result: z.any().optional(),
+  error: z.string().optional(),
+  duration: z.number().nonnegative(),
+});
+
+/**
+ * Browser-compatible Effect Sandbox
+ */
+export class EffectSandbox {
+  /**
+   *
+   */
+  constructor(config = {}) {
+    this.config = SandboxConfigSchema.parse(config);
+    this.workers = new Map();
+    this.executionCount = 0;
+    this.totalExecutions = 0;
+    this.totalDuration = 0;
+  }
+
+  /**
+   * Execute a hook effect in the sandbox
+   * @param {Function} effect - The effect function to execute
+   * @param {Object} context - Execution context
+   * @param {Object} [options] - Execution options
+   * @returns {Promise<Object>} Execution result
+   */
+  async executeEffect(effect, context, options = {}) {
+    const executionId = randomUUID();
+    const startTime = Date.now();
+
+    try {
+      // Validate context
+      const validatedContext = SandboxContextSchema.parse(context);
+
+      let result;
+      switch (this.config.type) {
+        case 'worker':
+          result = await this._executeInWorker(effect, validatedContext, executionId, options);
+          break;
+        case 'global':
+          // Not recommended for browser, but allowed for testing
+          result = await this._executeInGlobal(effect, validatedContext, executionId, options);
+          break;
+        default:
+          throw new Error(`Unsupported sandbox type: ${this.config.type}`);
+      }
+
+      const duration = Date.now() - startTime;
+      this.totalExecutions++;
+      this.totalDuration += duration;
+
+      const validatedResult = SandboxResultSchema.parse({
+        ...result,
+        duration,
+      });
+
+      return validatedResult;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this.totalExecutions++;
+
+      return {
+        success: false,
+        error: error.message,
+        duration,
+      };
+    }
+  }
+
+  /**
+   * Execute effect in Web Worker
+   * @private
+   */
+  async _executeInWorker(effect, context, executionId, _options) {
+    const workerScript = this._createWorkerScript(effect);
+
+    const worker = new Worker(workerScript, {
+      name: `effect-sandbox-${executionId}`,
+    });
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        worker.terminate();
+        reject(new Error(`Worker execution timeout after ${this.config.timeout}ms`));
+      }, this.config.timeout);
+
+      worker.onmessage = event => {
+        clearTimeout(timeout);
+        worker.terminate();
+
+        if (event.data.error) {
+          reject(new Error(event.data.error));
+        } else {
+          resolve(event.data);
+        }
+      };
+
+      worker.onerror = error => {
+        clearTimeout(timeout);
+        worker.terminate();
+        reject(new Error(`Worker error: ${error.message}`));
+      };
+
+      worker.postMessage({ context, config: this.config });
+    });
+  }
+
+  /**
+   * Execute effect in global scope (not recommended for production)
+   * @private
+   */
+  async _executeInGlobal(effect, context, _executionId, _options) {
+    return new Promise((resolve, reject) => {
+      try {
+        const result = effect(context, {
+          emitEvent: event => console.log('Event:', event),
+          log: message => console.log(message),
+          assert: (condition, message) => {
+            if (!condition) throw new Error(message || 'Assertion failed');
+          },
+        });
+
+        if (result instanceof Promise) {
+          result.then(resolve).catch(reject);
+        } else {
+          resolve({ success: true, result });
+        }
+      } catch (error) {
+        resolve({ success: false, error: error.message });
+      }
+    });
+  }
+
+  /**
+   * Create worker script from effect function
+   * @private
+   */
+  _createWorkerScript(effect) {
+    const _allowedGlobals = this.config._allowedGlobals.join(', ');
+
+    return `
+      // Worker script for effect sandbox
+      const effect = ${effect.toString()};
+      
+      // Sandbox globals
+      ${this.config.allowedGlobals.map(global => `const ${global} = self.${global};`).join('\n')}
+      
+      // Safe console
+      const console = {
+        log: (...args) => self.postMessage({ type: 'console', level: 'log', args }),
+        warn: (...args) => self.postMessage({ type: 'console', level: 'warn', args }),
+        error: (...args) => self.postMessage({ type: 'console', level: 'error', args }),
+        info: (...args) => self.postMessage({ type: 'console', level: 'info', args })
+      };
+      
+      // Safe API implementations
+      const emitEvent = (event) => {
+        self.postMessage({ type: 'event', event });
+      };
+      
+      const log = (message) => {
+        self.postMessage({ type: 'log', message });
+      };
+      
+      const assert = (condition, message) => {
+        throw new Error(message || 'Assertion failed');
+      };
+      
+      // Message handler
+      self.onmessage = async (event) => {
+        try {
+          const { context, config } = event.data;
+          
+          const result = await effect(context, {
+            emitEvent,
+            log,
+            assert
+          });
+          
+          self.postMessage({ 
+            success: true, 
+            result,
+            type: 'result'
+          });
+        } catch (error) {
+          self.postMessage({ 
+            success: false, 
+            error: error.message,
+            type: 'error'
+          });
+        }
+      };
+    `;
+  }
+
+  /**
+   * Get sandbox statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    return {
+      type: this.config.type,
+      activeWorkers: this.workers.size,
+      totalExecutions: this.totalExecutions,
+      averageDuration: this.totalExecutions > 0 ? this.totalDuration / this.totalExecutions : 0,
+      config: this.config,
+    };
+  }
+
+  /**
+   * Clear sandbox state
+   */
+  clear() {
+    // Terminate all workers
+    for (const worker of this.workers.values()) {
+      worker.terminate();
+    }
+    this.workers.clear();
+
+    this.executionCount = 0;
+    this.totalExecutions = 0;
+    this.totalDuration = 0;
+  }
+}
+
+/**
+ * Create a new effect sandbox
+ * @param {Object} [config] - Sandbox configuration
+ * @returns {EffectSandbox} New sandbox instance
+ */
+export function createEffectSandbox(config = {}) {
+  return new EffectSandbox(config);
+}
+
+export default EffectSandbox;

package/src/effect-sandbox-worker.mjs

@@ -0,0 +1,170 @@
+/**
+ * @file Worker thread implementation for effect sandbox
+ * @module effect-sandbox-worker
+ *
+ * @description
+ * Worker thread implementation for secure hook effect execution.
+ * This file runs in a separate worker thread to isolate hook execution.
+ */
+
+import { parentPort, workerData, isMainThread } from 'worker_threads';
+
+/**
+ * Worker thread entry point
+ */
+if (!isMainThread) {
+  const { effect, context, executionId, config, _options } = workerData;
+
+  try {
+    // Create safe execution environment
+    const safeGlobals = createSafeGlobals(context, config);
+
+    // Create safe effect function
+    const safeEffect = createSafeEffect(effect, safeGlobals);
+
+    // Execute effect with timeout
+    const result = await executeWithTimeout(safeEffect, context, config.timeout);
+
+    // Send result back to main thread
+    parentPort.postMessage({
+      success: true,
+      result: result.result,
+      assertions: result.assertions || [],
+      events: result.events || [],
+      executionId,
+    });
+  } catch (error) {
+    // Send error back to main thread
+    parentPort.postMessage({
+      success: false,
+      error: error.message,
+      executionId,
+    });
+  }
+}
+
+/**
+ * Create safe globals for worker execution
+ * @param {Object} context - Execution context
+ * @param {Object} config - Sandbox configuration
+ * @returns {Object} Safe globals
+ */
+function createSafeGlobals(context, config) {
+  const globals = {};
+
+  // Add context data
+  globals.event = context.event;
+  globals.store = context.store;
+  globals.delta = context.delta;
+  globals.metadata = context.metadata || {};
+
+  // Add safe console
+  globals.console = {
+    log: message => console.log(`[Worker] ${message}`),
+    warn: message => console.warn(`[Worker] ${message}`),
+    error: message => console.error(`[Worker] ${message}`),
+    info: message => console.info(`[Worker] ${message}`),
+  };
+
+  // Add safe functions
+  globals.emitEvent = eventData => {
+    if (!context.events) context.events = [];
+    context.events.push(eventData);
+  };
+
+  globals.log = (message, level = 'info') => {
+    console.log(`[Sandbox ${level.toUpperCase()}] ${message}`);
+  };
+
+  globals.assert = (subject, predicate, object, graph) => {
+    if (!context.assertions) context.assertions = [];
+    context.assertions.push({ subject, predicate, object, graph });
+  };
+
+  // Add allowed globals
+  for (const globalName of config.allowedGlobals || []) {
+    if (globalName === 'Date') globals.Date = Date;
+    if (globalName === 'Math') globals.Math = Math;
+    if (globalName === 'JSON') globals.JSON = JSON;
+  }
+
+  return globals;
+}
+
+/**
+ * Create safe effect function
+ * @param {string} effectCode - Effect function code
+ * @param {Object} safeGlobals - Safe globals
+ * @returns {Function} Safe effect function
+ */
+function createSafeEffect(effectCode, safeGlobals) {
+  // Create function with safe globals
+  const safeFunction = new Function(
+    ...Object.keys(safeGlobals),
+    `
+    "use strict";
+    
+    // Override dangerous globals
+    const process = undefined;
+    const require = undefined;
+    const module = undefined;
+    const exports = undefined;
+    const __dirname = undefined;
+    const __filename = undefined;
+    
+    // Create effect function
+    const effect = ${effectCode};
+    
+    // Return wrapper that captures assertions and events
+    return function(context) {
+      const result = effect(context);
+      
+      return {
+        result,
+        assertions: context.assertions || [],
+        events: context.events || []
+      };
+    };
+    `
+  );
+
+  return safeFunction(...Object.values(safeGlobals));
+}
+
+/**
+ * Execute function with timeout
+ * @param {Function} fn - Function to execute
+ * @param {Object} context - Execution context
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<Object>} Execution result
+ */
+async function executeWithTimeout(fn, context, timeout) {
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(new Error(`Execution timeout after ${timeout}ms`));
+    }, timeout);
+
+    try {
+      const result = fn(context);
+
+      // Handle both sync and async results
+      if (result && typeof result.then === 'function') {
+        result
+          .then(res => {
+            clearTimeout(timeoutId);
+            resolve(res);
+          })
+          .catch(err => {
+            clearTimeout(timeoutId);
+            reject(err);
+          });
+      } else {
+        clearTimeout(timeoutId);
+        resolve(result);
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      reject(error);
+    }
+  });
+}