@unrdf/knowledge-engine 5.0.1 → 26.4.3

package/src/chatman-operator.mjs

@@ -0,0 +1,342 @@
+/**
+ * @file Chatman Operator - μ Closure Operator Implementation
+ * @module knowledge-engine/chatman-operator
+ *
+ * @description
+ * Implements the μ (mu) closure operator from the Chatman Equation.
+ * The μ operator calculates the closure of observable patterns to reveal
+ * the complete artifact space including invisible dark field components.
+ *
+ * Core Formula: A = μ(O)
+ * Where:
+ * - A = Complete artifact space (100%)
+ * - μ = Closure operator
+ * - O = Observable patterns (~5%)
+ */
+
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+
+/**
+ * Observable pattern schema
+ */
+export const ObservablePatternSchema = z.object({
+  id: z.string().uuid().optional(),
+  type: z.enum(['market', 'organizational', 'strategic', 'disruption']),
+  patterns: z.array(z.string()).min(1),
+  visibility: z.number().min(0).max(1).default(0.05),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Closure result schema
+ */
+export const ClosureResultSchema = z.object({
+  observable: ObservablePatternSchema,
+  darkField: z.object({
+    patterns: z.array(z.string()),
+    visibility: z.number(),
+    coverage: z.number(),
+  }),
+  completeness: z.number().min(0).max(1),
+  timestamp: z.number(),
+  operatorId: z.string().uuid(),
+});
+
+/**
+ * Chatman μ operator - Calculates closure of observable patterns
+ */
+export class ChatmanOperator {
+  /**
+   * Create a new Chatman operator
+   * @param {Object} [options] - Operator options
+   * @param {number} [options.observableRatio=0.05] - Observable to dark field ratio (5% default)
+   * @param {number} [options.closureThreshold=0.95] - Minimum completeness threshold
+   * @param {Function} [options.tracer] - OTEL tracer function
+   */
+  constructor(options = {}) {
+    this.observableRatio = options.observableRatio ?? 0.05;
+    this.closureThreshold = options.closureThreshold ?? 0.95;
+    this.tracer = options.tracer;
+    this.operatorId = randomUUID();
+    this.metrics = {
+      closureOperations: 0,
+      averageCompleteness: 0,
+      totalDarkFieldRevealed: 0,
+    };
+  }
+
+  /**
+   * Apply μ operator to observable patterns to compute closure
+   * @param {Object} observable - Observable pattern
+   * @returns {Promise<Object>} Closure result
+   */
+  async apply(observable) {
+    const span = this.tracer?.startSpan?.('chatman.operator.apply');
+    const startTime = Date.now();
+
+    try {
+      // Validate input
+      const validated = ObservablePatternSchema.parse(observable);
+      if (!validated.id) {
+        validated.id = randomUUID();
+      }
+
+      span?.setAttribute?.('pattern.type', validated.type);
+      span?.setAttribute?.('pattern.count', validated.patterns.length);
+
+      // Calculate dark field using closure operator
+      const darkField = this._calculateDarkField(validated);
+
+      // Compute completeness metric
+      const completeness = this._computeCompleteness(validated, darkField);
+
+      span?.setAttribute?.('completeness', completeness);
+      span?.setAttribute?.('dark_field_size', darkField.patterns.length);
+
+      const result = {
+        observable: validated,
+        darkField,
+        completeness,
+        timestamp: Date.now(),
+        operatorId: this.operatorId,
+      };
+
+      // Update metrics
+      this.metrics.closureOperations++;
+      this.metrics.averageCompleteness =
+        (this.metrics.averageCompleteness * (this.metrics.closureOperations - 1) + completeness) /
+        this.metrics.closureOperations;
+      this.metrics.totalDarkFieldRevealed += darkField.patterns.length;
+
+      span?.addEvent?.('closure_computed', {
+        'closure.completeness': completeness,
+        'closure.duration_ms': Date.now() - startTime,
+      });
+
+      return ClosureResultSchema.parse(result);
+    } catch (error) {
+      span?.recordException?.(error);
+      span?.setStatus?.({ code: 2, message: error.message }); // ERROR
+      throw error;
+    } finally {
+      span?.end?.();
+    }
+  }
+
+  /**
+   * Calculate dark field patterns from observable patterns
+   * @param {Object} observable - Observable pattern
+   * @returns {Object} Dark field
+   * @private
+   */
+  _calculateDarkField(observable) {
+    const observableCount = observable.patterns.length;
+
+    // μ(O) = O ∪ DarkField
+    // where |DarkField| ≈ |O| * (1/observableRatio - 1)
+    const darkFieldMultiplier = 1 / this.observableRatio - 1;
+    const darkFieldSize = Math.floor(observableCount * darkFieldMultiplier);
+
+    // Generate dark field patterns based on observable type
+    const darkFieldPatterns = this._generateDarkFieldPatterns(
+      observable.type,
+      observable.patterns,
+      darkFieldSize
+    );
+
+    return {
+      patterns: darkFieldPatterns,
+      visibility: 1 - this.observableRatio,
+      coverage: darkFieldSize / (darkFieldSize + observableCount),
+    };
+  }
+
+  /**
+   * Generate dark field patterns based on type and observables
+   * @param {string} type - Pattern type
+   * @param {Array<string>} observablePatterns - Observable patterns
+   * @param {number} targetSize - Target dark field size
+   * @returns {Array<string>} Dark field patterns
+   * @private
+   */
+  _generateDarkFieldPatterns(type, observablePatterns, targetSize) {
+    const darkField = [];
+    const generators = {
+      market: this._generateMarketDarkField.bind(this),
+      organizational: this._generateOrganizationalDarkField.bind(this),
+      strategic: this._generateStrategicDarkField.bind(this),
+      disruption: this._generateDisruptionDarkField.bind(this),
+    };
+
+    const generator = generators[type] || generators.market;
+    return generator(observablePatterns, targetSize);
+  }
+
+  /**
+   * Generate market dynamics dark field
+   * @param {Array<string>} patterns - Observable patterns
+   * @param {number} size - Target size
+   * @returns {Array<string>} Dark field patterns
+   * @private
+   */
+  _generateMarketDarkField(patterns, size) {
+    const darkField = [];
+    const dimensions = [
+      'hidden_customer_needs',
+      'latent_market_segments',
+      'unspoken_value_drivers',
+      'invisible_competition',
+      'emergent_demand_patterns',
+      'tacit_buying_criteria',
+      'underground_distribution_channels',
+      'implicit_price_expectations',
+    ];
+
+    for (let i = 0; i < size; i++) {
+      const dimension = dimensions[i % dimensions.length];
+      const patternIndex = i % patterns.length;
+      darkField.push(`${dimension}:derived_from:${patterns[patternIndex]}`);
+    }
+
+    return darkField;
+  }
+
+  /**
+   * Generate organizational dynamics dark field
+   * @param {Array<string>} patterns - Observable patterns
+   * @param {number} size - Target size
+   * @returns {Array<string>} Dark field patterns
+   * @private
+   */
+  _generateOrganizationalDarkField(patterns, size) {
+    const darkField = [];
+    const dimensions = [
+      'informal_power_structures',
+      'tacit_knowledge_networks',
+      'hidden_resource_flows',
+      'implicit_decision_criteria',
+      'unwritten_cultural_norms',
+      'latent_capability_reserves',
+      'invisible_coordination_mechanisms',
+      'emergent_collaboration_patterns',
+    ];
+
+    for (let i = 0; i < size; i++) {
+      const dimension = dimensions[i % dimensions.length];
+      const patternIndex = i % patterns.length;
+      darkField.push(`${dimension}:derived_from:${patterns[patternIndex]}`);
+    }
+
+    return darkField;
+  }
+
+  /**
+   * Generate strategic dynamics dark field
+   * @param {Array<string>} patterns - Observable patterns
+   * @param {number} size - Target size
+   * @returns {Array<string>} Dark field patterns
+   * @private
+   */
+  _generateStrategicDarkField(patterns, size) {
+    const darkField = [];
+    const dimensions = [
+      'latent_strategic_options',
+      'hidden_competitive_advantages',
+      'implicit_strategic_assumptions',
+      'emergent_industry_shifts',
+      'tacit_success_factors',
+      'invisible_threat_vectors',
+      'unrecognized_opportunities',
+      'hidden_ecosystem_dependencies',
+    ];
+
+    for (let i = 0; i < size; i++) {
+      const dimension = dimensions[i % dimensions.length];
+      const patternIndex = i % patterns.length;
+      darkField.push(`${dimension}:derived_from:${patterns[patternIndex]}`);
+    }
+
+    return darkField;
+  }
+
+  /**
+   * Generate disruption arithmetic dark field
+   * @param {Array<string>} patterns - Observable patterns
+   * @param {number} size - Target size
+   * @returns {Array<string>} Dark field patterns
+   * @private
+   */
+  _generateDisruptionDarkField(patterns, size) {
+    const darkField = [];
+    const dimensions = [
+      'latent_disruption_vectors',
+      'hidden_innovation_barriers',
+      'implicit_adoption_triggers',
+      'emergent_technology_convergence',
+      'tacit_resistance_patterns',
+      'invisible_tipping_points',
+      'unrecognized_substitutes',
+      'hidden_value_chain_vulnerabilities',
+    ];
+
+    for (let i = 0; i < size; i++) {
+      const dimension = dimensions[i % dimensions.length];
+      const patternIndex = i % patterns.length;
+      darkField.push(`${dimension}:derived_from:${patterns[patternIndex]}`);
+    }
+
+    return darkField;
+  }
+
+  /**
+   * Compute completeness of closure
+   * @param {Object} observable - Observable pattern
+   * @param {Object} darkField - Dark field
+   * @returns {number} Completeness ratio [0, 1]
+   * @private
+   */
+  _computeCompleteness(observable, darkField) {
+    const totalPatterns = observable.patterns.length + darkField.patterns.length;
+    const coverageScore = darkField.patterns.length / totalPatterns;
+
+    // Completeness is high when dark field coverage approaches (1 - observableRatio)
+    const targetCoverage = 1 - this.observableRatio;
+    const completeness = Math.min(1, coverageScore / targetCoverage);
+
+    return completeness;
+  }
+
+  /**
+   * Get operator metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    return {
+      ...this.metrics,
+      operatorId: this.operatorId,
+      observableRatio: this.observableRatio,
+      closureThreshold: this.closureThreshold,
+    };
+  }
+
+  /**
+   * Reset operator metrics
+   */
+  resetMetrics() {
+    this.metrics = {
+      closureOperations: 0,
+      averageCompleteness: 0,
+      totalDarkFieldRevealed: 0,
+    };
+  }
+}
+
+/**
+ * Create a Chatman operator instance
+ * @param {Object} [options] - Operator options
+ * @returns {ChatmanOperator} Operator instance
+ */
+export function createChatmanOperator(options = {}) {
+  return new ChatmanOperator(options);
+}

package/src/dark-field-detector.mjs

@@ -0,0 +1,312 @@
+/**
+ * @file Dark Field Detector - 95% Invisible Field Detection
+ * @module knowledge-engine/dark-field-detector
+ *
+ * @description
+ * Detects and analyzes the dark field (invisible ~95%) of organizational,
+ * market, strategic, and disruption patterns using the Chatman Equation.
+ */
+
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+
+/**
+ * Detection result schema
+ */
+export const DetectionResultSchema = z.object({
+  id: z.string().uuid(),
+  type: z.enum(['market', 'organizational', 'strategic', 'disruption']),
+  observableSize: z.number().int().nonnegative(),
+  darkFieldSize: z.number().int().nonnegative(),
+  darkFieldRatio: z.number().min(0).max(1),
+  patterns: z.array(
+    z.object({
+      dimension: z.string(),
+      confidence: z.number().min(0).max(1),
+      derivedFrom: z.array(z.string()),
+    })
+  ),
+  detectedAt: z.number(),
+});
+
+/**
+ * Detection options schema
+ */
+export const DetectionOptionsSchema = z.object({
+  minConfidence: z.number().min(0).max(1).default(0.7),
+  maxPatterns: z.number().int().positive().default(100),
+  targetRatio: z.number().min(0).max(1).default(0.95),
+});
+
+/**
+ * Dark field detector for Chatman Equation
+ */
+export class DarkFieldDetector {
+  /**
+   * Create a new dark field detector
+   * @param {Object} [options] - Detector options
+   * @param {Function} [options.tracer] - OTEL tracer function
+   * @param {number} [options.targetRatio=0.95] - Target dark field ratio
+   */
+  constructor(options = {}) {
+    this.tracer = options.tracer;
+    this.targetRatio = options.targetRatio ?? 0.95;
+    this.metrics = {
+      detectionsPerformed: 0,
+      averageDarkFieldRatio: 0,
+      totalPatternsDetected: 0,
+    };
+  }
+
+  /**
+   * Detect dark field patterns from observable data
+   * @param {Object} observable - Observable pattern data
+   * @param {Object} [options] - Detection options
+   * @returns {Promise<Object>} Detection result
+   */
+  async detect(observable, options = {}) {
+    const span = this.tracer?.startSpan?.('chatman.darkfield.detect');
+    const startTime = Date.now();
+
+    try {
+      const opts = DetectionOptionsSchema.parse(options);
+
+      span?.setAttribute?.('observable.type', observable.type);
+      span?.setAttribute?.('observable.size', observable.patterns.length);
+      span?.setAttribute?.('target_ratio', opts.targetRatio);
+
+      // Calculate expected dark field size
+      const observableSize = observable.patterns.length;
+      const darkFieldSize = this._calculateDarkFieldSize(observableSize, opts.targetRatio);
+
+      // Detect dark field patterns
+      const patterns = this._detectPatterns(observable, darkFieldSize, opts);
+
+      const darkFieldRatio = darkFieldSize / (darkFieldSize + observableSize);
+
+      const result = {
+        id: randomUUID(),
+        type: observable.type,
+        observableSize,
+        darkFieldSize,
+        darkFieldRatio,
+        patterns,
+        detectedAt: Date.now(),
+      };
+
+      // Update metrics
+      this.metrics.detectionsPerformed++;
+      this.metrics.averageDarkFieldRatio =
+        (this.metrics.averageDarkFieldRatio * (this.metrics.detectionsPerformed - 1) +
+          darkFieldRatio) /
+        this.metrics.detectionsPerformed;
+      this.metrics.totalPatternsDetected += patterns.length;
+
+      span?.addEvent?.('detection_completed', {
+        'detection.id': result.id,
+        'detection.dark_field_size': darkFieldSize,
+        'detection.ratio': darkFieldRatio,
+        'detection.pattern_count': patterns.length,
+        'detection.duration_ms': Date.now() - startTime,
+      });
+
+      return DetectionResultSchema.parse(result);
+    } catch (error) {
+      span?.recordException?.(error);
+      span?.setStatus?.({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span?.end?.();
+    }
+  }
+
+  /**
+   * Calculate dark field size from observable size and target ratio
+   * @param {number} observableSize - Number of observable patterns
+   * @param {number} targetRatio - Target dark field ratio
+   * @returns {number} Dark field size
+   * @private
+   */
+  _calculateDarkFieldSize(observableSize, targetRatio) {
+    // targetRatio = darkField / (darkField + observable)
+    // darkField = observable * targetRatio / (1 - targetRatio)
+    return Math.floor((observableSize * targetRatio) / (1 - targetRatio));
+  }
+
+  /**
+   * Detect dark field patterns
+   * @param {Object} observable - Observable pattern
+   * @param {number} targetSize - Target dark field size
+   * @param {Object} options - Detection options
+   * @returns {Array<Object>} Detected patterns
+   * @private
+   */
+  _detectPatterns(observable, targetSize, options) {
+    const detectors = {
+      market: this._detectMarketDarkField.bind(this),
+      organizational: this._detectOrganizationalDarkField.bind(this),
+      strategic: this._detectStrategicDarkField.bind(this),
+      disruption: this._detectDisruptionDarkField.bind(this),
+    };
+
+    const detector = detectors[observable.type] || detectors.market;
+    return detector(observable.patterns, targetSize, options);
+  }
+
+  /**
+   * Detect market dark field patterns
+   * @param {Array<string>} observablePatterns - Observable patterns
+   * @param {number} targetSize - Target size
+   * @param {Object} options - Options
+   * @returns {Array<Object>} Detected patterns
+   * @private
+   */
+  _detectMarketDarkField(observablePatterns, targetSize, options) {
+    const dimensions = [
+      'hidden_customer_needs',
+      'latent_market_segments',
+      'unspoken_value_drivers',
+      'invisible_competition',
+      'emergent_demand_patterns',
+    ];
+
+    return this._generateDetectedPatterns(dimensions, observablePatterns, targetSize, options);
+  }
+
+  /**
+   * Detect organizational dark field patterns
+   * @param {Array<string>} observablePatterns - Observable patterns
+   * @param {number} targetSize - Target size
+   * @param {Object} options - Options
+   * @returns {Array<Object>} Detected patterns
+   * @private
+   */
+  _detectOrganizationalDarkField(observablePatterns, targetSize, options) {
+    const dimensions = [
+      'informal_power_structures',
+      'tacit_knowledge_networks',
+      'hidden_resource_flows',
+      'implicit_decision_criteria',
+      'unwritten_cultural_norms',
+    ];
+
+    return this._generateDetectedPatterns(dimensions, observablePatterns, targetSize, options);
+  }
+
+  /**
+   * Detect strategic dark field patterns
+   * @param {Array<string>} observablePatterns - Observable patterns
+   * @param {number} targetSize - Target size
+   * @param {Object} options - Options
+   * @returns {Array<Object>} Detected patterns
+   * @private
+   */
+  _detectStrategicDarkField(observablePatterns, targetSize, options) {
+    const dimensions = [
+      'latent_strategic_options',
+      'hidden_competitive_advantages',
+      'implicit_strategic_assumptions',
+      'emergent_industry_shifts',
+      'tacit_success_factors',
+    ];
+
+    return this._generateDetectedPatterns(dimensions, observablePatterns, targetSize, options);
+  }
+
+  /**
+   * Detect disruption dark field patterns
+   * @param {Array<string>} observablePatterns - Observable patterns
+   * @param {number} targetSize - Target size
+   * @param {Object} options - Options
+   * @returns {Array<Object>} Detected patterns
+   * @private
+   */
+  _detectDisruptionDarkField(observablePatterns, targetSize, options) {
+    const dimensions = [
+      'latent_disruption_vectors',
+      'hidden_innovation_barriers',
+      'implicit_adoption_triggers',
+      'emergent_technology_convergence',
+      'tacit_resistance_patterns',
+    ];
+
+    return this._generateDetectedPatterns(dimensions, observablePatterns, targetSize, options);
+  }
+
+  /**
+   * Generate detected patterns from dimensions
+   * @param {Array<string>} dimensions - Pattern dimensions
+   * @param {Array<string>} observablePatterns - Observable patterns
+   * @param {number} targetSize - Target size
+   * @param {Object} options - Options
+   * @returns {Array<Object>} Detected patterns
+   * @private
+   */
+  _generateDetectedPatterns(dimensions, observablePatterns, targetSize, options) {
+    const patterns = [];
+    const maxPatterns = Math.min(targetSize, options.maxPatterns);
+
+    for (let i = 0; i < maxPatterns; i++) {
+      const dimension = dimensions[i % dimensions.length];
+      const patternIndex = i % observablePatterns.length;
+      const confidence = this._calculateConfidence(i, maxPatterns, options.minConfidence);
+
+      if (confidence >= options.minConfidence) {
+        patterns.push({
+          dimension,
+          confidence,
+          derivedFrom: [observablePatterns[patternIndex]],
+        });
+      }
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Calculate confidence score for pattern
+   * @param {number} index - Pattern index
+   * @param {number} total - Total patterns
+   * @param {number} minConfidence - Minimum confidence
+   * @returns {number} Confidence score
+   * @private
+   */
+  _calculateConfidence(index, total, minConfidence) {
+    // Confidence decreases slightly as we generate more patterns
+    const decay = 0.1;
+    const baseConfidence = 0.95;
+    const confidence = baseConfidence - (index / total) * decay;
+    return Math.max(minConfidence, confidence);
+  }
+
+  /**
+   * Get detector metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    return {
+      ...this.metrics,
+      targetRatio: this.targetRatio,
+    };
+  }
+
+  /**
+   * Reset detector metrics
+   */
+  resetMetrics() {
+    this.metrics = {
+      detectionsPerformed: 0,
+      averageDarkFieldRatio: 0,
+      totalPatternsDetected: 0,
+    };
+  }
+}
+
+/**
+ * Create a dark field detector instance
+ * @param {Object} [options] - Detector options
+ * @returns {DarkFieldDetector} Detector instance
+ */
+export function createDarkFieldDetector(options = {}) {
+  return new DarkFieldDetector(options);
+}