aiden-shared-calculations-unified 1.0.14 → 1.0.16

package/calculations/behavioural/{asset_crowd_flow.js → historical/asset_crowd_flow.js}

@@ -1,5 +1,5 @@
-const { loadAllPriceData, getDailyPriceChange } = require('../../utils/price_data_provider');
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+const { loadAllPriceData, getDailyPriceChange } = require('../../../utils/price_data_provider');
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 /**
  * @fileoverview Calculates "Net Crowd Flow" for each asset.

package/calculations/behavioural/{smart_money_flow.js → historical/smart_money_flow.js}

@@ -5,7 +5,7 @@
 const { Firestore } = require('@google-cloud/firestore');
 const firestore = new Firestore();
 // CORRECTED PATH: ../utils/ instead of ../../utils/
-const { getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+const { getInstrumentSectorMap } = require('../../../utils/sector_mapping_provider');
 
 class SmartMoneyFlow {
     // ... (rest of the code is unchanged) ...

package/calculations/meta/cash-flow-liquidation.js

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Correlates a crowd-wide withdrawal signal with the specific assets
+ * that are being sold (liquidated) to fund those withdrawals.
+ * This is a meta-calculation that runs in Pass 3.
+ */
+
+const { FieldValue } = require('@google-cloud/firestore');
+
+class CashFlowLiquidation {
+    constructor() {
+        this.lookbackDays = 7;
+        this.correlationWindow = 3;
+        // A positive value signals a net crowd withdrawal
+        this.withdrawalSignalThreshold = 1.0; 
+    }
+
+    _getDateStr(baseDate, daysAgo) {
+        const date = new Date(baseDate + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() - daysAgo);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger).
+     * @param {object} config The computation system configuration.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+
+        // 1. Build all needed refs in advance for this day
+        const dateRefs = [];
+        const dates = [];
+
+        // Refs for the lookback period (for the signal)
+        for (let i = 1; i <= this.lookbackDays; i++) {
+            const checkDate = this._getDateStr(dateStr, i);
+            dates.push({ date: checkDate, category: 'capital_flow', computation: 'crowd-cash-flow-proxy' });
+        }
+
+        // Refs for today's two dependencies
+        dates.push({ date: dateStr, category: 'capital_flow', computation: 'crowd-cash-flow-proxy' });
+        dates.push({ date: dateStr, category: 'behavioural', computation: 'asset-crowd-flow' });
+
+        // Build refs array
+        const refs = dates.map(d =>
+            db.collection(collection).doc(d.date)
+                .collection('results').doc(d.category)
+                .collection('computations').doc(d.computation)
+        );
+
+        const snapshots = await db.getAll(...refs);
+
+        // Build map(path -> data)
+        const dataMap = new Map();
+        snapshots.forEach((snap, idx) => {
+            if (snap.exists) dataMap.set(idx, snap.data());
+        });
+
+        // 2. Find the withdrawal signal
+        let withdrawalSignal = null;
+        let withdrawalSignalDay = null;
+
+        for (let i = 0; i < this.lookbackDays; i++) {
+            const flowData = dataMap.get(i);
+            const dateUsed = dates[i].date;
+            // INVERTED LOGIC: Look for a POSITIVE value
+            if (flowData && flowData.cash_flow_effect_proxy > this.withdrawalSignalThreshold) {
+                withdrawalSignal = flowData;
+                withdrawalSignalDay = dateUsed;
+                break; // Found the most recent signal
+            }
+        }
+
+        if (!withdrawalSignal) {
+            return {
+                status: 'no_withdrawal_signal_found',
+                lookback_days: this.lookbackDays,
+                signal_threshold: this.withdrawalSignalThreshold
+            };
+        }
+
+        const daysSinceSignal = (new Date(dateStr) - new Date(withdrawalSignalDay)) / (1000 * 60 * 60 * 24);
+
+        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
+            return {
+                status: 'outside_correlation_window',
+                signal_day: withdrawalSignalDay,
+                days_since_signal: daysSinceSignal
+            };
+        }
+
+        // 3. Get today's data to find the correlation
+        const cashFlowData = dataMap.get(this.lookbackDays);
+        const assetFlowData = dataMap.get(this.lookbackDays + 1);
+
+        if (!cashFlowData || !assetFlowData) {
+            logger.log('WARN', `[CashFlowLiquidation] Missing dependency data for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        // 'trading_effect' will be negative if the crowd is net-selling
+        const netSellPct = cashFlowData.components?.trading_effect || 0;
+        const netWithdrawalPct = Math.abs(withdrawalSignal.cash_flow_effect_proxy);
+
+        // INVERTED LOGIC: Find top *sells*
+        const topLiquidations = Object.entries(assetFlowData)
+            .filter(([ticker, data]) => data.net_crowd_flow_pct < 0) // Find assets with negative flow
+            .sort(([, a], [, b]) => a.net_crowd_flow_pct - b.net_crowd_flow_pct) // Sort ascending (most negative first)
+            .slice(0, 10)
+            .map(([ticker, data]) => ({
+                ticker,
+                net_flow_pct: data.net_crowd_flow_pct
+            }));
+
+        return {
+            status: 'analysis_complete',
+            analysis_date: dateStr,
+            signal_date: withdrawalSignalDay,
+            days_since_signal: daysSinceSignal,
+            signal_withdrawal_proxy_pct: netWithdrawalPct,
+            day_net_sell_pct: netSellPct, // This value should be negative
+            pct_of_withdrawal_funded_today: (Math.abs(netSellPct) / netWithdrawalPct) * 100,
+            top_liquidation_assets: topLiquidations
+        };
+    }
+
+    // Must exist for the meta-computation runner
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = CashFlowLiquidation;

package/calculations/sectors/{diversification_pnl.js → historical/diversification_pnl.js}

@@ -1,5 +1,5 @@
 // CORRECTED PATH: ../utils/ instead of ../../utils/
-const { getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+const { getInstrumentSectorMap } = require('../../../utils/sector_mapping_provider');
 
 /**
  * Aggregates P/L by the number of unique sectors a user is invested in.

package/calculations/sectors/{sector_rotation.js → historical/sector_rotation.js}

@@ -2,7 +2,7 @@
  * @fileoverview Analyzes sector rotation by comparing investment amounts between two days.
  */
 // CORRECTED PATH: ../utils/ instead of ../../utils/
-const { getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+const { getInstrumentSectorMap } = require('../../../utils/sector_mapping_provider');
 
 class SectorRotation {
     // ... (rest of the code is unchanged) ...

package/calculations/sentiment/{crowd_conviction_score.js → historical/crowd_conviction_score.js}

@@ -2,7 +2,7 @@
  * @fileoverview Calculates a "Crowd Conviction" score for each instrument.
  */
 // CORRECTED PATH: ../utils/ instead of ../../utils/
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 
 class CrowdConvictionScore {

package/package.json

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