@unrdf/knowledge-engine 5.0.1 → 26.4.3

package/src/define-hook.mjs

@@ -1,213 +0,0 @@
-/**
- * @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

@@ -1,283 +0,0 @@
-/**
- * @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

@@ -1,170 +0,0 @@
-/**
- * @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);
-    }
-  });
-}