@unrdf/hooks 26.4.2 → 26.4.4

package/examples/atomvm-fibo-hooks-demo.mjs

@@ -0,0 +1,323 @@
+/**
+ * @unrdf/hooks - AtomVM/Erlang Integration Example
+ *
+ * Demonstrates the HooksBridge for executing knowledge hooks
+ * from Erlang/BEAM processes via AtomVM.
+ *
+ * This bridges two distributed systems:
+ * - Erlang: Financial transaction processing (hot path, concurrent)
+ * - JavaScript (Node.js + oxigraph): Knowledge hooks (governance, validation)
+ *
+ * Use Case: Real-time trade validation in Erlang financial exchange
+ */
+
+import { createStore, namedNode, literal } from '@unrdf/oxigraph';
+import { createHooksBridge } from '../src/atomvm.mjs';
+import { createContext } from '@unrdf/v6-core/receipt-pattern';
+
+const FIBO_NS = 'https://spec.edmcouncil.org/fibo/ontology/';
+const EX_NS = 'http://example.org/';
+
+console.log('═'.repeat(70));
+console.log('AtomVM/Erlang Integration - FIBO Hooks Demo');
+console.log('═'.repeat(70));
+
+// Initialize store and bridge
+console.log('\n1️⃣  Initializing HooksBridge...');
+const store = createStore();
+const bridge = createHooksBridge(store, {
+  persistReceipts: true,
+  maxHooks: 100,
+});
+console.log('✅ Bridge initialized');
+
+// Simulate registration from Erlang processes
+console.log('\n2️⃣  Registering Hooks (Erlang → Bridge)...');
+
+(async () => {
+  try {
+    // Hook 1: Basic ASK condition for any trade
+    const hook1Id = await bridge.registerHook({
+      name: 'erlang-verify-trade',
+      condition: {
+        kind: 'sparql-ask',
+        query: `
+          PREFIX ex: <${EX_NS}>
+          ASK {
+            ?trade a ex:Trade ;
+                   ex:amount ?amt .
+            FILTER (?amt > 0)
+          }
+        `,
+      },
+      effects: [
+        {
+          kind: 'sparql-construct',
+          query: `
+            PREFIX ex: <${EX_NS}>
+            CONSTRUCT {
+              ?trade ex:bridgeVerified true ;
+                     ex:verificationTime ?now .
+            }
+            WHERE {
+              ?trade a ex:Trade .
+              BIND (NOW() as ?now)
+            }
+          `,
+        },
+      ],
+      metadata: {
+        source: 'erlang-process-1',
+        version: '1.0',
+      },
+    });
+
+    console.log(`✅ Registered hook 1: ID=${hook1Id}`);
+
+    // Hook 2: Datalog-based risk assessment
+    const hook2Id = await bridge.registerHook({
+      name: 'erlang-assess-risk',
+      condition: {
+        kind: 'datalog',
+        facts: [
+          'trader("alice")',
+          'trader("bob")',
+          'authorized("alice")',
+          'position("alice", 100000)',
+          'position("bob", 50000)',
+        ],
+        rules: [
+          'can_trade(T) :- trader(T), authorized(T)',
+          'large_position(T) :- position(T, P), P >= 100000',
+          'needs_review(T) :- large_position(T), can_trade(T)',
+        ],
+        goal: 'needs_review("alice")',
+      },
+      effects: [
+        {
+          kind: 'sparql-construct',
+          query: `
+            PREFIX ex: <${EX_NS}>
+            CONSTRUCT {
+              ?trader ex:riskReviewRequired true ;
+                      ex:riskLevel ex:High .
+            }
+            WHERE {
+              ?trader a ex:Trader .
+            }
+          `,
+        },
+      ],
+      metadata: {
+        source: 'erlang-process-2',
+      },
+    });
+
+    console.log(`✅ Registered hook 2: ID=${hook2Id}`);
+
+    // Hook 3: N3 inference rules for compliance
+    const hook3Id = await bridge.registerHook({
+      name: 'erlang-infer-compliance',
+      condition: {
+        kind: 'n3',
+        rules: `
+          PREFIX ex: <${EX_NS}>
+
+          { ?trade ex:amount ?amt . ?amt math:lessThan 1000000 }
+          =>
+          { ?trade ex:complianceLevel ex:Standard } .
+
+          { ?trade ex:amount ?amt . ?amt math:greaterThanOrEqual 1000000 }
+          =>
+          { ?trade ex:complianceLevel ex:Enhanced } .
+
+          { ?trade ex:complianceLevel ex:Enhanced }
+          =>
+          { ?trade ex:requiresAudit true } .
+        `,
+        askQuery: `
+          PREFIX ex: <${EX_NS}>
+          ASK { ?trade ex:requiresAudit true }
+        `,
+      },
+      effects: [
+        {
+          kind: 'sparql-construct',
+          query: `
+            PREFIX ex: <${EX_NS}>
+            CONSTRUCT {
+              ?trade ex:auditInitiated true ;
+                     ex:auditTimestamp ?now .
+            }
+            WHERE {
+              ?trade a ex:Trade .
+              BIND (NOW() as ?now)
+            }
+          `,
+        },
+      ],
+      metadata: {
+        source: 'erlang-process-3',
+        reasoning: 'n3-eye-reasoner',
+      },
+    });
+
+    console.log(`✅ Registered hook 3: ID=${hook3Id}`);
+
+    // List all registered hooks
+    console.log('\n3️⃣  Listing Registered Hooks...');
+    const hooks = bridge.listHooks();
+    console.log(`📋 Total hooks registered: ${hooks.length}`);
+    hooks.forEach((h, i) => {
+      console.log(`   ${i + 1}. ${h.name} (ID: ${h.id})`);
+    });
+
+    // Simulate data from Erlang
+    console.log('\n4️⃣  Loading Trade Data...');
+    const tradeQuads = [
+      [
+        namedNode(`${EX_NS}trade/erlang-trade-001`),
+        namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+        namedNode(`${EX_NS}Trade`),
+      ],
+      [
+        namedNode(`${EX_NS}trade/erlang-trade-001`),
+        namedNode(`${EX_NS}amount`),
+        literal('500000'),
+      ],
+      [
+        namedNode(`${EX_NS}trade/erlang-trade-001`),
+        namedNode(`${EX_NS}status`),
+        namedNode(`${EX_NS}Active`),
+      ],
+    ];
+
+    tradeQuads.forEach(([s, p, o]) => {
+      store.insert([s, p, o], namedNode(`${EX_NS}default`));
+    });
+    console.log(`✅ Loaded ${tradeQuads.length} quads`);
+
+    // Evaluate conditions from Erlang
+    console.log('\n5️⃣  Evaluating Conditions from Erlang...');
+
+    const sparqlAskResult = await bridge.evaluateCondition({
+      kind: 'sparql-ask',
+      query: `
+        PREFIX ex: <${EX_NS}>
+        ASK {
+          ?trade a ex:Trade ;
+                 ex:amount ?amt .
+          FILTER (?amt > 0)
+        }
+      `,
+    });
+    console.log(`✅ SPARQL ASK result: ${sparqlAskResult ? '✓ True' : '✗ False'}`);
+
+    const datalogResult = await bridge.evaluateCondition({
+      kind: 'datalog',
+      facts: ['trade("erlang-trade-001")'],
+      rules: ['valid(T) :- trade(T)'],
+      goal: 'valid("erlang-trade-001")',
+    });
+    console.log(`✅ Datalog result: ${datalogResult ? '✓ True' : '✗ False'}`);
+
+    // Execute hooks with receipt chaining
+    console.log('\n6️⃣  Executing Hooks (Erlang → Bridge → Store)...');
+
+    const executionContext = createContext({
+      nodeId: 'erlang-trade-processor',
+      t_ns: BigInt(Date.now() * 1000000),
+    });
+
+    const result = await bridge.executeHooks(executionContext, [
+      hook1Id,
+      hook2Id,
+      hook3Id,
+    ]);
+
+    console.log(`✅ Execution complete:`);
+    console.log(`   Successful: ${result.successful}`);
+    console.log(`   Failed: ${result.failed}`);
+
+    // Receipt chain (Priority 1 & 4)
+    console.log('\n7️⃣  Receipt Chain Verification...');
+    const receipt = result.receipt;
+    console.log(`✅ Receipt Hash:  ${receipt.receiptHash.substring(0, 32)}...`);
+    console.log(`   Input Hash:   ${receipt.input_hash.substring(0, 32)}...`);
+    console.log(`   Output Hash:  ${receipt.output_hash.substring(0, 32)}...`);
+    console.log(`   Node ID:      ${receipt.nodeId}`);
+
+    // Verify receipt chain
+    const chain = bridge.getReceiptChain();
+    console.log(`\n8️⃣  Receipt Chain Status...`);
+    console.log(`📊 Total receipts: ${chain.length}`);
+
+    const verification = bridge.verifyReceiptChain();
+    if (verification.valid) {
+      console.log(`✅ Chain integrity verified`);
+    } else {
+      console.log(`❌ Chain broken at receipt ${verification.brokenAt}`);
+    }
+
+    // State changes
+    if (receipt.delta) {
+      console.log(`\n9️⃣  State Changes (Delta)`);
+      console.log(`📝 Additions:  ${receipt.delta.adds.length} quads`);
+      console.log(`🗑️  Deletions: ${receipt.delta.deletes.length} quads`);
+
+      if (receipt.delta.adds.length > 0) {
+        console.log('\nSample additions:');
+        receipt.delta.adds.slice(0, 3).forEach((add) => {
+          console.log(`   + ${add.subject} ${add.predicate} ${add.object}`);
+        });
+      }
+    }
+
+    // Bridge statistics
+    console.log('\n🔟 Bridge Statistics');
+    const stats = bridge.getStats();
+    console.log(`📊 Hooks registered: ${stats.hookCount}`);
+    console.log(`📊 Receipt history: ${stats.receiptCount}`);
+    console.log(`📊 Memory usage: ${(stats.memoryBytes / 1024).toFixed(2)} KB`);
+
+    // Simulate multiple execution cycles (as would happen in Erlang)
+    console.log('\n1️⃣1️⃣  Simulating Multiple Execution Cycles...');
+
+    for (let i = 0; i < 2; i++) {
+      const ctx = createContext({
+        nodeId: 'erlang-trade-processor',
+        t_ns: BigInt(Date.now() * 1000000),
+        previousReceiptHash: i > 0 ? chain[chain.length - 1].receiptHash : undefined,
+      });
+
+      await bridge.executeHooks(ctx, [hook1Id]);
+      const updatedChain = bridge.getReceiptChain();
+      console.log(`✅ Cycle ${i + 1}: ${updatedChain.length} receipts in chain`);
+    }
+
+    // Final summary
+    console.log('\n' + '═'.repeat(70));
+    console.log('✨ AtomVM Bridge Demo Complete!');
+    console.log('═'.repeat(70));
+
+    console.log('\n📋 Summary:');
+    console.log('  ✅ Hooks registered from Erlang');
+    console.log('  ✅ Conditions evaluated dynamically');
+    console.log('  ✅ Hooks executed with receipt chaining');
+    console.log('  ✅ Receipt chain integrity verified');
+    console.log('  ✅ State changes tracked (delta)');
+    console.log('  ✅ Multi-cycle execution demonstrates deterministic receipts');
+
+    console.log('\n💡 Next Steps:');
+    console.log('  1. Connect via HTTP gateway to Erlang processes');
+    console.log('  2. Implement Erlang gen_server for async hook evaluation');
+    console.log('  3. Persist receipts to distributed ledger');
+    console.log('  4. Scale to thousands of concurrent trades');
+
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+})();

package/examples/delta-monitoring-example.mjs

@@ -0,0 +1,213 @@
+/**
+ * @unrdf/hooks - Delta Monitoring Example
+ *
+ * Demonstrates change detection using Delta conditions.
+ * Triggers rules when data grows, shrinks, or changes significantly.
+ *
+ * Use cases:
+ * - Validation on large imports (increase > 10%)
+ * - Anomaly detection on suspicious deletes
+ * - Rate limiting on rapid changes
+ * - Archive triggers on data growth
+ */
+
+import { createStore } from '@unrdf/oxigraph';
+import { evaluateCondition } from '../src/hooks/condition-evaluator.mjs';
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+
+const { namedNode, literal, quad } = DataFactory;
+
+console.log('=== Delta Monitoring Example ===\n');
+
+// Utility: create a hook condition with delta spec
+function createDeltaCondition(changeType, threshold = 0.1) {
+  return {
+    kind: 'delta',
+    spec: {
+      change: changeType,
+      threshold: threshold
+    }
+  };
+}
+
+// Example 1: Detect any change
+console.log('1. Detect Any Change\n');
+const anyChangeCondition = createDeltaCondition('any');
+
+console.log('Condition:');
+console.log(JSON.stringify(anyChangeCondition, null, 2));
+console.log('');
+console.log('Triggers when: any quad is added or deleted');
+console.log('Use for: audit trails, change notifications');
+console.log('');
+
+// Example 2: Detect data growth
+console.log('2. Detect Data Growth (Increase)\n');
+const growthCondition = createDeltaCondition('increase', 0.1);
+
+console.log('Condition:');
+console.log(JSON.stringify(growthCondition, null, 2));
+console.log('');
+console.log('Triggers when: net adds > 10% of total quads');
+console.log('Example: If store has 100 quads, triggers if 11+ net adds');
+console.log('Use for: validation after imports, reindexing\n');
+
+// Example 3: Detect data loss
+console.log('3. Detect Data Loss (Decrease)\n');
+const shrinkCondition = createDeltaCondition('decrease', 0.05);
+
+console.log('Condition:');
+console.log(JSON.stringify(shrinkCondition, null, 2));
+console.log('');
+console.log('Triggers when: net deletes > 5% of total quads');
+console.log('Example: If store has 100 quads, triggers if 6+ net deletes');
+console.log('Use for: anomaly detection, suspicious deletion alerts\n');
+
+// Example 4: Detect significant modifications
+console.log('4. Detect Significant Changes (Modify)\n');
+const modifyCondition = createDeltaCondition('modify', 0.15);
+
+console.log('Condition:');
+console.log(JSON.stringify(modifyCondition, null, 2));
+console.log('');
+console.log('Triggers when: |adds - deletes| > 15% of total quads');
+console.log('Example: 20 adds + 5 deletes = 25 net, triggers if > 15 quads');
+console.log('Use for: detecting bulk replace/sync operations\n');
+
+// Practical scenarios
+console.log('5. Real-World Scenarios\n');
+
+console.log('Scenario A: Data Import Validation');
+console.log('-'.repeat(40));
+console.log(`
+Hook: {
+  condition: {
+    kind: 'delta',
+    spec: { change: 'increase', threshold: 0.2 }  // 20% growth
+  },
+  effects: [{
+    kind: 'sparql-construct',
+    query: 'CONSTRUCT { ?s ex:imported true } WHERE { ?s a ex:NewData }'
+  }]
+}
+
+Trigger: When bulk data import adds > 20% new quads
+Action: Mark imported entities, run compliance checks
+`);
+
+console.log('Scenario B: Suspicious Deletion Alert');
+console.log('-'.repeat(40));
+console.log(`
+Hook: {
+  condition: {
+    kind: 'delta',
+    spec: { change: 'decrease', threshold: 0.02 }  // 2% loss
+  },
+  effects: [{
+    kind: 'sparql-construct',
+    query: 'CONSTRUCT { ?s ex:audit ex:DeleteAlert } WHERE { ?s ?p ?o }'
+  }]
+}
+
+Trigger: When deletions exceed 2% (unusual for stable data)
+Action: Create audit record for investigation
+`);
+
+console.log('Scenario C: Archive on Growth');
+console.log('-'.repeat(40));
+console.log(`
+Hook: {
+  condition: {
+    kind: 'delta',
+    spec: { change: 'increase', threshold: 0.5 }  // 50% growth
+  },
+  effects: [{
+    kind: 'function',
+    inline: async (store) => {
+      // Archive cold data to external storage
+      return { archived: true, count: store.size };
+    }
+  }]
+}
+
+Trigger: When data doubles (50% growth)
+Action: Archive historical data to long-term storage
+`);
+
+// Change calculation logic
+console.log('\n6. Delta Calculation Details\n');
+
+console.log('Formula for change magnitude:');
+console.log('  changeMagnitude = (additions - deletions) / totalQuads\n');
+
+console.log('Example calculation:');
+console.log('  Store size:    1000 quads');
+console.log('  Additions:     250 quads');
+console.log('  Deletions:     50 quads');
+console.log('  Net change:    250 - 50 = 200');
+console.log('  Magnitude:     200 / 1000 = 0.2 (20%)\n');
+
+console.log('  Condition evaluation:');
+console.log('  - increase (threshold 0.1):  0.2 > 0.1 ✓ TRIGGERS');
+console.log('  - increase (threshold 0.3):  0.2 > 0.3 ✗ no trigger');
+console.log('  - decrease (threshold 0.1): -0.2 < -0.1 ✗ no trigger');
+console.log('  - modify (threshold 0.15):  |0.2| > 0.15 ✓ TRIGGERS\n');
+
+// Threshold recommendations
+console.log('7. Recommended Thresholds\n');
+
+console.log('Data Size          Increase   Decrease   Modify   Use Case');
+console.log('-' * 60);
+console.log('< 100 quads        0.20       0.20       0.20     Development');
+console.log('100-1K quads       0.15       0.10       0.15     Small datasets');
+console.log('1K-100K quads      0.10       0.05       0.10     Medium datasets');
+console.log('> 100K quads       0.05       0.02       0.05     Large graphs\n');
+
+// Combining with effects
+console.log('8. Combined Example: Monitor + React\n');
+
+console.log(`
+const importValidationHook = {
+  name: 'validate-large-import',
+
+  condition: {
+    kind: 'delta',
+    spec: { change: 'increase', threshold: 0.1 }  // 10% growth trigger
+  },
+
+  effects: [
+    // Effect 1: Mark newly added entities
+    {
+      kind: 'sparql-construct',
+      query: \`CONSTRUCT {
+        ?s ex:addedAt ?now ;
+           ex:source ex:Import .
+      } WHERE {
+        ?s a ex:Trade .
+        BIND (NOW() as ?now)
+      }\`
+    },
+
+    // Effect 2: Run compliance check
+    {
+      kind: 'sparql-construct',
+      query: \`CONSTRUCT {
+        ?s ex:complianceStatus ex:PendingReview .
+      } WHERE {
+        ?s a ex:Trade ;
+           ex:source ex:Import .
+      }\`
+    }
+  ]
+};
+`);
+
+console.log('\nExecution flow:');
+console.log('1. New data added to store (e.g., 250 of 1000 quads)');
+console.log('2. Delta condition evaluates: 0.25 > 0.10 ✓');
+console.log('3. First effect executes: mark new trades with timestamp');
+console.log('4. Second effect executes: set compliance status');
+console.log('5. Hook completes successfully');
+console.log('6. Compliance team notified for batch review\n');
+
+console.log('=== Example Complete ===');