@unrdf/knowledge-engine 5.0.1

package/src/hook-management.mjs

@@ -0,0 +1,150 @@
+/**
+ * @file Standalone Hook Management Functions
+ * @module hook-management
+ *
+ * @description
+ * Provides standalone functions for hook management as expected by the README API.
+ * These functions wrap the class methods for easier usage.
+ */
+
+import { defineHook } from './define-hook.mjs';
+import { KnowledgeHookManager } from './knowledge-hook-manager.mjs';
+
+// Global hook manager instance for standalone functions
+let globalHookManager = null;
+
+/**
+ * Initialize the global hook manager if not already initialized
+ * @param {Object} options - Options for the hook manager
+ * @returns {KnowledgeHookManager} The global hook manager
+ */
+function getGlobalHookManager(options = {}) {
+  if (!globalHookManager) {
+    globalHookManager = new KnowledgeHookManager(options);
+  }
+  return globalHookManager;
+}
+
+/**
+ * Register a knowledge hook globally
+ * @param {Object} hook - The knowledge hook to register
+ * @param {Object} options - Manager options (if manager needs initialization)
+ * @throws {Error} If hook is invalid or already exists
+ *
+ * @example
+ * const hook = defineHook({
+ *   meta: { name: 'test-hook', description: 'Test hook' },
+ *   when: { kind: 'sparql-ask', query: 'ASK { ?s ?p ?o }' },
+ *   run: async (event) => console.log('Hook triggered')
+ * });
+ *
+ * await registerHook(hook);
+ */
+export async function registerHook(hook, options = {}) {
+  const manager = getGlobalHookManager(options);
+
+  // Validate hook if it's not already validated
+  const validatedHook = typeof hook === 'object' && !hook._validated ? defineHook(hook) : hook;
+
+  return manager.addKnowledgeHook(validatedHook);
+}
+
+/**
+ * Deregister (remove) a knowledge hook globally
+ * @param {string} hookName - The name of the hook to remove
+ * @returns {boolean} True if hook was removed, false if not found
+ *
+ * @example
+ * const removed = await deregisterHook('test-hook');
+ * console.log('Hook removed:', removed);
+ */
+export async function deregisterHook(hookName) {
+  if (!globalHookManager) {
+    return false;
+  }
+
+  return globalHookManager.removeKnowledgeHook(hookName);
+}
+
+/**
+ * Manually evaluate a hook against given data
+ * @param {Object} hook - The hook to evaluate
+ * @param {Store} store - The RDF store to evaluate against
+ * @param {Object} context - Additional context for evaluation
+ * @returns {Object} Evaluation result
+ *
+ * @example
+ * const result = await evaluateHook(hook, store, { timestamp: Date.now() });
+ * console.log('Hook evaluation result:', result);
+ */
+export async function evaluateHook(hook, store, context = {}) {
+  // Validate hook if needed
+  const validatedHook = typeof hook === 'object' && !hook._validated ? defineHook(hook) : hook;
+
+  // Create a temporary manager for evaluation
+  const tempManager = new KnowledgeHookManager({ enableKnowledgeHooks: true });
+
+  try {
+    // Add hook temporarily
+    tempManager.addKnowledgeHook(validatedHook);
+
+    // Evaluate the hook
+    const event = {
+      store,
+      context,
+      timestamp: Date.now(),
+      hookName: validatedHook.meta.name,
+    };
+
+    // Run the hook evaluation logic
+    const conditionResult = await tempManager.conditionEvaluator.isSatisfied(
+      validatedHook.when,
+      store,
+      context
+    );
+
+    event.result = conditionResult;
+    event.satisfied = conditionResult === true;
+
+    // Execute hook if condition is satisfied
+    if (event.satisfied && validatedHook.run) {
+      event.output = await validatedHook.run(event);
+    }
+
+    return event;
+  } catch (error) {
+    return {
+      error: error.message,
+      hookName: validatedHook.meta.name,
+      timestamp: Date.now(),
+    };
+  }
+}
+
+/**
+ * Get all registered hooks
+ * @returns {Array} Array of registered hook names
+ */
+export function getRegisteredHooks() {
+  if (!globalHookManager) {
+    return [];
+  }
+
+  return Array.from(globalHookManager.knowledgeHooks.keys());
+}
+
+/**
+ * Reset the global hook manager
+ * Useful for testing or cleanup
+ */
+export function resetGlobalHookManager() {
+  globalHookManager = null;
+}
+
+export default {
+  registerHook,
+  deregisterHook,
+  evaluateHook,
+  getRegisteredHooks,
+  resetGlobalHookManager,
+};

package/src/index.mjs

@@ -0,0 +1,93 @@
+/**
+ * @file Central Knowledge Engine Index
+ * @module knowledge-engine
+ *
+ * @description
+ * Centralized export hub for the entire knowledge engine system.
+ * This provides a single import point for all functionality.
+ */
+
+// Core Engine Components
+export { KnowledgeHookManager } from './knowledge-hook-manager.mjs';
+export { TransactionManager } from './transaction.mjs';
+
+// Hook System
+export { defineHook } from './define-hook.mjs';
+export { createHookExecutor } from './hook-executor.mjs';
+export { createConditionEvaluator } from './condition-evaluator.mjs';
+export {
+  registerHook,
+  deregisterHook,
+  evaluateHook,
+  getRegisteredHooks,
+  resetGlobalHookManager,
+} from './hook-management.mjs';
+
+// Knowledge Substrate Core (80/20 Framework)
+export {
+  KnowledgeSubstrateCore,
+  createKnowledgeSubstrateCore,
+  KnowledgeSubstrateFactory,
+  // Legacy compatibility
+  DarkMatterCore,
+  createDarkMatterCore,
+  DarkMatterFactory,
+} from './knowledge-substrate-core.mjs';
+
+// Storage & Persistence
+export { LockchainWriter, createLockchainWriter } from './lockchain-writer.mjs';
+export { ResolutionLayer } from './resolution-layer.mjs';
+
+// Query & Optimization
+export { QueryOptimizer } from './query-optimizer.mjs';
+export { query } from './query.mjs';
+
+// Utilities
+export { parseTurtle, toTurtle, toNQuads, parseJsonLd, toJsonLd } from './parse.mjs';
+export {
+  validateShacl,
+  validateShaclMultiple,
+  formatValidationReport,
+  hasValidationErrors,
+  getValidationErrors,
+  getValidationWarnings,
+} from './validate.mjs';
+export {
+  canonicalize,
+  isIsomorphic,
+  getCanonicalHash,
+  groupByIsomorphism,
+  findDuplicates,
+  getCanonicalizationStats,
+  createCanonicalizationSession,
+} from './canonicalize.mjs';
+export {
+  reason,
+  reasonMultiple,
+  extractInferred,
+  getReasoningStats,
+  validateRules,
+  createReasoningSession,
+} from './reason.mjs';
+export {
+  resolveFileUri,
+  calculateFileHash,
+  loadFileWithHash,
+  loadSparqlFile,
+} from './file-resolver.mjs';
+
+// Security & Sandbox
+export { EffectSandbox } from './effect-sandbox.mjs';
+
+// Policy Management
+export { PolicyPackManager, PolicyPack } from './policy-pack.mjs';
+
+// Observability System
+export {
+  ObservabilityManager,
+  createObservabilityManager,
+  defaultObservabilityManager,
+} from './observability.mjs';
+
+// Consolidated Schemas (single source of truth)
+export * from './schemas.mjs';

package/src/ken-parliment.mjs

@@ -0,0 +1,119 @@
+/**
+ * @file ken-parliament-debug.mjs
+ * @description Debugging version of Parliamentary Swarm Demo with Robert's Rules
+ */
+
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
+import { TransactionManager, printReceipt } from './knowledge-engine.mjs';
+
+const { namedNode, literal, quad } = DataFactory;
+
+async function main() {
+  console.log('🏛️ Starting Parliamentary Swarm Demo (Debug Mode)...\n');
+
+  const store = createStore();
+  const tx = new TransactionManager();
+  const ex = 'http://example.org/';
+
+  // === Hooks ===
+  tx.addHook({
+    id: 'motion-must-be-seconded',
+    mode: 'pre',
+    condition: async (store, delta) => {
+      const adoptions = delta.additions.filter(q => q.predicate.value === `${ex}adoptMotion`);
+      for (const adoption of adoptions) {
+        const motion = adoption.subject;
+        const seconds = store.getQuads(motion, namedNode(`${ex}secondedBy`), null, null);
+        console.log(`🔎 Hook check: ${motion.value} has ${seconds.length} seconds in store.`);
+        if (seconds.length === 0) return false;
+      }
+      return true;
+    },
+    effect: 'veto',
+  });
+
+  tx.addHook({
+    id: 'vote-before-adoption',
+    mode: 'pre',
+    condition: async (store, delta) => {
+      const adoptions = delta.additions.filter(q => q.predicate.value === `${ex}adoptMotion`);
+      for (const adoption of adoptions) {
+        const motion = adoption.subject;
+        const votes = store.getQuads(motion, namedNode(`${ex}votedBy`), null, null);
+        console.log(`🔎 Hook check: ${motion.value} has ${votes.length} votes in store.`);
+        if (votes.length === 0) return false;
+      }
+      return true;
+    },
+    effect: 'veto',
+  });
+
+  tx.addHook({
+    id: 'audit-log',
+    mode: 'post',
+    condition: async () => true,
+    effect: async (_store, delta) => {
+      delta.additions.forEach(q => {
+        console.log(`🪵 Audit: ${q.subject.value} ${q.predicate.value} ${q.object.value}`);
+      });
+    },
+  });
+
+  // === Helper to apply commits ===
+  async function commit(description, additions, actor) {
+    console.log(`\n🤖 ${description}`);
+    const delta = { additions, removals: [] };
+    const { receipt, store: updatedStore } = await tx.apply(store, delta, {
+      actor,
+    });
+
+    // Dump motion state after each commit
+    const motion1Quads = updatedStore.getQuads(namedNode(`${ex}motion1`), null, null, null);
+    console.log('📊 Current motion1 state:');
+    motion1Quads.forEach(q =>
+      console.log(`   • ${q.subject.value} ${q.predicate.value} ${q.object.value}`)
+    );
+
+    // Use the new printReceipt helper
+    printReceipt(receipt, { verbose: true });
+  }
+
+  // === Scenario ===
+  await commit(
+    'PlannerAgent proposes: Introduce motion1: fund AI project',
+    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}introducedBy`), literal('PlannerAgent'))],
+    'PlannerAgent'
+  );
+
+  await commit(
+    'ResearchAgent proposes: Second motion1',
+    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}secondedBy`), literal('ResearchAgent'))],
+    'ResearchAgent'
+  );
+
+  await commit(
+    'CoderAgent proposes: Vote YES on motion1',
+    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}votedBy`), literal('CoderAgent'))],
+    'CoderAgent'
+  );
+
+  await commit(
+    'PlannerAgent proposes: Adopt motion1',
+    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}adoptMotion`), literal('PlannerAgent'))],
+    'PlannerAgent'
+  );
+
+  await commit(
+    'AdversarialAgent proposes: Adopt motion2 (no process)',
+    [quad(namedNode(`${ex}motion2`), namedNode(`${ex}adoptMotion`), literal('AdversarialAgent'))],
+    'AdversarialAgent'
+  );
+
+  console.log('\n✅ Debug demo complete.');
+}
+
+main().catch(err => {
+  console.error('❌ Demo failed:', err);
+  process.exit(1);
+});

package/src/ken.mjs

@@ -0,0 +1,149 @@
+/**
+ * @file Knowledge Engine Bulk Example with Assertions
+ */
+
+import {
+  _parseTurtle,
+  _toTurtle,
+  query,
+  validateShacl,
+  reason,
+  canonicalize,
+  isIsomorphic,
+  TransactionManager,
+} from './knowledge-engine.mjs';
+
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
+import { faker } from '@faker-js/faker';
+import assert from 'assert';
+
+const { namedNode, literal, quad } = DataFactory;
+
+async function generatePeople(count) {
+  const store = createStore();
+  const ex = 'http://example.org/';
+
+  for (let i = 0; i < count; i++) {
+    const id = faker.string.uuid();
+    const iri = namedNode(`${ex}person-${id}`);
+    const name = literal(faker.person.firstName());
+    const age = literal(
+      faker.number.int({ min: 18, max: 90 }).toString(),
+      namedNode('http://www.w3.org/2001/XMLSchema#integer')
+    );
+
+    store.addQuad(iri, namedNode(`${ex}type`), namedNode(`${ex}Person`));
+    store.addQuad(iri, namedNode(`${ex}name`), name);
+    store.addQuad(iri, namedNode(`${ex}age`), age);
+
+    if (i > 0 && Math.random() > 0.5) {
+      const otherIndex = Math.floor(Math.random() * i);
+      const otherIri = namedNode(`${ex}person-${otherIndex}`);
+      store.addQuad(iri, namedNode(`${ex}knows`), otherIri);
+    }
+  }
+
+  return store;
+}
+
+async function main() {
+  const bulkStore = await generatePeople(50);
+  console.log('Generated bulk store size:', bulkStore.size);
+
+  // === Assertion 1: Store has expected number of quads ===
+  assert(bulkStore.size >= 150, 'Store should have at least 3 triples per person');
+
+  // === SPARQL Query ===
+  const rows = await query(
+    bulkStore,
+    `
+    PREFIX ex: <http://example.org/>
+    SELECT ?person ?name ?age WHERE {
+      ?person ex:name ?name ;
+              ex:age ?age .
+    } LIMIT 5
+  `
+  );
+  console.log('SPARQL query results:', rows);
+  assert(rows.length > 0, 'SPARQL query should return at least 1 result');
+  rows.forEach(r => {
+    console.log('Row:', r);
+    assert(r.name && r.name !== '[object Object]', 'Each row should have a name');
+    assert(r.age && r.age !== '[object Object]', 'Each row should have an age');
+  });
+
+  // === SHACL Validation ===
+  const shapesTtl = `
+    @prefix sh: <http://www.w3.org/ns/shacl#> .
+    @prefix ex: <http://example.org/> .
+    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+    ex:PersonShape a sh:NodeShape ;
+      sh:targetClass ex:Person ;
+      sh:property [
+        sh:path ex:name ;
+        sh:datatype xsd:string ;
+        sh:minCount 1
+      ] ;
+      sh:property [
+        sh:path ex:age ;
+        sh:datatype xsd:integer ;
+        sh:minInclusive 0
+      ] .
+  `;
+  const report = validateShacl(bulkStore, shapesTtl);
+  console.log('SHACL validation report:', report);
+  // SHACL validation may return undefined for conforms, so we check that there are no results
+  assert(report.conforms !== false, 'SHACL validation should not have violations');
+  assert(report.results.length === 0, 'SHACL validation should have no validation results');
+
+  // === Reasoning ===
+  const rulesTtl = `
+    @prefix ex: <http://example.org/> .
+    { ?x ex:knows ?y } => { ?y ex:knows ?x } .
+  `;
+  const reasonedStore = await reason(bulkStore, rulesTtl);
+  assert(reasonedStore.size >= bulkStore.size, 'Reasoned store should be same size or larger');
+
+  // === Canonicalization & Isomorphism ===
+  const canonical = await canonicalize(bulkStore);
+  assert(canonical.length > 0, 'Canonicalization should produce non-empty output');
+
+  const copy = createStore(bulkStore.getQuads());
+  const iso = await isIsomorphic(bulkStore, copy);
+  assert.strictEqual(iso, true, 'Copy of store should be isomorphic');
+
+  // === Transactions ===
+  const tx = new TransactionManager();
+  tx.addHook({
+    id: 'no-teenagers',
+    mode: 'pre',
+    condition: async (_store, delta) => {
+      return !delta.additions.some(
+        q => q.predicate.value.endsWith('age') && parseInt(q.object.value) < 18
+      );
+    },
+    effect: 'veto',
+  });
+
+  const delta = {
+    additions: [
+      quad(
+        namedNode('http://example.org/person-extra'),
+        namedNode('http://example.org/age'),
+        literal('15')
+      ),
+    ],
+    removals: [],
+  };
+  const { receipt } = await tx.apply(bulkStore, delta);
+  assert.strictEqual(receipt.committed, false, 'Transaction with underage person should be vetoed');
+
+  console.log('✅ All assertions passed successfully.');
+}
+
+main().catch(err => {
+  console.error('❌ Assertion failed:', err.message);
+  process.exit(1);
+});

package/src/knowledge-engine/builtin-rules.mjs

@@ -0,0 +1,190 @@
+/**
+ * @file Built-in RDFS Inference Rules
+ * @module @unrdf/knowledge-engine/builtin-rules
+ */
+
+import { defineRule } from './rules.mjs';
+
+/**
+ * RDFS SubClass inference rule
+ * If A rdfs:subClassOf B and X rdf:type A, then infer X rdf:type B
+ */
+export const rdfsSubClassRule = defineRule({
+  name: 'rdfs:subClassOf',
+  description: 'Infer type from subclass hierarchy',
+  pattern: [
+    { subject: '?subClass', predicate: 'rdfs:subClassOf', object: '?superClass' },
+    { subject: '?instance', predicate: 'rdf:type', object: '?subClass' },
+  ],
+  consequent: {
+    subject: '?instance',
+    predicate: 'rdf:type',
+    object: '?superClass',
+  },
+  salience: 80,
+});
+
+/**
+ * RDFS SubProperty inference rule
+ * If P rdfs:subPropertyOf Q and X P Y, then infer X Q Y
+ */
+export const rdfsSubPropertyRule = defineRule({
+  name: 'rdfs:subPropertyOf',
+  description: 'Infer property from subproperty hierarchy',
+  pattern: [
+    { subject: '?subProp', predicate: 'rdfs:subPropertyOf', object: '?superProp' },
+    { subject: '?x', predicate: '?subProp', object: '?y' },
+  ],
+  consequent: {
+    subject: '?x',
+    predicate: '?superProp',
+    object: '?y',
+  },
+  salience: 75,
+});
+
+/**
+ * RDFS Domain inference rule
+ * If P rdfs:domain C and X P Y, then infer X rdf:type C
+ */
+export const rdfsDomainRule = defineRule({
+  name: 'rdfs:domain',
+  description: 'Infer type from property domain',
+  pattern: [
+    { subject: '?property', predicate: 'rdfs:domain', object: '?class' },
+    { subject: '?x', predicate: '?property', object: '?y' },
+  ],
+  consequent: {
+    subject: '?x',
+    predicate: 'rdf:type',
+    object: '?class',
+  },
+  salience: 70,
+});
+
+/**
+ * RDFS Range inference rule
+ * If P rdfs:range C and X P Y, then infer Y rdf:type C
+ */
+export const rdfsRangeRule = defineRule({
+  name: 'rdfs:range',
+  description: 'Infer type from property range',
+  pattern: [
+    { subject: '?property', predicate: 'rdfs:range', object: '?class' },
+    { subject: '?x', predicate: '?property', object: '?y' },
+  ],
+  consequent: {
+    subject: '?y',
+    predicate: 'rdf:type',
+    object: '?class',
+  },
+  salience: 70,
+});
+
+/**
+ * OWL Transitive Property rule
+ * If P rdf:type owl:TransitiveProperty and X P Y and Y P Z, then infer X P Z
+ */
+export const owlTransitiveRule = defineRule({
+  name: 'owl:TransitiveProperty',
+  description: 'Apply transitive property closure',
+  pattern: [
+    { subject: '?property', predicate: 'rdf:type', object: 'owl:TransitiveProperty' },
+    { subject: '?x', predicate: '?property', object: '?y' },
+    { subject: '?y', predicate: '?property', object: '?z' },
+  ],
+  consequent: {
+    subject: '?x',
+    predicate: '?property',
+    object: '?z',
+  },
+  salience: 60,
+});
+
+/**
+ * OWL Symmetric Property rule
+ * If P rdf:type owl:SymmetricProperty and X P Y, then infer Y P X
+ */
+export const owlSymmetricRule = defineRule({
+  name: 'owl:SymmetricProperty',
+  description: 'Apply symmetric property',
+  pattern: [
+    { subject: '?property', predicate: 'rdf:type', object: 'owl:SymmetricProperty' },
+    { subject: '?x', predicate: '?property', object: '?y' },
+  ],
+  consequent: {
+    subject: '?y',
+    predicate: '?property',
+    object: '?x',
+  },
+  salience: 65,
+});
+
+/**
+ * OWL Inverse Property rule
+ * If P owl:inverseOf Q and X P Y, then infer Y Q X
+ */
+export const owlInverseRule = defineRule({
+  name: 'owl:inverseOf',
+  description: 'Apply inverse property',
+  pattern: [
+    { subject: '?p', predicate: 'owl:inverseOf', object: '?q' },
+    { subject: '?x', predicate: '?p', object: '?y' },
+  ],
+  consequent: {
+    subject: '?y',
+    predicate: '?q',
+    object: '?x',
+  },
+  salience: 65,
+});
+
+/**
+ * Collection of all built-in RDFS/OWL rules
+ */
+export const builtinRules = [
+  rdfsSubClassRule,
+  rdfsSubPropertyRule,
+  rdfsDomainRule,
+  rdfsRangeRule,
+  owlTransitiveRule,
+  owlSymmetricRule,
+  owlInverseRule,
+];
+
+/**
+ * Get all built-in rules
+ *
+ * @returns {Object[]} Array of built-in rules
+ *
+ * @example
+ * const rules = getBuiltinRules();
+ * addRules(engine, rules);
+ */
+export function getBuiltinRules() {
+  return builtinRules;
+}
+
+/**
+ * Get RDFS rules only (no OWL)
+ *
+ * @returns {Object[]} Array of RDFS rules
+ *
+ * @example
+ * const rdfsRules = getRDFSRules();
+ */
+export function getRDFSRules() {
+  return [rdfsSubClassRule, rdfsSubPropertyRule, rdfsDomainRule, rdfsRangeRule];
+}
+
+/**
+ * Get OWL rules only
+ *
+ * @returns {Object[]} Array of OWL rules
+ *
+ * @example
+ * const owlRules = getOWLRules();
+ */
+export function getOWLRules() {
+  return [owlTransitiveRule, owlSymmetricRule, owlInverseRule];
+}