@unrdf/knowledge-engine 5.0.1 → 26.4.2

package/src/artifact-generator.mjs

@@ -0,0 +1,252 @@
+/**
+ * @file Artifact Generator - A = μ(O) Calculator
+ * @module knowledge-engine/artifact-generator
+ *
+ * @description
+ * Implements the artifact generation function A = μ(O) from the Chatman Equation.
+ * Transforms observable patterns into complete artifact spaces including dark field.
+ */
+
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+import { ChatmanOperator } from './chatman-operator.mjs';
+
+/**
+ * Artifact schema
+ */
+export const ArtifactSchema = z.object({
+  id: z.string().uuid(),
+  type: z.enum(['market', 'organizational', 'strategic', 'disruption']),
+  observable: z.object({
+    patterns: z.array(z.string()),
+    visibility: z.number(),
+  }),
+  darkField: z.object({
+    patterns: z.array(z.string()),
+    visibility: z.number(),
+    coverage: z.number(),
+  }),
+  totalPatterns: z.number().int().positive(),
+  completeness: z.number().min(0).max(1),
+  generatedAt: z.number(),
+  receipt: z
+    .object({
+      id: z.string().uuid(),
+      operation: z.literal('artifact_generation'),
+      timestamp: z.number(),
+    })
+    .optional(),
+});
+
+/**
+ * Generation options schema
+ */
+export const GenerationOptionsSchema = z.object({
+  includeReceipt: z.boolean().default(true),
+  observableRatio: z.number().min(0).max(1).default(0.05),
+  validate: z.boolean().default(true),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Artifact generator for Chatman Equation
+ */
+export class ArtifactGenerator {
+  /**
+   * Create a new artifact generator
+   * @param {Object} [options] - Generator options
+   * @param {Function} [options.tracer] - OTEL tracer function
+   * @param {Function} [options.receiptGenerator] - Receipt generation function
+   */
+  constructor(options = {}) {
+    this.tracer = options.tracer;
+    this.receiptGenerator = options.receiptGenerator;
+    this.operator = new ChatmanOperator({
+      tracer: this.tracer,
+      observableRatio: options.observableRatio,
+    });
+    this.metrics = {
+      artifactsGenerated: 0,
+      averageCompleteness: 0,
+      averageDarkFieldSize: 0,
+    };
+  }
+
+  /**
+   * Generate artifact from observable patterns: A = μ(O)
+   * @param {Object} observable - Observable pattern
+   * @param {Object} [options] - Generation options
+   * @returns {Promise<Object>} Generated artifact
+   */
+  async generate(observable, options = {}) {
+    const span = this.tracer?.startSpan?.('chatman.artifact.generate');
+    const startTime = Date.now();
+
+    try {
+      const opts = GenerationOptionsSchema.parse(options);
+
+      span?.setAttribute?.('observable.type', observable.type);
+      span?.setAttribute?.('observable.pattern_count', observable.patterns.length);
+      span?.setAttribute?.('options.include_receipt', opts.includeReceipt);
+
+      // Apply μ operator to compute closure
+      const closure = await this.operator.apply(observable);
+
+      // Generate artifact from closure
+      const artifact = {
+        id: randomUUID(),
+        type: observable.type,
+        observable: {
+          patterns: closure.observable.patterns,
+          visibility: closure.observable.visibility,
+        },
+        darkField: closure.darkField,
+        totalPatterns:
+          closure.observable.patterns.length + closure.darkField.patterns.length,
+        completeness: closure.completeness,
+        generatedAt: Date.now(),
+      };
+
+      // Generate receipt if requested
+      if (opts.includeReceipt) {
+        artifact.receipt = this._generateReceipt(artifact, closure);
+      }
+
+      // Validate artifact
+      if (opts.validate) {
+        ArtifactSchema.parse(artifact);
+      }
+
+      // Update metrics
+      this.metrics.artifactsGenerated++;
+      this.metrics.averageCompleteness =
+        (this.metrics.averageCompleteness * (this.metrics.artifactsGenerated - 1) +
+          artifact.completeness) /
+        this.metrics.artifactsGenerated;
+      this.metrics.averageDarkFieldSize =
+        (this.metrics.averageDarkFieldSize * (this.metrics.artifactsGenerated - 1) +
+          artifact.darkField.patterns.length) /
+        this.metrics.artifactsGenerated;
+
+      span?.addEvent?.('artifact_generated', {
+        'artifact.id': artifact.id,
+        'artifact.completeness': artifact.completeness,
+        'artifact.total_patterns': artifact.totalPatterns,
+        'artifact.duration_ms': Date.now() - startTime,
+      });
+
+      return artifact;
+    } catch (error) {
+      span?.recordException?.(error);
+      span?.setStatus?.({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span?.end?.();
+    }
+  }
+
+  /**
+   * Generate multiple artifacts in batch
+   * @param {Array<Object>} observables - Array of observable patterns
+   * @param {Object} [options] - Generation options
+   * @returns {Promise<Array<Object>>} Generated artifacts
+   */
+  async generateBatch(observables, options = {}) {
+    const span = this.tracer?.startSpan?.('chatman.artifact.generate_batch');
+
+    try {
+      span?.setAttribute?.('batch_size', observables.length);
+
+      const artifacts = await Promise.all(
+        observables.map(observable => this.generate(observable, options))
+      );
+
+      span?.addEvent?.('batch_generated', {
+        'batch.count': artifacts.length,
+        'batch.avg_completeness': this._calculateAverageCompleteness(artifacts),
+      });
+
+      return artifacts;
+    } catch (error) {
+      span?.recordException?.(error);
+      span?.setStatus?.({ code: 2, message: error.message });
+      throw error;
+    } finally {
+      span?.end?.();
+    }
+  }
+
+  /**
+   * Generate receipt for artifact
+   * @param {Object} artifact - Generated artifact
+   * @param {Object} closure - Closure result
+   * @returns {Object} Receipt
+   * @private
+   */
+  _generateReceipt(artifact, closure) {
+    if (this.receiptGenerator) {
+      return this.receiptGenerator({
+        operation: 'artifact_generation',
+        entityType: 'ChatmanArtifact',
+        entityId: artifact.id,
+        data: {
+          observableCount: artifact.observable.patterns.length,
+          darkFieldCount: artifact.darkField.patterns.length,
+          completeness: artifact.completeness,
+          operatorId: closure.operatorId,
+        },
+      });
+    }
+
+    // Default receipt
+    return {
+      id: randomUUID(),
+      operation: 'artifact_generation',
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Calculate average completeness from artifacts
+   * @param {Array<Object>} artifacts - Artifacts
+   * @returns {number} Average completeness
+   * @private
+   */
+  _calculateAverageCompleteness(artifacts) {
+    if (artifacts.length === 0) return 0;
+    const sum = artifacts.reduce((acc, a) => acc + a.completeness, 0);
+    return sum / artifacts.length;
+  }
+
+  /**
+   * Get generator metrics
+   * @returns {Object} Metrics
+   */
+  getMetrics() {
+    return {
+      ...this.metrics,
+      operator: this.operator.getMetrics(),
+    };
+  }
+
+  /**
+   * Reset generator metrics
+   */
+  resetMetrics() {
+    this.metrics = {
+      artifactsGenerated: 0,
+      averageCompleteness: 0,
+      averageDarkFieldSize: 0,
+    };
+    this.operator.resetMetrics();
+  }
+}
+
+/**
+ * Create an artifact generator instance
+ * @param {Object} [options] - Generator options
+ * @returns {ArtifactGenerator} Generator instance
+ */
+export function createArtifactGenerator(options = {}) {
+  return new ArtifactGenerator(options);
+}

package/src/browser.mjs

@@ -8,7 +8,7 @@
  */
 
 import { _isBrowser } from './browser-shims.mjs';
-import { randomUUID, path, _fs } from './browser-shims.mjs';
+import { randomUUID, path, fs } from './browser-shims.mjs';
 import { process as _browserProcess } from './browser-shims.mjs';
 
 // Browser-compatible versions

package/src/chatman/disruption-arithmetic.mjs

@@ -0,0 +1,140 @@
+/**
+ * @file Disruption Arithmetic Rules
+ * @module knowledge-engine/chatman/disruption-arithmetic
+ *
+ * @description
+ * Disruption arithmetic rules for Chatman Equation analysis.
+ * Defines patterns for disruption vectors, innovation barriers,
+ * adoption triggers, technology convergence, and resistance patterns.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Disruption arithmetic rule schema
+ */
+export const DisruptionArithmeticRuleSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  category: z.enum([
+    'disruption_vectors',
+    'innovation_barriers',
+    'adoption_triggers',
+    'technology_convergence',
+    'resistance_patterns',
+  ]),
+  pattern: z.string(),
+  darkFieldMultiplier: z.number().positive().default(19),
+  confidence: z.number().min(0).max(1).default(0.8),
+});
+
+/**
+ * Disruption arithmetic rules
+ */
+export const DISRUPTION_ARITHMETIC_RULES = [
+  {
+    id: 'da-001',
+    name: 'Latent Disruption Vectors',
+    category: 'disruption_vectors',
+    pattern: 'latent_disruption_vectors',
+    darkFieldMultiplier: 19,
+    confidence: 0.85,
+  },
+  {
+    id: 'da-002',
+    name: 'Hidden Innovation Barriers',
+    category: 'innovation_barriers',
+    pattern: 'hidden_innovation_barriers',
+    darkFieldMultiplier: 19,
+    confidence: 0.83,
+  },
+  {
+    id: 'da-003',
+    name: 'Implicit Adoption Triggers',
+    category: 'adoption_triggers',
+    pattern: 'implicit_adoption_triggers',
+    darkFieldMultiplier: 19,
+    confidence: 0.84,
+  },
+  {
+    id: 'da-004',
+    name: 'Emergent Technology Convergence',
+    category: 'technology_convergence',
+    pattern: 'emergent_technology_convergence',
+    darkFieldMultiplier: 19,
+    confidence: 0.86,
+  },
+  {
+    id: 'da-005',
+    name: 'Tacit Resistance Patterns',
+    category: 'resistance_patterns',
+    pattern: 'tacit_resistance_patterns',
+    darkFieldMultiplier: 19,
+    confidence: 0.82,
+  },
+  {
+    id: 'da-006',
+    name: 'Invisible Tipping Points',
+    category: 'disruption_vectors',
+    pattern: 'invisible_tipping_points',
+    darkFieldMultiplier: 19,
+    confidence: 0.87,
+  },
+  {
+    id: 'da-007',
+    name: 'Unrecognized Substitutes',
+    category: 'innovation_barriers',
+    pattern: 'unrecognized_substitutes',
+    darkFieldMultiplier: 19,
+    confidence: 0.8,
+  },
+  {
+    id: 'da-008',
+    name: 'Hidden Value Chain Vulnerabilities',
+    category: 'disruption_vectors',
+    pattern: 'hidden_value_chain_vulnerabilities',
+    darkFieldMultiplier: 19,
+    confidence: 0.81,
+  },
+];
+
+/**
+ * Get disruption arithmetic rules by category
+ * @param {string} category - Rule category
+ * @returns {Array<Object>} Filtered rules
+ */
+export function getRulesByCategory(category) {
+  return DISRUPTION_ARITHMETIC_RULES.filter(rule => rule.category === category);
+}
+
+/**
+ * Get disruption arithmetic rule by ID
+ * @param {string} id - Rule ID
+ * @returns {Object|undefined} Rule or undefined
+ */
+export function getRuleById(id) {
+  return DISRUPTION_ARITHMETIC_RULES.find(rule => rule.id === id);
+}
+
+/**
+ * Validate disruption arithmetic rules
+ * @param {Array<Object>} rules - Rules to validate
+ * @returns {Object} Validation result
+ */
+export function validateRules(rules) {
+  const errors = [];
+  for (const rule of rules) {
+    const result = DisruptionArithmeticRuleSchema.safeParse(rule);
+    if (!result.success) {
+      errors.push({
+        rule: rule.id || 'unknown',
+        errors: result.error.errors,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/chatman/market-dynamics.mjs

@@ -0,0 +1,140 @@
+/**
+ * @file Market Dynamics Rules
+ * @module knowledge-engine/chatman/market-dynamics
+ *
+ * @description
+ * Market dynamics rules for Chatman Equation analysis.
+ * Defines patterns for customer needs, market segments, value drivers,
+ * competition, and demand patterns.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Market dynamics rule schema
+ */
+export const MarketDynamicsRuleSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  category: z.enum([
+    'customer_needs',
+    'market_segments',
+    'value_drivers',
+    'competition',
+    'demand_patterns',
+  ]),
+  pattern: z.string(),
+  darkFieldMultiplier: z.number().positive().default(19),
+  confidence: z.number().min(0).max(1).default(0.8),
+});
+
+/**
+ * Market dynamics rules
+ */
+export const MARKET_DYNAMICS_RULES = [
+  {
+    id: 'md-001',
+    name: 'Hidden Customer Needs Detection',
+    category: 'customer_needs',
+    pattern: 'hidden_customer_needs',
+    darkFieldMultiplier: 19,
+    confidence: 0.85,
+  },
+  {
+    id: 'md-002',
+    name: 'Latent Market Segments',
+    category: 'market_segments',
+    pattern: 'latent_market_segments',
+    darkFieldMultiplier: 19,
+    confidence: 0.82,
+  },
+  {
+    id: 'md-003',
+    name: 'Unspoken Value Drivers',
+    category: 'value_drivers',
+    pattern: 'unspoken_value_drivers',
+    darkFieldMultiplier: 19,
+    confidence: 0.8,
+  },
+  {
+    id: 'md-004',
+    name: 'Invisible Competition',
+    category: 'competition',
+    pattern: 'invisible_competition',
+    darkFieldMultiplier: 19,
+    confidence: 0.78,
+  },
+  {
+    id: 'md-005',
+    name: 'Emergent Demand Patterns',
+    category: 'demand_patterns',
+    pattern: 'emergent_demand_patterns',
+    darkFieldMultiplier: 19,
+    confidence: 0.83,
+  },
+  {
+    id: 'md-006',
+    name: 'Tacit Buying Criteria',
+    category: 'customer_needs',
+    pattern: 'tacit_buying_criteria',
+    darkFieldMultiplier: 19,
+    confidence: 0.81,
+  },
+  {
+    id: 'md-007',
+    name: 'Underground Distribution Channels',
+    category: 'market_segments',
+    pattern: 'underground_distribution_channels',
+    darkFieldMultiplier: 19,
+    confidence: 0.77,
+  },
+  {
+    id: 'md-008',
+    name: 'Implicit Price Expectations',
+    category: 'value_drivers',
+    pattern: 'implicit_price_expectations',
+    darkFieldMultiplier: 19,
+    confidence: 0.79,
+  },
+];
+
+/**
+ * Get market dynamics rules by category
+ * @param {string} category - Rule category
+ * @returns {Array<Object>} Filtered rules
+ */
+export function getRulesByCategory(category) {
+  return MARKET_DYNAMICS_RULES.filter(rule => rule.category === category);
+}
+
+/**
+ * Get market dynamics rule by ID
+ * @param {string} id - Rule ID
+ * @returns {Object|undefined} Rule or undefined
+ */
+export function getRuleById(id) {
+  return MARKET_DYNAMICS_RULES.find(rule => rule.id === id);
+}
+
+/**
+ * Validate market dynamics rules
+ * @param {Array<Object>} rules - Rules to validate
+ * @returns {Object} Validation result
+ */
+export function validateRules(rules) {
+  const errors = [];
+  for (const rule of rules) {
+    const result = MarketDynamicsRuleSchema.safeParse(rule);
+    if (!result.success) {
+      errors.push({
+        rule: rule.id || 'unknown',
+        errors: result.error.errors,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/chatman/organizational-dynamics.mjs

@@ -0,0 +1,140 @@
+/**
+ * @file Organizational Dynamics Rules
+ * @module knowledge-engine/chatman/organizational-dynamics
+ *
+ * @description
+ * Organizational dynamics rules for Chatman Equation analysis.
+ * Defines patterns for power structures, knowledge networks, resource flows,
+ * decision criteria, and cultural norms.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Organizational dynamics rule schema
+ */
+export const OrganizationalDynamicsRuleSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  category: z.enum([
+    'power_structures',
+    'knowledge_networks',
+    'resource_flows',
+    'decision_criteria',
+    'cultural_norms',
+  ]),
+  pattern: z.string(),
+  darkFieldMultiplier: z.number().positive().default(19),
+  confidence: z.number().min(0).max(1).default(0.8),
+});
+
+/**
+ * Organizational dynamics rules
+ */
+export const ORGANIZATIONAL_DYNAMICS_RULES = [
+  {
+    id: 'od-001',
+    name: 'Informal Power Structures',
+    category: 'power_structures',
+    pattern: 'informal_power_structures',
+    darkFieldMultiplier: 19,
+    confidence: 0.86,
+  },
+  {
+    id: 'od-002',
+    name: 'Tacit Knowledge Networks',
+    category: 'knowledge_networks',
+    pattern: 'tacit_knowledge_networks',
+    darkFieldMultiplier: 19,
+    confidence: 0.84,
+  },
+  {
+    id: 'od-003',
+    name: 'Hidden Resource Flows',
+    category: 'resource_flows',
+    pattern: 'hidden_resource_flows',
+    darkFieldMultiplier: 19,
+    confidence: 0.82,
+  },
+  {
+    id: 'od-004',
+    name: 'Implicit Decision Criteria',
+    category: 'decision_criteria',
+    pattern: 'implicit_decision_criteria',
+    darkFieldMultiplier: 19,
+    confidence: 0.8,
+  },
+  {
+    id: 'od-005',
+    name: 'Unwritten Cultural Norms',
+    category: 'cultural_norms',
+    pattern: 'unwritten_cultural_norms',
+    darkFieldMultiplier: 19,
+    confidence: 0.85,
+  },
+  {
+    id: 'od-006',
+    name: 'Latent Capability Reserves',
+    category: 'resource_flows',
+    pattern: 'latent_capability_reserves',
+    darkFieldMultiplier: 19,
+    confidence: 0.79,
+  },
+  {
+    id: 'od-007',
+    name: 'Invisible Coordination Mechanisms',
+    category: 'power_structures',
+    pattern: 'invisible_coordination_mechanisms',
+    darkFieldMultiplier: 19,
+    confidence: 0.81,
+  },
+  {
+    id: 'od-008',
+    name: 'Emergent Collaboration Patterns',
+    category: 'knowledge_networks',
+    pattern: 'emergent_collaboration_patterns',
+    darkFieldMultiplier: 19,
+    confidence: 0.83,
+  },
+];
+
+/**
+ * Get organizational dynamics rules by category
+ * @param {string} category - Rule category
+ * @returns {Array<Object>} Filtered rules
+ */
+export function getRulesByCategory(category) {
+  return ORGANIZATIONAL_DYNAMICS_RULES.filter(rule => rule.category === category);
+}
+
+/**
+ * Get organizational dynamics rule by ID
+ * @param {string} id - Rule ID
+ * @returns {Object|undefined} Rule or undefined
+ */
+export function getRuleById(id) {
+  return ORGANIZATIONAL_DYNAMICS_RULES.find(rule => rule.id === id);
+}
+
+/**
+ * Validate organizational dynamics rules
+ * @param {Array<Object>} rules - Rules to validate
+ * @returns {Object} Validation result
+ */
+export function validateRules(rules) {
+  const errors = [];
+  for (const rule of rules) {
+    const result = OrganizationalDynamicsRuleSchema.safeParse(rule);
+    if (!result.success) {
+      errors.push({
+        rule: rule.id || 'unknown',
+        errors: result.error.errors,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}