@timecell/engine 0.1.0

package/dist/crash-survival.d.ts

@@ -0,0 +1,26 @@
+import type { PortfolioInput, HedgePosition, SurvivalResult, CrashSurvivalConfig } from "./types.js";
+/** Default configuration — all values overridable */
+export declare const DEFAULT_CONFIG: CrashSurvivalConfig;
+/**
+ * Calculate crash survival across multiple drawdown scenarios.
+ *
+ * For each scenario:
+ * - BTC drops by drawdownPct%
+ * - Non-BTC assets drop by drawdownPct * config.nonBtcCorrelation
+ * - Hedge payoff = sum of max(0, strike - crashPrice) * quantity for each position
+ * - Runway = (portfolio after crash + hedge payoff + liquid reserve) / monthly burn
+ * - Survival status based on runway vs config thresholds
+ */
+export declare function calculateCrashSurvival(portfolio: PortfolioInput, hedgePositions?: HedgePosition[], config?: Partial<CrashSurvivalConfig>): SurvivalResult;
+/**
+ * Calculate hedge payoff at various BTC price multipliers.
+ */
+export declare function calculatePriceScenarios(hedgePositions: HedgePosition[], totalBtcHoldings: number, currentBtcPrice: number, multipliers?: number[]): {
+    btcPrice: number;
+    portfolioValue: number;
+    hedgePayoff: number;
+    netValue: number;
+    protectionPct: number;
+    changePct: number;
+}[];
+//# sourceMappingURL=crash-survival.d.ts.map

package/dist/crash-survival.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-survival.d.ts","sourceRoot":"","sources":["../src/crash-survival.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,cAAc,EACd,aAAa,EAEb,cAAc,EACd,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAOpB,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE,mBAK5B,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,cAAc,GAAE,aAAa,EAAO,EACpC,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM,GACvC,cAAc,CAwBhB;AAqDD;;GAEG;AACH,wBAAgB,uBAAuB,CACtC,cAAc,EAAE,aAAa,EAAE,EAC/B,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,WAAW,GAAE,MAAM,EAA4D;;;;;;;IAoB/E"}

package/dist/crash-survival.js

@@ -0,0 +1,98 @@
+import { calculateRunwayMonths } from "./runway.js";
+// =============================================================================
+// Crash Survival Calculator
+// =============================================================================
+/** Default configuration — all values overridable */
+export const DEFAULT_CONFIG = {
+    drawdowns: [30, 50, 70, 80],
+    nonBtcCorrelation: 0.5,
+    runwayWarningMonths: 24,
+    runwayCriticalMonths: 18,
+};
+/**
+ * Calculate crash survival across multiple drawdown scenarios.
+ *
+ * For each scenario:
+ * - BTC drops by drawdownPct%
+ * - Non-BTC assets drop by drawdownPct * config.nonBtcCorrelation
+ * - Hedge payoff = sum of max(0, strike - crashPrice) * quantity for each position
+ * - Runway = (portfolio after crash + hedge payoff + liquid reserve) / monthly burn
+ * - Survival status based on runway vs config thresholds
+ */
+export function calculateCrashSurvival(portfolio, hedgePositions = [], config = {}) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const btcValue = portfolio.totalValueUsd * (portfolio.btcPercentage / 100);
+    const nonBtcValue = portfolio.totalValueUsd - btcValue;
+    const scenarios = cfg.drawdowns.map((drawdownPct) => calculateScenario(portfolio, btcValue, nonBtcValue, drawdownPct, hedgePositions, cfg));
+    // Find max survivable drawdown (highest where status is not critical)
+    const survivable = scenarios.filter((s) => s.survivalStatus !== "critical");
+    const maxSurvivableDrawdown = survivable.length > 0 ? Math.max(...survivable.map((s) => s.drawdownPct)) : 0;
+    // Ruin test: survive highest drawdown scenario
+    const worstScenario = scenarios[scenarios.length - 1];
+    const ruinTestPassed = worstScenario ? worstScenario.survivalStatus !== "critical" : false;
+    return {
+        portfolio,
+        scenarios,
+        maxSurvivableDrawdown,
+        ruinTestPassed,
+    };
+}
+function calculateScenario(portfolio, btcValue, nonBtcValue, drawdownPct, hedgePositions, config) {
+    const btcDrawdown = drawdownPct / 100;
+    const nonBtcDrawdown = btcDrawdown * config.nonBtcCorrelation;
+    const btcPriceAtCrash = portfolio.btcPriceUsd * (1 - btcDrawdown);
+    const btcValueAfterCrash = btcValue * (1 - btcDrawdown);
+    const nonBtcValueAfterCrash = nonBtcValue * (1 - nonBtcDrawdown);
+    const portfolioValueAfterCrash = btcValueAfterCrash + nonBtcValueAfterCrash;
+    // Hedge payoff: intrinsic value of puts
+    let hedgePayoff = 0;
+    for (const pos of hedgePositions) {
+        hedgePayoff += Math.max(0, pos.strikeUsd - btcPriceAtCrash) * pos.quantityBtc;
+    }
+    const netPosition = portfolioValueAfterCrash + hedgePayoff + portfolio.liquidReserveUsd;
+    // Runway: net position / monthly burn — how many months you can sustain
+    // by liquidating everything (portfolio after crash + hedge payoff + liquid reserve)
+    const runwayMonths = calculateRunwayMonths(netPosition, portfolio.monthlyBurnUsd);
+    // Survival status
+    let survivalStatus;
+    if (runwayMonths >= config.runwayWarningMonths) {
+        survivalStatus = "safe";
+    }
+    else if (runwayMonths >= config.runwayCriticalMonths) {
+        survivalStatus = "warning";
+    }
+    else {
+        survivalStatus = "critical";
+    }
+    return {
+        drawdownPct,
+        btcPriceAtCrash,
+        btcValueAfterCrash,
+        nonBtcValueAfterCrash,
+        portfolioValueAfterCrash,
+        hedgePayoff,
+        netPosition,
+        runwayMonths,
+        survivalStatus,
+    };
+}
+/**
+ * Calculate hedge payoff at various BTC price multipliers.
+ */
+export function calculatePriceScenarios(hedgePositions, totalBtcHoldings, currentBtcPrice, multipliers = [0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.4]) {
+    const currentPortfolioValue = totalBtcHoldings * currentBtcPrice;
+    return multipliers.map((m) => {
+        const btcPrice = m === 1.0 ? currentBtcPrice : Math.round((currentBtcPrice * m) / 5000) * 5000;
+        const portfolioValue = totalBtcHoldings * btcPrice;
+        let hedgePayoff = 0;
+        for (const p of hedgePositions) {
+            hedgePayoff += Math.max(0, p.strikeUsd - btcPrice) * p.quantityBtc;
+        }
+        const netValue = portfolioValue + hedgePayoff;
+        const portfolioLoss = currentPortfolioValue - portfolioValue;
+        const protectionPct = portfolioLoss > 0 ? hedgePayoff / portfolioLoss : 0;
+        const changePct = ((btcPrice - currentBtcPrice) / currentBtcPrice) * 100;
+        return { btcPrice, portfolioValue, hedgePayoff, netValue, protectionPct, changePct };
+    });
+}
+//# sourceMappingURL=crash-survival.js.map

package/dist/crash-survival.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-survival.js","sourceRoot":"","sources":["../src/crash-survival.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAwB;IAClD,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;IAC3B,iBAAiB,EAAE,GAAG;IACtB,mBAAmB,EAAE,EAAE;IACvB,oBAAoB,EAAE,EAAE;CACxB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,iBAAkC,EAAE,EACpC,SAAuC,EAAE;IAEzC,MAAM,GAAG,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,SAAS,CAAC,aAAa,GAAG,CAAC,SAAS,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC;IAC3E,MAAM,WAAW,GAAG,SAAS,CAAC,aAAa,GAAG,QAAQ,CAAC;IAEvD,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CACnD,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,CAAC,CACrF,CAAC;IAEF,sEAAsE;IACtE,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,KAAK,UAAU,CAAC,CAAC;IAC5E,MAAM,qBAAqB,GAC1B,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/E,+CAA+C;IAC/C,MAAM,aAAa,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;IAE3F,OAAO;QACN,SAAS;QACT,SAAS;QACT,qBAAqB;QACrB,cAAc;KACd,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CACzB,SAAyB,EACzB,QAAgB,EAChB,WAAmB,EACnB,WAAmB,EACnB,cAA+B,EAC/B,MAA2B;IAE3B,MAAM,WAAW,GAAG,WAAW,GAAG,GAAG,CAAC;IACtC,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAE9D,MAAM,eAAe,GAAG,SAAS,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;IAClE,MAAM,kBAAkB,GAAG,QAAQ,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;IACxD,MAAM,qBAAqB,GAAG,WAAW,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC;IACjE,MAAM,wBAAwB,GAAG,kBAAkB,GAAG,qBAAqB,CAAC;IAE5E,wCAAwC;IACxC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QAClC,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,GAAG,eAAe,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;IAC/E,CAAC;IAED,MAAM,WAAW,GAAG,wBAAwB,GAAG,WAAW,GAAG,SAAS,CAAC,gBAAgB,CAAC;IAExF,wEAAwE;IACxE,oFAAoF;IACpF,MAAM,YAAY,GAAG,qBAAqB,CAAC,WAAW,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;IAElF,kBAAkB;IAClB,IAAI,cAA+C,CAAC;IACpD,IAAI,YAAY,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAChD,cAAc,GAAG,MAAM,CAAC;IACzB,CAAC;SAAM,IAAI,YAAY,IAAI,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACxD,cAAc,GAAG,SAAS,CAAC;IAC5B,CAAC;SAAM,CAAC;QACP,cAAc,GAAG,UAAU,CAAC;IAC7B,CAAC;IAED,OAAO;QACN,WAAW;QACX,eAAe;QACf,kBAAkB;QAClB,qBAAqB;QACrB,wBAAwB;QACxB,WAAW;QACX,WAAW;QACX,YAAY;QACZ,cAAc;KACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACtC,cAA+B,EAC/B,gBAAwB,EACxB,eAAuB,EACvB,cAAwB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAE/E,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,eAAe,CAAC;IAEjE,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC5B,MAAM,QAAQ,GACb,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAE/E,MAAM,cAAc,GAAG,gBAAgB,GAAG,QAAQ,CAAC;QACnD,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE,CAAC;YAChC,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;QACpE,CAAC;QACD,MAAM,QAAQ,GAAG,cAAc,GAAG,WAAW,CAAC;QAC9C,MAAM,aAAa,GAAG,qBAAqB,GAAG,cAAc,CAAC;QAC7D,MAAM,aAAa,GAAG,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,SAAS,GAAG,CAAC,CAAC,QAAQ,GAAG,eAAe,CAAC,GAAG,eAAe,CAAC,GAAG,GAAG,CAAC;QAEzE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;IACtF,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/fixtures/demo-portfolio.d.ts

@@ -0,0 +1,10 @@
+import type { PortfolioInput, HedgePosition } from "../types.js";
+/** Default BTC price for demo (approximate Feb 2026) */
+export declare const DEMO_BTC_PRICE = 84000;
+/** Demo portfolio: $5M, 35% BTC, $25K/mo burn, $600K liquid reserve */
+export declare const DEMO_PORTFOLIO: PortfolioInput;
+/** Demo hedge positions (optional — shows with vs without insurance) */
+export declare const DEMO_HEDGE_POSITIONS: HedgePosition[];
+/** Portfolio with no hedge — for comparison */
+export declare const DEMO_PORTFOLIO_NO_HEDGE: HedgePosition[];
+//# sourceMappingURL=demo-portfolio.d.ts.map

package/dist/fixtures/demo-portfolio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-portfolio.d.ts","sourceRoot":"","sources":["../../src/fixtures/demo-portfolio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjE,wDAAwD;AACxD,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,uEAAuE;AACvE,eAAO,MAAM,cAAc,EAAE,cAM5B,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,EAAE,aAAa,EAM/C,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,uBAAuB,EAAE,aAAa,EAAO,CAAC"}

package/dist/fixtures/demo-portfolio.js

@@ -0,0 +1,24 @@
+// =============================================================================
+// Demo Portfolio — Realistic YPO-relevant example
+// =============================================================================
+/** Default BTC price for demo (approximate Feb 2026) */
+export const DEMO_BTC_PRICE = 84000;
+/** Demo portfolio: $5M, 35% BTC, $25K/mo burn, $600K liquid reserve */
+export const DEMO_PORTFOLIO = {
+    totalValueUsd: 5_000_000,
+    btcPercentage: 35,
+    monthlyBurnUsd: 25_000,
+    liquidReserveUsd: 600_000,
+    btcPriceUsd: DEMO_BTC_PRICE,
+};
+/** Demo hedge positions (optional — shows with vs without insurance) */
+export const DEMO_HEDGE_POSITIONS = [
+    {
+        strikeUsd: 60_000,
+        quantityBtc: 10,
+        expiryDate: "2026-09-30",
+    },
+];
+/** Portfolio with no hedge — for comparison */
+export const DEMO_PORTFOLIO_NO_HEDGE = [];
+//# sourceMappingURL=demo-portfolio.js.map

package/dist/fixtures/demo-portfolio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-portfolio.js","sourceRoot":"","sources":["../../src/fixtures/demo-portfolio.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,kDAAkD;AAClD,gFAAgF;AAEhF,wDAAwD;AACxD,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AAEpC,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC7C,aAAa,EAAE,SAAS;IACxB,aAAa,EAAE,EAAE;IACjB,cAAc,EAAE,MAAM;IACtB,gBAAgB,EAAE,OAAO;IACzB,WAAW,EAAE,cAAc;CAC3B,CAAC;AAEF,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAoB;IACpD;QACC,SAAS,EAAE,MAAM;QACjB,WAAW,EAAE,EAAE;QACf,UAAU,EAAE,YAAY;KACxB;CACD,CAAC;AAEF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,uBAAuB,GAAoB,EAAE,CAAC"}

package/dist/geometric-mean.d.ts

@@ -0,0 +1,21 @@
+import type { GeometricMeanResult } from "./types.js";
+/**
+ * Compare hedged vs unhedged CAGR over a crash cycle.
+ *
+ * Model: (n-1) good years at normalReturn, then 1 crash year.
+ * Hedge costs annualCost each year but recovers a fraction of crash loss.
+ *
+ * Ported from open-fo calculateGeometricMeanCAGR.
+ */
+export declare function calculateGeometricMeanCAGR(normalReturn: number, annualCost: number, crashMagnitude: number, recoveryOfLoss: number, cycleLength: number): GeometricMeanResult;
+/**
+ * Find the max cycle length where hedge improves CAGR (break-even point).
+ * Lower = better (crash only needs to happen once every N years to justify hedge).
+ *
+ * Ported from open-fo calculateGeometricBreakeven.
+ */
+export declare function calculateGeometricBreakeven(annualCost: number, recoveryOfLoss: number, crashMagnitude?: number, normalReturn?: number): {
+    breakEvenYears: number | null;
+    annualProbability: number | null;
+};
+//# sourceMappingURL=geometric-mean.d.ts.map

package/dist/geometric-mean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometric-mean.d.ts","sourceRoot":"","sources":["../src/geometric-mean.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMtD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GACjB,mBAAmB,CA6BrB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAC1C,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,cAAc,SAAM,EACpB,YAAY,SAAO,GACjB;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiCrE"}

package/dist/geometric-mean.js

@@ -0,0 +1,72 @@
+// =============================================================================
+// Geometric Mean CAGR (Spitznagel Safe Haven Framework)
+// =============================================================================
+/**
+ * Compare hedged vs unhedged CAGR over a crash cycle.
+ *
+ * Model: (n-1) good years at normalReturn, then 1 crash year.
+ * Hedge costs annualCost each year but recovers a fraction of crash loss.
+ *
+ * Ported from open-fo calculateGeometricMeanCAGR.
+ */
+export function calculateGeometricMeanCAGR(normalReturn, annualCost, crashMagnitude, recoveryOfLoss, cycleLength) {
+    const recoveryValue = recoveryOfLoss * crashMagnitude;
+    // Unhedged: (n-1) normal years then one crash year
+    const unhedgedGrowth = Math.pow(1 + normalReturn, cycleLength - 1) * (1 - crashMagnitude);
+    const unhedgedCAGR = Math.pow(unhedgedGrowth, 1 / cycleLength) - 1;
+    // Hedged: (n-1) normal years minus cost, then crash year with recovery
+    const hedgedGrowth = Math.pow(1 + normalReturn - annualCost, cycleLength - 1) *
+        (1 - crashMagnitude + recoveryValue);
+    const hedgedCAGR = Math.pow(hedgedGrowth, 1 / cycleLength) - 1;
+    const improvement = hedgedCAGR - unhedgedCAGR;
+    return {
+        unhedgedCAGR,
+        hedgedCAGR,
+        improvement,
+        isPositiveEV: improvement > 0,
+        assumptions: {
+            normalReturn,
+            crashMagnitude,
+            cycleLength,
+            annualCost,
+            recoveryPercent: recoveryOfLoss,
+        },
+    };
+}
+/**
+ * Find the max cycle length where hedge improves CAGR (break-even point).
+ * Lower = better (crash only needs to happen once every N years to justify hedge).
+ *
+ * Ported from open-fo calculateGeometricBreakeven.
+ */
+export function calculateGeometricBreakeven(annualCost, recoveryOfLoss, crashMagnitude = 0.5, normalReturn = 0.15) {
+    if (annualCost <= 0) {
+        return { breakEvenYears: 1, annualProbability: 100 };
+    }
+    let lo = 2;
+    let hi = 200;
+    const atMin = calculateGeometricMeanCAGR(normalReturn, annualCost, crashMagnitude, recoveryOfLoss, lo);
+    if (atMin.improvement <= 0) {
+        return { breakEvenYears: null, annualProbability: null };
+    }
+    const atMax = calculateGeometricMeanCAGR(normalReturn, annualCost, crashMagnitude, recoveryOfLoss, hi);
+    if (atMax.improvement > 0) {
+        return { breakEvenYears: 200, annualProbability: 0.5 };
+    }
+    for (let i = 0; i < 50; i++) {
+        const mid = (lo + hi) / 2;
+        const result = calculateGeometricMeanCAGR(normalReturn, annualCost, crashMagnitude, recoveryOfLoss, mid);
+        if (result.improvement > 0) {
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    const breakEvenYears = Math.round(lo);
+    return {
+        breakEvenYears,
+        annualProbability: breakEvenYears > 0 ? (1 / breakEvenYears) * 100 : null,
+    };
+}
+//# sourceMappingURL=geometric-mean.js.map

package/dist/geometric-mean.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { PortfolioInput, HedgePosition, CrashScenario, SurvivalResult, CrashSurvivalConfig, GeometricMeanResult, } from "./types.js";
+export { calculateCrashSurvival, calculatePriceScenarios, DEFAULT_CONFIG } from "./crash-survival.js";
+export { calculateRunwayMonths } from "./runway.js";
+export { ruinTest } from "./ruin-test.js";
+export { calculateGeometricMeanCAGR, calculateGeometricBreakeven } from "./geometric-mean.js";
+export { DEMO_PORTFOLIO, DEMO_HEDGE_POSITIONS, DEMO_BTC_PRICE } from "./fixtures/demo-portfolio.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// =============================================================================
+// @timecell/engine — Public API
+// =============================================================================
+export { calculateCrashSurvival, calculatePriceScenarios, DEFAULT_CONFIG } from "./crash-survival.js";
+export { calculateRunwayMonths } from "./runway.js";
+export { ruinTest } from "./ruin-test.js";
+export { calculateGeometricMeanCAGR, calculateGeometricBreakeven } from "./geometric-mean.js";
+export { DEMO_PORTFOLIO, DEMO_HEDGE_POSITIONS, DEMO_BTC_PRICE } from "./fixtures/demo-portfolio.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,gCAAgC;AAChC,gFAAgF;AAWhF,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/ruin-test.d.ts

@@ -0,0 +1,17 @@
+import type { PortfolioInput, HedgePosition } from "./types.js";
+/**
+ * The Ruin Test from Bitcoin Investing Framework v2:
+ *
+ * "If Bitcoin drops 80% AND your other assets drop 40% simultaneously
+ *  — as happened in 2022 — do you survive? Can you meet all obligations?"
+ *
+ * Returns true if you survive the worst-case correlated crash.
+ */
+export declare function ruinTest(portfolio: PortfolioInput, hedgePositions?: HedgePosition[]): {
+    passed: boolean;
+    runwayMonths: number;
+    portfolioValueAfterCrash: number;
+    netPosition: number;
+    hedgePayoff: number;
+};
+//# sourceMappingURL=ruin-test.d.ts.map

package/dist/ruin-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruin-test.d.ts","sourceRoot":"","sources":["../src/ruin-test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACvB,SAAS,EAAE,cAAc,EACzB,cAAc,GAAE,aAAa,EAAO,GAClC;IACF,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB,EAAE,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACpB,CAWA"}

package/dist/ruin-test.js

@@ -0,0 +1,24 @@
+import { calculateCrashSurvival } from "./crash-survival.js";
+// =============================================================================
+// Ruin Test (Framework Part 3, Step 3)
+// =============================================================================
+/**
+ * The Ruin Test from Bitcoin Investing Framework v2:
+ *
+ * "If Bitcoin drops 80% AND your other assets drop 40% simultaneously
+ *  — as happened in 2022 — do you survive? Can you meet all obligations?"
+ *
+ * Returns true if you survive the worst-case correlated crash.
+ */
+export function ruinTest(portfolio, hedgePositions = []) {
+    const result = calculateCrashSurvival(portfolio, hedgePositions, { drawdowns: [80] });
+    const scenario = result.scenarios[0];
+    return {
+        passed: scenario.survivalStatus !== "critical",
+        runwayMonths: scenario.runwayMonths,
+        portfolioValueAfterCrash: scenario.portfolioValueAfterCrash,
+        netPosition: scenario.netPosition,
+        hedgePayoff: scenario.hedgePayoff,
+    };
+}
+//# sourceMappingURL=ruin-test.js.map

package/dist/ruin-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruin-test.js","sourceRoot":"","sources":["../src/ruin-test.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,gFAAgF;AAChF,uCAAuC;AACvC,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACvB,SAAyB,EACzB,iBAAkC,EAAE;IAQpC,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,EAAE,cAAc,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACtF,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAErC,OAAO;QACN,MAAM,EAAE,QAAQ,CAAC,cAAc,KAAK,UAAU;QAC9C,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,wBAAwB,EAAE,QAAQ,CAAC,wBAAwB;QAC3D,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,WAAW,EAAE,QAAQ,CAAC,WAAW;KACjC,CAAC;AACH,CAAC"}

package/dist/runway.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Calculate runway in months: how long can you sustain current burn
+ * from available liquidity without selling assets.
+ */
+export declare function calculateRunwayMonths(availableLiquidity: number, monthlyBurn: number): number;
+//# sourceMappingURL=runway.d.ts.map

package/dist/runway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runway.d.ts","sourceRoot":"","sources":["../src/runway.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,MAAM,GACjB,MAAM,CAIR"}

package/dist/runway.js

@@ -0,0 +1,15 @@
+// =============================================================================
+// Runway Calculator
+// =============================================================================
+/**
+ * Calculate runway in months: how long can you sustain current burn
+ * from available liquidity without selling assets.
+ */
+export function calculateRunwayMonths(availableLiquidity, monthlyBurn) {
+    if (monthlyBurn <= 0)
+        return Infinity;
+    if (availableLiquidity <= 0)
+        return 0;
+    return availableLiquidity / monthlyBurn;
+}
+//# sourceMappingURL=runway.js.map

package/dist/runway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runway.js","sourceRoot":"","sources":["../src/runway.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACpC,kBAA0B,EAC1B,WAAmB;IAEnB,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtC,IAAI,kBAAkB,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,OAAO,kBAAkB,GAAG,WAAW,CAAC;AACzC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/** User's portfolio configuration */
+export interface PortfolioInput {
+    totalValueUsd: number;
+    btcPercentage: number;
+    monthlyBurnUsd: number;
+    liquidReserveUsd: number;
+    btcPriceUsd: number;
+}
+/** Optional hedge position (put option) */
+export interface HedgePosition {
+    strikeUsd: number;
+    quantityBtc: number;
+    expiryDate?: string;
+}
+/** Result for a single crash scenario */
+export interface CrashScenario {
+    drawdownPct: number;
+    btcPriceAtCrash: number;
+    btcValueAfterCrash: number;
+    nonBtcValueAfterCrash: number;
+    portfolioValueAfterCrash: number;
+    hedgePayoff: number;
+    netPosition: number;
+    runwayMonths: number;
+    survivalStatus: "safe" | "warning" | "critical";
+}
+/** Full survival analysis result */
+export interface SurvivalResult {
+    portfolio: PortfolioInput;
+    scenarios: CrashScenario[];
+    maxSurvivableDrawdown: number;
+    ruinTestPassed: boolean;
+}
+/** Configuration for crash survival calculations */
+export interface CrashSurvivalConfig {
+    drawdowns: number[];
+    nonBtcCorrelation: number;
+    runwayWarningMonths: number;
+    runwayCriticalMonths: number;
+}
+/** Geometric mean CAGR comparison (hedged vs unhedged) */
+export interface GeometricMeanResult {
+    unhedgedCAGR: number;
+    hedgedCAGR: number;
+    improvement: number;
+    isPositiveEV: boolean;
+    assumptions: {
+        normalReturn: number;
+        crashMagnitude: number;
+        cycleLength: number;
+        annualCost: number;
+        recoveryPercent: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wBAAwB,EAAE,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;CAChD;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,cAAc,CAAC;IAC1B,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE;QACZ,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,eAAe,EAAE,MAAM,CAAC;KACxB,CAAC;CACF"}

package/dist/types.js

@@ -0,0 +1,5 @@
+// =============================================================================
+// Core Types for TimeCell Engine
+// =============================================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@timecell/engine",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TimeCell core engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "latest"
+  }
+}