aiden-shared-calculations-unified 1.0.25 → 1.0.26

package/calculations/meta/capital_liquidation_performance.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) that tracks the performance
+ * of assets that were heavily liquidated (sold) by the crowd to fund
+ * a withdrawal event.
+ *
+ * This answers: "After the crowd sold an asset to withdraw cash,
+ * did that asset recover (implying a panic-sell) or
+ * continue to fall (implying a smart exit)?"
+ */
+
+class CapitalLiquidationPerformance {
+    constructor() {
+        // How many days to look back/forward to measure performance
+        this.PERFORMANCE_WINDOW_DAYS = 7;
+        this.dependenciesLoaded = false;
+        this.priceMap = null;
+        this.tickerToIdMap = null;
+    }
+
+    /**
+     * Helper to load all dependencies in parallel
+     */
+    async _loadDependencies(calculationUtils) {
+        if (this.dependenciesLoaded) return;
+
+        const { loadAllPriceData, loadInstrumentMappings } = calculationUtils;
+
+        const [priceData, mappings] = await Promise.all([
+            loadAllPriceData(),
+            loadInstrumentMappings()
+        ]);
+
+        this.priceMap = priceData;
+
+        // Create a reverse map for easy lookup
+        this.tickerToIdMap = {};
+        if (mappings && mappings.instrumentToTicker) {
+            for (const [id, ticker] of Object.entries(mappings.instrumentToTicker)) {
+                this.tickerToIdMap[ticker] = id;
+            }
+        }
+
+        this.dependenciesLoaded = true;
+    }
+
+    /**
+     * Helper to get a date string X days from a base date
+     */
+    _getDateStr(baseDateStr, daysOffset) {
+        const date = new Date(baseDateStr + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() + daysOffset);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * Helper to calculate the average return of a basket of assets
+     * over a specified period.
+     */
+    _calculateBasketPerformance(assets, startDateStr, endDateStr) {
+        if (!assets || assets.length === 0) {
+            return 0;
+        }
+
+        let totalReturn = 0;
+        let validAssets = 0;
+
+        for (const asset of assets) {
+            const ticker = asset.ticker;
+            const instrumentId = this.tickerToIdMap[ticker];
+
+            if (!instrumentId || !this.priceMap[instrumentId]) {
+                continue; // No price data for this ticker
+            }
+
+            const startPrice = this.priceMap[instrumentId][startDateStr];
+            const endPrice = this.priceMap[instrumentId][endDateStr];
+
+            if (startPrice && endPrice && startPrice > 0) {
+                const assetReturn = (endPrice - startPrice) / startPrice;
+                totalReturn += assetReturn;
+                validAssets++;
+            }
+        }
+
+        if (validAssets === 0) return 0;
+        return (totalReturn / validAssets) * 100; // Return as percentage
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger, calculationUtils).
+     * @param {object} config The computation system configuration.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger, calculationUtils } = dependencies;
+
+        // 1. Load all price/mapping data
+        await this._loadDependencies(calculationUtils);
+
+        // 2. Define and fetch dependency: cash-flow-liquidation
+        const depRef = db.collection(config.resultsCollection).doc(dateStr)
+            .collection('results').doc('meta')
+            .collection('computations').doc('cash-flow-liquidation'); // <-- This is the dependency
+
+        const snapshot = await depRef.get();
+
+        if (!snapshot.exists || snapshot.data().status !== 'analysis_complete') {
+            logger.log('WARN', `[CapitalLiquidation] Skipping ${dateStr}, no valid 'cash-flow-liquidation' data found.`);
+            return null;
+        }
+
+        const data = snapshot.data();
+        // This is the key change: we get the list of *sold* assets
+        const topAssets = data.top_liquidation_assets; // [{ ticker: 'MSFT', ... }]
+        const signalDate = data.signal_date; // The day the withdrawal signal occurred
+        const liquidationDate = data.analysis_date; // The day the capital was sold (dateStr)
+
+        if (!topAssets || topAssets.length === 0) {
+             logger.log('INFO', `[CapitalLiquidation] No top assets liquidated on ${dateStr}.`);
+             return { status: 'no_liquidation' };
+        }
+
+        // 3. Define performance windows
+        // "Before" window: 7 days leading up to the signal
+        const preSignalStart = this._getDateStr(signalDate, -this.PERFORMANCE_WINDOW_DAYS);
+        const preSignalEnd = signalDate;
+        
+        // "After" window: 7 days starting from the liquidation
+        const postLiquidationStart = liquidationDate;
+        const postLiquidationEnd = this._getDateStr(liquidationDate, this.PERFORMANCE_WINDOW_DAYS);
+
+        // 4. Calculate performance
+        const preSignalReturnPct = this._calculateBasketPerformance(
+            topAssets, preSignalStart, preSignalEnd
+        );
+        
+        const postLiquidationReturnPct = this._calculateBasketPerformance(
+            topAssets, postLiquidationStart, postLiquidationEnd
+        );
+        
+        // This answers the question:
+        // A positive value means the assets RECOVERED (crowd panic-sold at the bottom).
+        // A negative value means the assets CONTINUED TO FALL (crowd made a good exit).
+        const crowdTimingError = postLiquidationReturnPct; 
+
+        return {
+            status: 'analysis_complete',
+            signal_date: signalDate,
+            liquidation_date: liquidationDate,
+            performance_window_days: this.PERFORMANCE_WINDOW_DAYS,
+            liquidated_assets: topAssets.map(a => a.ticker),
+            pre_signal_return_pct: preSignalReturnPct,
+            post_liquidation_return_pct: postLiquidationReturnPct,
+            crowd_timing_error: crowdTimingError,
+            interpretation: "Measures the 7-day return of liquidated assets *after* being sold. Positive = asset recovered (bad timing). Negative = asset kept falling (good timing)."
+        };
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = CapitalLiquidationPerformance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-shared-calculations-unified",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "description": "Shared calculation modules for the BullTrackers Computation System.",
   "main": "index.js",
   "files": [