@robotixai/calculator-engine 0.1.0 → 0.2.0

package/dist/advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,OAAO,EACR,MAAM,SAAS,CAAC;AAwIjB,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAqrB/C"}
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,OAAO,EACR,MAAM,SAAS,CAAC;AAyIjB,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAusB/C"}

package/dist/advanced.js

@@ -19,6 +19,7 @@
 import { CadenceMultiplier } from './defaults';
 import { calculateTax } from './tax';
 import { calculateWithdrawal, } from './withdrawal';
+import { getLogger } from './logger';
 // =============================================================================
 // Helper Functions
 // =============================================================================
@@ -140,6 +141,12 @@ const INCOME_CATEGORIES = new Set([
 export function runAdvancedProjection(scenario, overrideReturns) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1;
     const { current_age, retirement_age, end_age, inflation_pct, inflation_enabled, financial_items, liquidity_events, enable_taxes, effective_tax_rate_pct, tax_jurisdiction, tax_config, black_swan_enabled, black_swan_age, black_swan_loss_pct, desired_estate, } = scenario;
+    const log = getLogger();
+    log.info('Starting advanced projection', {
+        currentAge: current_age,
+        retirementAge: retirement_age,
+        itemCount: financial_items.length,
+    });
     const items = financial_items.filter((item) => item.enabled);
     // -------------------------------------------------------------------------
     // Initialize state
@@ -489,7 +496,9 @@ export function runAdvancedProjection(scenario, overrideReturns) {
                     continue;
                 // Cap at available cash
                 if (contrib > Math.max(0, cashBalance)) {
-                    shortfallContributions += contrib - Math.max(0, cashBalance);
+                    const shortfall = contrib - Math.max(0, cashBalance);
+                    log.warn('Contribution shortfall', { age, shortfall, requested: contrib, available: Math.max(0, cashBalance) });
+                    shortfallContributions += shortfall;
                     contrib = Math.max(0, cashBalance);
                 }
                 cashBalance -= contrib;
@@ -552,6 +561,9 @@ export function runAdvancedProjection(scenario, overrideReturns) {
         // 8. INSOLVENCY CHECK
         // =====================================================================
         const insolvency = cashBalance < 0;
+        if (insolvency) {
+            log.warn('Insolvency detected', { age, cashBalance });
+        }
         if (insolvency && firstShortfallAge === null) {
             firstShortfallAge = age;
         }
@@ -722,6 +734,11 @@ export function runAdvancedProjection(scenario, overrideReturns) {
                 ? Math.min(200, (totalActual / totalDesired) * 100)
                 : 100;
     }
+    const insolvencyCount = timeline.filter((r) => r.insolvency).length;
+    log.info('Advanced projection complete', {
+        terminalReal,
+        insolvencyCount,
+    });
     const metrics = {
         terminal_nominal: terminalNominal,
         terminal_real: terminalReal,

package/dist/backtest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backtest.d.ts","sourceRoot":"","sources":["../src/backtest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AA6KjD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACrE,cAAc,CAoEhB"}
+{"version":3,"file":"backtest.d.ts","sourceRoot":"","sources":["../src/backtest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AA8KjD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACrE,cAAc,CAyEhB"}

package/dist/backtest.js

@@ -1,3 +1,4 @@
+import { getLogger } from './logger';
 // ---------------------------------------------------------------------------
 // Historical Backtest — Shiller Data (real total stock returns, 1871-2024)
 // ---------------------------------------------------------------------------
@@ -177,6 +178,7 @@ const SHILLER_DATA = [
  * @returns  Array of BacktestPeriod results and the overall success rate (0-100).
  */
 export function runHistoricalBacktest(scenario, projectionFn) {
+    const log = getLogger();
     const span = scenario.end_age - scenario.current_age;
     // Guard: span must be at least 1
     if (span < 1) {
@@ -199,6 +201,7 @@ export function runHistoricalBacktest(scenario, projectionFn) {
     for (const entry of SHILLER_DATA) {
         returnsByYear.set(entry.year, entry.realStockReturn);
     }
+    log.info('Starting backtest', { spanYears: span, windowCount });
     let survivedCount = 0;
     for (let i = 0; i < windowCount; i++) {
         const startYear = firstYear + i;
@@ -231,5 +234,6 @@ export function runHistoricalBacktest(scenario, projectionFn) {
     const successRate = periods.length > 0
         ? (survivedCount / periods.length) * 100
         : 0;
+    log.info('Backtest complete', { successRate, periodsAnalyzed: periods.length });
     return { periods, successRate };
 }

package/dist/defaults.d.ts

@@ -1,4 +1,10 @@
-import type { Cadence, Scenario } from './types';
+import type { Cadence, CurrencyCode, Scenario } from './types';
 export declare const CadenceMultiplier: Record<Cadence, number>;
+export interface CurrencyInfo {
+    code: CurrencyCode;
+    symbol: string;
+    decimals: number;
+}
+export declare const CURRENCY_MAP: Record<CurrencyCode, CurrencyInfo>;
 export declare const DEFAULT_SCENARIO: Scenario;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAMjD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAKrD,CAAC;AAMF,eAAO,MAAM,gBAAgB,EAAE,QAqF9B,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAM/D,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAKrD,CAAC;AAMF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,YAAY,CAiB3D,CAAC;AAMF,eAAO,MAAM,gBAAgB,EAAE,QAqF9B,CAAC"}

package/dist/defaults.js

@@ -10,6 +10,24 @@ export const CadenceMultiplier = {
     'Bi-Weekly': 26,
     Weekly: 52,
 };
+export const CURRENCY_MAP = {
+    USD: { code: 'USD', symbol: '$', decimals: 2 },
+    EUR: { code: 'EUR', symbol: '€', decimals: 2 },
+    GBP: { code: 'GBP', symbol: '£', decimals: 2 },
+    CHF: { code: 'CHF', symbol: 'CHF', decimals: 2 },
+    HKD: { code: 'HKD', symbol: 'HK$', decimals: 2 },
+    SGD: { code: 'SGD', symbol: 'S$', decimals: 2 },
+    AED: { code: 'AED', symbol: 'د.إ', decimals: 2 },
+    JPY: { code: 'JPY', symbol: '¥', decimals: 0 },
+    CAD: { code: 'CAD', symbol: 'C$', decimals: 2 },
+    AUD: { code: 'AUD', symbol: 'A$', decimals: 2 },
+    NZD: { code: 'NZD', symbol: 'NZ$', decimals: 2 },
+    ZAR: { code: 'ZAR', symbol: 'R', decimals: 2 },
+    INR: { code: 'INR', symbol: '₹', decimals: 2 },
+    BRL: { code: 'BRL', symbol: 'R$', decimals: 2 },
+    MXN: { code: 'MXN', symbol: 'Mex$', decimals: 2 },
+    KYD: { code: 'KYD', symbol: 'CI$', decimals: 2 },
+};
 // ---------------------------------------------------------------------------
 // Default Scenario
 // ---------------------------------------------------------------------------

package/dist/heatmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../src/heatmap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMjD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,EAAE,CAoDf"}
+{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../src/heatmap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAOjD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,EAAE,CA0Df"}

package/dist/heatmap.js

@@ -1,3 +1,4 @@
+import { getLogger } from './logger';
 /**
  * Deep-clone a scenario.
  */
@@ -34,6 +35,8 @@ export function generateHeatmap(scenario, projectionFn, options) {
     const effectiveSteps = Math.max(steps, 2);
     const ageStep = (ageMax - ageMin) / (effectiveSteps - 1);
     const spendStep = (spendMax - spendMin) / (effectiveSteps - 1);
+    const log = getLogger();
+    log.info('Generating heatmap', { rows: effectiveSteps, cols: effectiveSteps });
     const cells = [];
     const desiredEstate = (_k = scenario.desired_estate) !== null && _k !== void 0 ? _k : 0;
     for (let ai = 0; ai < effectiveSteps; ai++) {
@@ -59,5 +62,7 @@ export function generateHeatmap(scenario, projectionFn, options) {
             });
         }
     }
+    const viableCells = cells.filter((c) => c.viable).length;
+    log.info('Heatmap complete', { viableCells, totalCells: cells.length });
     return cells;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { Cadence, CurrencyCode, ContribStep, ProfitStep, RaiseStep, YieldStep, IncomeStep, LoanDraw, LumpRepayment, SpendingPhase, TaxConfig, IncomeSource, Asset, LiquidityEvent, FinancialItemCategory, FinancialItem, Scenario, TimelineRow, FanChartRow, Metrics, } from './types';
-export { CadenceMultiplier, DEFAULT_SCENARIO } from './defaults';
+export { CadenceMultiplier, CURRENCY_MAP, DEFAULT_SCENARIO, type CurrencyInfo } from './defaults';
 export { runProjection } from './projection';
 export { runAdvancedProjection } from './advanced';
 export { runMonteCarloSimulation, type MCOptions, type MCResult, type ProjectionFn, } from './monte-carlo';
@@ -8,4 +8,5 @@ export { runHistoricalBacktest, type BacktestPeriod, type BacktestResult, } from
 export { findEarliestRetirementAge, type OptimizerResult, type OptimizerOutput, type OptimizerOptions, } from './optimizer';
 export { generateHeatmap, type HeatmapCell, type HeatmapOptions, } from './heatmap';
 export { blendPortfolio, calculateEstateValue, type BlendedPortfolio, } from './portfolio';
+export { getLogger, setLogLevel, setLogger, type Logger, type LogLevel } from './logger';
 //# 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":"AAKA,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,WAAW,EACX,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,EACL,uBAAuB,EACvB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,WAAW,EACX,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAGlG,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,EACL,uBAAuB,EACvB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // Engine — barrel export
 // ---------------------------------------------------------------------------
-export { CadenceMultiplier, DEFAULT_SCENARIO } from './defaults';
+export { CadenceMultiplier, CURRENCY_MAP, DEFAULT_SCENARIO } from './defaults';
 // Deterministic projection (basic & advanced)
 export { runProjection } from './projection';
 export { runAdvancedProjection } from './advanced';
@@ -17,3 +17,5 @@ export { findEarliestRetirementAge, } from './optimizer';
 export { generateHeatmap, } from './heatmap';
 // Portfolio blending & estate value
 export { blendPortfolio, calculateEstateValue, } from './portfolio';
+// Logger utilities
+export { getLogger, setLogLevel, setLogger } from './logger';

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+export interface Logger {
+    error(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+/** Get the active logger instance */
+export declare function getLogger(): Logger;
+/** Set the minimum log level (default: 'warn') */
+export declare function setLogLevel(level: LogLevel): void;
+/** Provide a custom logger implementation (e.g., for server-side or testing) */
+export declare function setLogger(logger: Logger | null): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D;AAyCD,qCAAqC;AACrC,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,kDAAkD;AAClD,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAErD"}

package/dist/logger.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// Logger — structured logging with configurable levels
+//
+// Consumers can configure via setLogLevel() or provide a custom logger.
+// Defaults to silent in production, 'warn' otherwise.
+// ---------------------------------------------------------------------------
+const LOG_PRIORITY = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+let currentLevel = 'warn';
+let customLogger = null;
+function shouldLog(level) {
+    return LOG_PRIORITY[level] <= LOG_PRIORITY[currentLevel];
+}
+function formatMessage(level, message, data) {
+    const timestamp = new Date().toISOString();
+    const prefix = `[calculator-engine] ${timestamp} ${level.toUpperCase()}:`;
+    if (data && Object.keys(data).length > 0) {
+        return `${prefix} ${message} ${JSON.stringify(data)}`;
+    }
+    return `${prefix} ${message}`;
+}
+const defaultLogger = {
+    error(message, data) {
+        if (shouldLog('error'))
+            console.error(formatMessage('error', message, data));
+    },
+    warn(message, data) {
+        if (shouldLog('warn'))
+            console.warn(formatMessage('warn', message, data));
+    },
+    info(message, data) {
+        if (shouldLog('info'))
+            console.info(formatMessage('info', message, data));
+    },
+    debug(message, data) {
+        if (shouldLog('debug'))
+            console.debug(formatMessage('debug', message, data));
+    },
+};
+/** Get the active logger instance */
+export function getLogger() {
+    return customLogger !== null && customLogger !== void 0 ? customLogger : defaultLogger;
+}
+/** Set the minimum log level (default: 'warn') */
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+/** Provide a custom logger implementation (e.g., for server-side or testing) */
+export function setLogger(logger) {
+    customLogger = logger;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"monte-carlo.d.ts","sourceRoot":"","sources":["../src/monte-carlo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3E,MAAM,MAAM,YAAY,GAAG,CACzB,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,KACvB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,wBAAwB,EAAE,MAAM,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAS;gBAEV,IAAI,GAAE,MAAW;IAI7B,uEAAuE;IACvE,IAAI,IAAI,MAAM;IAQd,yEAAyE;IACzE,QAAQ,IAAI,MAAM;CAUnB;AAMD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,GAAG,QAAQ,GACpC,MAAM,CAuBR;AAMD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,SAAc,GACtB,QAAQ,CAoIV"}
+{"version":3,"file":"monte-carlo.d.ts","sourceRoot":"","sources":["../src/monte-carlo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAO3E,MAAM,MAAM,YAAY,GAAG,CACzB,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,KACvB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,wBAAwB,EAAE,MAAM,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAS;gBAEV,IAAI,GAAE,MAAW;IAI7B,uEAAuE;IACvE,IAAI,IAAI,MAAM;IAQd,yEAAyE;IACzE,QAAQ,IAAI,MAAM;CAUnB;AAMD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,GAAG,QAAQ,GACpC,MAAM,CAuBR;AAMD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,SAAc,GACtB,QAAQ,CA+IV"}

package/dist/monte-carlo.js

@@ -6,6 +6,7 @@
  * a caller-provided projection function, keeping MC fully decoupled from the
  * projection engine.
  */
+import { getLogger } from './logger';
 // ---------------------------------------------------------------------------
 // SeededRNG — Deterministic PRNG (mulberry32)
 // ---------------------------------------------------------------------------
@@ -88,6 +89,8 @@ export function runMonteCarloSimulation(scenario, projectionFn, options = {}) {
     if (runs < 100 || runs > 10000) {
         throw new Error(`mc_runs must be 0 (disabled) or between 100 and 10000. Got: ${runs}`);
     }
+    const log = getLogger();
+    log.info('Starting Monte Carlo', { runs, seed, distribution: scenario.return_distribution });
     const rng = new SeededRNG(seed);
     const startTime = Date.now();
     const numYears = scenario.end_age - scenario.current_age;
@@ -108,6 +111,7 @@ export function runMonteCarloSimulation(scenario, projectionFn, options = {}) {
             const elapsed = Date.now() - startTime;
             if (elapsed > budgetMs) {
                 truncated = true;
+                log.warn('Monte Carlo truncated due to budget', { runsCompleted: run, elapsed, budgetMs });
                 break;
             }
         }
@@ -165,6 +169,12 @@ export function runMonteCarloSimulation(scenario, projectionFn, options = {}) {
     // Compute probability of no shortfall
     // -----------------------------------------------------------------------
     const probabilityNoShortfall = runsCompleted > 0 ? (noShortfallCount / runsCompleted) * 100 : 0;
+    log.info('Monte Carlo complete', {
+        runsCompleted,
+        successProbability: probabilityNoShortfall,
+        medianTerminal: p50Terminal,
+        truncated,
+    });
     return {
         probability_no_shortfall: probabilityNoShortfall,
         median_terminal: p50Terminal,

package/dist/optimizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../src/optimizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMjD,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA4GD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EACnD,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,wBAAwB,EAAE,MAAM,CAAA;CAAE,EAC5D,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAkDjB"}
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../src/optimizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAOjD,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA4GD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EACnD,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,wBAAwB,EAAE,MAAM,CAAA;CAAE,EAC5D,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAiEjB"}

package/dist/optimizer.js

@@ -1,3 +1,4 @@
+import { getLogger } from './logger';
 /**
  * Deep-clone a scenario.
  */
@@ -102,11 +103,16 @@ function findMinContribution(scenario, retirementAge, projectionFn, mcFn, mcThre
  */
 export function findEarliestRetirementAge(scenario, projectionFn, mcFn, options) {
     var _a;
+    const log = getLogger();
     const mcThreshold = (_a = options === null || options === void 0 ? void 0 : options.mcThreshold) !== null && _a !== void 0 ? _a : 90;
     const results = [];
     let earliestViableAge = null;
     const startAge = scenario.current_age + 1;
     const endAge = scenario.end_age - 1;
+    log.info('Starting optimizer', {
+        searchRange: [startAge, endAge],
+        mcEnabled: mcFn != null,
+    });
     // Budget guard: track wall-clock time (50s limit per CONTRACT-005)
     const startTime = Date.now();
     const BUDGET_MS = 50000;
@@ -116,6 +122,12 @@ export function findEarliestRetirementAge(scenario, projectionFn, mcFn, options)
             break;
         }
         const { result, viable } = isViable(scenario, age, projectionFn, mcFn, mcThreshold);
+        log.debug('Optimizer candidate', {
+            age,
+            terminalReal: result.terminalReal,
+            survived: result.survived,
+            viable,
+        });
         results.push(result);
         if (viable && earliestViableAge === null) {
             earliestViableAge = age;
@@ -126,6 +138,7 @@ export function findEarliestRetirementAge(scenario, projectionFn, mcFn, options)
     if (earliestViableAge !== null) {
         minContribution = findMinContribution(scenario, earliestViableAge, projectionFn, mcFn, mcThreshold);
     }
+    log.info('Optimizer complete', { earliestViableAge, minContribution });
     return {
         results,
         earliestViableAge,

package/dist/portfolio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portfolio.d.ts","sourceRoot":"","sources":["../src/portfolio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAMpD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAsDhE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,aAAa,EAAE,EAC/B,SAAS,EAAE,MAAM,GAChB,MAAM,CAcR"}
+{"version":3,"file":"portfolio.d.ts","sourceRoot":"","sources":["../src/portfolio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAOpD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CA6DhE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,aAAa,EAAE,EAC/B,SAAS,EAAE,MAAM,GAChB,MAAM,CAcR"}

package/dist/portfolio.js

@@ -1,3 +1,4 @@
+import { getLogger } from './logger';
 /**
  * Computes weighted-average return, fee, perf-fee, and liquid percentage
  * across a set of basic-mode assets.
@@ -44,6 +45,12 @@ export function blendPortfolio(assets) {
         .filter((a) => a.is_liquid)
         .reduce((sum, a) => sum + a.current_value, 0);
     const liquidPct = (liquidTotal / totalValue) * 100;
+    const log = getLogger();
+    log.debug('Portfolio blended', {
+        assetCount: enabled.length,
+        blendedReturn,
+        liquidPct,
+    });
     return {
         totalValue,
         blendedReturn,

package/dist/projection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAgB,MAAM,SAAS,CAAC;AAoE5E,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA2a/C"}
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAgB,MAAM,SAAS,CAAC;AAqE5E,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA+b/C"}

package/dist/projection.js

@@ -11,6 +11,7 @@
 import { CadenceMultiplier } from './defaults';
 import { calculateTax, getRMDAmount, calculateRothConversion } from './tax';
 import { calculateWithdrawal, NEAR_ZERO_THRESHOLD, } from './withdrawal';
+import { getLogger } from './logger';
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -57,6 +58,13 @@ export function runProjection(scenario, overrideReturns) {
     const { current_age, retirement_age, end_age, current_balance, contrib_amount, contrib_cadence, contrib_increase_pct, nominal_return_pct, inflation_pct, inflation_enabled, fee_pct, perf_fee_pct, enable_taxes, effective_tax_rate_pct, tax_jurisdiction, tax_config, tax_deferred_pct, planning_mode, partner_current_age, partner_income_sources, income_sources, liquidity_events, 
     // assets — not used in basic-mode projection (estate_pct is advanced-mode only)
     black_swan_enabled, black_swan_age, black_swan_loss_pct, spending_phases, withdrawal_strategy, } = scenario;
+    const log = getLogger();
+    log.info('Starting projection', {
+        currentAge: current_age,
+        retirementAge: retirement_age,
+        endAge: end_age,
+        detailMode: scenario.detail_mode,
+    });
     const timeline = [];
     // Running state
     let prevEndBalance = current_balance;
@@ -271,6 +279,7 @@ export function runProjection(scenario, overrideReturns) {
         if (black_swan_enabled && age === black_swan_age) {
             // Override growth with the loss
             growth = -(startBalance * (black_swan_loss_pct / 100));
+            log.warn('Black swan event triggered', { age, lossPct: black_swan_loss_pct });
         }
         else {
             // Mid-year cash flow assumption:
@@ -286,6 +295,7 @@ export function runProjection(scenario, overrideReturns) {
         // Track shortfall before flooring
         if (endBalance < 0 && age >= retirement_age && firstShortfallAge === null) {
             firstShortfallAge = age;
+            log.warn('First shortfall detected', { age, endBalance });
         }
         // Near-zero depletion threshold (edge case: asymptotic drain)
         if (endBalance >= 0 &&
@@ -293,6 +303,7 @@ export function runProjection(scenario, overrideReturns) {
             age >= retirement_age &&
             firstShortfallAge === null) {
             firstShortfallAge = age;
+            log.warn('Near-zero depletion shortfall', { age, endBalance });
         }
         // Floor at 0 in basic mode
         endBalance = Math.max(endBalance, 0);
@@ -330,6 +341,7 @@ export function runProjection(scenario, overrideReturns) {
             shortfall_contributions: 0,
             shortfall_withdrawals: shortfallWithdrawals,
         };
+        log.debug('Year end', { age, end_balance: endBalance });
         timeline.push(row);
         // Update running state for next year
         prevEndBalance = endBalance;
@@ -378,5 +390,11 @@ export function runProjection(scenario, overrideReturns) {
         total_taxes: totalTaxes,
         estate_value: estateValue,
     };
+    log.info('Projection complete', {
+        terminalReal,
+        terminalNominal,
+        shortfallAge: firstShortfallAge,
+        years: timeline.length,
+    });
     return { timeline, metrics };
 }

package/dist/sensitivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sensitivity.d.ts","sourceRoot":"","sources":["../src/sensitivity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMjD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAClD,iBAAiB,EAAE,CAgErB"}
+{"version":3,"file":"sensitivity.d.ts","sourceRoot":"","sources":["../src/sensitivity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAOjD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAClD,iBAAiB,EAAE,CA6ErB"}

package/dist/sensitivity.js

@@ -1,3 +1,4 @@
+import { getLogger } from './logger';
 const PARAMETERS = [
     { name: 'nominal_return_pct', label: 'Return +/-1%', delta: 1, deltaIsPct: false },
     { name: 'inflation_pct', label: 'Inflation +/-0.5%', delta: 0.5, deltaIsPct: false },
@@ -36,6 +37,9 @@ function clamp(value, min, max) {
  *   - withdrawal_pct delta is skipped when withdrawal_strategy is Age-Banded
  */
 export function runSensitivityAnalysis(scenario, projectionFn) {
+    var _a;
+    const log = getLogger();
+    log.info('Starting sensitivity analysis', { parameterCount: PARAMETERS.length });
     const factors = [];
     for (const param of PARAMETERS) {
         // Skip withdrawal_pct when strategy is Age-Banded (not applicable)
@@ -76,6 +80,13 @@ export function runSensitivityAnalysis(scenario, projectionFn) {
         const highScenario = cloneScenario(scenario);
         highScenario[param.name] = highValue;
         const highResult = projectionFn(highScenario);
+        const spread = Math.abs(highResult.metrics.terminal_real - lowResult.metrics.terminal_real);
+        log.debug('Sensitivity parameter result', {
+            name: param.name,
+            lowTerminal: lowResult.metrics.terminal_real,
+            highTerminal: highResult.metrics.terminal_real,
+            spread,
+        });
         factors.push({
             name: param.name,
             label: param.label,
@@ -83,10 +94,11 @@ export function runSensitivityAnalysis(scenario, projectionFn) {
             highValue,
             lowTerminal: lowResult.metrics.terminal_real,
             highTerminal: highResult.metrics.terminal_real,
-            spread: Math.abs(highResult.metrics.terminal_real - lowResult.metrics.terminal_real),
+            spread,
         });
     }
     // Sort by spread descending (largest impact first)
     factors.sort((a, b) => b.spread - a.spread);
+    log.info('Sensitivity complete', { topFactor: (_a = factors[0]) === null || _a === void 0 ? void 0 : _a.name });
     return factors;
 }

package/dist/tax.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tax.d.ts","sourceRoot":"","sources":["../src/tax.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AA4JzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,CAiBR;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,SAAS,EAAE,MAAM,GAChB,MAAM,CAUR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,GAChB,MAAM,CAMR"}
+{"version":3,"file":"tax.d.ts","sourceRoot":"","sources":["../src/tax.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AA6JzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,CA4BR;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,SAAS,EAAE,MAAM,GAChB,MAAM,CAUR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,GAChB,MAAM,CAMR"}

package/dist/tax.js

@@ -6,6 +6,7 @@
  *
  * Also includes RMD (Required Minimum Distribution) and Roth conversion logic.
  */
+import { getLogger } from './logger';
 const US_STANDARD_DEDUCTION_SINGLE = 15000;
 const US_STANDARD_DEDUCTION_MFJ = 30000;
 const US_BRACKETS_2025_SINGLE = [
@@ -136,17 +137,25 @@ function calculateUKTax(grossIncome) {
 export function calculateTax(taxableIncome, config, jurisdiction) {
     if (taxableIncome <= 0)
         return 0;
+    let taxAmount;
     switch (jurisdiction) {
         case 'Cayman Islands':
-            return 0;
+            taxAmount = 0;
+            break;
         case 'US':
-            return calculateUSTax(taxableIncome, config.filing_status);
+            taxAmount = calculateUSTax(taxableIncome, config.filing_status);
+            break;
         case 'UK':
-            return calculateUKTax(taxableIncome);
+            taxAmount = calculateUKTax(taxableIncome);
+            break;
         case 'Custom':
         default:
-            return taxableIncome * (config.flat_rate_pct / 100);
+            taxAmount = taxableIncome * (config.flat_rate_pct / 100);
+            break;
     }
+    const log = getLogger();
+    log.debug('Tax calculated', { jurisdiction, taxableIncome, taxAmount });
+    return taxAmount;
 }
 // =============================================================================
 // RMD (Required Minimum Distributions)

package/dist/withdrawal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../src/withdrawal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAMvD,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAMvC,MAAM,WAAW,OAAO;IACtB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,wBAAwB;IACvC,gBAAgB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,6BAA6B;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAExB,4EAA4E;IAC5E,cAAc,EAAE,wBAAwB,CAAC;IAEzC,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAMD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CA2BR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,6BAA6B,GACpC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAkF1C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,yBAAyB,GAChC,MAAM,CA6BR;AAMD,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,QAAQ,CAAC;IAEnB,gCAAgC;IAChC,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;KACzB,CAAC;CACH;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC/B,gBAAgB,CA0FlB"}
+{"version":3,"file":"withdrawal.d.ts","sourceRoot":"","sources":["../src/withdrawal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAOvD,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAMvC,MAAM,WAAW,OAAO;IACtB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,wBAAwB;IACvC,gBAAgB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,6BAA6B;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAExB,4EAA4E;IAC5E,cAAc,EAAE,wBAAwB,CAAC;IAEzC,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAMD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CA2BR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,6BAA6B,GACpC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAkF1C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,yBAAyB,GAChC,MAAM,CA2BR;AAMD,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,QAAQ,CAAC;IAEnB,gCAAgC;IAChC,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;KACzB,CAAC;CACH;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC/B,gBAAgB,CA6FlB"}

package/dist/withdrawal.js

@@ -11,6 +11,7 @@
  * - GK oscillation: bounded by floor/ceiling — no special handling needed
  * - RMD override: caller responsibility (if RMD > withdrawal, caller uses RMD)
  */
+import { getLogger } from './logger';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -150,8 +151,8 @@ export function calculateAgeBandedWithdrawal(params) {
     const phase = spendingPhases.find((p) => age >= p.start_age && age <= p.end_age);
     if (!phase) {
         // Gap in spending phases — no withdrawal for this year
-        console.warn(`[withdrawal] Age-Banded: no spending phase covers age ${age}. Withdrawal defaults to $0. ` +
-            `Check for gaps in spending phase definitions.`);
+        const log = getLogger();
+        log.warn('Age-Banded gap: no spending phase covers age', { age });
         return 0;
     }
     let withdrawal;
@@ -230,6 +231,8 @@ export function calculateWithdrawal(scenario, state) {
             throw new Error(`Unknown withdrawal strategy: ${_exhaustive}`);
         }
     }
+    const log = getLogger();
+    log.debug('Withdrawal calculated', { strategy: withdrawal_strategy, amount: withdrawal });
     // Near-zero threshold: if balance after withdrawal would be below $100, treat as depleted
     const balanceAfterWithdrawal = availableBalance - withdrawal;
     const effectivelyDepleted = balanceAfterWithdrawal >= 0 && balanceAfterWithdrawal < NEAR_ZERO_THRESHOLD;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robotixai/calculator-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Financial retirement projection engine with Monte Carlo simulation, multi-jurisdiction tax, and withdrawal strategies",
   "private": false,
   "main": "./dist/index.js",