@higher.archi/boe 1.0.0

package/dist/engines/state-machine/types.d.ts

@@ -0,0 +1,229 @@
+/**
+ * State Machine Engine Types
+ *
+ * Defines types for state machine definitions, transitions, guards, and actions.
+ * State machines track entity lifecycle through defined states and transitions.
+ */
+import { Condition } from '../../core';
+/**
+ * Action to execute on state entry, exit, or during transition.
+ * Uses the same familiar syntax as forward chaining actions.
+ */
+export type StateMachineActionItem = {
+    set: Record<string, any>;
+} | {
+    emit: string;
+    data?: Record<string, any>;
+} | {
+    call: string;
+} | {
+    log: string;
+};
+/**
+ * A transition between states
+ */
+export type StateTransition = {
+    /** Event that triggers this transition */
+    event: string;
+    /** Target state to transition to */
+    target: string;
+    /** Optional guard condition - transition only if true */
+    guard?: Condition;
+    /** Actions to execute during transition */
+    actions?: StateMachineActionItem[];
+};
+/**
+ * A state definition
+ */
+export type StateDefinition = {
+    /** Mark as final (terminal) state - no transitions out */
+    type?: 'final' | 'parallel';
+    /** Initial sub-state for compound states */
+    initial?: string;
+    /** Nested states for hierarchical state machines */
+    states?: Record<string, StateDefinition>;
+    /** Transitions from this state */
+    transitions?: StateTransition[];
+    /** Actions to execute when entering this state */
+    onEnter?: StateMachineActionItem[];
+    /** Actions to execute when exiting this state */
+    onExit?: StateMachineActionItem[];
+};
+/**
+ * State machine definition (source format)
+ */
+export type StateMachineDefinition = {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name?: string;
+    /** Engine mode */
+    mode: 'state-machine';
+    /** Initial state */
+    initial: string;
+    /** Initial context data */
+    context?: Record<string, any>;
+    /** State definitions */
+    states: Record<string, StateDefinition>;
+    /** Configuration options */
+    config?: Partial<StateMachineConfig>;
+};
+/**
+ * State machine configuration
+ */
+export type StateMachineConfig = {
+    mode: 'state-machine';
+    /** Whether to throw on invalid transitions (default: true) */
+    strict: boolean;
+    /** Maximum transition history to keep (default: 100) */
+    maxHistory: number;
+};
+/**
+ * Compiled action item (normalized internal format)
+ */
+export type CompiledStateMachineAction = {
+    type: 'set' | 'emit' | 'call' | 'log';
+    /** For 'set': map of path arrays to values */
+    assignments?: Array<{
+        path: string[];
+        value: any;
+    }>;
+    /** For 'emit': event name */
+    event?: string;
+    /** For 'emit': event data */
+    data?: Record<string, any>;
+    /** For 'call': handler name */
+    handler?: string;
+    /** For 'log': message template */
+    message?: string;
+};
+/**
+ * Compiled transition
+ */
+export type CompiledTransition = {
+    event: string;
+    target: string;
+    guard?: any;
+    actions: CompiledStateMachineAction[];
+};
+/**
+ * Compiled state definition
+ */
+export type CompiledStateDefinition = {
+    name: string;
+    type?: 'final' | 'parallel';
+    initial?: string;
+    states?: Record<string, CompiledStateDefinition>;
+    transitions: CompiledTransition[];
+    onEnter: CompiledStateMachineAction[];
+    onExit: CompiledStateMachineAction[];
+    /** All valid events from this state */
+    validEvents: string[];
+    /** Parent state name (for hierarchical) */
+    parent?: string;
+};
+/**
+ * Compiled state machine definition
+ */
+export type CompiledStateMachineDefinition = {
+    id: string;
+    name?: string;
+    mode: 'state-machine';
+    initial: string;
+    initialContext: Record<string, any>;
+    states: Record<string, CompiledStateDefinition>;
+    /** Flattened map of all states including nested */
+    stateMap: Map<string, CompiledStateDefinition>;
+    config: StateMachineConfig;
+};
+/**
+ * A snapshot of machine state (serializable)
+ */
+export type MachineSnapshot = {
+    /** Current state (dot-notation for nested: "active.running") */
+    state: string;
+    /** Current context data */
+    context: Record<string, any>;
+    /** Transition history */
+    history: TransitionRecord[];
+};
+/**
+ * Record of a transition that occurred
+ */
+export type TransitionRecord = {
+    from: string;
+    to: string;
+    event: string;
+    timestamp: string;
+    payload?: any;
+};
+/**
+ * Handler for custom actions
+ */
+export type StateMachineActionHandler = (context: Record<string, any>, event: {
+    type: string;
+    payload?: any;
+}, meta: {
+    from: string;
+    to: string;
+}) => void;
+/**
+ * Registry of action handlers
+ */
+export type StateMachineActionRegistry = Record<string, StateMachineActionHandler>;
+/**
+ * Event listener for state machine events
+ */
+export type StateMachineEventListener = (event: string, data: Record<string, any>, snapshot: MachineSnapshot) => void;
+/**
+ * Options for state machine execution
+ */
+export type StateMachineOptions = {
+    /** Custom action handlers */
+    actions?: StateMachineActionRegistry;
+    /** Event listener for emitted events */
+    onEmit?: StateMachineEventListener;
+    /** Callback when state changes */
+    onTransition?: (from: string, to: string, event: string) => void;
+    /** Temporal override for testing */
+    temporal?: Date;
+};
+/**
+ * Result of a transition attempt
+ */
+export type TransitionResult = {
+    /** Whether transition succeeded */
+    success: boolean;
+    /** Previous state */
+    from: string;
+    /** New state (same as 'from' if failed) */
+    to: string;
+    /** Event that triggered transition */
+    event: string;
+    /** Error message if failed */
+    error?: string;
+    /** Actions that were executed */
+    actionsExecuted: string[];
+};
+/**
+ * A live state machine instance
+ */
+export interface IStateMachineInstance {
+    /** Current state */
+    readonly state: string;
+    /** Current context */
+    readonly context: Record<string, any>;
+    /** Check if event is valid from current state */
+    can(event: string): boolean;
+    /** Get all valid events from current state */
+    nextEvents(): string[];
+    /** Send an event to trigger transition */
+    send(event: string, payload?: any): TransitionResult;
+    /** Check if machine is in a final state */
+    isFinal(): boolean;
+    /** Get serializable snapshot */
+    snapshot(): MachineSnapshot;
+    /** Get transition history */
+    history(): TransitionRecord[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/engines/state-machine/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engines/state-machine/types.ts"],"names":[],"mappings":"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"}

package/dist/engines/state-machine/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * State Machine Engine Types
+ *
+ * Defines types for state machine definitions, transitions, guards, and actions.
+ * State machines track entity lifecycle through defined states and transitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/engines/state-machine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engines/state-machine/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/engines/utility/compiler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility/MCDM Engine Compiler
+ */
+import { UtilityRule, UtilityRuleSet, CompiledUtilityRule, CompiledUtilityRuleSet } from './types';
+export declare function compileUtilityRule(rule: UtilityRule, index?: number): CompiledUtilityRule;
+export declare function compileUtilityRuleSet(ruleSet: UtilityRuleSet): CompiledUtilityRuleSet;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/engines/utility/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/engines/utility/compiler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EACL,WAAW,EACX,cAAc,EAGd,mBAAmB,EACnB,sBAAsB,EAIvB,MAAM,SAAS,CAAC;AAiHjB,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,GAAE,MAAU,GAAG,mBAAmB,CAkB5F;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,sBAAsB,CAkDrF"}

package/dist/engines/utility/compiler.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Utility/MCDM Engine Compiler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileUtilityRule = compileUtilityRule;
+exports.compileUtilityRuleSet = compileUtilityRuleSet;
+const core_1 = require("../../core");
+const types_1 = require("./types");
+// ========================================
+// Helper Functions
+// ========================================
+function countConditions(condition) {
+    if (!condition)
+        return 0;
+    if (condition.children) {
+        return 1 + condition.children.reduce((sum, c) => sum + countConditions(c), 0);
+    }
+    return 1;
+}
+function calculateComplexity(inputs, where) {
+    let score = 0;
+    score += inputs.length * 10;
+    score += countConditions(where) * 5;
+    for (const input of inputs) {
+        score += countConditions(input.where) * 2;
+    }
+    return score;
+}
+function compilePath(from) {
+    const str = from.startsWith('$') ? from.slice(1) : from;
+    const parts = str.split('.');
+    return {
+        param: parts[0],
+        path: parts.slice(1)
+    };
+}
+// ========================================
+// Parameter Compilation
+// ========================================
+function compileInputParameter(input) {
+    const compiled = {
+        name: input.name,
+        type: input.type,
+        schema: input.shape ? (0, core_1.normalizeShape)(input.shape) : { type: 'object' }
+    };
+    if (input.where) {
+        compiled.where = (0, core_1.compileCondition)(input.where);
+    }
+    if (input.from) {
+        compiled.from = compilePath(input.from);
+    }
+    return compiled;
+}
+// ========================================
+// Criterion Compilation
+// ========================================
+/**
+ * Convert a criterion weight to a numeric value.
+ * Handles both numeric weights (0-1) and semantic priorities.
+ */
+function resolveWeight(weight) {
+    if (typeof weight === 'number') {
+        return weight;
+    }
+    if ((0, types_1.isSemanticPriority)(weight)) {
+        return types_1.SEMANTIC_PRIORITY_VALUES[weight];
+    }
+    throw new Error(`Invalid weight value: ${weight}. Must be a number (0-1) or SemanticPriority`);
+}
+/**
+ * Compile a single criterion, converting semantic weights to numeric values.
+ * Note: Weights are normalized later in compileUtilityRuleSet.
+ */
+function compileCriterion(criterion) {
+    const numericWeight = resolveWeight(criterion.weight);
+    // For numeric weights, validate 0-1 range (semantic weights use different scale)
+    if (typeof criterion.weight === 'number' && (numericWeight < 0 || numericWeight > 1)) {
+        throw new Error(`Numeric criterion weight must be between 0 and 1, got ${numericWeight} for "${criterion.id}"`);
+    }
+    return {
+        id: criterion.id,
+        name: criterion.name,
+        weight: numericWeight,
+        direction: criterion.direction
+    };
+}
+/**
+ * Normalize criterion weights so they sum to 1.0.
+ * This allows semantic weights (which use a different scale) to work correctly.
+ */
+function normalizeWeights(criteria) {
+    const totalWeight = criteria.reduce((sum, c) => sum + c.weight, 0);
+    if (totalWeight === 0) {
+        throw new Error('At least one criterion must have a non-zero weight');
+    }
+    for (const criterion of criteria) {
+        criterion.weight = criterion.weight / totalWeight;
+    }
+}
+// ========================================
+// Rule Compilation
+// ========================================
+function compileUtilityRule(rule, index = 0) {
+    const inputs = rule.inputs.map(compileInputParameter);
+    const when = rule.when ? (0, core_1.compileCondition)(rule.when) : undefined;
+    // Compile the compute expression
+    const compute = (0, core_1.compileCondition)(rule.compute);
+    return {
+        id: rule.id,
+        name: rule.name,
+        salience: rule.salience ?? 0,
+        complexity: calculateComplexity(inputs, when),
+        index,
+        inputs,
+        when,
+        criterion: rule.criterion,
+        compute
+    };
+}
+// ========================================
+// RuleSet Compilation
+// ========================================
+function compileUtilityRuleSet(ruleSet) {
+    // Validate criteria
+    if (!ruleSet.criteria || ruleSet.criteria.length === 0) {
+        throw new Error('UtilityRuleSet must have at least one criterion');
+    }
+    // Check if any criteria use semantic weights
+    const hasSemanticWeights = ruleSet.criteria.some(c => (0, types_1.isSemanticPriority)(c.weight));
+    // Compile criteria (converts semantic weights to numeric)
+    const compiledCriteria = ruleSet.criteria.map(compileCriterion);
+    // Normalize weights to sum to 1.0
+    // This is always done now to support semantic weights and mixed weight types
+    if (hasSemanticWeights) {
+        // Semantic weights: always normalize
+        normalizeWeights(compiledCriteria);
+    }
+    else {
+        // Numeric weights: validate they sum to ~1.0, then normalize for precision
+        const totalWeight = compiledCriteria.reduce((sum, c) => sum + c.weight, 0);
+        if (Math.abs(totalWeight - 1.0) > 0.01) {
+            throw new Error(`Criterion weights must sum to 1.0, got ${totalWeight.toFixed(4)}`);
+        }
+        // Normalize for floating point precision
+        normalizeWeights(compiledCriteria);
+    }
+    // Validate that all rules reference valid criteria
+    const criterionIds = new Set(compiledCriteria.map(c => c.id));
+    for (const rule of ruleSet.rules) {
+        if (!criterionIds.has(rule.criterion)) {
+            throw new Error(`Rule "${rule.id}" references unknown criterion "${rule.criterion}"`);
+        }
+    }
+    const config = {
+        mode: 'utility',
+        normalization: ruleSet.config?.normalization ?? 'min-max',
+        aggregation: ruleSet.config?.aggregation ?? 'weighted-sum'
+    };
+    return {
+        id: ruleSet.id,
+        name: ruleSet.name,
+        mode: 'utility',
+        schema: ruleSet.shape ? (0, core_1.normalizeShape)(ruleSet.shape) : { type: 'object' },
+        criteria: compiledCriteria,
+        rules: ruleSet.rules.map((rule, index) => compileUtilityRule(rule, index)),
+        config
+    };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/engines/utility/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../../../src/engines/utility/compiler.ts"],"names":[],"mappings":"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"}

package/dist/engines/utility/engine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Utility/MCDM Engine
+ *
+ * Self-contained engine for Multi-Criteria Decision Making.
+ * Compares multiple alternatives across weighted criteria to find the best option.
+ *
+ * Key difference from Scoring Engine:
+ * - Scoring: evaluates ONE item and produces a score
+ * - Utility: compares MULTIPLE alternatives and ranks them
+ */
+import { IRuleEngine, WorkingMemory, Fact, FactInput, FactChange } from '../../core';
+import { CompiledUtilityRuleSet, UtilityOptions, UtilityResult } from './types';
+/**
+ * Alternative input - convenience type for adding alternatives
+ */
+export type AlternativeInput = {
+    id?: string;
+    name: string;
+    data: Record<string, any>;
+};
+/**
+ * Extended options that include the alternative type
+ */
+export type UtilityExecuteOptions = UtilityOptions & {
+    /** The fact type to treat as alternatives (required) */
+    alternativeType: string;
+};
+/**
+ * Utility/MCDM rule engine.
+ *
+ * Evaluates multiple alternatives across weighted criteria and ranks them
+ * by their overall utility score.
+ *
+ * @example
+ * ```typescript
+ * const engine = new UtilityEngine();
+ *
+ * // Add alternatives
+ * engine.addAlternative('JobOffer', {
+ *   name: 'TechCorp',
+ *   baseSalary: 150000,
+ *   remotePolicy: 'hybrid'
+ * });
+ * engine.addAlternative('JobOffer', {
+ *   name: 'StartupXYZ',
+ *   baseSalary: 130000,
+ *   remotePolicy: 'full'
+ * });
+ *
+ * const result = engine.execute(compiledRules, { alternativeType: 'JobOffer' });
+ * console.log(`Best option: ${result.winner?.name}`);
+ * ```
+ */
+export declare class UtilityEngine implements IRuleEngine<CompiledUtilityRuleSet, UtilityExecuteOptions, UtilityResult> {
+    private wm;
+    private strategy;
+    constructor(workingMemory?: WorkingMemory);
+    add(input: FactInput): Fact;
+    remove(factId: string): Fact | undefined;
+    update(input: FactInput): Fact;
+    get(factId: string): Fact | undefined;
+    getByType(type: string): Fact[];
+    getAll(): Fact[];
+    has(factId: string): boolean;
+    size(): number;
+    clear(): void;
+    getChanges(): FactChange[];
+    clearChanges(): void;
+    /**
+     * Add an alternative to compare.
+     *
+     * Convenience method that creates a fact with the given type and data.
+     *
+     * @param type - The type of alternative (e.g., 'JobOffer', 'Vendor', 'House')
+     * @param alternative - The alternative data including a name
+     * @returns The created fact
+     *
+     * @example
+     * ```typescript
+     * engine.addAlternative('JobOffer', {
+     *   name: 'TechCorp',
+     *   salary: 150000,
+     *   benefits: 'excellent'
+     * });
+     * ```
+     */
+    addAlternative(type: string, alternative: AlternativeInput): Fact;
+    /**
+     * Get all alternatives of a given type.
+     *
+     * @param type - The type of alternatives to retrieve
+     * @returns Array of facts representing alternatives
+     */
+    getAlternatives(type: string): Fact[];
+    /**
+     * Execute a utility ruleset to compare alternatives.
+     *
+     * All alternatives of the specified type are evaluated against each criterion,
+     * normalized, weighted, and ranked by their overall utility score.
+     *
+     * @param ruleSet - Compiled utility ruleset
+     * @param options - Runtime options including alternativeType (required)
+     * @returns Result with ranked alternatives and optional sensitivity analysis
+     */
+    execute(ruleSet: CompiledUtilityRuleSet, options: UtilityExecuteOptions): UtilityResult;
+    getWorkingMemory(): WorkingMemory;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engines/utility/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/engines/utility/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,IAAI,EACJ,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,aAAa,EACd,MAAM,SAAS,CAAC;AAIjB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG;IACnD,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAc,YAAW,WAAW,CAAC,sBAAsB,EAAE,qBAAqB,EAAE,aAAa,CAAC;IAC7G,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,aAAa,CAAC,EAAE,aAAa;IASzC,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI3B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIxC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI9B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE;IAI/B,MAAM,IAAI,IAAI,EAAE;IAIhB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;IAIb,UAAU,IAAI,UAAU,EAAE;IAI1B,YAAY,IAAI,IAAI;IAQpB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,IAAI;IAWjE;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE;IAQrC;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,EAAE,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,GAAG,aAAa;IAYvF,gBAAgB,IAAI,aAAa;CAGlC"}