@unrdf/knowledge-engine 5.0.1 → 26.4.3

package/src/formation-theorems.mjs

@@ -0,0 +1,345 @@
+/**
+ * @file Formation Theorems - Blue Ocean Calculus
+ * @module knowledge-engine/formation-theorems
+ *
+ * @description
+ * Implements the formation theorems from blue ocean calculus, deriving
+ * strategic formations from dark field patterns in the Chatman Equation.
+ *
+ * Key Theorems:
+ * 1. Formation Emergence: Uncontested spaces emerge from dark field
+ * 2. Value Innovation: New value curves from pattern recombination
+ * 3. Strategic Canvas: Competitive factors mapped to dark field dimensions
+ */
+
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+
+/**
+ * Formation schema
+ */
+export const FormationSchema = z.object({
+  id: z.string().uuid(),
+  theorem: z.enum(['emergence', 'value_innovation', 'strategic_canvas', 'four_actions']),
+  type: z.enum(['market', 'organizational', 'strategic', 'disruption']),
+  input: z.object({
+    darkFieldPatterns: z.array(z.string()),
+    observablePatterns: z.array(z.string()),
+  }),
+  output: z.object({
+    formation: z.array(z.string()),
+    valueProposition: z.string(),
+    strategicMoves: z.array(z.string()),
+  }),
+  confidence: z.number().min(0).max(1),
+  derivedAt: z.number(),
+});
+
+/**
+ * Formation options schema
+ */
+export const FormationOptionsSchema = z.object({
+  theorem: z
+    .enum(['emergence', 'value_innovation', 'strategic_canvas', 'four_actions'])
+    .default('emergence'),
+  minConfidence: z.number().min(0).max(1).default(0.7),
+  maxFormations: z.number().int().positive().default(10),
+});
+
+/**
+ * Formation theorems calculator
+ */
+export class FormationTheorems {
+  /**
+   * Create a new formation theorems calculator
+   * @param {Object} [options] - Calculator options
+   * @param {Function} [options.tracer] - OTEL tracer function
+   */
+  constructor(options = {}) {
+    this.tracer = options.tracer;
+    this.metrics = {
+      theoremsApplied: 0,
+      formationsGenerated: 0,
+      averageConfidence: 0,
+    };
+  }
+
+  /**
+   * Apply formation theorem to derive strategic formations
+   * @param {Object} artifact - Artifact with observable and dark field
+   * @param {Object} [options] - Formation options
+   * @returns {Promise<Object>} Formation result
+   */
+  async derive(artifact, options = {}) {
+    const span = this.tracer?.startSpan?.('chatman.formation.derive');
+    const startTime = Date.now();
+
+    try {
+      const opts = FormationOptionsSchema.parse(options);
+
+      span?.setAttribute?.('artifact.type', artifact.type);
+      span?.setAttribute?.('theorem', opts.theorem);
+      span?.setAttribute?.('dark_field_size', artifact.darkField.patterns.length);
+
+      const theoremFn = this._getTheoremFunction(opts.theorem);
+      const formation = theoremFn(artifact, opts);
+
+      // Update metrics
+      this.metrics.theoremsApplied++;
+      this.metrics.formationsGenerated += formation.output.formation.length;
+      this.metrics.averageConfidence =
+        (this.metrics.averageConfidence * (this.metrics.theoremsApplied - 1) +
+          formation.confidence) /
+        this.metrics.theoremsApplied;
+
+      span?.addEvent?.('formation_derived', {
+        'formation.id': formation.id,
+        'formation.theorem': formation.theorem,
+        'formation.confidence': formation.confidence,
+        'formation.size': formation.output.formation.length,
+        'formation.duration_ms': Date.now() - startTime,
+      });
+
+      return FormationSchema.parse(formation);
+    } catch (error) {
+      span?.recordException?.(error);
+      span?.setStatus?.({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span?.end?.();
+    }
+  }
+
+  /**
+   * Get theorem function by name
+   * @param {string} theorem - Theorem name
+   * @returns {Function} Theorem function
+   * @private
+   */
+  _getTheoremFunction(theorem) {
+    const theorems = {
+      emergence: this._applyEmergenceTheorem.bind(this),
+      value_innovation: this._applyValueInnovationTheorem.bind(this),
+      strategic_canvas: this._applyStrategicCanvasTheorem.bind(this),
+      four_actions: this._applyFourActionsTheorem.bind(this),
+    };
+    return theorems[theorem];
+  }
+
+  /**
+   * Apply emergence theorem - uncontested spaces from dark field
+   * @param {Object} artifact - Artifact
+   * @param {Object} options - Options
+   * @returns {Object} Formation
+   * @private
+   */
+  _applyEmergenceTheorem(artifact, options) {
+    const formation = [];
+    const strategicMoves = [];
+
+    // Identify uncontested spaces in dark field
+    const uncontestedPatterns = artifact.darkField.patterns
+      .filter((p, i) => i < options.maxFormations)
+      .filter(p => p.includes('latent') || p.includes('emergent') || p.includes('hidden'));
+
+    for (const pattern of uncontestedPatterns) {
+      formation.push(`blue_ocean_space:${pattern}`);
+      strategicMoves.push(`explore:${pattern}`);
+    }
+
+    const valueProposition = `Create uncontested market space in: ${uncontestedPatterns
+      .map(p => p.split(':')[0])
+      .join(', ')}`;
+
+    return {
+      id: randomUUID(),
+      theorem: 'emergence',
+      type: artifact.type,
+      input: {
+        darkFieldPatterns: artifact.darkField.patterns,
+        observablePatterns: artifact.observable.patterns,
+      },
+      output: {
+        formation,
+        valueProposition,
+        strategicMoves,
+      },
+      confidence: 0.85,
+      derivedAt: Date.now(),
+    };
+  }
+
+  /**
+   * Apply value innovation theorem - new value curves from recombination
+   * @param {Object} artifact - Artifact
+   * @param {Object} options - Options
+   * @returns {Object} Formation
+   * @private
+   */
+  _applyValueInnovationTheorem(artifact, options) {
+    const formation = [];
+    const strategicMoves = [];
+
+    // Recombine dark field and observable to create value innovations
+    const innovations = artifact.darkField.patterns
+      .slice(0, Math.min(5, options.maxFormations))
+      .map((darkPattern, i) => {
+        const observablePattern =
+          artifact.observable.patterns[i % artifact.observable.patterns.length];
+        return `${darkPattern}+${observablePattern}`;
+      });
+
+    for (const innovation of innovations) {
+      formation.push(`value_innovation:${innovation}`);
+      strategicMoves.push(`innovate:${innovation}`);
+    }
+
+    const valueProposition = `Simultaneous differentiation and low cost through: ${innovations.length} value innovations`;
+
+    return {
+      id: randomUUID(),
+      theorem: 'value_innovation',
+      type: artifact.type,
+      input: {
+        darkFieldPatterns: artifact.darkField.patterns,
+        observablePatterns: artifact.observable.patterns,
+      },
+      output: {
+        formation,
+        valueProposition,
+        strategicMoves,
+      },
+      confidence: 0.8,
+      derivedAt: Date.now(),
+    };
+  }
+
+  /**
+   * Apply strategic canvas theorem - map competitive factors
+   * @param {Object} artifact - Artifact
+   * @param {Object} options - Options
+   * @returns {Object} Formation
+   * @private
+   */
+  _applyStrategicCanvasTheorem(artifact, options) {
+    const formation = [];
+    const strategicMoves = [];
+
+    // Map observable (current factors) vs dark field (new factors)
+    const currentFactors = artifact.observable.patterns.slice(0, 5);
+    const newFactors = artifact.darkField.patterns
+      .filter(p => p.includes('hidden') || p.includes('latent'))
+      .slice(0, 5);
+
+    // Eliminate-Reduce-Raise-Create framework
+    strategicMoves.push(`eliminate:${currentFactors[0]}`);
+    strategicMoves.push(`reduce:${currentFactors[1]}`);
+    strategicMoves.push(`raise:${newFactors[0]}`);
+    strategicMoves.push(`create:${newFactors[1]}`);
+
+    formation.push(`strategic_canvas:eliminate-reduce-raise-create`);
+    formation.push(...newFactors.map(f => `new_factor:${f}`));
+
+    const valueProposition = `Reconstruct market boundaries with ${newFactors.length} new competitive factors`;
+
+    return {
+      id: randomUUID(),
+      theorem: 'strategic_canvas',
+      type: artifact.type,
+      input: {
+        darkFieldPatterns: artifact.darkField.patterns,
+        observablePatterns: artifact.observable.patterns,
+      },
+      output: {
+        formation,
+        valueProposition,
+        strategicMoves,
+      },
+      confidence: 0.78,
+      derivedAt: Date.now(),
+    };
+  }
+
+  /**
+   * Apply four actions theorem - ERRC framework
+   * @param {Object} artifact - Artifact
+   * @param {Object} options - Options
+   * @returns {Object} Formation
+   * @private
+   */
+  _applyFourActionsTheorem(artifact, options) {
+    const formation = [];
+    const strategicMoves = [];
+
+    const observable = artifact.observable.patterns;
+    const darkField = artifact.darkField.patterns;
+
+    // Eliminate: factors to remove
+    const eliminate = observable.slice(0, 2).map(p => `eliminate:${p}`);
+
+    // Reduce: factors to reduce below industry standard
+    const reduce = observable.slice(2, 4).map(p => `reduce:${p}`);
+
+    // Raise: factors to raise above industry standard
+    const raise = darkField
+      .filter(p => p.includes('emergent'))
+      .slice(0, 2)
+      .map(p => `raise:${p}`);
+
+    // Create: factors never offered by industry
+    const create = darkField
+      .filter(p => p.includes('hidden') || p.includes('latent'))
+      .slice(0, 3)
+      .map(p => `create:${p}`);
+
+    formation.push(...eliminate, ...reduce, ...raise, ...create);
+    strategicMoves.push(...eliminate, ...reduce, ...raise, ...create);
+
+    const valueProposition = `Four Actions Framework: Eliminate ${eliminate.length}, Reduce ${reduce.length}, Raise ${raise.length}, Create ${create.length}`;
+
+    return {
+      id: randomUUID(),
+      theorem: 'four_actions',
+      type: artifact.type,
+      input: {
+        darkFieldPatterns: artifact.darkField.patterns,
+        observablePatterns: artifact.observable.patterns,
+      },
+      output: {
+        formation,
+        valueProposition,
+        strategicMoves,
+      },
+      confidence: 0.82,
+      derivedAt: Date.now(),
+    };
+  }
+
+  /**
+   * Get calculator metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    return { ...this.metrics };
+  }
+
+  /**
+   * Reset calculator metrics
+   */
+  resetMetrics() {
+    this.metrics = {
+      theoremsApplied: 0,
+      formationsGenerated: 0,
+      averageConfidence: 0,
+    };
+  }
+}
+
+/**
+ * Create a formation theorems calculator instance
+ * @param {Object} [options] - Calculator options
+ * @returns {FormationTheorems} Calculator instance
+ */
+export function createFormationTheorems(options = {}) {
+  return new FormationTheorems(options);
+}

package/src/index.mjs

@@ -35,12 +35,12 @@ export {
 } from './knowledge-substrate-core.mjs';
 
 // Storage & Persistence
-export { LockchainWriter, createLockchainWriter } from './lockchain-writer.mjs';
+export { LockchainWriter, createLockchainWriter } from '@unrdf/core/utils/lockchain-writer';
 export { ResolutionLayer } from './resolution-layer.mjs';
 
 // Query & Optimization
 export { QueryOptimizer } from './query-optimizer.mjs';
-export { query } from './query.mjs';
+export { query, select, ask, construct, describe, update, getQueryStats } from './query.mjs';
 
 // Utilities
 export { parseTurtle, toTurtle, toNQuads, parseJsonLd, toJsonLd } from './parse.mjs';
@@ -89,5 +89,23 @@ export {
   defaultObservabilityManager,
 } from './observability.mjs';
 
+// Chatman Equation Integration
+export { ChatmanOperator, createChatmanOperator } from './chatman-operator.mjs';
+export { ArtifactGenerator, createArtifactGenerator } from './artifact-generator.mjs';
+export { DarkFieldDetector, createDarkFieldDetector } from './dark-field-detector.mjs';
+export { FormationTheorems, createFormationTheorems } from './formation-theorems.mjs';
+export {
+  ChatmanConfigLoader,
+  createChatmanConfigLoader,
+  loadChatmanConfig,
+} from './chatman-config-loader.mjs';
+export { ChatmanEngine, createChatmanEngine } from './chatman-engine.mjs';
+
+// Chatman Dynamics Rules
+export * from './chatman/market-dynamics.mjs';
+export * from './chatman/organizational-dynamics.mjs';
+export * from './chatman/strategic-dynamics.mjs';
+export * from './chatman/disruption-arithmetic.mjs';
+
 // Consolidated Schemas (single source of truth)
 export * from './schemas.mjs';

package/src/knowledge-hook-manager.mjs

@@ -12,7 +12,7 @@ import { createHookExecutor } from './hook-executor.mjs';
 import { createConditionEvaluator } from './condition-evaluator.mjs';
 import { PolicyPackManager } from './policy-pack.mjs';
 import { createSecurityValidator } from './security-validator.mjs';
-import { validateManagerConfig, _validateTransactionDelta, validateHookEvent } from './schemas.mjs';
+import { validateManagerConfig, validateTransactionDelta, validateHookEvent } from './schemas.mjs';
 
 /**
  * Knowledge Hook Manager that extends the transaction system with file-based hooks.

package/src/lockchain-writer-browser.mjs

@@ -8,9 +8,9 @@
  * verification without Git dependencies.
  */
 
-import { randomUUID, createHash, _fs } from './browser-shims.mjs';
+import { randomUUID, createHash, fs } from './browser-shims.mjs';
 import { sha3_256 } from '@noble/hashes/sha3.js';
-import { _blake3 } from '@noble/hashes/blake3.js';
+import { _BLAKE3 } from '@noble/hashes/blake3.js';
 import { utf8ToBytes, bytesToHex } from '@noble/hashes/utils.js';
 import { z } from 'zod';
 

package/src/observability.mjs

@@ -8,10 +8,9 @@
  * error isolation, and performance tracking.
  */
 
-import { _randomUUID } from 'crypto';
-import { _z } from 'zod';
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
 import { ObservabilityConfigSchema, PerformanceMetricsSchema } from './schemas.mjs';
-import { getRuntimeConfig } from '../context/config.mjs';
 
 /**
  * OpenTelemetry observability manager
@@ -38,6 +37,9 @@ export class ObservabilityManager {
     this.activeSpans = new Map();
     this.initialized = false;
     this._lastMetrics = null; // for smoothing fallback
+    this.samplingRate = config.samplingRate ?? 0.1; // Default 10% sampling
+    this.logSamplingRate = config.logSamplingRate ?? 0.01; // Default 1% DEBUG log sampling
+    this._debugLogCounter = 0;
   }
 
   /**
@@ -84,12 +86,17 @@ export class ObservabilityManager {
         exportTimeoutMillis: this.config.exportTimeoutMillis,
       });
 
-      // Initialize SDK
+      // Create sampler for head-based sampling
+      const { TraceIdRatioBasedSampler } = await import('@opentelemetry/sdk-trace-base');
+      const sampler = new TraceIdRatioBasedSampler(this.samplingRate);
+
+      // Initialize SDK with sampling
       const sdk = new NodeSDK({
         resource,
         traceExporter: this.config.enableTracing ? traceExporter : undefined,
         metricReader: this.config.enableMetrics ? metricReader : undefined,
         instrumentations: this.config.enableTracing ? [getNodeAutoInstrumentations()] : [],
+        sampler: this.config.enableTracing ? sampler : undefined,
       });
 
       await sdk.start();
@@ -499,6 +506,35 @@ export class ObservabilityManager {
     return values[Math.max(0, index)];
   }
 
+  /**
+   * Log with sampling (DEBUG logs sampled, WARN/ERROR always logged)
+   * @param {string} level - Log level (DEBUG, INFO, WARN, ERROR)
+   * @param {string} message - Log message
+   * @param {Object} [context] - Additional context
+   */
+  log(level, message, context = {}) {
+    const upperLevel = level.toUpperCase();
+
+    // Always log WARN and ERROR
+    if (upperLevel === 'WARN' || upperLevel === 'ERROR') {
+      console[upperLevel === 'ERROR' ? 'error' : 'warn'](`[${upperLevel}] ${message}`, context);
+      return;
+    }
+
+    // Sample DEBUG logs
+    if (upperLevel === 'DEBUG') {
+      this._debugLogCounter++;
+      const sampleThreshold = Math.floor(1 / this.logSamplingRate);
+      if (this._debugLogCounter % sampleThreshold === 0) {
+        console.log(`[DEBUG:SAMPLED] ${message}`, context);
+      }
+      return;
+    }
+
+    // INFO and other levels always logged
+    console.log(`[${upperLevel}] ${message}`, context);
+  }
+
   /**
    * Shutdown observability
    * @returns {Promise<void>}

package/src/query-optimizer.mjs

@@ -11,7 +11,7 @@ import { sha3_256 } from '@noble/hashes/sha3.js';
 import { utf8ToBytes, bytesToHex } from '@noble/hashes/utils.js';
 import { randomUUID } from 'crypto';
 import { z } from 'zod';
-import LRUCache from 'lru-cache';
+import { LRUCache } from 'lru-cache';
 import { trace, metrics, SpanStatusCode } from '@opentelemetry/api';
 
 /**

package/src/resolution-layer.mjs

@@ -447,7 +447,7 @@ export class ResolutionLayer {
    * @returns {number} Confidence score
    * @private
    */
-  _calculateConfidence(proposals, _resolvedDelta) {
+  _calculateConfidence(proposals, resolvedDelta) {
     if (proposals.length === 0) return 0;
 
     let totalConfidence = 0;

package/src/transaction.mjs

@@ -8,7 +8,7 @@ import { sha3_256 } from '@noble/hashes/sha3.js';
 import { blake3 } from '@noble/hashes/blake3.js';
 import { utf8ToBytes, bytesToHex } from '@noble/hashes/utils.js';
 import { canonicalize } from './canonicalize.mjs';
-import { createLockchainWriter } from './lockchain-writer.mjs';
+import { createLockchainWriter } from '@unrdf/core/utils/lockchain-writer';
 import { createResolutionLayer } from './resolution-layer.mjs';
 import { createObservabilityManager } from './observability.mjs';
 import { randomUUID } from 'crypto';
@@ -19,16 +19,18 @@ const tracer = trace.getTracer('unrdf');
 
 // Import consolidated schemas
 import {
-  _QuadSchema,
-  DeltaSchema,
-  TransactionHookSchema,
-  _TransactionHookResultSchema,
-  _HashSchema,
-  _TransactionReceiptSchemaNew,
-  TransactionOptionsSchema,
-  ManagerOptionsSchema,
+  TransactionDeltaSchema as DeltaSchema,
+  TransactionReceiptSchema,
+  HookResultSchema as TransactionHookResultSchema,
 } from './schemas.mjs';
 
+// Define missing schemas locally
+const QuadSchema = z.any();
+const TransactionHookSchema = z.any();
+const HashSchema = z.string();
+const TransactionOptionsSchema = z.any();
+const ManagerOptionsSchema = z.any();
+
 // Zod schemas for validation
 // QuadSchema now imported from schemas.mjs
 

package/README.md

@@ -1,84 +0,0 @@
-# @unrdf/knowledge-engine
-
-![Version](https://img.shields.io/badge/version-5.0.0--beta.1-blue) ![Production Ready](https://img.shields.io/badge/production-ready-green)
-
-
-**Rule Engine, Inference, and Pattern Matching** *(Optional Extension)*
-
-Apply business rules and inference to RDF data. Includes reasoning engine and pattern matching.
-
-## Installation
-
-```bash
-pnpm add @unrdf/knowledge-engine
-```
-
-## 📚 Examples
-
-See these examples that demonstrate @unrdf/knowledge-engine:
-
-- **[knowledge-engine-example.mjs](../../examples/knowledge-engine-example.mjs)** - Complete AI semantic analysis demo (1 hour)
-- **[ai-semantic-example.mjs](../../examples/ai-semantic-example.mjs)** - Embedding-based semantic search
-- **[comprehensive-feature-test.mjs](../../examples/comprehensive-feature-test.mjs)** - Knowledge engine integration
-
-**Want AI-powered queries?** Start with [knowledge-engine-example.mjs](../../examples/knowledge-engine-example.mjs).
-
-## Quick Start
-
-```javascript
-import { inferPatterns, createRuleSet } from '@unrdf/knowledge-engine'
-
-// Define rules
-const rules = createRuleSet([
-  {
-    name: 'infer-person',
-    pattern: '?x rdf:type foaf:Person',
-    then: '?x rdfs:label ?name'
-  }
-])
-
-// Apply inference
-const inferred = await inferPatterns(store, rules)
-```
-
-## Features
-
-- ✅ Forward chaining inference
-- ✅ Rule definition and execution
-- ✅ Pattern matching on RDF data
-- ✅ Built-in ontology reasoning (RDF, RDFS, OWL)
-- ✅ Custom rule sets
-- ✅ Performance optimization
-
-## Use Cases
-
-- **Business rules**: Apply domain rules to RDF
-- **Data enrichment**: Infer new facts from existing data
-- **Ontology reasoning**: RDFS and OWL inference
-- **Data quality**: Detect and fix inconsistencies
-- **Knowledge extraction**: Mine patterns from data
-
-## Documentation
-
-- **[API Reference](./docs/API.md)** - Complete API documentation
-- **[User Guide](./docs/GUIDE.md)** - Rule definition and usage
-- **[Examples](./examples/)** - Code examples
-- **[Contributing](./docs/CONTRIBUTING.md)** - How to contribute
-
-## Status
-
-**Optional Extension** - Not required for core UNRDF functionality.
-Use only if you need rule-based inference.
-
-## Depends On
-
-- `@unrdf/core` - RDF substrate
-- `@unrdf/streaming` - Change subscriptions
-
-## VOC Usage
-
-- VOC-3: ML Agent (pattern matching)
-
-## License
-
-MIT