@higher.archi/boe 1.0.15 → 1.0.17

package/dist/compare/compare.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Ruleset Comparison Utility
+ *
+ * Scores a set of entities against two rulesets and computes per-entity
+ * deltas and aggregate tier migration statistics. Designed for preview/dry-run
+ * workflows where a draft config is compared against the active config
+ * before activation.
+ */
+import type { CompiledScoringRuleSet, ScoringOptions, TierDefinition } from '../engines/scoring/types';
+import type { CompareInput, ComparisonResult } from './types';
+/**
+ * Compare two scoring rulesets by executing both against the same inputs.
+ *
+ * For each input, creates a fresh ScoringEngine, adds the facts, and executes
+ * against both rulesets. Returns per-entity deltas and aggregate statistics
+ * including tier migration counts.
+ *
+ * @param rulesetA - The baseline ruleset (e.g. active/current config)
+ * @param rulesetB - The candidate ruleset (e.g. draft/proposed config)
+ * @param inputs - Entity fact sets to score with both rulesets
+ * @param options - Optional scoring options passed to both executions
+ * @returns Comparison result with per-entity deltas and summary statistics
+ *
+ * @example
+ * ```typescript
+ * const result = compareRulesets(activeRuleset, draftRuleset, [
+ *   { entityId: 'user-1', facts: [{ type: 'User', data: { score: 750 } }] },
+ *   { entityId: 'user-2', facts: [{ type: 'User', data: { score: 620 } }] },
+ * ]);
+ *
+ * console.log(`Avg score delta: ${result.summary.avgScoreDelta}`);
+ * console.log(`Tier changes: ${result.summary.tierChanges}`);
+ * console.log(`Migrations:`, result.summary.tierMigrations);
+ * ```
+ */
+export declare function compareRulesets<T extends TierDefinition = TierDefinition>(rulesetA: CompiledScoringRuleSet<T>, rulesetB: CompiledScoringRuleSet<T>, inputs: CompareInput[], options?: ScoringOptions): ComparisonResult<T>;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../src/compare/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACvG,OAAO,KAAK,EAAE,YAAY,EAAe,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACvE,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,EACnC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,EACnC,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CAAC,CAAC,CAAC,CA8DrB"}

package/dist/compare/compare.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Ruleset Comparison Utility
+ *
+ * Scores a set of entities against two rulesets and computes per-entity
+ * deltas and aggregate tier migration statistics. Designed for preview/dry-run
+ * workflows where a draft config is compared against the active config
+ * before activation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareRulesets = compareRulesets;
+const engine_1 = require("../engines/scoring/engine");
+/**
+ * Compare two scoring rulesets by executing both against the same inputs.
+ *
+ * For each input, creates a fresh ScoringEngine, adds the facts, and executes
+ * against both rulesets. Returns per-entity deltas and aggregate statistics
+ * including tier migration counts.
+ *
+ * @param rulesetA - The baseline ruleset (e.g. active/current config)
+ * @param rulesetB - The candidate ruleset (e.g. draft/proposed config)
+ * @param inputs - Entity fact sets to score with both rulesets
+ * @param options - Optional scoring options passed to both executions
+ * @returns Comparison result with per-entity deltas and summary statistics
+ *
+ * @example
+ * ```typescript
+ * const result = compareRulesets(activeRuleset, draftRuleset, [
+ *   { entityId: 'user-1', facts: [{ type: 'User', data: { score: 750 } }] },
+ *   { entityId: 'user-2', facts: [{ type: 'User', data: { score: 620 } }] },
+ * ]);
+ *
+ * console.log(`Avg score delta: ${result.summary.avgScoreDelta}`);
+ * console.log(`Tier changes: ${result.summary.tierChanges}`);
+ * console.log(`Migrations:`, result.summary.tierMigrations);
+ * ```
+ */
+function compareRulesets(rulesetA, rulesetB, inputs, options = {}) {
+    const deltas = [];
+    for (const input of inputs) {
+        const engineA = new engine_1.ScoringEngine();
+        for (const fact of input.facts) {
+            engineA.add(fact);
+        }
+        const resultA = engineA.execute(rulesetA, options);
+        const engineB = new engine_1.ScoringEngine();
+        for (const fact of input.facts) {
+            engineB.add(fact);
+        }
+        const resultB = engineB.execute(rulesetB, options);
+        deltas.push({
+            entityId: input.entityId,
+            scoreA: resultA.totalScore,
+            scoreB: resultB.totalScore,
+            scoreDelta: resultB.totalScore - resultA.totalScore,
+            tierA: resultA.tier?.id,
+            tierB: resultB.tier?.id,
+            tierChanged: resultA.tier?.id !== resultB.tier?.id,
+            resultA,
+            resultB,
+        });
+    }
+    // Compute summary
+    const entityCount = deltas.length;
+    let sumDelta = 0;
+    let minDelta = Infinity;
+    let maxDelta = -Infinity;
+    let tierChanges = 0;
+    const tierMigrations = {};
+    for (const d of deltas) {
+        sumDelta += d.scoreDelta;
+        if (d.scoreDelta < minDelta)
+            minDelta = d.scoreDelta;
+        if (d.scoreDelta > maxDelta)
+            maxDelta = d.scoreDelta;
+        if (d.tierChanged) {
+            tierChanges++;
+            const from = d.tierA ?? '(none)';
+            const to = d.tierB ?? '(none)';
+            if (!tierMigrations[from])
+                tierMigrations[from] = {};
+            tierMigrations[from][to] = (tierMigrations[from][to] ?? 0) + 1;
+        }
+    }
+    return {
+        deltas,
+        summary: {
+            entityCount,
+            avgScoreDelta: entityCount > 0 ? sumDelta / entityCount : 0,
+            minScoreDelta: entityCount > 0 ? minDelta : 0,
+            maxScoreDelta: entityCount > 0 ? maxDelta : 0,
+            tierChanges,
+            tierMigrations,
+        },
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/compare/compare.js.map

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

package/dist/compare/index.d.ts

@@ -0,0 +1,3 @@
+export type { CompareInput, EntityDelta, ComparisonResult } from './types';
+export { compareRulesets } from './compare';
+//# sourceMappingURL=index.d.ts.map

package/dist/compare/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compare/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG3E,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/compare/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareRulesets = void 0;
+// Core comparison
+var compare_1 = require("./compare");
+Object.defineProperty(exports, "compareRulesets", { enumerable: true, get: function () { return compare_1.compareRulesets; } });
+//# sourceMappingURL=index.js.map

package/dist/compare/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compare/index.ts"],"names":[],"mappings":";;;AAGA,kBAAkB;AAClB,qCAA4C;AAAnC,0GAAA,eAAe,OAAA"}

package/dist/compare/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Compare Module Types
+ *
+ * Types for scoring ruleset comparison — computing per-entity score deltas
+ * and tier migration statistics between two rulesets.
+ */
+import type { ScoringResult, TierDefinition } from '../engines/scoring/types';
+import type { FactInput } from '../core';
+/** A single test case: a set of facts to score with both rulesets */
+export type CompareInput = {
+    entityId: string;
+    facts: FactInput[];
+};
+/** Per-entity diff between ruleset A and B results */
+export type EntityDelta<T extends TierDefinition = TierDefinition> = {
+    entityId: string;
+    scoreA: number;
+    scoreB: number;
+    scoreDelta: number;
+    tierA?: string;
+    tierB?: string;
+    tierChanged: boolean;
+    resultA: ScoringResult<T>;
+    resultB: ScoringResult<T>;
+};
+/** Aggregate comparison result */
+export type ComparisonResult<T extends TierDefinition = TierDefinition> = {
+    deltas: EntityDelta<T>[];
+    summary: {
+        entityCount: number;
+        avgScoreDelta: number;
+        minScoreDelta: number;
+        maxScoreDelta: number;
+        tierChanges: number;
+        tierMigrations: Record<string, Record<string, number>>;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/compare/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/compare/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CAC3B,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACxE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IACzB,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACxD,CAAC;CACH,CAAC"}

package/dist/compare/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Compare Module Types
+ *
+ * Types for scoring ruleset comparison — computing per-entity score deltas
+ * and tier migration statistics between two rulesets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/compare/types.js.map

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

package/dist/index.d.ts

@@ -59,4 +59,6 @@ export { calculateDecayMultiplier, resolveDecayTimestamp } from './core/evaluati
 export type { DecayCurve, DecayTimeUnit, DecayConfig, DecayInfo } from './core/evaluation/decay';
 export * from './qfacts';
 export * from './abtesting';
+export * from './compare';
+export * from './promotion';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -187,4 +187,12 @@ __exportStar(require("./qfacts"), exports);
 // A/B Testing - Deterministic Variant Resolution
 // ========================================
 __exportStar(require("./abtesting"), exports);
+// ========================================
+// Compare - Ruleset Comparison Utility
+// ========================================
+__exportStar(require("./compare"), exports);
+// ========================================
+// Promotion — Counterfactual Scoring Analysis
+// ========================================
+__exportStar(require("./promotion"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;;AAEH,2CAA2C;AAC3C,UAAU;AACV,2CAA2C;AAE3C,iEAAiE;AACjE,6CAAkD;AAAzC,wGAAA,aAAa,OAAA;AACtB,+CAAoD;AAA3C,0GAAA,cAAc,OAAA;AACvB,6CAAkD;AAAzC,wGAAA,aAAa,OAAA;AACtB,mDAAwD;AAA/C,8GAAA,gBAAgB,OAAA;AACzB,yCAA8C;AAArC,oGAAA,WAAW,OAAA;AACpB,+CAAoD;AAA3C,0GAAA,cAAc,OAAA;AACvB,qDAAyD;AAAhD,+GAAA,gBAAgB,OAAA;AACzB,yDAA6D;AAApD,mHAAA,kBAAkB,OAAA;AAC3B,mDAAwD;AAA/C,8GAAA,gBAAgB,OAAA;AACzB,6CAAkD;AAAzC,wGAAA,aAAa,OAAA;AACtB,6CAAkD;AAAzC,wGAAA,aAAa,OAAA;AAEtB,2CAA2C;AAC3C,yBAAyB;AACzB,2CAA2C;AAE3C,yCAAuB;AAEvB,2CAA2C;AAC3C,UAAU;AACV,2CAA2C;AAE3C,mBAAmB;AACnB,6CAK2B;AAJzB,kHAAA,uBAAuB,OAAA;AACvB,gHAAA,qBAAqB,OAAA;AACrB,6GAAA,kBAAkB,OAAA;AAClB,0GAAA,eAAe,OAAA;AAcjB,oBAAoB;AACpB,+CAI4B;AAH1B,oHAAA,wBAAwB,OAAA;AACxB,kHAAA,sBAAsB,OAAA;AACtB,4GAAA,gBAAgB,OAAA;AAalB,UAAU;AACV,6CAK2B;AAJzB,0GAAA,eAAe,OAAA;AACf,gHAAA,qBAAqB,OAAA;AACrB,0GAAA,eAAe,OAAA;AACf,8GAAA,mBAAmB,OAAA;AAmCrB,aAAa;AACb,mDAI8B;AAH5B,gHAAA,kBAAkB,OAAA;AAClB,sHAAA,wBAAwB,OAAA;AACxB,gHAAA,kBAAkB,OAAA;AAWpB,QAAQ;AACR,yCAOyB;AANvB,sGAAA,aAAa,OAAA;AACb,4GAAA,mBAAmB,OAAA;AACnB,sGAAA,aAAa,OAAA;AACb,6GAAA,oBAAoB,OAAA;AACpB,wGAAA,eAAe,OAAA;AACf,2GAAA,kBAAkB,OAAA;AAepB,WAAW;AACX,+CAO4B;AAN1B,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AACtB,+GAAA,mBAAmB,OAAA;AACnB,4GAAA,gBAAgB,OAAA;AAChB,2GAAA,eAAe,OAAA;AACf,gHAAA,oBAAoB,OAAA;AAmBtB,cAAc;AACd,qDAI+B;AAH7B,iHAAA,kBAAkB,OAAA;AAClB,uHAAA,wBAAwB,OAAA;AACxB,iHAAA,kBAAkB,OAAA;AAapB,gBAAgB;AAChB,yDAKiC;AAJ/B,qHAAA,oBAAoB,OAAA;AACpB,oHAAA,mBAAmB,OAAA;AACnB,8HAAA,6BAA6B,OAAA;AAC7B,qHAAA,oBAAoB,OAAA;AAatB,0BAA0B;AAC1B,mDAI8B;AAH5B,gHAAA,kBAAkB,OAAA;AAClB,sHAAA,wBAAwB,OAAA;AACxB,gHAAA,kBAAkB,OAAA;AAiBpB,mDAAwD;AAA/C,8GAAA,gBAAgB,OAAA;AAEzB,eAAe;AACf,6CAK2B;AAJzB,0GAAA,eAAe,OAAA;AACf,gHAAA,qBAAqB,OAAA;AACrB,6GAAA,kBAAkB,OAAA;AAClB,0GAAA,eAAe,OAAA;AAkBjB,aAAa;AACb,mDAG8B;AAF5B,8GAAA,gBAAgB,OAAA;AAChB,sHAAA,wBAAwB,OAAA;AAW1B,gBAAgB;AAChB,2CAS0B;AARxB,sGAAA,YAAY,OAAA;AACZ,wGAAA,cAAc,OAAA;AACd,8GAAA,oBAAoB,OAAA;AACpB,wGAAA,cAAc,OAAA;AACd,yGAAA,eAAe,OAAA;AACf,qGAAA,WAAW,OAAA;AACX,0GAAA,gBAAgB,OAAA;AAChB,4GAAA,kBAAkB,OAAA;AAoBpB,2CAA2C;AAC3C,oEAAoE;AACpE,2CAA2C;AAE3C,iBAAiB;AACjB,6CAkB2B;AAjBzB,0GAAA,eAAe,OAAA;AACf,gHAAA,qBAAqB,OAAA;AACrB,6GAAA,kBAAkB,OAAA;AAClB,0GAAA,eAAe,OAAA;AACf,wGAAA,aAAa,OAAA;AACb,wGAAA,aAAa,OAAA;AACb,6GAAA,kBAAkB,OAAA;AAClB,0GAAA,eAAe,OAAA;AACf,yGAAA,cAAc,OAAA;AACd,uGAAA,YAAY,OAAA;AACZ,wGAAA,aAAa,OAAA;AACb,gGAAA,KAAK,OAAA;AACL,4GAAA,iBAAiB,OAAA;AACjB,sGAAA,WAAW,OAAA;AACX,qBAAqB;AACrB,qGAAA,UAAU,OAAA;AACV,0GAAA,eAAe,OAAA;AAqDjB,2CAA2C;AAC3C,oEAAoE;AACpE,2CAA2C;AAE3C,yCAA6E;AAApE,oGAAA,OAAO,OAAA;AAAE,mGAAA,MAAM,OAAA;AAAE,wGAAA,WAAW,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAEvD,uDAAuD;AACvD,wCAAyE;AAAhE,kGAAA,QAAQ,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAAE,sGAAA,YAAY,OAAA;AAGjD,yDAAyD;AACzD,iDAGiC;AAF/B,iHAAA,wBAAwB,OAAA;AACxB,8GAAA,qBAAqB,OAAA;AASvB,2CAA2C;AAC3C,wCAAwC;AACxC,2CAA2C;AAE3C,2CAAyB;AAEzB,2CAA2C;AAC3C,iDAAiD;AACjD,2CAA2C;AAE3C,8CAA4B;AAE5B,2CAA2C;AAC3C,uCAAuC;AACvC,2CAA2C;AAE3C,4CAA0B;AAE1B,2CAA2C;AAC3C,8CAA8C;AAC9C,2CAA2C;AAE3C,8CAA4B"}

package/dist/promotion/index.d.ts

@@ -0,0 +1,3 @@
+export type { PromotionOpportunity, PromotionTarget, PromotionResult } from './types';
+export { promotionPath } from './promotion';
+//# sourceMappingURL=index.d.ts.map

package/dist/promotion/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/promotion/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGtF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/promotion/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promotionPath = void 0;
+// Core promotion path
+var promotion_1 = require("./promotion");
+Object.defineProperty(exports, "promotionPath", { enumerable: true, get: function () { return promotion_1.promotionPath; } });
+//# sourceMappingURL=index.js.map

package/dist/promotion/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/promotion/index.ts"],"names":[],"mappings":";;;AAGA,sBAAsB;AACtB,yCAA4C;AAAnC,0GAAA,aAAa,OAAA"}

package/dist/promotion/promotion.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Promotion Path — Counterfactual Scoring Analysis
+ *
+ * Analyzes unfired rules in a scoring result to generate ranked,
+ * actionable improvement roadmaps. Given a ruleset, facts, and a
+ * target (tier or score), identifies what scoring opportunities
+ * remain and how much each could contribute.
+ */
+import type { CompiledScoringRuleSet, ScoringOptions, TierDefinition } from '../engines/scoring/types';
+import type { FactInput } from '../core';
+import type { PromotionTarget, PromotionResult } from './types';
+/**
+ * Compute a promotion path — the ranked set of unfired rules that could
+ * close the gap between a current score and a target score or tier.
+ *
+ * @param ruleset - Compiled scoring ruleset to analyze
+ * @param facts - Facts to score against the ruleset
+ * @param target - Target tier or score to reach
+ * @param options - Optional scoring options passed to engine execution
+ * @returns Promotion result with gap analysis and ranked opportunities
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(athleteRuleset, athleteFacts, { tier: 'premium' });
+ *
+ * console.log(`Current: ${path.currentScore} (${path.currentTier})`);
+ * console.log(`Target: ${path.targetScore} (${path.targetTier})`);
+ * console.log(`Gap: ${path.gap} points`);
+ *
+ * for (const opp of path.opportunities) {
+ *   const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+ *   console.log(`  ${opp.ruleId}: ${impact} — ${opp.reason ?? 'no reason'}`);
+ * }
+ * ```
+ */
+export declare function promotionPath<T extends TierDefinition = TierDefinition>(ruleset: CompiledScoringRuleSet<T>, facts: FactInput[], target: PromotionTarget, options?: ScoringOptions): PromotionResult<T>;
+//# sourceMappingURL=promotion.d.ts.map

package/dist/promotion/promotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion.d.ts","sourceRoot":"","sources":["../../src/promotion/promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,sBAAsB,EACtB,cAAc,EACd,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAwB,MAAM,SAAS,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACrE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAClC,KAAK,EAAE,SAAS,EAAE,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAAC,CAAC,CAAC,CAmGpB"}

package/dist/promotion/promotion.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Promotion Path — Counterfactual Scoring Analysis
+ *
+ * Analyzes unfired rules in a scoring result to generate ranked,
+ * actionable improvement roadmaps. Given a ruleset, facts, and a
+ * target (tier or score), identifies what scoring opportunities
+ * remain and how much each could contribute.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promotionPath = promotionPath;
+const engine_1 = require("../engines/scoring/engine");
+/**
+ * Compute a promotion path — the ranked set of unfired rules that could
+ * close the gap between a current score and a target score or tier.
+ *
+ * @param ruleset - Compiled scoring ruleset to analyze
+ * @param facts - Facts to score against the ruleset
+ * @param target - Target tier or score to reach
+ * @param options - Optional scoring options passed to engine execution
+ * @returns Promotion result with gap analysis and ranked opportunities
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(athleteRuleset, athleteFacts, { tier: 'premium' });
+ *
+ * console.log(`Current: ${path.currentScore} (${path.currentTier})`);
+ * console.log(`Target: ${path.targetScore} (${path.targetTier})`);
+ * console.log(`Gap: ${path.gap} points`);
+ *
+ * for (const opp of path.opportunities) {
+ *   const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+ *   console.log(`  ${opp.ruleId}: ${impact} — ${opp.reason ?? 'no reason'}`);
+ * }
+ * ```
+ */
+function promotionPath(ruleset, facts, target, options = {}) {
+    const start = performance.now();
+    // 1. Execute scoring engine
+    const engine = new engine_1.ScoringEngine();
+    for (const fact of facts) {
+        engine.add(fact);
+    }
+    const result = engine.execute(ruleset, options);
+    // 2. Resolve target score
+    let targetScore;
+    let targetTier;
+    if ('tier' in target && target.tier !== undefined) {
+        targetTier = target.tier;
+        const tiers = ruleset.config.tiers;
+        if (!tiers || tiers.length === 0) {
+            throw new Error(`Cannot target tier "${target.tier}": no tiers configured in ruleset`);
+        }
+        const tierDef = tiers.find(t => t.id === target.tier);
+        if (!tierDef) {
+            const available = tiers.map(t => t.id).join(', ');
+            throw new Error(`Tier "${target.tier}" not found. Available: ${available}`);
+        }
+        const threshold = tierDef.threshold;
+        targetScore = threshold === '-Infinity' ? 0 : threshold;
+    }
+    else {
+        targetScore = target.score;
+    }
+    // 3. Compute gap
+    const currentScore = result.totalScore;
+    const gap = Math.max(0, targetScore - currentScore);
+    const alreadyMet = currentScore >= targetScore;
+    // 4. Identify unfired rules and extract opportunities
+    const firedSet = new Set(result.fired);
+    const opportunities = [];
+    for (const rule of ruleset.rules) {
+        if (firedSet.has(rule.id))
+            continue;
+        const score = rule.action.score;
+        const weight = rule.action.weight ?? 1;
+        let potentialScore;
+        let dynamic;
+        if (typeof score === 'number') {
+            potentialScore = score * weight;
+            dynamic = false;
+        }
+        else {
+            // string (function name) or CompiledCondition (expression)
+            potentialScore = null;
+            dynamic = true;
+        }
+        opportunities.push({
+            ruleId: rule.id,
+            ruleName: rule.name,
+            category: rule.category,
+            potentialScore,
+            reason: rule.action.reason,
+            dynamic,
+        });
+    }
+    // 5. Sort: static scores descending, dynamic (nulls) at end
+    opportunities.sort((a, b) => {
+        if (a.potentialScore !== null && b.potentialScore !== null) {
+            return b.potentialScore - a.potentialScore;
+        }
+        if (a.potentialScore !== null)
+            return -1;
+        if (b.potentialScore !== null)
+            return 1;
+        return 0;
+    });
+    // 6. Sum static recoverable scores
+    let totalRecoverable = 0;
+    for (const opp of opportunities) {
+        if (opp.potentialScore !== null) {
+            totalRecoverable += opp.potentialScore;
+        }
+    }
+    const executionTimeMs = performance.now() - start;
+    return {
+        currentScore,
+        currentTier: result.tier?.id,
+        targetScore,
+        targetTier,
+        gap,
+        alreadyMet,
+        opportunities,
+        totalRecoverable,
+        result,
+        executionTimeMs,
+    };
+}
+//# sourceMappingURL=promotion.js.map

package/dist/promotion/promotion.js.map

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

package/dist/promotion/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Promotion Path Types
+ *
+ * Types for counterfactual scoring analysis — identifying unfired rules
+ * and ranking them by potential impact to generate promotion roadmaps.
+ */
+import type { ScoringResult, TierDefinition } from '../engines/scoring/types';
+/** A single unfired rule representing a scoring opportunity */
+export type PromotionOpportunity = {
+    ruleId: string;
+    ruleName?: string;
+    category?: string;
+    potentialScore: number | null;
+    reason?: string;
+    dynamic: boolean;
+};
+/** Target specification — reach a tier or a raw score threshold */
+export type PromotionTarget = {
+    tier: string;
+    score?: never;
+} | {
+    score: number;
+    tier?: never;
+};
+/** Promotion path result */
+export type PromotionResult<T extends TierDefinition = TierDefinition> = {
+    currentScore: number;
+    currentTier?: string;
+    targetScore: number;
+    targetTier?: string;
+    gap: number;
+    alreadyMet: boolean;
+    opportunities: PromotionOpportunity[];
+    totalRecoverable: number;
+    result: ScoringResult<T>;
+    executionTimeMs: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/promotion/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/promotion/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpC,4BAA4B;AAC5B,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,oBAAoB,EAAE,CAAC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC"}

package/dist/promotion/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Promotion Path Types
+ *
+ * Types for counterfactual scoring analysis — identifying unfired rules
+ * and ranking them by potential impact to generate promotion roadmaps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/promotion/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higher.archi/boe",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "A multi-strategy rule engine supporting forward chaining, backward chaining, scoring, sequential, fuzzy logic, and Bayesian inference",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/compare/compare.ts

@@ -0,0 +1,106 @@
+/**
+ * Ruleset Comparison Utility
+ *
+ * Scores a set of entities against two rulesets and computes per-entity
+ * deltas and aggregate tier migration statistics. Designed for preview/dry-run
+ * workflows where a draft config is compared against the active config
+ * before activation.
+ */
+
+import { ScoringEngine } from '../engines/scoring/engine';
+import type { CompiledScoringRuleSet, ScoringOptions, TierDefinition } from '../engines/scoring/types';
+import type { CompareInput, EntityDelta, ComparisonResult } from './types';
+
+/**
+ * Compare two scoring rulesets by executing both against the same inputs.
+ *
+ * For each input, creates a fresh ScoringEngine, adds the facts, and executes
+ * against both rulesets. Returns per-entity deltas and aggregate statistics
+ * including tier migration counts.
+ *
+ * @param rulesetA - The baseline ruleset (e.g. active/current config)
+ * @param rulesetB - The candidate ruleset (e.g. draft/proposed config)
+ * @param inputs - Entity fact sets to score with both rulesets
+ * @param options - Optional scoring options passed to both executions
+ * @returns Comparison result with per-entity deltas and summary statistics
+ *
+ * @example
+ * ```typescript
+ * const result = compareRulesets(activeRuleset, draftRuleset, [
+ *   { entityId: 'user-1', facts: [{ type: 'User', data: { score: 750 } }] },
+ *   { entityId: 'user-2', facts: [{ type: 'User', data: { score: 620 } }] },
+ * ]);
+ *
+ * console.log(`Avg score delta: ${result.summary.avgScoreDelta}`);
+ * console.log(`Tier changes: ${result.summary.tierChanges}`);
+ * console.log(`Migrations:`, result.summary.tierMigrations);
+ * ```
+ */
+export function compareRulesets<T extends TierDefinition = TierDefinition>(
+  rulesetA: CompiledScoringRuleSet<T>,
+  rulesetB: CompiledScoringRuleSet<T>,
+  inputs: CompareInput[],
+  options: ScoringOptions = {}
+): ComparisonResult<T> {
+  const deltas: EntityDelta<T>[] = [];
+
+  for (const input of inputs) {
+    const engineA = new ScoringEngine();
+    for (const fact of input.facts) {
+      engineA.add(fact);
+    }
+    const resultA = engineA.execute(rulesetA, options);
+
+    const engineB = new ScoringEngine();
+    for (const fact of input.facts) {
+      engineB.add(fact);
+    }
+    const resultB = engineB.execute(rulesetB, options);
+
+    deltas.push({
+      entityId: input.entityId,
+      scoreA: resultA.totalScore,
+      scoreB: resultB.totalScore,
+      scoreDelta: resultB.totalScore - resultA.totalScore,
+      tierA: resultA.tier?.id,
+      tierB: resultB.tier?.id,
+      tierChanged: resultA.tier?.id !== resultB.tier?.id,
+      resultA,
+      resultB,
+    });
+  }
+
+  // Compute summary
+  const entityCount = deltas.length;
+  let sumDelta = 0;
+  let minDelta = Infinity;
+  let maxDelta = -Infinity;
+  let tierChanges = 0;
+  const tierMigrations: Record<string, Record<string, number>> = {};
+
+  for (const d of deltas) {
+    sumDelta += d.scoreDelta;
+    if (d.scoreDelta < minDelta) minDelta = d.scoreDelta;
+    if (d.scoreDelta > maxDelta) maxDelta = d.scoreDelta;
+
+    if (d.tierChanged) {
+      tierChanges++;
+      const from = d.tierA ?? '(none)';
+      const to = d.tierB ?? '(none)';
+      if (!tierMigrations[from]) tierMigrations[from] = {};
+      tierMigrations[from][to] = (tierMigrations[from][to] ?? 0) + 1;
+    }
+  }
+
+  return {
+    deltas,
+    summary: {
+      entityCount,
+      avgScoreDelta: entityCount > 0 ? sumDelta / entityCount : 0,
+      minScoreDelta: entityCount > 0 ? minDelta : 0,
+      maxScoreDelta: entityCount > 0 ? maxDelta : 0,
+      tierChanges,
+      tierMigrations,
+    },
+  };
+}

package/src/compare/index.ts

@@ -0,0 +1,5 @@
+// Types
+export type { CompareInput, EntityDelta, ComparisonResult } from './types';
+
+// Core comparison
+export { compareRulesets } from './compare';

package/src/compare/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Compare Module Types
+ *
+ * Types for scoring ruleset comparison — computing per-entity score deltas
+ * and tier migration statistics between two rulesets.
+ */
+
+import type { ScoringResult, TierDefinition } from '../engines/scoring/types';
+import type { FactInput } from '../core';
+
+/** A single test case: a set of facts to score with both rulesets */
+export type CompareInput = {
+  entityId: string;
+  facts: FactInput[];
+};
+
+/** Per-entity diff between ruleset A and B results */
+export type EntityDelta<T extends TierDefinition = TierDefinition> = {
+  entityId: string;
+  scoreA: number;
+  scoreB: number;
+  scoreDelta: number;
+  tierA?: string;
+  tierB?: string;
+  tierChanged: boolean;
+  resultA: ScoringResult<T>;
+  resultB: ScoringResult<T>;
+};
+
+/** Aggregate comparison result */
+export type ComparisonResult<T extends TierDefinition = TierDefinition> = {
+  deltas: EntityDelta<T>[];
+  summary: {
+    entityCount: number;
+    avgScoreDelta: number;
+    minScoreDelta: number;
+    maxScoreDelta: number;
+    tierChanges: number;
+    tierMigrations: Record<string, Record<string, number>>;
+  };
+};

package/src/index.ts

@@ -412,3 +412,15 @@ export * from './qfacts';
 // ========================================
 
 export * from './abtesting';
+
+// ========================================
+// Compare - Ruleset Comparison Utility
+// ========================================
+
+export * from './compare';
+
+// ========================================
+// Promotion — Counterfactual Scoring Analysis
+// ========================================
+
+export * from './promotion';

package/src/promotion/index.ts

@@ -0,0 +1,5 @@
+// Types
+export type { PromotionOpportunity, PromotionTarget, PromotionResult } from './types';
+
+// Core promotion path
+export { promotionPath } from './promotion';

package/src/promotion/promotion.ts

@@ -0,0 +1,147 @@
+/**
+ * Promotion Path — Counterfactual Scoring Analysis
+ *
+ * Analyzes unfired rules in a scoring result to generate ranked,
+ * actionable improvement roadmaps. Given a ruleset, facts, and a
+ * target (tier or score), identifies what scoring opportunities
+ * remain and how much each could contribute.
+ */
+
+import { ScoringEngine } from '../engines/scoring/engine';
+import type {
+  CompiledScoringRuleSet,
+  ScoringOptions,
+  TierDefinition
+} from '../engines/scoring/types';
+import type { FactInput } from '../core';
+import type { PromotionTarget, PromotionResult, PromotionOpportunity } from './types';
+
+/**
+ * Compute a promotion path — the ranked set of unfired rules that could
+ * close the gap between a current score and a target score or tier.
+ *
+ * @param ruleset - Compiled scoring ruleset to analyze
+ * @param facts - Facts to score against the ruleset
+ * @param target - Target tier or score to reach
+ * @param options - Optional scoring options passed to engine execution
+ * @returns Promotion result with gap analysis and ranked opportunities
+ *
+ * @example
+ * ```typescript
+ * const path = promotionPath(athleteRuleset, athleteFacts, { tier: 'premium' });
+ *
+ * console.log(`Current: ${path.currentScore} (${path.currentTier})`);
+ * console.log(`Target: ${path.targetScore} (${path.targetTier})`);
+ * console.log(`Gap: ${path.gap} points`);
+ *
+ * for (const opp of path.opportunities) {
+ *   const impact = opp.dynamic ? 'variable' : `+${opp.potentialScore}`;
+ *   console.log(`  ${opp.ruleId}: ${impact} — ${opp.reason ?? 'no reason'}`);
+ * }
+ * ```
+ */
+export function promotionPath<T extends TierDefinition = TierDefinition>(
+  ruleset: CompiledScoringRuleSet<T>,
+  facts: FactInput[],
+  target: PromotionTarget,
+  options: ScoringOptions = {}
+): PromotionResult<T> {
+  const start = performance.now();
+
+  // 1. Execute scoring engine
+  const engine = new ScoringEngine();
+  for (const fact of facts) {
+    engine.add(fact);
+  }
+  const result = engine.execute(ruleset, options);
+
+  // 2. Resolve target score
+  let targetScore: number;
+  let targetTier: string | undefined;
+
+  if ('tier' in target && target.tier !== undefined) {
+    targetTier = target.tier;
+    const tiers = ruleset.config.tiers;
+    if (!tiers || tiers.length === 0) {
+      throw new Error(`Cannot target tier "${target.tier}": no tiers configured in ruleset`);
+    }
+    const tierDef = tiers.find(t => t.id === target.tier);
+    if (!tierDef) {
+      const available = tiers.map(t => t.id).join(', ');
+      throw new Error(`Tier "${target.tier}" not found. Available: ${available}`);
+    }
+    const threshold = tierDef.threshold;
+    targetScore = threshold === '-Infinity' ? 0 : threshold;
+  } else {
+    targetScore = target.score;
+  }
+
+  // 3. Compute gap
+  const currentScore = result.totalScore;
+  const gap = Math.max(0, targetScore - currentScore);
+  const alreadyMet = currentScore >= targetScore;
+
+  // 4. Identify unfired rules and extract opportunities
+  const firedSet = new Set(result.fired);
+  const opportunities: PromotionOpportunity[] = [];
+
+  for (const rule of ruleset.rules) {
+    if (firedSet.has(rule.id)) continue;
+
+    const score = rule.action.score;
+    const weight = rule.action.weight ?? 1;
+    let potentialScore: number | null;
+    let dynamic: boolean;
+
+    if (typeof score === 'number') {
+      potentialScore = score * weight;
+      dynamic = false;
+    } else {
+      // string (function name) or CompiledCondition (expression)
+      potentialScore = null;
+      dynamic = true;
+    }
+
+    opportunities.push({
+      ruleId: rule.id,
+      ruleName: rule.name,
+      category: rule.category,
+      potentialScore,
+      reason: rule.action.reason,
+      dynamic,
+    });
+  }
+
+  // 5. Sort: static scores descending, dynamic (nulls) at end
+  opportunities.sort((a, b) => {
+    if (a.potentialScore !== null && b.potentialScore !== null) {
+      return b.potentialScore - a.potentialScore;
+    }
+    if (a.potentialScore !== null) return -1;
+    if (b.potentialScore !== null) return 1;
+    return 0;
+  });
+
+  // 6. Sum static recoverable scores
+  let totalRecoverable = 0;
+  for (const opp of opportunities) {
+    if (opp.potentialScore !== null) {
+      totalRecoverable += opp.potentialScore;
+    }
+  }
+
+  const executionTimeMs = performance.now() - start;
+
+  return {
+    currentScore,
+    currentTier: result.tier?.id,
+    targetScore,
+    targetTier,
+    gap,
+    alreadyMet,
+    opportunities,
+    totalRecoverable,
+    result,
+    executionTimeMs,
+  };
+}

package/src/promotion/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Promotion Path Types
+ *
+ * Types for counterfactual scoring analysis — identifying unfired rules
+ * and ranking them by potential impact to generate promotion roadmaps.
+ */
+
+import type { ScoringResult, TierDefinition } from '../engines/scoring/types';
+
+/** A single unfired rule representing a scoring opportunity */
+export type PromotionOpportunity = {
+  ruleId: string;
+  ruleName?: string;
+  category?: string;
+  potentialScore: number | null;  // null = dynamic (expression/function)
+  reason?: string;                // from ScoringAction.reason
+  dynamic: boolean;               // true if score is expression/function
+};
+
+/** Target specification — reach a tier or a raw score threshold */
+export type PromotionTarget =
+  | { tier: string; score?: never }
+  | { score: number; tier?: never };
+
+/** Promotion path result */
+export type PromotionResult<T extends TierDefinition = TierDefinition> = {
+  currentScore: number;
+  currentTier?: string;
+  targetScore: number;            // resolved threshold of target tier, or explicit score
+  targetTier?: string;
+  gap: number;                    // targetScore - currentScore (0 if already met)
+  alreadyMet: boolean;            // true if current score/tier already meets target
+  opportunities: PromotionOpportunity[];  // ranked by potentialScore desc (nulls last)
+  totalRecoverable: number;       // sum of all static potentialScores
+  result: ScoringResult<T>;       // the full scoring result for reference
+  executionTimeMs: number;
+};