aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/meta/capital_liquidation_performance.js

@@ -1,136 +1,139 @@
 /**
- * @fileoverview Meta-calculation (Pass 3) that tracks the performance
- * of assets that were heavily liquidated (sold) by the crowd to fund
- * a withdrawal event.
+ * @fileoverview Calculation (Pass 4) for capital liquidation performance.
  *
- * --- META REFACTOR (v2) ---
- * This calculation is now stateless. It declares its dependencies and
- * expects them to be passed to its `process` method.
- * It still loads its own price data.
+ * This metric answers: "When users liquidate assets (net withdrawal),
+ * do they tend to sell winners or losers?"
+ *
+ * It *depends* on 'cash-flow-liquidation' (to get the list of
+ * liquidated assets) and 'asset_pnl_status' (to check the P&L
+ * status of those assets).
  */
-
 class CapitalLiquidationPerformance {
-
-    /**
-     * (NEW) Statically declare dependencies.
-     */
-    static getDependencies() {
-        return ['cash-flow-liquidation'];
-    }
-
     constructor() {
-        this.PERFORMANCE_WINDOW_DAYS = 7;
-        this.dependenciesLoaded = false;
-        this.priceMap = null;
-        this.tickerToIdMap = null;
-    }
-
-    async _loadDependencies(calculationUtils) {
-        if (this.dependenciesLoaded) return;
-        const { loadAllPriceData, loadInstrumentMappings } = calculationUtils;
-        const [priceData, mappings] = await Promise.all([
-            loadAllPriceData(),
-            loadInstrumentMappings()
-        ]);
-        this.priceMap = priceData;
-        this.tickerToIdMap = {};
-        if (mappings && mappings.instrumentToTicker) {
-            for (const [id, ticker] of Object.entries(mappings.instrumentToTicker)) {
-                this.tickerToIdMap[ticker] = id;
-            }
-        }
-        this.dependenciesLoaded = true;
-    }
-
-    _getDateStr(baseDateStr, daysOffset) {
-        const date = new Date(baseDateStr + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() + daysOffset);
-        return date.toISOString().slice(0, 10);
+        // No per-user processing needed
     }
 
-    _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;
-            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;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Analyzes if users sell winners or losers during net withdrawal events.",
+            "properties": {
+                "is_net_withdrawal_day": {
+                    "type": "boolean",
+                    "description": "True if today was a net withdrawal day."
+                },
+                "total_assets_liquidated": {
+                    "type": "number",
+                    "description": "The number of assets that saw net liquidation."
+                },
+                "assets_sold_at_profit_count": {
+                    "type": "number",
+                    "description": "Count of liquidated assets where the majority of users were in profit."
+                },
+                "assets_sold_at_loss_count": {
+                    "type": "number",
+                    "description": "Count of liquidated assets where the majority of users were in loss."
+                },
+                "winner_loser_sell_ratio": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of (Assets Sold at Profit / Assets Sold at Loss). Null if no assets sold at loss."
+                },
+                "details": {
+                    "type": "array",
+                    "description": "List of liquidated assets and their P&L status.",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "ticker": { "type": "string" },
+                            "net_flow_contribution": { "type": "number" },
+                            "status": { "type": "string", "enum": ["profit", "loss", "neutral"] },
+                            "profit_ratio": { "type": "number" }
+                        },
+                        "required": ["ticker", "net_flow_contribution", "status", "profit_ratio"]
+                    }
+                }
+            },
+            "required": ["is_net_withdrawal_day", "total_assets_liquidated", "assets_sold_at_profit_count", "assets_sold_at_loss_count", "winner_loser_sell_ratio", "details"]
+        };
     }
 
     /**
-     * REFACTORED PROCESS METHOD
-     * @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.
-     * @param {object} fetchedDependencies In-memory results from previous passes.
-     * @returns {Promise<object|null>} The analysis result or null.
+     * Statically declare dependencies.
      */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { db, logger, calculationUtils } = dependencies;
+    static getDependencies() {
+        return [
+            'cash-flow-liquidation', // Pass 3
+            'asset_pnl_status'       // Pass 1
+        ];
+    }
 
-        // 1. Load all price/mapping data
-        await this._loadDependencies(calculationUtils);
+    process() {
+        // No-op
+    }
 
-        // 2. Get dependency from `fetchedDependencies`
-        const data = fetchedDependencies['cash-flow-liquidation'];
+    getResult(fetchedDependencies) {
+        const liquidationData = fetchedDependencies['cash-flow-liquidation'];
+        const pnlStatusData = fetchedDependencies['asset_pnl_status'];
+
+        const defaults = {
+            is_net_withdrawal_day: false,
+            total_assets_liquidated: 0,
+            assets_sold_at_profit_count: 0,
+            assets_sold_at_loss_count: 0,
+            winner_loser_sell_ratio: null,
+            details: []
+        };
 
-        if (!data || data.status !== 'analysis_complete') {
-            logger.log('WARN', `[CapitalLiquidation] Skipping ${dateStr}, no valid 'cash-flow-liquidation' data found.`);
-            return null;
+        if (!liquidationData || !pnlStatusData || !liquidationData.is_net_withdrawal_day) {
+            return defaults;
         }
-        
-        const topAssets = data.top_liquidation_assets; // [{ ticker: 'MSFT', ... }]
-        const signalDate = data.signal_date;
-        const liquidationDate = data.analysis_date;
 
-        if (!topAssets || topAssets.length === 0) {
-             logger.log('INFO', `[CapitalLiquidation] No top assets liquidated on ${dateStr}.`);
-             return { status: 'no_liquidation' };
+        let profitCount = 0;
+        let lossCount = 0;
+        const details = [];
+
+        for (const asset of liquidationData.asset_flow_details) {
+            // We only care about assets that were *sold* (negative flow)
+            if (asset.net_flow_contribution < 0) {
+                const ticker = asset.ticker;
+                const pnlInfo = pnlStatusData[ticker];
+                
+                if (pnlInfo) {
+                    let status = 'neutral';
+                    if (pnlInfo.profit_ratio > 50) {
+                        status = 'profit';
+                        profitCount++;
+                    } else if (pnlInfo.profit_ratio < 50) {
+                        status = 'loss';
+                        lossCount++;
+                    }
+                    details.push({
+                        ticker: ticker,
+                        net_flow_contribution: asset.net_flow_contribution,
+                        status: status,
+                        profit_ratio: pnlInfo.profit_ratio
+                    });
+                }
+            }
         }
 
-        // 3. Define performance windows
-        const preSignalStart = this._getDateStr(signalDate, -this.PERFORMANCE_WINDOW_DAYS);
-        const preSignalEnd = signalDate;
-        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
-        );
-        
-        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)."
+            is_net_withdrawal_day: true,
+            total_assets_liquidated: details.length,
+            assets_sold_at_profit_count: profitCount,
+            assets_sold_at_loss_count: lossCount,
+            winner_loser_sell_ratio: (lossCount > 0) ? (profitCount / lossCount) : null,
+            details: details
         };
     }
 
-    async getResult() { return null; }
-    reset() {}
+    reset() {
+        // No state
+    }
 }
 
 module.exports = CapitalLiquidationPerformance;

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

@@ -1,137 +1,144 @@
 /**
- * @fileoverview Correlates a crowd-wide deposit signal with the specific assets
- * that are being bought with that new capital.
+ * @fileoverview Calculation (Pass 3) for cash flow deployment.
  *
- * --- META REFACTOR (v2) ---
- * This calc fetches *today's* dependencies from the runner, but still
- * performs its own historical lookback for the *signal*.
+ * This metric answers: "Following a net deposit event, what percentage
+ * of that new capital is deployed *today*, and which assets are
+ * receiving the most inflow?"
+ *
+ * It *depends* on 'crowd-cash-flow-proxy' (to know if it's a
+ * deposit day) and 'asset_crowd_flow' (to see where flow went).
  */
-
-const { FieldValue } = require('@google-cloud/firestore');
-
 class CashFlowDeployment {
-    
-    /**
-     * (NEW) Statically declare dependencies.
-     */
-    static getDependencies() {
-        return ['crowd-cash-flow-proxy', 'asset-crowd-flow'];
-    }
-
     constructor() {
-        this.lookbackDays = 7;
-        this.correlationWindow = 3;
-        this.depositSignalThreshold = -0.005; // Negative value = deposit
+        // No per-user processing
     }
 
-    _getDateStr(baseDate, daysAgo) {
-        const date = new Date(baseDate + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() - daysAgo);
-        return date.toISOString().slice(0, 10);
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const assetFlowSchema = {
+            "type": "object",
+            "properties": {
+                "ticker": { "type": "string" },
+                "net_flow_contribution": { "type": "number" },
+                "percent_of_total_inflow": { "type": "number" }
+            },
+            "required": ["ticker", "net_flow_contribution", "percent_of_total_inflow"]
+        };
+
+        return {
+            "type": "object",
+            "description": "On net deposit days, tracks % of new capital deployed and which assets received it.",
+            "properties": {
+                "is_net_deposit_day": {
+                    "type": "boolean",
+                    "description": "True if today was a net deposit day."
+                },
+                "net_cash_flow_proxy": {
+                    "type": "number",
+                    "description": "The total estimated net cash flow (positive)."
+                },
+                "total_net_capital_flow": {
+                    "type": "number",
+                    "description": "The sum of all *positive* net capital flows into assets."
+                },
+                "deployment_percentage": {
+                    "type": ["number", "null"],
+                    "description": "Percentage of net cash flow that was deployed (Total Net Flow / Net Cash Flow). Null if no cash flow."
+                },
+                "top_inflow_assets": {
+                    "type": "array",
+                    "description": "Top 5 assets receiving the most inflow.",
+                    "items": assetFlowSchema
+                },
+                "asset_flow_details": {
+                    "type": "array",
+                    "description": "Full list of all assets and their inflows.",
+                    "items": assetFlowSchema
+                }
+            },
+            "required": ["is_net_deposit_day", "net_cash_flow_proxy", "total_net_capital_flow", "deployment_percentage", "top_inflow_assets", "asset_flow_details"]
+        };
     }
 
     /**
-     * REFACTORED PROCESS METHOD
-     * @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.
-     * @param {object} fetchedDependencies In-memory results from previous passes.
-     * @returns {Promise<object|null>} The analysis result or null.
+     * Statically declare dependencies.
      */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { db, logger } = dependencies;
-        const collection = config.resultsCollection;
-        const resultsSub = config.resultsSubcollection || 'results';
-        const compsSub = config.computationsSubcollection || 'computations';
+    static getDependencies() {
+        return [
+            'crowd-cash-flow-proxy', // Pass 2
+            'asset_crowd_flow'       // Pass 2
+        ];
+    }
 
-        // 1. Get same-day dependencies from `fetchedDependencies`
-        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
-        const assetFlowData = fetchedDependencies['asset-crowd-flow'];
+    process() {
+        // No-op
+    }
 
-        if (!cashFlowData || !assetFlowData) {
-            logger.log('WARN', `[CashFlowDeployment] Missing critical in-memory dependency data for ${dateStr}. Skipping.`);
-            return null;
-        }
+    getResult(fetchedDependencies) {
+        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
+        const assetFlowData = fetchedDependencies['asset_crowd_flow'];
+
+        const defaults = {
+            is_net_deposit_day: false,
+            net_cash_flow_proxy: 0,
+            total_net_capital_flow: 0,
+            deployment_percentage: null,
+            top_inflow_assets: [],
+            asset_flow_details: []
+        };
 
-        // 2. Historical lookback for signal (still uses Firestore)
-        const refs = [];
-        const dates = [];
-        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' });
+        if (!cashFlowData || !assetFlowData || cashFlowData.net_cash_flow_proxy <= 0) {
+            // Not a net deposit day
+            return defaults;
         }
-        const histRefs = dates.map(d =>
-            db.collection(collection).doc(d.date)
-                .collection(resultsSub).doc(d.category)
-                .collection(compsSub).doc(d.computation)
-        );
-        const snapshots = await db.getAll(...histRefs);
-        const dataMap = new Map();
-        snapshots.forEach((snap, idx) => {
-            if (snap.exists) dataMap.set(idx, snap.data());
-        });
 
-        // 3. Find deposit signal
-        let depositSignal = null;
-        let depositSignalDay = null;
-
-        for (let i = 0; i < this.lookbackDays; i++) {
-            const flowData = dataMap.get(i);
-            const dateUsed = dates[i].date;
-            if (flowData && flowData.cash_flow_effect_proxy < this.depositSignalThreshold) {
-                depositSignal = flowData;
-                depositSignalDay = dateUsed;
-                break;
+        const netCashFlow = cashFlowData.net_cash_flow_proxy;
+        let totalNetInflow = 0;
+        const allFlows = [];
+
+        for (const [ticker, data] of Object.entries(assetFlowData)) {
+            // We only care about *positive* flow (deployment)
+            if (data.net_flow_contribution > 0) {
+                totalNetInflow += data.net_flow_contribution;
+                allFlows.push({
+                    ticker: ticker,
+                    net_flow_contribution: data.net_flow_contribution
+                });
             }
         }
 
-        if (!depositSignal) {
+        if (totalNetInflow === 0) {
+            // Net deposit day, but no positive flow detected
             return {
-                status: 'no_signal_found',
-                lookback_days: this.lookbackDays,
-                signal_threshold: this.depositSignalThreshold
+                ...defaults,
+                is_net_deposit_day: true,
+                net_cash_flow_proxy: netCashFlow,
+                deployment_percentage: 0
             };
         }
-
-        // 4. Check correlation window
-        const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
-
-        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
-            return {
-                status: 'outside_correlation_window',
-                signal_day: depositSignalDay,
-                days_since_signal: daysSinceSignal
-            };
-        }
-
-        // 5. Use the in-memory data for today's analysis
-        const netSpendPct = cashFlowData.components?.trading_effect || 0;
-        const netDepositPct = Math.abs(depositSignal.cash_flow_effect_proxy);
-
-        // Find top *buys*
-        const topBuys = Object.entries(assetFlowData)
-            .filter(([ticker, data]) => data.net_crowd_flow_pct > 0) // Find positive flow
-            .sort(([, a], [, b]) => b.net_crowd_flow_pct - a.net_crowd_flow_pct) // Sort descending
-            .slice(0, 10)
-            .map(([ticker, data]) => ({
-                ticker,
-                net_flow_pct: data.net_crowd_flow_pct
-            }));
+        
+        // Calculate percent_of_total_inflow for each
+        const asset_flow_details = allFlows.map(flow => ({
+            ...flow,
+            percent_of_total_inflow: (flow.net_flow_contribution / totalNetInflow) * 100
+        })).sort((a, b) => b.net_flow_contribution - a.net_flow_contribution);
 
         return {
-            status: 'analysis_complete',
-            analysis_date: dateStr,
-            signal_date: depositSignalDay,
-            days_since_signal: daysSinceSignal,
-            signal_deposit_proxy_pct: netDepositPct,
-            day_net_spend_pct: netSpendPct, // This value should be positive
-            pct_of_deposit_deployed_today: (netSpendPct / netDepositPct) * 100,
-            top_deployment_assets: topBuys
+            is_net_deposit_day: true,
+            net_cash_flow_proxy: netCashFlow,
+            total_net_capital_flow: totalNetInflow,
+            deployment_percentage: (netCashFlow > 0) ? (totalNetInflow / netCashFlow) * 100 : null,
+            top_inflow_assets: asset_flow_details.slice(0, 5),
+            asset_flow_details: asset_flow_details
         };
     }
 
-    async getResult() { return null; }
-    reset() {}
+    reset() {
+        // No state
+    }
 }
 
 module.exports = CashFlowDeployment;