aiden-shared-calculations-unified 1.0.64 → 1.0.66

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

@@ -1,139 +1,146 @@
 /**
- * @fileoverview Correlates a crowd-wide withdrawal signal with the specific assets
- * that are being sold (liquidated) to fund those withdrawals.
+ * @fileoverview Calculation (Pass 3) for cash flow liquidation.
  *
- * --- 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 withdrawal event, what percentage
+ * of that withdrawal was funded by selling *today*, and which assets
+ * are being liquidated the most?"
+ *
+ * It *depends* on 'crowd-cash-flow-proxy' (to know if it's a
+ * withdrawal day) and 'asset_crowd_flow' (to see where flow went).
  */
-
-const { FieldValue } = require('@google-cloud/firestore');
-
 class CashFlowLiquidation {
+    constructor() {
+        // No per-user processing
+    }
 
     /**
-     * (NEW) Statically declare dependencies.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    static getDependencies() {
-        return ['crowd-cash-flow-proxy', 'asset-crowd-flow'];
-    }
-    
-    constructor() {
-        this.lookbackDays = 7;
-        this.correlationWindow = 3;
-        // A positive value signals a net crowd withdrawal
-        this.withdrawalSignalThreshold = 0.005;
-    }
+    static getSchema() {
+        const assetFlowSchema = {
+            "type": "object",
+            "properties": {
+                "ticker": { "type": "string" },
+                "net_flow_contribution": { "type": "number" },
+                "percent_of_total_outflow": { "type": "number" }
+            },
+            "required": ["ticker", "net_flow_contribution", "percent_of_total_outflow"]
+        };
 
-    _getDateStr(baseDate, daysAgo) {
-        const date = new Date(baseDate + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() - daysAgo);
-        return date.toISOString().slice(0, 10);
+        return {
+            "type": "object",
+            "description": "On net withdrawal days, tracks % of withdrawal funded by selling and which assets were sold.",
+            "properties": {
+                "is_net_withdrawal_day": {
+                    "type": "boolean",
+                    "description": "True if today was a net withdrawal day."
+                },
+                "net_cash_flow_proxy": {
+                    "type": "number",
+                    "description": "The total estimated net cash flow (negative)."
+                },
+                "total_net_capital_flow": {
+                    "type": "number",
+                    "description": "The sum of all *negative* net capital flows from assets (total liquidation)."
+                },
+                "funding_percentage": {
+                    "type": ["number", "null"],
+                    "description": "Percentage of net cash flow funded by selling (Total Net Flow / Net Cash Flow). Null if no cash flow."
+                },
+                "top_outflow_assets": {
+                    "type": "array",
+                    "description": "Top 5 assets being liquidated.",
+                    "items": assetFlowSchema
+                },
+                "asset_flow_details": {
+                    "type": "array",
+                    "description": "Full list of all assets and their outflows.",
+                    "items": assetFlowSchema
+                }
+            },
+            "required": ["is_net_withdrawal_day", "net_cash_flow_proxy", "total_net_capital_flow", "funding_percentage", "top_outflow_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', `[CashFlowLiquidation] 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_withdrawal_day: false,
+            net_cash_flow_proxy: 0,
+            total_net_capital_flow: 0,
+            funding_percentage: null,
+            top_outflow_assets: [],
+            asset_flow_details: []
+        };
 
-        // 2. Historical lookback for signal (still uses Firestore)
-        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 withdrawal day
+            return defaults;
         }
-        const refs = dates.map(d =>
-            db.collection(collection).doc(d.date)
-                .collection(resultsSub).doc(d.category)
-                .collection(compsSub).doc(d.computation)
-        );
-        const snapshots = await db.getAll(...refs);
-        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
+        const netCashFlow = cashFlowData.net_cash_flow_proxy; // This is a negative number
+        let totalNetOutflow = 0;
+        const allFlows = [];
+
+        for (const [ticker, data] of Object.entries(assetFlowData)) {
+            // We only care about *negative* flow (liquidation)
+            if (data.net_flow_contribution < 0) {
+                totalNetOutflow += data.net_flow_contribution; // Summing negative numbers
+                allFlows.push({
+                    ticker: ticker,
+                    net_flow_contribution: data.net_flow_contribution
+                });
             }
         }
 
-        if (!withdrawalSignal) {
+        if (totalNetOutflow === 0) {
+            // Net withdrawal day, but no negative flow detected
             return {
-                status: 'no_withdrawal_signal_found',
-                lookback_days: this.lookbackDays,
-                signal_threshold: this.withdrawalSignalThreshold
+                ...defaults,
+                is_net_withdrawal_day: true,
+                net_cash_flow_proxy: netCashFlow,
+                funding_percentage: 0
             };
         }
         
-        // 3. Check correlation window
-        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
-            };
-        }
-
-        // 4. Use in-memory data for today's analysis
-        // '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
-            }));
+        // Calculate percent_of_total_outflow for each
+        const asset_flow_details = allFlows.map(flow => ({
+            ...flow,
+            // (Negative / Negative) * 100 = Positive %
+            percent_of_total_outflow: (flow.net_flow_contribution / totalNetOutflow) * 100
+        })).sort((a, b) => a.net_flow_contribution - b.net_flow_contribution); // Sort ascending (most negative first)
 
         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
+            is_net_withdrawal_day: true,
+            net_cash_flow_proxy: netCashFlow,
+            total_net_capital_flow: totalNetOutflow,
+            // (Negative / Negative) * 100 = Positive %
+            funding_percentage: (netCashFlow < 0) ? (totalNetOutflow / netCashFlow) * 100 : null,
+            top_outflow_assets: asset_flow_details.slice(0, 5),
+            asset_flow_details: asset_flow_details
         };
     }
 
-    async getResult() { return null; }
-    reset() {}
+    reset() {
+        // No state
+    }
 }
 
 module.exports = CashFlowLiquidation;

package/calculations/meta/crowd_sharpe_ratio_proxy.js

@@ -1,84 +1,124 @@
 /**
- * @fileoverview Meta-calculation (Pass 3) to calculate a proxy for the
- * crowd's "Sharpe Ratio" (risk-adjusted return) on a per-asset basis.
- * It uses the components from 'pnl_distribution_per_stock' to calculate
- * the standard deviation of P/L, which serves as the "risk".
+ * @fileoverview Calculation (Pass 2) for crowd sharpe ratio proxy.
+ *
+ * This metric answers: "What is the crowd's risk-adjusted return
+ * (Sharpe Ratio proxy) for each asset?"
+ *
+ * It uses the distribution of P&L from 'pnl_distribution_per_stock'
+ * to calculate variance (risk).
  */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class CrowdSharpeRatioProxy {
-    constructor() {}
+    constructor() {
+        this.mappings = null;
+    }
 
     /**
-     * @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} computedDependencies In-memory results from previous passes.
-     * @returns {Promise<object|null>} The analysis result or null.
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
-        const { logger } = dependencies;
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "description": "Sharpe Ratio proxy metrics for a specific asset.",
+            "properties": {
+                "sharpe_ratio_proxy": {
+                    "type": "number",
+                    "description": "Risk-adjusted return proxy (Mean P&L / StdDev P&L). Assumes risk-free rate is 0."
+                },
+                "average_pnl": { "type": "number" },
+                "std_dev_pnl": { "type": "number" },
+                "variance_pnl": { "type": "number" },
+                "position_count": { "type": "number" }
+            },
+            "required": ["sharpe_ratio_proxy", "average_pnl", "std_dev_pnl", "position_count"]
+        };
 
-        // 1. Get dependency from in-memory cache
-        const data = computedDependencies['pnl-distribution-per-stock'];
+        return {
+            "type": "object",
+            "description": "Calculates a risk-adjusted return (Sharpe Ratio proxy) for each asset based on P&L distribution.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Matches any string key (ticker)
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
 
-        // 2. Handle missing dependency
-        if (!data) {
-            logger.log('WARN', `[CrowdSharpeRatioProxy] Missing dependency 'pnl-distribution-per-stock' for ${dateStr}. Skipping.`);
-            return null;
-        }
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'pnl_distribution_per_stock' // Pass 1
+        ];
+    }
 
-        const pnlDistribution = data.pnl_distribution_by_asset;
+    process() {
+        // No-op
+    }
 
-        if (!pnlDistribution) {
-             logger.log('WARN', `[CrowdSharpeRatioProxy] Dependency data for ${dateStr} is empty. Skipping.`);
-             return null;
+    async getResult(fetchedDependencies) {
+        const pnlDistData = fetchedDependencies['pnl_distribution_per_stock'];
+        
+        if (!pnlDistData) {
+            return {};
+        }
+        
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
 
-        const results = {};
+        const result = {};
 
-        // 3. Calculate Sharpe Proxy for each asset
-        for (const ticker in pnlDistribution) {
-            const stats = pnlDistribution[ticker];
-            const N = stats.position_count;
+        for (const [instrumentId, data] of Object.entries(pnlDistData)) {
+            const { sum, sumSq, count } = data;
             
-            // Need at least 2 data points to calculate variance
-            if (N < 2) continue;
+            if (count < 2) {
+                continue; // Need at least 2 data points for variance
+            }
 
-            const mean = stats.pnl_sum / N; // E(x)
-            const mean_sq = stats.pnl_sum_sq / N; // E(x^2)
+            // Calculate Mean (Average P&L)
+            const mean = sum / count;
             
-            const variance = mean_sq - (mean * mean);
-
-            // If variance is negative (floating point error) or zero, we can't get std_dev
-            if (variance <= 0) {
-                results[ticker] = {
-                    average_pnl: mean,
-                    std_dev_pnl: 0,
-                    sharpe_ratio_proxy: 0,
-                    position_count: N
-                };
+            // Calculate Variance
+            // Var(X) = E[X^2] - (E[X])^2
+            const meanSq = sumSq / count;
+            const variance = meanSq - (mean * mean);
+            
+            // Handle potential float precision errors
+            if (variance < 0) {
                 continue;
             }
 
-            const std_dev = Math.sqrt(variance); // "Risk"
+            // Calculate Standard Deviation (Risk)
+            const stdDev = Math.sqrt(variance);
+
+            if (stdDev === 0) {
+                continue; // No risk, Sharpe ratio is infinite/undefined
+            }
+
+            // Calculate Sharpe Ratio Proxy (assuming risk-free rate = 0)
+            // Sharpe = Mean(Return) / StdDev(Return)
+            const sharpeProxy = mean / stdDev;
             
-            // Calculate Sharpe Ratio (Return / Risk)
-            // (Assuming 0 risk-free rate)
-            const sharpe_proxy = mean / std_dev;
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
 
-            results[ticker] = {
+            result[ticker] = {
+                sharpe_ratio_proxy: sharpeProxy,
                 average_pnl: mean,
-                std_dev_pnl: std_dev,
-                sharpe_ratio_proxy: sharpe_proxy,
-                position_count: N
+                std_dev_pnl: stdDev,
+                variance_pnl: variance,
+                position_count: count
             };
         }
-
-        return results;
+        
+        return result;
     }
 
-    async getResult() { return null; }
-    reset() {}
+    reset() {
+        this.mappings = null;
+    }
 }
 
 module.exports = CrowdSharpeRatioProxy;