@timecell/engine 0.1.2 → 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":"AAAA,gFAAgF;AAChF,mDAAmD;AACnD,gFAAgF;AAChF,8EAA8E;AAC9E,wEAAwE;AAwBxE,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,cAAc,GAAmC;IACtD,GAAG,EAAE,CAAC;IACN,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;CACR,CAAC;AAEF,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,UAAU,kBAAkB,CAAC,KAAsB;IACxD,MAAM,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GAChB,GAAG,KAAK,CAAC;IAEV,MAAM,KAAK,GAAiB,EAAE,CAAC;IAE/B,0BAA0B;IAE1B,IAAI,CAAC,cAAc,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,KAAK;YACf,OAAO,EACN,6FAA6F;YAC9F,IAAI,EAAE,WAAW;SACjB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,GAAG,EAAE,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,KAAK;YACf,OAAO,EACN,qEAAqE;YACtE,IAAI,EAAE,2BAA2B;SACjC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,KAAK;YACf,OAAO,EACN,0EAA0E;YAC3E,IAAI,EAAE,YAAY;SAClB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,GAAG,EAAE,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,wBAAwB,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,8EAA8E;YACjL,IAAI,EAAE,qBAAqB;SAC3B,CAAC,CAAC;IACJ,CAAC;IAED,6BAA6B;IAE7B,IAAI,aAAa,IAAI,EAAE,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM,aAAa,0HAA0H;YACtJ,IAAI,EAAE,kBAAkB;SACxB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,IAAI,EAAE,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,qCAAqC,aAAa,kCAAkC;YAC7F,IAAI,EAAE,kBAAkB;SACxB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,GAAG,EAAE,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EACN,uGAAuG;YACxG,IAAI,EAAE,0BAA0B;SAChC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,IAAI,EAAE,IAAI,gBAAgB,IAAI,EAAE,EAAE,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EACN,iFAAiF;YAClF,IAAI,EAAE,mBAAmB;SACzB,CAAC,CAAC;IACJ,CAAC;IAED,6BAA6B;IAE7B,IAAI,cAAc,IAAI,YAAY,IAAI,EAAE,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,2DAA2D,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,iBAAiB;YACvJ,IAAI,EAAE,kBAAkB;SACxB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,IAAI,EAAE,IAAI,gBAAgB,GAAG,EAAE,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,2CAA2C;YACpD,IAAI,EAAE,kBAAkB;SACxB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,IAAI,EAAE,IAAI,gBAAgB,GAAG,EAAE,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC;YACV,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,4CAA4C;YACrD,IAAI,EAAE,qBAAqB;SAC3B,CAAC,CAAC;IACJ,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE9E,kEAAkE;IAClE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,oBAAoB;QACpB,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QAE3D,+CAA+C;QAC/C,MAAM,MAAM,GAAG,CAAC,CAAC;QACjB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;QAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;QAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,CAAC;QAE7E,OAAO;YACN,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC;YACxB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC;YAC/B,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC;SAC/B,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACf,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/index.d.ts

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

@@ -8,4 +8,5 @@ export { calculateGeometricMeanCAGR, calculateGeometricBreakeven } from "./geome
 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;AAEpG,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACN,uBAAuB,EACvB,iBAAiB,GACjB,MAAM,sBAAsB,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/package.json

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