@higher.archi/boe 1.0.0

package/dist/engines/utility/engine.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UtilityEngine = void 0;
+const core_1 = require("../../core");
+const strategy_1 = require("./strategy");
+/**
+ * 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}`);
+ * ```
+ */
+class UtilityEngine {
+    wm;
+    strategy;
+    constructor(workingMemory) {
+        this.wm = workingMemory ?? new core_1.WorkingMemory();
+        this.strategy = new strategy_1.UtilityStrategy();
+    }
+    // ========================================
+    // IWorkingMemory Implementation
+    // ========================================
+    add(input) {
+        return this.wm.add(input);
+    }
+    remove(factId) {
+        return this.wm.remove(factId);
+    }
+    update(input) {
+        return this.wm.update(input);
+    }
+    get(factId) {
+        return this.wm.get(factId);
+    }
+    getByType(type) {
+        return this.wm.getByType(type);
+    }
+    getAll() {
+        return this.wm.getAll();
+    }
+    has(factId) {
+        return this.wm.has(factId);
+    }
+    size() {
+        return this.wm.size();
+    }
+    clear() {
+        this.wm.clear();
+    }
+    getChanges() {
+        return this.wm.getChanges();
+    }
+    clearChanges() {
+        this.wm.clearChanges();
+    }
+    // ========================================
+    // Utility-Specific Methods
+    // ========================================
+    /**
+     * 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, alternative) {
+        return this.wm.add({
+            id: alternative.id,
+            type,
+            data: {
+                name: alternative.name,
+                ...alternative.data
+            }
+        });
+    }
+    /**
+     * Get all alternatives of a given type.
+     *
+     * @param type - The type of alternatives to retrieve
+     * @returns Array of facts representing alternatives
+     */
+    getAlternatives(type) {
+        return this.wm.getByType(type);
+    }
+    // ========================================
+    // IRuleEngine Implementation
+    // ========================================
+    /**
+     * 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, options) {
+        if (!options.alternativeType) {
+            throw new Error('UtilityEngine.execute requires options.alternativeType');
+        }
+        return this.strategy.run(ruleSet, this.wm, options.alternativeType, options);
+    }
+    // ========================================
+    // Utility Methods
+    // ========================================
+    getWorkingMemory() {
+        return this.wm;
+    }
+}
+exports.UtilityEngine = UtilityEngine;
+//# sourceMappingURL=engine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/engines/utility/engine.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,qCAMoB;AAQpB,yCAA6C;AAmB7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,aAAa;IAChB,EAAE,CAAgB;IAClB,QAAQ,CAAkB;IAElC,YAAY,aAA6B;QACvC,IAAI,CAAC,EAAE,GAAG,aAAa,IAAI,IAAI,oBAAa,EAAE,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,IAAI,0BAAe,EAAE,CAAC;IACxC,CAAC;IAED,2CAA2C;IAC3C,gCAAgC;IAChC,2CAA2C;IAE3C,GAAG,CAAC,KAAgB;QAClB,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,KAAgB;QACrB,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC;IAC9B,CAAC;IAED,YAAY;QACV,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC;IACzB,CAAC;IAED,2CAA2C;IAC3C,2BAA2B;IAC3B,2CAA2C;IAE3C;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,IAAY,EAAE,WAA6B;QACxD,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;YACjB,EAAE,EAAE,WAAW,CAAC,EAAE;YAClB,IAAI;YACJ,IAAI,EAAE;gBACJ,IAAI,EAAE,WAAW,CAAC,IAAI;gBACtB,GAAG,WAAW,CAAC,IAAI;aACpB;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,IAAY;QAC1B,OAAO,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,2CAA2C;IAC3C,6BAA6B;IAC7B,2CAA2C;IAE3C;;;;;;;;;OASG;IACH,OAAO,CAAC,OAA+B,EAAE,OAA8B;QACrE,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QAED,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IAC/E,CAAC;IAED,2CAA2C;IAC3C,kBAAkB;IAClB,2CAA2C;IAE3C,gBAAgB;QACd,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;CACF;AAjID,sCAiIC"}

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

@@ -0,0 +1,17 @@
+/**
+ * Utility/MCDM Engine
+ *
+ * Provides Multi-Criteria Decision Making for comparing alternatives
+ * across weighted criteria. Use this when you need to rank multiple
+ * options based on trade-offs between different factors.
+ *
+ * Key difference from Scoring Engine:
+ * - Scoring: evaluates ONE item and produces a score
+ * - Utility: compares MULTIPLE alternatives and ranks them
+ */
+export type { SemanticPriority, UtilityCriterion, CompiledUtilityCriterion, UtilityRule, UtilityRuleSet, UtilityConfig, CompiledUtilityRule, CompiledUtilityRuleSet, AlternativeResult, SensitivityInfo, UtilityOptions, UtilityResult } from './types';
+export { SEMANTIC_PRIORITY_VALUES, isSemanticPriority } from './types';
+export { compileUtilityRule, compileUtilityRuleSet } from './compiler';
+export { UtilityStrategy, utilityStrategy } from './strategy';
+export { UtilityEngine, AlternativeInput, UtilityExecuteOptions } from './engine';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engines/utility/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EAEV,gBAAgB,EAEhB,gBAAgB,EAChB,wBAAwB,EAExB,WAAW,EACX,cAAc,EACd,aAAa,EAEb,mBAAmB,EACnB,sBAAsB,EAEtB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}

package/dist/engines/utility/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Utility/MCDM Engine
+ *
+ * Provides Multi-Criteria Decision Making for comparing alternatives
+ * across weighted criteria. Use this when you need to rank multiple
+ * options based on trade-offs between different factors.
+ *
+ * Key difference from Scoring Engine:
+ * - Scoring: evaluates ONE item and produces a score
+ * - Utility: compares MULTIPLE alternatives and ranks them
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UtilityEngine = exports.utilityStrategy = exports.UtilityStrategy = exports.compileUtilityRuleSet = exports.compileUtilityRule = exports.isSemanticPriority = exports.SEMANTIC_PRIORITY_VALUES = void 0;
+// Semantic priority utilities
+var types_1 = require("./types");
+Object.defineProperty(exports, "SEMANTIC_PRIORITY_VALUES", { enumerable: true, get: function () { return types_1.SEMANTIC_PRIORITY_VALUES; } });
+Object.defineProperty(exports, "isSemanticPriority", { enumerable: true, get: function () { return types_1.isSemanticPriority; } });
+// Compiler
+var compiler_1 = require("./compiler");
+Object.defineProperty(exports, "compileUtilityRule", { enumerable: true, get: function () { return compiler_1.compileUtilityRule; } });
+Object.defineProperty(exports, "compileUtilityRuleSet", { enumerable: true, get: function () { return compiler_1.compileUtilityRuleSet; } });
+// Strategy
+var strategy_1 = require("./strategy");
+Object.defineProperty(exports, "UtilityStrategy", { enumerable: true, get: function () { return strategy_1.UtilityStrategy; } });
+Object.defineProperty(exports, "utilityStrategy", { enumerable: true, get: function () { return strategy_1.utilityStrategy; } });
+// Engine
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "UtilityEngine", { enumerable: true, get: function () { return engine_1.UtilityEngine; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engines/utility/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAuBH,8BAA8B;AAC9B,iCAGiB;AAFf,iHAAA,wBAAwB,OAAA;AACxB,2GAAA,kBAAkB,OAAA;AAGpB,WAAW;AACX,uCAGoB;AAFlB,8GAAA,kBAAkB,OAAA;AAClB,iHAAA,qBAAqB,OAAA;AAGvB,WAAW;AACX,uCAGoB;AAFlB,2GAAA,eAAe,OAAA;AACf,2GAAA,eAAe,OAAA;AAGjB,SAAS;AACT,mCAAkF;AAAzE,uGAAA,aAAa,OAAA"}

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

@@ -0,0 +1,30 @@
+/**
+ * Utility/MCDM Engine Strategy
+ *
+ * Compares alternatives across weighted criteria using Multi-Criteria
+ * Decision Making (MCDM) methodology.
+ *
+ * Algorithm:
+ * 1. Identify all alternatives in working memory (by type)
+ * 2. For each alternative, evaluate all criterion rules to get raw scores
+ * 3. Normalize scores across alternatives (min-max or z-score)
+ * 4. Apply direction (flip scores for 'minimize' criteria)
+ * 5. Aggregate weighted scores per alternative
+ * 6. Rank alternatives by utility score
+ */
+import { IWorkingMemory } from '../../core/memory';
+import { CompiledUtilityRuleSet, UtilityOptions, UtilityResult } from './types';
+export declare class UtilityStrategy {
+    run(ruleSet: CompiledUtilityRuleSet, wm: IWorkingMemory, alternativeType: string, options?: UtilityOptions): UtilityResult;
+    /**
+     * Match a rule against a single alternative fact
+     */
+    private matchAlternative;
+    /**
+     * Compute sensitivity analysis: how much would weights need to change
+     * for the ranking to change?
+     */
+    private computeSensitivity;
+}
+export declare const utilityStrategy: UtilityStrategy;
+//# sourceMappingURL=strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../../src/engines/utility/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD,OAAO,EACL,sBAAsB,EAEtB,cAAc,EACd,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,qBAAa,eAAe;IAC1B,GAAG,CACD,OAAO,EAAE,sBAAsB,EAC/B,EAAE,EAAE,cAAc,EAClB,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE,cAAmB,GAC3B,aAAa;IA8LhB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwCxB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAsC3B;AAGD,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/engines/utility/strategy.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Utility/MCDM Engine Strategy
+ *
+ * Compares alternatives across weighted criteria using Multi-Criteria
+ * Decision Making (MCDM) methodology.
+ *
+ * Algorithm:
+ * 1. Identify all alternatives in working memory (by type)
+ * 2. For each alternative, evaluate all criterion rules to get raw scores
+ * 3. Normalize scores across alternatives (min-max or z-score)
+ * 4. Apply direction (flip scores for 'minimize' criteria)
+ * 5. Aggregate weighted scores per alternative
+ * 6. Rank alternatives by utility score
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utilityStrategy = exports.UtilityStrategy = void 0;
+const core_1 = require("../../core");
+class UtilityStrategy {
+    run(ruleSet, wm, alternativeType, options = {}) {
+        const startTime = performance.now();
+        const { onEvaluate, onScore, computeSensitivity = false } = options;
+        const config = ruleSet.config;
+        const criteria = ruleSet.criteria;
+        // Get all alternatives of the specified type
+        const alternatives = wm.getByType(alternativeType);
+        if (alternatives.length === 0) {
+            const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+            return {
+                alternatives: [],
+                ranking: [],
+                winner: null,
+                executionTimeMs
+            };
+        }
+        // Phase 1: Compute raw scores for each alternative-criterion pair
+        const rawScores = new Map();
+        for (const alt of alternatives) {
+            const altId = alt.id;
+            const scores = {};
+            for (const criterion of criteria) {
+                // Find rules that compute this criterion
+                const criterionRules = ruleSet.rules.filter(r => r.criterion === criterion.id);
+                for (const rule of criterionRules) {
+                    // Create a temporary working memory with just this alternative
+                    // to match against the rule
+                    const activations = this.matchAlternative(rule, alt, wm);
+                    for (const activation of activations) {
+                        // Evaluate the compute expression
+                        const result = (0, core_1.evaluateCondition)(rule.compute, activation.facts);
+                        const value = typeof result === 'number' ? result : 0;
+                        // Store the score (last one wins if multiple rules match)
+                        scores[criterion.id] = value;
+                        if (onEvaluate) {
+                            onEvaluate(altId, criterion.id, value);
+                        }
+                    }
+                }
+                // Default to 0 if no rule matched
+                if (scores[criterion.id] === undefined) {
+                    scores[criterion.id] = 0;
+                }
+            }
+            rawScores.set(altId, scores);
+        }
+        // Phase 2: Normalize scores across alternatives
+        const normalizedScores = new Map();
+        for (const criterion of criteria) {
+            const allValues = alternatives.map(alt => rawScores.get(alt.id)[criterion.id]);
+            if (config.normalization === 'min-max') {
+                const min = Math.min(...allValues);
+                const max = Math.max(...allValues);
+                const range = max - min;
+                for (const alt of alternatives) {
+                    if (!normalizedScores.has(alt.id)) {
+                        normalizedScores.set(alt.id, {});
+                    }
+                    const raw = rawScores.get(alt.id)[criterion.id];
+                    let normalized = range > 0 ? (raw - min) / range : 0.5;
+                    // Flip for minimize criteria (lower raw = higher normalized)
+                    if (criterion.direction === 'minimize') {
+                        normalized = 1 - normalized;
+                    }
+                    normalizedScores.get(alt.id)[criterion.id] = normalized;
+                }
+            }
+            else if (config.normalization === 'z-score') {
+                const mean = allValues.reduce((a, b) => a + b, 0) / allValues.length;
+                const variance = allValues.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / allValues.length;
+                const stdDev = Math.sqrt(variance);
+                for (const alt of alternatives) {
+                    if (!normalizedScores.has(alt.id)) {
+                        normalizedScores.set(alt.id, {});
+                    }
+                    const raw = rawScores.get(alt.id)[criterion.id];
+                    let normalized = stdDev > 0 ? (raw - mean) / stdDev : 0;
+                    // Convert z-score to 0-1 range (approximately)
+                    // Using sigmoid-like transformation
+                    normalized = 1 / (1 + Math.exp(-normalized));
+                    // Flip for minimize criteria
+                    if (criterion.direction === 'minimize') {
+                        normalized = 1 - normalized;
+                    }
+                    normalizedScores.get(alt.id)[criterion.id] = normalized;
+                }
+            }
+            else {
+                // No normalization - just copy raw scores (and flip for minimize)
+                for (const alt of alternatives) {
+                    if (!normalizedScores.has(alt.id)) {
+                        normalizedScores.set(alt.id, {});
+                    }
+                    let value = rawScores.get(alt.id)[criterion.id];
+                    if (criterion.direction === 'minimize') {
+                        // For no normalization with minimize, invert the value
+                        value = value !== 0 ? 1 / value : Infinity;
+                    }
+                    normalizedScores.get(alt.id)[criterion.id] = value;
+                }
+            }
+        }
+        // Phase 3: Compute weighted scores and aggregate
+        const results = [];
+        for (const alt of alternatives) {
+            const normalized = normalizedScores.get(alt.id);
+            const weighted = {};
+            let utilityScore;
+            if (config.aggregation === 'weighted-sum') {
+                utilityScore = 0;
+                for (const criterion of criteria) {
+                    const weightedValue = normalized[criterion.id] * criterion.weight;
+                    weighted[criterion.id] = weightedValue;
+                    utilityScore += weightedValue;
+                }
+            }
+            else {
+                // weighted-product
+                utilityScore = 1;
+                for (const criterion of criteria) {
+                    const weightedValue = Math.pow(normalized[criterion.id], criterion.weight);
+                    weighted[criterion.id] = weightedValue;
+                    utilityScore *= weightedValue;
+                }
+            }
+            const result = {
+                id: alt.id,
+                name: alt.data.name || alt.id,
+                rawScores: rawScores.get(alt.id),
+                normalizedScores: normalized,
+                weightedScores: weighted,
+                utilityScore
+            };
+            results.push(result);
+            if (onScore) {
+                onScore(result);
+            }
+        }
+        // Phase 4: Rank by utility score (descending)
+        const ranking = [...results].sort((a, b) => b.utilityScore - a.utilityScore);
+        const winner = ranking.length > 0 ? ranking[0] : null;
+        // Phase 5: Sensitivity analysis (optional)
+        let sensitivity;
+        if (computeSensitivity && winner && ranking.length > 1) {
+            sensitivity = this.computeSensitivity(ranking, criteria);
+        }
+        const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+        return {
+            alternatives: results,
+            ranking,
+            winner,
+            sensitivity,
+            executionTimeMs
+        };
+    }
+    /**
+     * Match a rule against a single alternative fact
+     */
+    matchAlternative(rule, alternative, wm) {
+        // Simple matching: if the rule's first input type matches the alternative type
+        const firstInput = rule.inputs[0];
+        if (!firstInput)
+            return [];
+        if (firstInput.type !== alternative.type) {
+            return [];
+        }
+        // Build bindings with fact-like objects (condition evaluator expects { data: ... })
+        const bindings = {
+            [firstInput.name]: { data: alternative.data }
+        };
+        // Handle additional inputs (join with other facts in working memory)
+        for (let i = 1; i < rule.inputs.length; i++) {
+            const input = rule.inputs[i];
+            const facts = wm.getByType(input.type);
+            if (facts.length === 0) {
+                return []; // Required input type not found
+            }
+            // For simplicity, take the first matching fact
+            // A more sophisticated implementation would handle all combinations
+            const fact = facts[0];
+            bindings[input.name] = { data: fact.data };
+        }
+        // Check when condition
+        if (rule.when) {
+            const result = (0, core_1.evaluateCondition)(rule.when, bindings);
+            if (!result) {
+                return [];
+            }
+        }
+        return [{ facts: bindings }];
+    }
+    /**
+     * Compute sensitivity analysis: how much would weights need to change
+     * for the ranking to change?
+     */
+    computeSensitivity(ranking, criteria) {
+        const winner = ranking[0];
+        const runnerUp = ranking[1];
+        const sensitivity = {};
+        for (const criterion of criteria) {
+            const info = {
+                currentTop: winner.name
+            };
+            // Calculate the weight change needed to flip the ranking
+            const winnerNorm = winner.normalizedScores[criterion.id];
+            const runnerNorm = runnerUp.normalizedScores[criterion.id];
+            // Only interesting if runner-up scores better on this criterion
+            if (runnerNorm > winnerNorm) {
+                // Simplified sensitivity: would need significant weight increase
+                // to flip (actual calculation is more complex)
+                const gap = winner.utilityScore - runnerUp.utilityScore;
+                const scoreDiff = runnerNorm - winnerNorm;
+                if (scoreDiff > 0) {
+                    const weightNeeded = gap / scoreDiff + criterion.weight;
+                    if (weightNeeded <= 1) {
+                        info.topChangeAt = weightNeeded;
+                        info.wouldBecome = runnerUp.name;
+                    }
+                }
+            }
+            sensitivity[criterion.id] = info;
+        }
+        return sensitivity;
+    }
+}
+exports.UtilityStrategy = UtilityStrategy;
+// Export a singleton instance for convenience
+exports.utilityStrategy = new UtilityStrategy();
+//# sourceMappingURL=strategy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../../src/engines/utility/strategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,qCAEoB;AAapB,MAAa,eAAe;IAC1B,GAAG,CACD,OAA+B,EAC/B,EAAkB,EAClB,eAAuB,EACvB,UAA0B,EAAE;QAE5B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QACpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAElC,6CAA6C;QAC7C,MAAM,YAAY,GAAG,EAAE,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QAEnD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;YAChF,OAAO;gBACL,YAAY,EAAE,EAAE;gBAChB,OAAO,EAAE,EAAE;gBACX,MAAM,EAAE,IAAI;gBACZ,eAAe;aAChB,CAAC;QACJ,CAAC;QAED,kEAAkE;QAClE,MAAM,SAAS,GAAwC,IAAI,GAAG,EAAE,CAAC;QAEjE,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,MAAM,GAA2B,EAAE,CAAC;YAE1C,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;gBACjC,yCAAyC;gBACzC,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,EAAE,CAAC,CAAC;gBAE/E,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;oBAClC,+DAA+D;oBAC/D,4BAA4B;oBAC5B,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;oBAEzD,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;wBACrC,kCAAkC;wBAClC,MAAM,MAAM,GAAG,IAAA,wBAAiB,EAAC,IAAI,CAAC,OAAc,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;wBACxE,MAAM,KAAK,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;wBAEtD,0DAA0D;wBAC1D,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC;wBAE7B,IAAI,UAAU,EAAE,CAAC;4BACf,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;wBACzC,CAAC;oBACH,CAAC;gBACH,CAAC;gBAED,kCAAkC;gBAClC,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,SAAS,EAAE,CAAC;oBACvC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;gBAC3B,CAAC;YACH,CAAC;YAED,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;QAED,gDAAgD;QAChD,MAAM,gBAAgB,GAAwC,IAAI,GAAG,EAAE,CAAC;QAExE,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;YAEhF,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;gBACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;gBACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;gBACnC,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,CAAC;gBAExB,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;oBAC/B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;wBAClC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBACnC,CAAC;oBAED,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;oBACjD,IAAI,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;oBAEvD,6DAA6D;oBAC7D,IAAI,SAAS,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;wBACvC,UAAU,GAAG,CAAC,GAAG,UAAU,CAAC;oBAC9B,CAAC;oBAED,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC;gBAC3D,CAAC;YACH,CAAC;iBAAM,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;gBAC9C,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;gBACrE,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;gBACjG,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAEnC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;oBAC/B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;wBAClC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBACnC,CAAC;oBAED,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;oBACjD,IAAI,UAAU,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;oBAExD,+CAA+C;oBAC/C,oCAAoC;oBACpC,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;oBAE7C,6BAA6B;oBAC7B,IAAI,SAAS,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;wBACvC,UAAU,GAAG,CAAC,GAAG,UAAU,CAAC;oBAC9B,CAAC;oBAED,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC;gBAC3D,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,kEAAkE;gBAClE,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;oBAC/B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;wBAClC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBACnC,CAAC;oBAED,IAAI,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;oBAEjD,IAAI,SAAS,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;wBACvC,uDAAuD;wBACvD,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;oBAC7C,CAAC;oBAED,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC;gBACtD,CAAC;YACH,CAAC;QACH,CAAC;QAED,iDAAiD;QACjD,MAAM,OAAO,GAAwB,EAAE,CAAC;QAExC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;YACjD,MAAM,QAAQ,GAA2B,EAAE,CAAC;YAC5C,IAAI,YAAoB,CAAC;YAEzB,IAAI,MAAM,CAAC,WAAW,KAAK,cAAc,EAAE,CAAC;gBAC1C,YAAY,GAAG,CAAC,CAAC;gBACjB,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;oBACjC,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;oBAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC;oBACvC,YAAY,IAAI,aAAa,CAAC;gBAChC,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,mBAAmB;gBACnB,YAAY,GAAG,CAAC,CAAC;gBACjB,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;oBACjC,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;oBAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC;oBACvC,YAAY,IAAI,aAAa,CAAC;gBAChC,CAAC;YACH,CAAC;YAED,MAAM,MAAM,GAAsB;gBAChC,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE;gBAC7B,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE;gBACjC,gBAAgB,EAAE,UAAU;gBAC5B,cAAc,EAAE,QAAQ;gBACxB,YAAY;aACb,CAAC;YAEF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAErB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,MAAM,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QAED,8CAA8C;QAC9C,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;QAC7E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAEtD,2CAA2C;QAC3C,IAAI,WAAwD,CAAC;QAE7D,IAAI,kBAAkB,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvD,WAAW,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC3D,CAAC;QAED,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAEhF,OAAO;YACL,YAAY,EAAE,OAAO;YACrB,OAAO;YACP,MAAM;YACN,WAAW;YACX,eAAe;SAChB,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,gBAAgB,CAAC,IAAS,EAAE,WAAiB,EAAE,EAAkB;QACvE,+EAA+E;QAC/E,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,UAAU;YAAE,OAAO,EAAE,CAAC;QAE3B,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC;YACzC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,oFAAoF;QACpF,MAAM,QAAQ,GAAwB;YACpC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE;SAC9C,CAAC;QAEF,qEAAqE;QACrE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,KAAK,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAEvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO,EAAE,CAAC,CAAC,gCAAgC;YAC7C,CAAC;YAED,+CAA+C;YAC/C,oEAAoE;YACpE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7C,CAAC;QAED,uBAAuB;QACvB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,IAAA,wBAAiB,EAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QAED,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACK,kBAAkB,CACxB,OAA4B,EAC5B,QAAoC;QAEpC,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,WAAW,GAAoC,EAAE,CAAC;QAExD,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,GAAoB;gBAC5B,UAAU,EAAE,MAAM,CAAC,IAAI;aACxB,CAAC;YAEF,yDAAyD;YACzD,MAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACzD,MAAM,UAAU,GAAG,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YAE3D,gEAAgE;YAChE,IAAI,UAAU,GAAG,UAAU,EAAE,CAAC;gBAC5B,iEAAiE;gBACjE,+CAA+C;gBAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;gBACxD,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;gBAE1C,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;oBAClB,MAAM,YAAY,GAAG,GAAG,GAAG,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC;oBACxD,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;wBACtB,IAAI,CAAC,WAAW,GAAG,YAAY,CAAC;wBAChC,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC;oBACnC,CAAC;gBACH,CAAC;YACH,CAAC;YAED,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACnC,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;CACF;AAzRD,0CAyRC;AAED,8CAA8C;AACjC,QAAA,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC"}