@higher.archi/boe 1.0.0

package/dist/engines/monte-carlo/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Monte Carlo Engine Types
+ *
+ * Provides uncertainty quantification through random sampling.
+ * Run thousands of simulations with probabilistic inputs to get
+ * statistical distributions of possible outcomes.
+ */
+import { BaseRuleSet, CompiledBaseRuleSet, CompiledCondition, InputParameter, CompiledInputParameter, Expression, Condition } from '../../core';
+/**
+ * Iteration presets for Monte Carlo simulations.
+ *
+ * Monte Carlo error follows: Error ∝ 1/√n
+ *
+ * | Preset   | Iterations | Relative Error | Use Case                      |
+ * |----------|------------|----------------|-------------------------------|
+ * | quick    | 2,500      | 2.00%          | Development, quick estimates  |
+ * | standard | 5,000      | 1.41%          | Production default            |
+ * | precise  | 10,000     | 1.00%          | Final reports, tail analysis  |
+ *
+ * Why cap at 10,000? Diminishing returns:
+ * - 50k iterations: only ~2.2x more accurate than 10k, but 5x slower
+ * - To halve the error, must quadruple iterations
+ */
+export declare const ITERATIONS_QUICK = 2500;
+export declare const ITERATIONS_STANDARD = 5000;
+export declare const ITERATIONS_PRECISE = 10000;
+export declare const ITERATIONS_MIN = 2500;
+export declare const ITERATIONS_MAX = 10000;
+export declare const ITERATIONS_DEFAULT = 5000;
+export type IterationPreset = 'quick' | 'standard' | 'precise';
+export declare const ITERATION_PRESETS: Record<IterationPreset, number>;
+/**
+ * Estimate type determines the probability distribution shape.
+ * Multiple aliases supported for different audiences.
+ */
+export type EstimateType = 'best-likely-worst' | 'low-mid-high' | 'min-expected-max' | 'optimistic-realistic-pessimistic' | 'typically-around' | 'bell-curve' | 'normal' | 'anywhere-from' | 'uniform' | 'any-between' | 'one-of' | 'weighted' | 'choice';
+/**
+ * Percent or number value
+ * Strings ending in '%' are parsed: '50%' -> 0.50
+ */
+export type PercentOrNumber = number | string;
+/**
+ * Triangular distribution variable (three-point estimate)
+ */
+export type TriangularVariable = {
+    name: string;
+    estimate: 'best-likely-worst' | 'low-mid-high' | 'min-expected-max' | 'optimistic-realistic-pessimistic';
+} & ({
+    best: PercentOrNumber;
+    likely: PercentOrNumber;
+    worst: PercentOrNumber;
+} | {
+    low: PercentOrNumber;
+    mid: PercentOrNumber;
+    high: PercentOrNumber;
+} | {
+    min: PercentOrNumber;
+    expected: PercentOrNumber;
+    max: PercentOrNumber;
+} | {
+    optimistic: PercentOrNumber;
+    realistic: PercentOrNumber;
+    pessimistic: PercentOrNumber;
+});
+/**
+ * Normal distribution variable (bell curve)
+ */
+export type NormalVariable = {
+    name: string;
+    estimate: 'typically-around' | 'bell-curve' | 'normal';
+    value?: PercentOrNumber;
+    mean?: PercentOrNumber;
+    varies?: PercentOrNumber;
+    spread?: PercentOrNumber;
+    stdDev?: PercentOrNumber;
+};
+/**
+ * Uniform distribution variable (equal probability in range)
+ */
+export type UniformVariable = {
+    name: string;
+    estimate: 'anywhere-from' | 'uniform' | 'any-between';
+    low?: PercentOrNumber;
+    high?: PercentOrNumber;
+    min?: PercentOrNumber;
+    max?: PercentOrNumber;
+};
+/**
+ * Discrete distribution variable (weighted choices)
+ */
+export type DiscreteVariable = {
+    name: string;
+    estimate: 'one-of' | 'weighted' | 'choice';
+    options: number[];
+    weights?: number[];
+};
+/**
+ * Union of all variable types
+ */
+export type MonteCarloVariable = TriangularVariable | NormalVariable | UniformVariable | DiscreteVariable;
+/**
+ * Output definition - computed value tracked across simulations
+ */
+export type MonteCarloOutput = {
+    name: string;
+    formula: Expression;
+};
+/**
+ * Monte Carlo ruleset - defines inputs, variables, and outputs
+ */
+export type MonteCarloRuleSet = BaseRuleSet & {
+    mode: 'monte-carlo';
+    iterations?: number | IterationPreset;
+    inputs?: InputParameter[];
+    variables: MonteCarloVariable[];
+    outputs: MonteCarloOutput[];
+    config?: Partial<MonteCarloConfig>;
+};
+/**
+ * Monte Carlo configuration
+ */
+export type MonteCarloConfig = {
+    mode: 'monte-carlo';
+    iterations: number;
+    seed?: number;
+    percentiles?: number[];
+    includeSensitivity?: boolean;
+};
+/**
+ * Normalized variable (all aliases resolved to canonical form)
+ */
+export type CompiledVariable = {
+    name: string;
+    distribution: 'triangular' | 'normal' | 'uniform' | 'discrete';
+    params: {
+        min?: number;
+        mode?: number;
+        max?: number;
+        mean?: number;
+        stdDev?: number;
+        options?: number[];
+        weights?: number[];
+    };
+};
+/**
+ * Context for formula evaluation - flat key-value lookup
+ */
+export type FormulaContext = Record<string, number>;
+/**
+ * Pre-compiled formula function for fast evaluation
+ */
+export type CompiledFormulaFn = (ctx: FormulaContext) => number;
+/**
+ * Compiled output
+ */
+export type CompiledOutput = {
+    name: string;
+    formula: CompiledCondition;
+    evaluate?: CompiledFormulaFn;
+};
+/**
+ * Compiled Monte Carlo ruleset
+ */
+export type CompiledMonteCarloRuleSet = CompiledBaseRuleSet & {
+    mode: 'monte-carlo';
+    inputs: CompiledInputParameter[];
+    variables: CompiledVariable[];
+    outputs: CompiledOutput[];
+    config: MonteCarloConfig;
+};
+/**
+ * Runtime options for simulation
+ */
+export type MonteCarloOptions = {
+    onIteration?: (iteration: number, values: Record<string, number>) => void;
+    onProgress?: (percent: number) => void;
+};
+/**
+ * Statistics for a single output variable
+ */
+export type OutputStatistics = {
+    mean: number;
+    median: number;
+    stdDev: number;
+    min: number;
+    max: number;
+    percentiles: Record<string, number>;
+    histogram: HistogramBin[];
+};
+/**
+ * Histogram bin
+ */
+export type HistogramBin = {
+    min: number;
+    max: number;
+    count: number;
+    probability: number;
+};
+/**
+ * Sensitivity analysis result
+ */
+export type SensitivityAnalysis = {
+    [outputName: string]: {
+        [variableName: string]: number;
+    };
+};
+/**
+ * Execution result
+ */
+export type MonteCarloResult = {
+    iterations: number;
+    outputs: Record<string, OutputStatistics>;
+    sensitivity: SensitivityAnalysis;
+    executionTimeMs: number;
+    /**
+     * Helper method for probability queries
+     *
+     * Accepts array condition: ['greaterThan', '$totalCost', 500000]
+     *
+     * Examples:
+     *   probability(['greaterThan', '$totalCost', 500000])
+     *   probability(['and', ['lessThan', '$weeks', 10], ['lessThanOrEquals', '$budget', 100000]])
+     */
+    probability: (query: Condition) => number;
+    rawData?: {
+        variables: Record<string, number[]>;
+        outputs: Record<string, number[]>;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/engines/monte-carlo/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engines/monte-carlo/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,eAAO,MAAM,cAAc,OAAmB,CAAC;AAC/C,eAAO,MAAM,cAAc,QAAqB,CAAC;AACjD,eAAO,MAAM,kBAAkB,OAAsB,CAAC;AAEtD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAI7D,CAAC;AAMF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAEpB,mBAAmB,GACnB,cAAc,GACd,kBAAkB,GAClB,kCAAkC,GAGlC,kBAAkB,GAClB,YAAY,GACZ,QAAQ,GAGR,eAAe,GACf,SAAS,GACT,aAAa,GAGb,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAMb;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,mBAAmB,GAAG,cAAc,GAAG,kBAAkB,GAAG,kCAAkC,CAAC;CAC1G,GAAG,CACA;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GAC1E;IAAE,GAAG,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACrE;IAAE,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,eAAe,CAAA;CAAE,GACzE;IAAE,UAAU,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,eAAe,CAAA;CAAE,CAC5F,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,GAAG,YAAY,GAAG,QAAQ,CAAC;IACvD,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC;IACtD,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,kBAAkB,GAClB,cAAc,GACd,eAAe,GACf,gBAAgB,CAAC;AAMrB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;CACrB,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAGtC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAG1B,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAGhC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAE5B,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IAC/D,MAAM,EAAE;QAEN,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QAEb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GAAG;IAC5D,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IAC1E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;KAChC,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,WAAW,EAAE,mBAAmB,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;IAG1C,OAAO,CAAC,EAAE;QACR,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;KACnC,CAAC;CACH,CAAC"}

package/dist/engines/monte-carlo/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Monte Carlo Engine Types
+ *
+ * Provides uncertainty quantification through random sampling.
+ * Run thousands of simulations with probabilistic inputs to get
+ * statistical distributions of possible outcomes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ITERATION_PRESETS = exports.ITERATIONS_DEFAULT = exports.ITERATIONS_MAX = exports.ITERATIONS_MIN = exports.ITERATIONS_PRECISE = exports.ITERATIONS_STANDARD = exports.ITERATIONS_QUICK = void 0;
+// ========================================
+// Iteration Presets & Constants
+// ========================================
+/**
+ * Iteration presets for Monte Carlo simulations.
+ *
+ * Monte Carlo error follows: Error ∝ 1/√n
+ *
+ * | Preset   | Iterations | Relative Error | Use Case                      |
+ * |----------|------------|----------------|-------------------------------|
+ * | quick    | 2,500      | 2.00%          | Development, quick estimates  |
+ * | standard | 5,000      | 1.41%          | Production default            |
+ * | precise  | 10,000     | 1.00%          | Final reports, tail analysis  |
+ *
+ * Why cap at 10,000? Diminishing returns:
+ * - 50k iterations: only ~2.2x more accurate than 10k, but 5x slower
+ * - To halve the error, must quadruple iterations
+ */
+exports.ITERATIONS_QUICK = 2500;
+exports.ITERATIONS_STANDARD = 5000;
+exports.ITERATIONS_PRECISE = 10000;
+exports.ITERATIONS_MIN = exports.ITERATIONS_QUICK;
+exports.ITERATIONS_MAX = exports.ITERATIONS_PRECISE;
+exports.ITERATIONS_DEFAULT = exports.ITERATIONS_STANDARD;
+exports.ITERATION_PRESETS = {
+    quick: exports.ITERATIONS_QUICK,
+    standard: exports.ITERATIONS_STANDARD,
+    precise: exports.ITERATIONS_PRECISE
+};
+//# sourceMappingURL=types.js.map

package/dist/engines/monte-carlo/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engines/monte-carlo/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAYH,2CAA2C;AAC3C,gCAAgC;AAChC,2CAA2C;AAE3C;;;;;;;;;;;;;;GAcG;AACU,QAAA,gBAAgB,GAAG,IAAI,CAAC;AACxB,QAAA,mBAAmB,GAAG,IAAI,CAAC;AAC3B,QAAA,kBAAkB,GAAG,KAAK,CAAC;AAE3B,QAAA,cAAc,GAAG,wBAAgB,CAAC;AAClC,QAAA,cAAc,GAAG,0BAAkB,CAAC;AACpC,QAAA,kBAAkB,GAAG,2BAAmB,CAAC;AAIzC,QAAA,iBAAiB,GAAoC;IAChE,KAAK,EAAE,wBAAgB;IACvB,QAAQ,EAAE,2BAAmB;IAC7B,OAAO,EAAE,0BAAkB;CAC5B,CAAC"}

package/dist/engines/pricing/calculator.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Pricing Calculator Utilities
+ *
+ * Core calculation functions for different pricing modes:
+ * - Flat: Simple quantity * price
+ * - Graduated: Each tier priced separately
+ * - Volume: Total volume determines single rate for all units
+ */
+import { TierBreakdown, CompiledGraduatedTier, CompiledVolumeBracket } from './types';
+import { CompiledOperand } from '../../core';
+/**
+ * Context for resolving operand values.
+ */
+export type CalculatorContext = {
+    /** Resolve a compiled operand to its value */
+    resolve: (operand: CompiledOperand) => number;
+};
+/**
+ * Result from a tier calculation.
+ */
+export type TierCalculationResult = {
+    /** Total calculated price */
+    total: number;
+    /** Breakdown by tier */
+    breakdown: TierBreakdown[];
+};
+/**
+ * Calculate flat pricing.
+ *
+ * @param quantity - Number of units
+ * @param pricePerUnit - Price per unit operand
+ * @param context - Context for resolving operands
+ * @returns Calculation result
+ */
+export declare function calculateFlat(quantity: number, pricePerUnit: CompiledOperand, context: CalculatorContext): TierCalculationResult;
+/**
+ * Calculate graduated pricing.
+ *
+ * In graduated pricing, each tier applies only to units within its range.
+ * Example: First 1M at $0.20, next 4M at $0.10
+ * For 3M units: (1M * $0.20) + (2M * $0.10) = $400
+ *
+ * @param quantity - Total number of units
+ * @param tiers - Graduated tiers (must be sorted by upTo ascending)
+ * @param context - Context for resolving operands
+ * @returns Calculation result with breakdown
+ */
+export declare function calculateGraduated(quantity: number, tiers: CompiledGraduatedTier[], context: CalculatorContext): TierCalculationResult;
+/**
+ * Calculate volume pricing.
+ *
+ * In volume pricing, total volume determines a single rate applied to ALL units.
+ * Example: <1M at $0.20, 1M-5M at $0.15, >5M at $0.10
+ * For 3M units: 3M * $0.15 = $450 (single rate)
+ *
+ * @param quantity - Total number of units
+ * @param brackets - Volume brackets (must be sorted by minVolume ascending)
+ * @param context - Context for resolving operands
+ * @returns Calculation result
+ */
+export declare function calculateVolume(quantity: number, brackets: CompiledVolumeBracket[], context: CalculatorContext): TierCalculationResult;
+/**
+ * Format a number with thousands separators.
+ */
+export declare function formatNumber(n: number): string;
+/**
+ * Format currency value.
+ */
+export declare function formatCurrency(value: number, currency?: string, precision?: number): string;
+/**
+ * Format percentage value.
+ */
+export declare function formatPercent(value: number, precision?: number): string;
+/**
+ * Round to specified precision.
+ */
+export declare function round(value: number, precision: number): number;
+/**
+ * Calculate discount amount.
+ *
+ * @param total - Base amount
+ * @param percent - Percentage discount (0-100)
+ * @param fixedAmount - Fixed amount discount
+ * @returns Discount amount (positive value to subtract)
+ */
+export declare function calculateDiscount(total: number, percent?: number, fixedAmount?: number): number;
+/**
+ * Apply minimum/maximum caps.
+ *
+ * @param value - Current value
+ * @param min - Minimum value (optional)
+ * @param max - Maximum value (optional)
+ * @returns Capped value
+ */
+export declare function applyMinMax(value: number, min?: number, max?: number): {
+    value: number;
+    adjustment: number;
+    type?: 'minimum' | 'maximum';
+};
+//# sourceMappingURL=calculator.d.ts.map

package/dist/engines/pricing/calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.d.ts","sourceRoot":"","sources":["../../../src/engines/pricing/calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAC;CAC/C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,eAAe,EAC7B,OAAO,EAAE,iBAAiB,GACzB,qBAAqB,CAcvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,qBAAqB,EAAE,EAC9B,OAAO,EAAE,iBAAiB,GACzB,qBAAqB,CAyCvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,qBAAqB,EAAE,EACjC,OAAO,EAAE,iBAAiB,GACzB,qBAAqB,CAkCvB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAc,EACxB,SAAS,GAAE,MAAU,GACpB,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAU,GAAG,MAAM,CAE1E;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAaR;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,CAkBrE"}

package/dist/engines/pricing/calculator.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Pricing Calculator Utilities
+ *
+ * Core calculation functions for different pricing modes:
+ * - Flat: Simple quantity * price
+ * - Graduated: Each tier priced separately
+ * - Volume: Total volume determines single rate for all units
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateFlat = calculateFlat;
+exports.calculateGraduated = calculateGraduated;
+exports.calculateVolume = calculateVolume;
+exports.formatNumber = formatNumber;
+exports.formatCurrency = formatCurrency;
+exports.formatPercent = formatPercent;
+exports.round = round;
+exports.calculateDiscount = calculateDiscount;
+exports.applyMinMax = applyMinMax;
+/**
+ * Calculate flat pricing.
+ *
+ * @param quantity - Number of units
+ * @param pricePerUnit - Price per unit operand
+ * @param context - Context for resolving operands
+ * @returns Calculation result
+ */
+function calculateFlat(quantity, pricePerUnit, context) {
+    const rate = context.resolve(pricePerUnit);
+    const total = quantity * rate;
+    return {
+        total,
+        breakdown: [{
+                tier: 'Flat',
+                range: `All units`,
+                units: quantity,
+                rate,
+                subtotal: total
+            }]
+    };
+}
+/**
+ * Calculate graduated pricing.
+ *
+ * In graduated pricing, each tier applies only to units within its range.
+ * Example: First 1M at $0.20, next 4M at $0.10
+ * For 3M units: (1M * $0.20) + (2M * $0.10) = $400
+ *
+ * @param quantity - Total number of units
+ * @param tiers - Graduated tiers (must be sorted by upTo ascending)
+ * @param context - Context for resolving operands
+ * @returns Calculation result with breakdown
+ */
+function calculateGraduated(quantity, tiers, context) {
+    const breakdown = [];
+    let remaining = quantity;
+    let total = 0;
+    let previousUpTo = 0;
+    for (let i = 0; i < tiers.length && remaining > 0; i++) {
+        const tier = tiers[i];
+        const rate = context.resolve(tier.pricePerUnit);
+        // Calculate units in this tier
+        const tierCapacity = tier.upTo === Infinity
+            ? remaining
+            : tier.upTo - previousUpTo;
+        const unitsInTier = Math.min(remaining, tierCapacity);
+        if (unitsInTier > 0) {
+            const subtotal = unitsInTier * rate;
+            total += subtotal;
+            // Format range string
+            const rangeStart = formatNumber(previousUpTo + 1);
+            const rangeEnd = tier.upTo === Infinity
+                ? 'Unlimited'
+                : formatNumber(tier.upTo);
+            breakdown.push({
+                tier: `Tier ${i + 1}`,
+                range: `${rangeStart} - ${rangeEnd}`,
+                units: unitsInTier,
+                rate,
+                subtotal
+            });
+            remaining -= unitsInTier;
+        }
+        previousUpTo = tier.upTo;
+    }
+    return { total, breakdown };
+}
+/**
+ * Calculate volume pricing.
+ *
+ * In volume pricing, total volume determines a single rate applied to ALL units.
+ * Example: <1M at $0.20, 1M-5M at $0.15, >5M at $0.10
+ * For 3M units: 3M * $0.15 = $450 (single rate)
+ *
+ * @param quantity - Total number of units
+ * @param brackets - Volume brackets (must be sorted by minVolume ascending)
+ * @param context - Context for resolving operands
+ * @returns Calculation result
+ */
+function calculateVolume(quantity, brackets, context) {
+    // Find applicable bracket (last one where minVolume <= quantity)
+    let applicableBracket = brackets[0];
+    let bracketIndex = 0;
+    for (let i = 0; i < brackets.length; i++) {
+        if (brackets[i].minVolume <= quantity) {
+            applicableBracket = brackets[i];
+            bracketIndex = i;
+        }
+        else {
+            break;
+        }
+    }
+    const rate = context.resolve(applicableBracket.pricePerUnit);
+    const total = quantity * rate;
+    // Format bracket range
+    const nextBracket = brackets[bracketIndex + 1];
+    const rangeStart = formatNumber(applicableBracket.minVolume);
+    const rangeEnd = nextBracket
+        ? formatNumber(nextBracket.minVolume - 1)
+        : 'Unlimited';
+    return {
+        total,
+        breakdown: [{
+                tier: `Volume Bracket`,
+                range: `${rangeStart} - ${rangeEnd}`,
+                units: quantity,
+                rate,
+                subtotal: total
+            }]
+    };
+}
+/**
+ * Format a number with thousands separators.
+ */
+function formatNumber(n) {
+    if (n === 0)
+        return '0';
+    if (n === Infinity)
+        return 'Unlimited';
+    return n.toLocaleString('en-US');
+}
+/**
+ * Format currency value.
+ */
+function formatCurrency(value, currency = 'USD', precision = 2) {
+    return new Intl.NumberFormat('en-US', {
+        style: 'currency',
+        currency,
+        minimumFractionDigits: precision,
+        maximumFractionDigits: precision
+    }).format(value);
+}
+/**
+ * Format percentage value.
+ */
+function formatPercent(value, precision = 2) {
+    return `${value.toFixed(precision)}%`;
+}
+/**
+ * Round to specified precision.
+ */
+function round(value, precision) {
+    const factor = Math.pow(10, precision);
+    return Math.round(value * factor) / factor;
+}
+/**
+ * Calculate discount amount.
+ *
+ * @param total - Base amount
+ * @param percent - Percentage discount (0-100)
+ * @param fixedAmount - Fixed amount discount
+ * @returns Discount amount (positive value to subtract)
+ */
+function calculateDiscount(total, percent, fixedAmount) {
+    let discount = 0;
+    if (percent !== undefined && percent > 0) {
+        discount += total * (percent / 100);
+    }
+    if (fixedAmount !== undefined && fixedAmount > 0) {
+        discount += fixedAmount;
+    }
+    // Don't allow discount greater than total
+    return Math.min(discount, total);
+}
+/**
+ * Apply minimum/maximum caps.
+ *
+ * @param value - Current value
+ * @param min - Minimum value (optional)
+ * @param max - Maximum value (optional)
+ * @returns Capped value
+ */
+function applyMinMax(value, min, max) {
+    if (min !== undefined && value < min) {
+        return {
+            value: min,
+            adjustment: min - value,
+            type: 'minimum'
+        };
+    }
+    if (max !== undefined && value > max) {
+        return {
+            value: max,
+            adjustment: value - max,
+            type: 'maximum'
+        };
+    }
+    return { value, adjustment: 0 };
+}
+//# sourceMappingURL=calculator.js.map

package/dist/engines/pricing/calculator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.js","sourceRoot":"","sources":["../../../src/engines/pricing/calculator.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAoCH,sCAkBC;AAcD,gDA6CC;AAcD,0CAsCC;AAKD,oCAIC;AAKD,wCAWC;AAKD,sCAEC;AAKD,sBAGC;AAUD,8CAiBC;AAUD,kCAsBC;AA5OD;;;;;;;GAOG;AACH,SAAgB,aAAa,CAC3B,QAAgB,EAChB,YAA6B,EAC7B,OAA0B;IAE1B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;IAE9B,OAAO;QACL,KAAK;QACL,SAAS,EAAE,CAAC;gBACV,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,WAAW;gBAClB,KAAK,EAAE,QAAQ;gBACf,IAAI;gBACJ,QAAQ,EAAE,KAAK;aAChB,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,kBAAkB,CAChC,QAAgB,EAChB,KAA8B,EAC9B,OAA0B;IAE1B,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,IAAI,SAAS,GAAG,QAAQ,CAAC;IACzB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEhD,+BAA+B;QAC/B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ;YACzC,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QAEtD,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,WAAW,GAAG,IAAI,CAAC;YACpC,KAAK,IAAI,QAAQ,CAAC;YAElB,sBAAsB;YACtB,MAAM,UAAU,GAAG,YAAY,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;YAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ;gBACrC,CAAC,CAAC,WAAW;gBACb,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE5B,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE;gBACrB,KAAK,EAAE,GAAG,UAAU,MAAM,QAAQ,EAAE;gBACpC,KAAK,EAAE,WAAW;gBAClB,IAAI;gBACJ,QAAQ;aACT,CAAC,CAAC;YAEH,SAAS,IAAI,WAAW,CAAC;QAC3B,CAAC;QAED,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAC7B,QAAgB,EAChB,QAAiC,EACjC,OAA0B;IAE1B,iEAAiE;IACjE,IAAI,iBAAiB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,QAAQ,EAAE,CAAC;YACtC,iBAAiB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAChC,YAAY,GAAG,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,MAAM;QACR,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;IAE9B,uBAAuB;IACvB,MAAM,WAAW,GAAG,QAAQ,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,YAAY,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,WAAW;QAC1B,CAAC,CAAC,YAAY,CAAC,WAAW,CAAC,SAAS,GAAG,CAAC,CAAC;QACzC,CAAC,CAAC,WAAW,CAAC;IAEhB,OAAO;QACL,KAAK;QACL,SAAS,EAAE,CAAC;gBACV,IAAI,EAAE,gBAAgB;gBACtB,KAAK,EAAE,GAAG,UAAU,MAAM,QAAQ,EAAE;gBACpC,KAAK,EAAE,QAAQ;gBACf,IAAI;gBACJ,QAAQ,EAAE,KAAK;aAChB,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,CAAS;IACpC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACxB,IAAI,CAAC,KAAK,QAAQ;QAAE,OAAO,WAAW,CAAC;IACvC,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAC5B,KAAa,EACb,WAAmB,KAAK,EACxB,YAAoB,CAAC;IAErB,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE;QACpC,KAAK,EAAE,UAAU;QACjB,QAAQ;QACR,qBAAqB,EAAE,SAAS;QAChC,qBAAqB,EAAE,SAAS;KACjC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,KAAa,EAAE,YAAoB,CAAC;IAChE,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAgB,KAAK,CAAC,KAAa,EAAE,SAAiB;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,iBAAiB,CAC/B,KAAa,EACb,OAAgB,EAChB,WAAoB;IAEpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QACzC,QAAQ,IAAI,KAAK,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACjD,QAAQ,IAAI,WAAW,CAAC;IAC1B,CAAC;IAED,0CAA0C;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,WAAW,CACzB,KAAa,EACb,GAAY,EACZ,GAAY;IAEZ,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QACrC,OAAO;YACL,KAAK,EAAE,GAAG;YACV,UAAU,EAAE,GAAG,GAAG,KAAK;YACvB,IAAI,EAAE,SAAS;SAChB,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QACrC,OAAO;YACL,KAAK,EAAE,GAAG;YACV,UAAU,EAAE,KAAK,GAAG,GAAG;YACvB,IAAI,EAAE,SAAS;SAChB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * Pricing Engine Compiler
+ *
+ * Compiles pricing rulesets for efficient execution:
+ * - Validates product types and scenario schemas
+ * - Compiles expressions in pricing/quantity/metrics
+ * - Validates scenario values against product type schemas
+ */
+import { PricingRuleSet, PricingRule, ProductType, CompiledPricingRuleSet, CompiledPricingRule } from './types';
+/**
+ * Compile a pricing ruleset.
+ */
+export declare function compilePricingRuleSet(ruleSet: PricingRuleSet): CompiledPricingRuleSet;
+/**
+ * Compile a single pricing rule (for direct rule compilation).
+ */
+export declare function compilePricingRule(rule: PricingRule, productTypes?: Record<string, ProductType>, scenarioIds?: string[], strict?: boolean): CompiledPricingRule;
+//# sourceMappingURL=compiler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/engines/pricing/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EACL,cAAc,EACd,WAAW,EASX,WAAW,EACX,sBAAsB,EACtB,mBAAmB,EAUpB,MAAM,SAAS,CAAC;AA8RjB;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,sBAAsB,CA0CrF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAM,EAC9C,WAAW,GAAE,MAAM,EAAO,EAC1B,MAAM,GAAE,OAAe,GACtB,mBAAmB,CAErB"}