@timecell/engine 0.1.1 → 0.2.0

package/dist/action-plan.d.ts

@@ -0,0 +1,17 @@
+export interface ActionPlanInput {
+    btcPercentage: number;
+    ruinTestPassed: boolean;
+    runwayMonths: number;
+    temperatureScore: number;
+    liquidReserveUsd: number;
+    monthlyBurnUsd: number;
+    totalValueUsd: number;
+}
+export type ActionSeverity = "red" | "amber" | "green";
+export interface ActionItem {
+    severity: ActionSeverity;
+    message: string;
+    rule: string;
+}
+export declare function generateActionPlan(input: ActionPlanInput): ActionItem[];
+//# sourceMappingURL=action-plan.d.ts.map

package/dist/action-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-plan.d.ts","sourceRoot":"","sources":["../src/action-plan.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,eAAe;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACb;AAgBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,EAAE,CAsIvE"}

package/dist/action-plan.js

@@ -0,0 +1,121 @@
+// =============================================================================
+// Action Plan Engine (Framework-Driven Priorities)
+// =============================================================================
+// Evaluates portfolio state against the Bitcoin Investing Framework rules and
+// returns a prioritised list of actionable items (red / amber / green).
+// ---------------------------------------------------------------------------
+// Severity sort order
+// ---------------------------------------------------------------------------
+const SEVERITY_ORDER = {
+    red: 0,
+    amber: 1,
+    green: 2,
+};
+// ---------------------------------------------------------------------------
+// Rule evaluator
+// ---------------------------------------------------------------------------
+export function generateActionPlan(input) {
+    const { btcPercentage, ruinTestPassed, runwayMonths, temperatureScore, liquidReserveUsd, } = input;
+    const items = [];
+    // ---- Red (act now) ----
+    if (!ruinTestPassed) {
+        items.push({
+            severity: "red",
+            message: "Reduce BTC allocation until ruin test passes. Your portfolio does not survive an 80% crash.",
+            rule: "ruin-test",
+        });
+    }
+    if (temperatureScore > 75) {
+        items.push({
+            severity: "red",
+            message: "Extreme greed zone. Stop buying. Consider activating selling rules.",
+            rule: "temperature-extreme-greed",
+        });
+    }
+    if (liquidReserveUsd <= 0) {
+        items.push({
+            severity: "red",
+            message: "No liquid reserve. Build a safety net: 2+ years of expenses outside BTC.",
+            rule: "no-reserve",
+        });
+    }
+    if (runwayMonths < 18) {
+        items.push({
+            severity: "red",
+            message: `Insufficient runway (${runwayMonths === Infinity ? "unlimited" : Math.round(runwayMonths)} months). Need 18+ months. Increase liquid reserve or reduce BTC allocation.`,
+            rule: "insufficient-runway",
+        });
+    }
+    // ---- Amber (consider) ----
+    if (btcPercentage >= 25) {
+        items.push({
+            severity: "amber",
+            message: `At ${btcPercentage}% BTC, conviction gates should be checked: multi-cycle experience, 2yr expenses outside BTC, no forced-sale liabilities.`,
+            rule: "conviction-gates",
+        });
+    }
+    if (btcPercentage >= 50) {
+        items.push({
+            severity: "amber",
+            message: `Downside insurance recommended at ${btcPercentage}% allocation (Framework Part 6).`,
+            rule: "insurance-needed",
+        });
+    }
+    if (temperatureScore < 20) {
+        items.push({
+            severity: "amber",
+            message: "Extreme fear zone. Historically the best time to accumulate. Consider lump sum if conviction is high.",
+            rule: "temperature-extreme-fear",
+        });
+    }
+    if (temperatureScore >= 60 && temperatureScore <= 75) {
+        items.push({
+            severity: "amber",
+            message: "Greed zone. Slow down buying. Review your risk management and de-risk triggers.",
+            rule: "temperature-greed",
+        });
+    }
+    // ---- Green (on track) ----
+    if (ruinTestPassed && runwayMonths >= 18) {
+        items.push({
+            severity: "green",
+            message: `Ruin test passed. You survive the worst-case crash with ${runwayMonths === Infinity ? "unlimited" : Math.round(runwayMonths)} months runway.`,
+            rule: "ruin-test-passed",
+        });
+    }
+    if (temperatureScore >= 20 && temperatureScore < 40) {
+        items.push({
+            severity: "green",
+            message: "Fear zone. Good time to DCA aggressively.",
+            rule: "temperature-fear",
+        });
+    }
+    if (temperatureScore >= 40 && temperatureScore < 60) {
+        items.push({
+            severity: "green",
+            message: "Neutral zone. Continue DCA at normal pace.",
+            rule: "temperature-neutral",
+        });
+    }
+    // ---- Sort: red first, then amber, then green ----
+    items.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    // ---- Limit to 5 items (truncate greens first, then ambers) ----
+    if (items.length > 5) {
+        // Count by severity
+        const reds = items.filter((i) => i.severity === "red");
+        const ambers = items.filter((i) => i.severity === "amber");
+        const greens = items.filter((i) => i.severity === "green");
+        // Trim greens first, then ambers if still over
+        const budget = 5;
+        const redCount = reds.length;
+        const amberBudget = Math.min(ambers.length, budget - redCount);
+        const greenBudget = Math.min(greens.length, budget - redCount - amberBudget);
+        return [
+            ...reds.slice(0, budget),
+            ...ambers.slice(0, amberBudget),
+            ...greens.slice(0, greenBudget),
+        ].slice(0, 5);
+    }
+    return items;
+}
+//# sourceMappingURL=action-plan.js.map

package/dist/action-plan.js.map

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

package/dist/index.d.ts

@@ -4,4 +4,10 @@ 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";
+export type { TemperatureResult } from "./temperature.js";
+export { calculateTemperature, scoreToZone } from "./temperature.js";
+export { calculatePositionSizing, getConvictionRung, } from "./position-sizing.js";
+export type { PositionSizingInput, PositionSizingResult } from "./position-sizing.js";
+export { generateActionPlan } from "./action-plan.js";
+export type { ActionPlanInput, ActionItem, ActionSeverity } from "./action-plan.js";
 //# 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":"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"}
+{"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;AACpG,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACN,uBAAuB,EACvB,iBAAiB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -6,4 +6,7 @@ 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";
+export { calculateTemperature, scoreToZone } from "./temperature.js";
+export { calculatePositionSizing, getConvictionRung, } from "./position-sizing.js";
+export { generateActionPlan } from "./action-plan.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"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;AAEpG,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACN,uBAAuB,EACvB,iBAAiB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/position-sizing.d.ts

@@ -0,0 +1,42 @@
+export declare function getConvictionRung(btcPct: number): string;
+export interface PositionSizingInput {
+    totalValueUsd: number;
+    currentBtcPct: number;
+    targetBtcPct: number;
+    monthlyBurnUsd: number;
+    liquidReserveUsd: number;
+    btcPriceUsd: number;
+    dcaMonths?: number;
+}
+export interface PositionSizingResult {
+    /** Current BTC exposure in USD */
+    currentBtcUsd: number;
+    /** Target BTC exposure in USD */
+    targetBtcUsd: number;
+    /** Amount to buy (positive) or sell (negative) in USD */
+    gapUsd: number;
+    /** Amount to buy (positive) or sell (negative) in BTC */
+    gapBtc: number;
+    /** If DCA: monthly buy/sell amount in USD */
+    dcaMonthlyUsd: number;
+    /** If DCA: monthly buy/sell amount in BTC */
+    dcaMonthlyBtc: number;
+    /** Number of DCA months used in calculation */
+    dcaMonths: number;
+    /** Whether the ruin test passes after reallocation */
+    postReallocationRuinTest: boolean;
+    /** Post-reallocation runway (months) */
+    postReallocationRunwayMonths: number;
+    /** Conviction ladder rung name for the TARGET allocation */
+    convictionRung: string;
+    /** Conviction ladder rung name for the CURRENT allocation */
+    currentConvictionRung: string;
+}
+/**
+ * Calculate position sizing: gap analysis, DCA schedule, and post-reallocation
+ * ruin test for moving from current BTC% to target BTC%.
+ *
+ * Pure function — no side effects.
+ */
+export declare function calculatePositionSizing(input: PositionSizingInput): PositionSizingResult;
+//# sourceMappingURL=position-sizing.d.ts.map

package/dist/position-sizing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-sizing.d.ts","sourceRoot":"","sources":["../src/position-sizing.ts"],"names":[],"mappings":"AAqBA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKxD;AAMD,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,wBAAwB,EAAE,OAAO,CAAC;IAClC,wCAAwC;IACxC,4BAA4B,EAAE,MAAM,CAAC;IACrC,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAkDxF"}

package/dist/position-sizing.js

@@ -0,0 +1,71 @@
+// =============================================================================
+// Position Sizing (Framework Part 3)
+// =============================================================================
+// Determines how to move from current BTC allocation to target allocation,
+// including DCA strategy and post-reallocation ruin test.
+import { ruinTest } from "./ruin-test.js";
+// -----------------------------------------------------------------------------
+// Conviction ladder rung thresholds (mirrors ConvictionLadder.tsx)
+// -----------------------------------------------------------------------------
+const RUNGS = [
+    { level: 6, name: "Single-Asset Core", min: 50 },
+    { level: 5, name: "Owner-Class", min: 25 },
+    { level: 4, name: "High Conviction", min: 10 },
+    { level: 3, name: "Diversifier", min: 5 },
+    { level: 2, name: "Experimenter", min: 1 },
+    { level: 1, name: "Observer", min: 0 },
+];
+export function getConvictionRung(btcPct) {
+    for (const rung of RUNGS) {
+        if (btcPct >= rung.min)
+            return rung.name;
+    }
+    return "Observer";
+}
+// -----------------------------------------------------------------------------
+// Core calculation
+// -----------------------------------------------------------------------------
+/**
+ * Calculate position sizing: gap analysis, DCA schedule, and post-reallocation
+ * ruin test for moving from current BTC% to target BTC%.
+ *
+ * Pure function — no side effects.
+ */
+export function calculatePositionSizing(input) {
+    const { totalValueUsd, currentBtcPct, targetBtcPct, monthlyBurnUsd, liquidReserveUsd, btcPriceUsd, dcaMonths = 6, } = input;
+    // Absolute USD values
+    const currentBtcUsd = totalValueUsd * (currentBtcPct / 100);
+    const targetBtcUsd = totalValueUsd * (targetBtcPct / 100);
+    // Gap: positive = need to buy more BTC, negative = need to sell BTC
+    const gapUsd = targetBtcUsd - currentBtcUsd;
+    const gapBtc = btcPriceUsd > 0 ? gapUsd / btcPriceUsd : 0;
+    // DCA breakdown
+    const months = Math.max(1, dcaMonths);
+    const dcaMonthlyUsd = gapUsd / months;
+    const dcaMonthlyBtc = btcPriceUsd > 0 ? dcaMonthlyUsd / btcPriceUsd : 0;
+    // Post-reallocation ruin test
+    // After fully reallocating, portfolio still has the same totalValue —
+    // we just re-run the ruin test with the target BTC%.
+    const postPortfolio = {
+        totalValueUsd,
+        btcPercentage: targetBtcPct,
+        monthlyBurnUsd,
+        liquidReserveUsd,
+        btcPriceUsd,
+    };
+    const ruinResult = ruinTest(postPortfolio);
+    return {
+        currentBtcUsd,
+        targetBtcUsd,
+        gapUsd,
+        gapBtc,
+        dcaMonthlyUsd,
+        dcaMonthlyBtc,
+        dcaMonths: months,
+        postReallocationRuinTest: ruinResult.passed,
+        postReallocationRunwayMonths: ruinResult.runwayMonths,
+        convictionRung: getConvictionRung(targetBtcPct),
+        currentConvictionRung: getConvictionRung(currentBtcPct),
+    };
+}
+//# sourceMappingURL=position-sizing.js.map

package/dist/position-sizing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-sizing.js","sourceRoot":"","sources":["../src/position-sizing.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qCAAqC;AACrC,gFAAgF;AAChF,2EAA2E;AAC3E,0DAA0D;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,gFAAgF;AAChF,mEAAmE;AACnE,gFAAgF;AAChF,MAAM,KAAK,GAAG;IACb,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,EAAE,EAAE;IAChD,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,EAAE,EAAE;IAC1C,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,EAAE,EAAE;IAC9C,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE;IACzC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE;IAC1C,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,EAAE;CAC7B,CAAC;AAEX,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC/C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC1C,CAAC;IACD,OAAO,UAAU,CAAC;AACnB,CAAC;AAyCD,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAA0B;IACjE,MAAM,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,SAAS,GAAG,CAAC,GACb,GAAG,KAAK,CAAC;IAEV,sBAAsB;IACtB,MAAM,aAAa,GAAG,aAAa,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC;IAC5D,MAAM,YAAY,GAAG,aAAa,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC;IAE1D,oEAAoE;IACpE,MAAM,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAC5C,MAAM,MAAM,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1D,gBAAgB;IAChB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC,MAAM,aAAa,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAExE,8BAA8B;IAC9B,sEAAsE;IACtE,qDAAqD;IACrD,MAAM,aAAa,GAAmB;QACrC,aAAa;QACb,aAAa,EAAE,YAAY;QAC3B,cAAc;QACd,gBAAgB;QAChB,WAAW;KACX,CAAC;IAEF,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAE3C,OAAO;QACN,aAAa;QACb,YAAY;QACZ,MAAM;QACN,MAAM;QACN,aAAa;QACb,aAAa;QACb,SAAS,EAAE,MAAM;QACjB,wBAAwB,EAAE,UAAU,CAAC,MAAM;QAC3C,4BAA4B,EAAE,UAAU,CAAC,YAAY;QACrD,cAAc,EAAE,iBAAiB,CAAC,YAAY,CAAC;QAC/C,qBAAqB,EAAE,iBAAiB,CAAC,aAAa,CAAC;KACvD,CAAC;AACH,CAAC"}

package/dist/temperature.d.ts

@@ -0,0 +1,18 @@
+export interface TemperatureResult {
+    score: number;
+    zone: "Extreme Fear" | "Fear" | "Neutral" | "Greed" | "Extreme Greed";
+    mvrv: number;
+    rhodl: number;
+}
+/**
+ * Derive a 0–100 temperature score from raw MVRV and RHODL ratios.
+ *
+ * Normalization ranges (approximate historical bounds):
+ *   MVRV:  0.5 → 0,  4.5 → 100
+ *   RHODL: 0.5 → 0,  4.5 → 100  (RHODL ratio uses similar scale)
+ *
+ * Weighted composite: 60% MVRV + 40% RHODL, clamped to [0, 100].
+ */
+export declare function calculateTemperature(mvrv: number, rhodl: number): TemperatureResult;
+export declare function scoreToZone(score: number): TemperatureResult["zone"];
+//# sourceMappingURL=temperature.d.ts.map

package/dist/temperature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temperature.d.ts","sourceRoot":"","sources":["../src/temperature.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,eAAe,CAAC;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAcnF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAMpE"}

package/dist/temperature.js

@@ -0,0 +1,37 @@
+// =============================================================================
+// Temperature — Composite Bitcoin cycle position score
+// =============================================================================
+// Score: MVRV (60%) + RHODL (40%), normalized to 0–100
+// Zones: Extreme Fear / Fear / Neutral / Greed / Extreme Greed
+/**
+ * Derive a 0–100 temperature score from raw MVRV and RHODL ratios.
+ *
+ * Normalization ranges (approximate historical bounds):
+ *   MVRV:  0.5 → 0,  4.5 → 100
+ *   RHODL: 0.5 → 0,  4.5 → 100  (RHODL ratio uses similar scale)
+ *
+ * Weighted composite: 60% MVRV + 40% RHODL, clamped to [0, 100].
+ */
+export function calculateTemperature(mvrv, rhodl) {
+    const MVRV_MIN = 0.5;
+    const MVRV_MAX = 4.5;
+    const RHODL_MIN = 0.5;
+    const RHODL_MAX = 4.5;
+    const mvrvNorm = Math.max(0, Math.min(100, ((mvrv - MVRV_MIN) / (MVRV_MAX - MVRV_MIN)) * 100));
+    const rhodlNorm = Math.max(0, Math.min(100, ((rhodl - RHODL_MIN) / (RHODL_MAX - RHODL_MIN)) * 100));
+    const score = Math.round(mvrvNorm * 0.6 + rhodlNorm * 0.4);
+    const zone = scoreToZone(score);
+    return { score, zone, mvrv, rhodl };
+}
+export function scoreToZone(score) {
+    if (score < 20)
+        return "Extreme Fear";
+    if (score < 40)
+        return "Fear";
+    if (score < 60)
+        return "Neutral";
+    if (score < 75)
+        return "Greed";
+    return "Extreme Greed";
+}
+//# sourceMappingURL=temperature.js.map

package/dist/temperature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temperature.js","sourceRoot":"","sources":["../src/temperature.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,uDAAuD;AACvD,gFAAgF;AAChF,uDAAuD;AACvD,+DAA+D;AAS/D;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,KAAa;IAC/D,MAAM,QAAQ,GAAG,GAAG,CAAC;IACrB,MAAM,QAAQ,GAAG,GAAG,CAAC;IACrB,MAAM,SAAS,GAAG,GAAG,CAAC;IACtB,MAAM,SAAS,GAAG,GAAG,CAAC;IAEtB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC/F,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAEpG,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,GAAG,GAAG,SAAS,GAAG,GAAG,CAAC,CAAC;IAE3D,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEhC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACxC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,cAAc,CAAC;IACtC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IACjC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,OAAO,CAAC;IAC/B,OAAO,eAAe,CAAC;AACxB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timecell/engine",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "TimeCell core engine",
   "main": "dist/index.js",