@timecell/engine 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -4,4 +4,8 @@ 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";
 //# 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"}

package/dist/index.js

@@ -6,4 +6,6 @@ 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";
 //# 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"}

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.1.2",
   "type": "module",
   "description": "TimeCell core engine",
   "main": "dist/index.js",