@unrdf/hooks 26.4.3 → 26.4.4

package/examples/n3-reasoning-example.mjs

@@ -0,0 +1,279 @@
+/**
+ * @unrdf/hooks - N3 Forward-Chaining Reasoning Example
+ *
+ * Demonstrates semantic inference using N3 rules and EYE reasoner.
+ * Derives new facts from existing data through logical rules.
+ *
+ * Use cases:
+ * - RDFS/OWL-like reasoning (class hierarchies, property inference)
+ * - Business rule execution (access control, workflow logic)
+ * - Data enrichment (derive properties from rules)
+ * - Compliance checking (derive compliance status)
+ */
+
+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('=== N3 Forward-Chaining Reasoning Example ===\n');
+
+// Example 1: Simple class inheritance
+console.log('1. Simple Class Inheritance\n');
+
+const classInheritanceCondition = {
+  kind: 'n3',
+  rules: `
+    @prefix : <http://example.org/> .
+    @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+    # Rule: If X is subclass of Y and Z is instance of X, then Z is instance of Y
+    { ?x rdfs:subClassOf ?y . ?z a ?x } => { ?z a ?y } .
+  `,
+  askQuery: 'ASK { ?s a <http://example.org/Animal> }'
+};
+
+console.log('Rules:');
+console.log(classInheritanceCondition.rules);
+console.log('');
+console.log('Scenario:');
+console.log('  Data: Dog subClassOf Animal, Fido a Dog');
+console.log('  Inference: Fido a Animal (derived)');
+console.log('  Query: ASK { ?s a Animal } → true\n');
+
+// Example 2: Access control reasoning
+console.log('2. Access Control Reasoning\n');
+
+const accessControlCondition = {
+  kind: 'n3',
+  rules: `
+    @prefix : <http://example.org/> .
+
+    # Rule 1: Admins can access everything
+    { ?user a :Admin } => { ?user :canAccess :SecureArea } .
+
+    # Rule 2: Group members inherit group permissions
+    { ?user :isMemberOf ?group . ?group :hasPermission ?perm }
+      => { ?user :hasPermission ?perm } .
+
+    # Rule 3: Users with edit permission need audit logging
+    { ?user :hasPermission :EditContent }
+      => { ?user :requiresAuditLog true } .
+
+    # Rule 4: Audit logging required if accessing secure area
+    { ?user :canAccess :SecureArea }
+      => { ?user :requiresAuditLog true } .
+  `,
+  askQuery: 'ASK { ?user :requiresAuditLog true }'
+};
+
+console.log('Rules demonstrate multi-level inference:');
+console.log('  Rule 1: Admin role → access permission');
+console.log('  Rule 2: Group membership → inherit permissions');
+console.log('  Rule 3: Edit permission → audit requirement');
+console.log('  Rule 4: Secure access → audit requirement');
+console.log('');
+console.log('Scenario:');
+console.log('  Data: alice a Admin, bob :isMemberOf :editors');
+console.log('  Step 1: alice a Admin → alice :canAccess :SecureArea');
+console.log('  Step 2: alice :canAccess :SecureArea → alice :requiresAuditLog true');
+console.log('  Step 3: bob :isMemberOf :editors → check group permissions');
+console.log('  Result: Audit requirements derived from roles\n');
+
+// Example 3: Business process workflow
+console.log('3. Business Process Workflow Reasoning\n');
+
+const workflowCondition = {
+  kind: 'n3',
+  rules: `
+    @prefix : <http://example.org/> .
+
+    # Rule 1: Large trades require compliance review
+    { ?trade a :Trade ; :amount ?amt . ?amt > 1000000 }
+      => { ?trade :requiresCompliance true } .
+
+    # Rule 2: Compliance required trades need risk assessment
+    { ?trade :requiresCompliance true }
+      => { ?trade :requiresRiskAssessment true } .
+
+    # Rule 3: Risk assessment must be approved by senior reviewer
+    { ?trade :requiresRiskAssessment true }
+      => { ?trade :requiresApprovalLevel :Senior } .
+
+    # Rule 4: High-risk trades need compliance officer sign-off
+    { ?trade :riskLevel :High ; :requiresApprovalLevel :Senior }
+      => { ?trade :requiresComplianceOfficer true } .
+
+    # Rule 5: Anything needing compliance officer needs audit trail
+    { ?trade :requiresComplianceOfficer true }
+      => { ?trade :auditTrailRequired true } .
+  `,
+  askQuery: 'ASK { ?trade :auditTrailRequired true }'
+};
+
+console.log('Multi-step workflow rules:');
+console.log('  Trade amount > $1M → requires compliance');
+console.log('  Requires compliance → requires risk assessment');
+console.log('  Requires risk assessment → requires senior approval');
+console.log('  High risk + senior approval → needs compliance officer');
+console.log('  Needs compliance officer → needs audit trail');
+console.log('');
+console.log('Execution:');
+console.log('  Input: Trade with amount $1.5M');
+console.log('  Derives: auditTrailRequired = true');
+console.log('  Effect: Create audit record in system\n');
+
+// Example 4: Data enrichment
+console.log('4. Data Enrichment Through Reasoning\n');
+
+const enrichmentCondition = {
+  kind: 'n3',
+  rules: `
+    @prefix : <http://example.org/> .
+    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+    # Rule 1: Calculate age from birthDate
+    { ?person :birthDate ?birth }
+      => { ?person :age ?age } .  # Would need SPARQL for real calculation
+
+    # Rule 2: Categorize by age
+    { ?person :age ?age . ?age > 65 }
+      => { ?person :category :Senior } .
+
+    { ?person :age ?age . ?age >= 18 . ?age <= 65 }
+      => { ?person :category :Adult } .
+
+    { ?person :age ?age . ?age < 18 }
+      => { ?person :category :Minor } .
+
+    # Rule 3: Seniors get special benefits
+    { ?person :category :Senior }
+      => { ?person :eligibleFor :SeniorDiscount } .
+
+    # Rule 4: Mark complete profiles
+    { ?person :name ?n ; :email ?e ; :category ?c }
+      => { ?person :profileComplete true } .
+  `,
+  askQuery: 'ASK { ?p :profileComplete true }'
+};
+
+console.log('Enrichment rules:');
+console.log('  Birthdate → derive age');
+console.log('  Age → categorize as Senior/Adult/Minor');
+console.log('  Senior → eligible for discount');
+console.log('  Complete profile (name + email + category) → mark as complete');
+console.log('');
+console.log('Input: Person with name, email, age');
+console.log('Output: Category, discounts, completeness flag\n');
+
+// Example 5: Compliance rule engine
+console.log('5. Compliance Rule Engine\n');
+
+const complianceCondition = {
+  kind: 'n3',
+  rules: `
+    @prefix : <http://example.org/> .
+
+    # GDPR Rules
+    { ?entity a :PersonalData ; :storedIn ?jurisdiction .
+      ?jurisdiction :region ?region . ?region != :EU }
+      => { ?entity :gdprViolation :DataResidency } .
+
+    # PCI-DSS Rules
+    { ?entity a :CardData ; :encryptionLevel ?level .
+      ?level < 256 }
+      => { ?entity :pciViolation :InsufficientEncryption } .
+
+    # SOX Rules (for public companies)
+    { ?company a :PublicCompany ;
+               :hasFinancialData ?data }
+      => { ?company :requiresSoxCompliance true } .
+
+    # Any violation → requires remediation
+    { ?entity :gdprViolation ?v } => { ?entity :requiresRemediation true } .
+    { ?entity :pciViolation ?v } => { ?entity :requiresRemediation true } .
+
+    # Mark non-compliant if has violations
+    { ?entity :requiresRemediation true }
+      => { ?entity :complianceStatus :NonCompliant } .
+  `,
+  askQuery: 'ASK { ?entity :complianceStatus :NonCompliant }'
+};
+
+console.log('Compliance engine checks:');
+console.log('  GDPR: Personal data must be in EU jurisdiction');
+console.log('  PCI-DSS: Card data must be 256-bit encrypted');
+console.log('  SOX: Public companies must audit financial data');
+console.log('  Any violation → mark non-compliant\n');
+
+// Performance considerations
+console.log('6. Performance Considerations\n');
+
+console.log('Forward-chaining semantics:');
+console.log('  - All applicable rules fire until fixpoint');
+console.log('  - Derives all possible new facts');
+console.log('  - Complete closure of logical consequences');
+console.log('');
+console.log('Performance factors:');
+console.log('  1. Rule count: More rules = more inference steps');
+console.log('  2. Data size: Large graphs = more match attempts');
+console.log('  3. Rule complexity: Join patterns in antecedents');
+console.log('  4. Iteration count: Fixpoint may require many passes');
+console.log('');
+console.log('Optimization tips:');
+console.log('  ✓ Materialize frequently derived facts');
+console.log('  ✓ Use specific patterns (avoid ?x ?p ?o)');
+console.log('  ✓ Order rules: simple → complex');
+console.log('  ✗ Avoid rules that derive rule premises');
+console.log('  ✗ Don\'t use reasoning for high-frequency checks\n');
+
+// Full hook example
+console.log('7. Complete Hook with N3 Reasoning\n');
+
+console.log(`
+const dataEnrichmentHook = {
+  name: 'enriched-trade-data',
+
+  condition: {
+    kind: 'n3',
+    rules: \`
+      @prefix : <http://example.org/> .
+
+      { ?trade a :Trade ; :amount ?amt . ?amt > 500000 }
+        => { ?trade :largeTradeIndicator true } .
+
+      { ?trade :largeTradeIndicator true }
+        => { ?trade :requiresReview true } .
+
+      { ?trade :requiresReview true ; :counterparty ?cp }
+        => { ?cp :hadLargeTrade true } .
+    \`,
+    askQuery: 'ASK { ?t :requiresReview true }'
+  },
+
+  effects: [{
+    kind: 'sparql-construct',
+    query: \`
+      CONSTRUCT {
+        ?trade :reviewStatus ex:Pending ;
+               :derivedFrom ex:N3Rules ;
+               :timestamp ?now .
+      }
+      WHERE {
+        ?trade :requiresReview true .
+        BIND (NOW() as ?now)
+      }
+    \`
+  }]
+};
+
+Execution:
+1. Trade added with amount > $500K
+2. N3 reasoning: derives :requiresReview true
+3. Condition ASK: "is there a :requiresReview?" → true
+4. Effect executes: marks trade as pending review
+5. Counterparty flagged for trading pattern analysis
+`);
+
+console.log('\n=== Example Complete ===');

package/examples/shacl-repair-example.mjs

@@ -0,0 +1,191 @@
+/**
+ * @unrdf/hooks - SHACL Repair Mode Example
+ *
+ * Demonstrates SHACL validation with automatic repair.
+ * When validation fails, repair queries fix data, then re-validate.
+ *
+ * Use cases:
+ * - Auto-filling missing required properties with defaults
+ * - Normalizing invalid references
+ * - Fixing data quality issues automatically
+ */
+
+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('=== SHACL Repair Mode Example ===\n');
+
+// Create a test store
+const store = createStore();
+
+// Add test data (some valid, some missing required properties)
+console.log('1. Loading test data...');
+store.add(
+  quad(
+    namedNode('http://example.org/trade/t1'),
+    namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+    namedNode('http://example.org/Trade')
+  )
+);
+store.add(
+  quad(
+    namedNode('http://example.org/trade/t1'),
+    namedNode('http://example.org/amount'),
+    literal('150000')
+  )
+);
+// Note: missing riskScore
+
+store.add(
+  quad(
+    namedNode('http://example.org/trade/t2'),
+    namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+    namedNode('http://example.org/Trade')
+  )
+);
+// Note: missing both amount and riskScore
+
+console.log(`   Loaded ${store.size} quads\n`);
+
+// Define SHACL condition with repair query
+console.log('2. Defining SHACL repair condition...\n');
+
+const shaclRepairCondition = {
+  kind: 'shacl',
+  ref: {
+    uri: 'file:///shapes/trade-shape.ttl',
+    // Note: in production, provide actual sha256 hash
+    // sha256: 'abc123def456...'
+  },
+  enforcementMode: 'repair',
+  repairConstruct: `
+    # Fill in missing required properties with defaults
+    CONSTRUCT {
+      ?trade ex:riskScore ?defaultRisk ;
+             ex:amount ?defaultAmount ;
+             ex:status ex:Pending .
+    }
+    WHERE {
+      ?trade a ex:Trade .
+      OPTIONAL { ?trade ex:riskScore ?existing . }
+      OPTIONAL { ?trade ex:amount ?existingAmount . }
+      FILTER (!BOUND(?existing) || !BOUND(?existingAmount))
+      BIND (50 as ?defaultRisk)
+      BIND (0 as ?defaultAmount)
+    }
+  `
+};
+
+console.log('Repair CONSTRUCT query:');
+console.log(shaclRepairCondition.repairConstruct);
+console.log('');
+
+// Example 1: Block mode (strictest - no repairs)
+console.log('3. Example: Block Mode (no repairs)\n');
+const blockCondition = {
+  ...shaclRepairCondition,
+  enforcementMode: 'block'
+};
+
+console.log('With block mode:');
+console.log('- Validation failure = hook fails (false)');
+console.log('- No automatic repair attempted');
+console.log('- Application must handle fix separately\n');
+
+// Example 2: Annotate mode (audit trail)
+console.log('4. Example: Annotate Mode (logging)\n');
+const annotateCondition = {
+  ...shaclRepairCondition,
+  enforcementMode: 'annotate'
+};
+
+console.log('With annotate mode:');
+console.log('- Validation failure = add sh:ValidationResult triples');
+console.log('- Returns true (permits operation)');
+console.log('- Violations recorded in RDF for audit trail');
+console.log('- Good for compliance tracking\n');
+
+// Example 3: Repair mode (automatic fixing)
+console.log('5. Example: Repair Mode (automatic fix)\n');
+const repairCondition = {
+  ...shaclRepairCondition,
+  enforcementMode: 'repair'
+};
+
+console.log('With repair mode:');
+console.log('- Validation failure = execute repairConstruct');
+console.log('- Repair adds missing properties with defaults');
+console.log('- Re-validates after repair');
+console.log('- Returns success/failure of final validation\n');
+
+// Example 4: Multi-phase repair strategy
+console.log('6. Complex Example: Multi-Phase Repair\n');
+
+const complexRepairCondition = {
+  kind: 'shacl',
+  ref: { uri: 'file:///shapes/comprehensive.ttl' },
+  enforcementMode: 'repair',
+  repairConstruct: `
+    PREFIX ex: <http://example.org/>
+    PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+
+    CONSTRUCT {
+      ?entity ex:status ex:Reviewed ;
+              ex:lastChecked ?now ;
+              ex:quality ?quality .
+    }
+    WHERE {
+      ?entity a ex:Entity .
+      BIND (NOW() as ?now)
+
+      # Quality assessment: calculate based on completeness
+      OPTIONAL { ?entity ex:description ?desc . }
+      OPTIONAL { ?entity ex:classification ?class . }
+      OPTIONAL { ?entity ex:owner ?owner . }
+
+      BIND (
+        IF(BOUND(?desc) && BOUND(?class) && BOUND(?owner),
+           "high",
+           "medium")
+        as ?quality
+      )
+    }
+  `
+};
+
+console.log('Multi-phase repair includes:');
+console.log('1. Add status field if missing');
+console.log('2. Record timestamp of check');
+console.log('3. Calculate quality score based on available properties\n');
+
+// Practical workflow
+console.log('7. Practical Workflow\n');
+console.log('Step 1: Data arrives (potentially with gaps)');
+console.log('Step 2: evaluateCondition() with shacl/repair');
+console.log('Step 3: If validation fails:');
+console.log('        - Auto repair executes');
+console.log('        - Missing properties filled with defaults');
+console.log('        - Re-validation checks if repair succeeded');
+console.log('Step 4: Result indicates success/failure');
+console.log('Step 5: Application continues based on result\n');
+
+// Best practices
+console.log('8. Best Practices for Repair Mode\n');
+console.log('✓ Use repair for:');
+console.log('  - Filling optional properties with sensible defaults');
+console.log('  - Normalizing data format (URI standardization)');
+console.log('  - Adding audit/lifecycle properties');
+console.log('');
+console.log('✗ Avoid repair for:');
+console.log('  - Changing core business data semantics');
+console.log('  - Complex transformations (use effects instead)');
+console.log('  - Expensive computations (will run on every violation)');
+console.log('');
+console.log('💡 Combine with effects:');
+console.log('  1. Condition: shacl/repair → auto-fix violations');
+console.log('  2. Effect: sparql-construct → apply business logic\n');
+
+console.log('=== Example Complete ===');