aiden-shared-calculations-unified 1.0.35 → 1.0.37

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

@@ -1,143 +1,127 @@
-/**
- * @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 = 0.005; // Formerly 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());
-        });
-
-        // --- START MODIFICATION ---
-        // Check for THIS DATE's dependencies (cash-flow and asset-flow) FIRST.
-        const cashFlowData = dataMap.get(this.lookbackDays);
-        const assetFlowData = dataMap.get(this.lookbackDays + 1);
-
-        if (!cashFlowData || !assetFlowData) {
-            logger.log('WARN', `[CashFlowLiquidation] Missing critical dependency data (cash-flow or asset-flow) for ${dateStr}. Skipping to allow backfill.`);
-            return null; // This allows backfill
-        }
-        // --- END MODIFICATION ---
-
-
-        // 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
-            };
-        }
-
-        // --- REMOVED ---
-        // The check for cashFlowData and assetFlowData was here
-        // but has been moved up.
-        // --- END REMOVED ---
-
-        // '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() {}
-}
-
+/**
+ * @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 = 0.005; // Formerly 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.
+     * @param {object} computedDependencies In-memory results from previous passes.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, computedDependencies) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+
+        // --- MODIFICATION: Get same-day dependencies from cache ---
+        const cashFlowData = computedDependencies['crowd-cash-flow-proxy'];
+        const assetFlowData = computedDependencies['asset-crowd-flow'];
+
+        if (!cashFlowData || !assetFlowData) {
+            logger.log('WARN', `[CashFlowLiquidation] Missing critical in-memory dependency data for ${dateStr}. Skipping.`);
+            return null;
+        }
+        // --- END MODIFICATION ---
+
+        // --- 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' });
+        }
+        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);
+        const dataMap = new Map();
+        snapshots.forEach((snap, idx) => {
+            if (snap.exists) dataMap.set(idx, snap.data());
+        });
+        // --- End historical lookback ---
+
+
+        // 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
+            };
+        }
+
+        // '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/meta/crowd_sharpe_ratio_proxy.js

@@ -1,92 +1,84 @@
-/**
- * @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".
- */
-
-class CrowdSharpeRatioProxy {
-    constructor() {}
-
-    /**
-     * @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. Define dependency
-        const dependency = { category: 'pnl', computation: 'pnl-distribution-per-stock' };
-
-        // 2. Build ref and fetch
-        const docRef = db.collection(collection).doc(dateStr)
-            .collection('results').doc(dependency.category)
-            .collection('computations').doc(dependency.computation);
-
-        const snapshot = await docRef.get();
-
-        // 3. Handle the "day-delay"
-        if (!snapshot.exists) {
-            logger.log('WARN', `[CrowdSharpeRatioProxy] Missing dependency 'pnl-distribution-per-stock' for ${dateStr}. Allowing backfill.`);
-            return null; // Let backfill handle it
-        }
-
-        const data = snapshot.data();
-        const pnlDistribution = data.pnl_distribution_by_asset;
-
-        if (!pnlDistribution) {
-             logger.log('WARN', `[CrowdSharpeRatioProxy] Dependency data for ${dateStr} is empty. Skipping.`);
-             return null;
-        }
-
-        const results = {};
-
-        // 4. Calculate Sharpe Proxy for each asset
-        for (const ticker in pnlDistribution) {
-            const stats = pnlDistribution[ticker];
-            const N = stats.position_count;
-            
-            // Need at least 2 data points to calculate variance
-            if (N < 2) continue;
-
-            const mean = stats.pnl_sum / N; // E(x)
-            const mean_sq = stats.pnl_sum_sq / N; // E(x^2)
-            
-            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
-                };
-                continue;
-            }
-
-            const std_dev = Math.sqrt(variance); // "Risk"
-            
-            // Calculate Sharpe Ratio (Return / Risk)
-            // (Assuming 0 risk-free rate)
-            const sharpe_proxy = mean / std_dev;
-
-            results[ticker] = {
-                average_pnl: mean,
-                std_dev_pnl: std_dev,
-                sharpe_ratio_proxy: sharpe_proxy,
-                position_count: N
-            };
-        }
-
-        return results;
-    }
-
-    async getResult() { return null; }
-    reset() {}
-}
-
+/**
+ * @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".
+ */
+
+class CrowdSharpeRatioProxy {
+    constructor() {}
+
+    /**
+     * @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.
+     */
+    async process(dateStr, dependencies, config, computedDependencies) {
+        const { logger } = dependencies;
+
+        // 1. Get dependency from in-memory cache
+        const data = computedDependencies['pnl-distribution-per-stock'];
+
+        // 2. Handle missing dependency
+        if (!data) {
+            logger.log('WARN', `[CrowdSharpeRatioProxy] Missing dependency 'pnl-distribution-per-stock' for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        const pnlDistribution = data.pnl_distribution_by_asset;
+
+        if (!pnlDistribution) {
+             logger.log('WARN', `[CrowdSharpeRatioProxy] Dependency data for ${dateStr} is empty. Skipping.`);
+             return null;
+        }
+
+        const results = {};
+
+        // 3. Calculate Sharpe Proxy for each asset
+        for (const ticker in pnlDistribution) {
+            const stats = pnlDistribution[ticker];
+            const N = stats.position_count;
+            
+            // Need at least 2 data points to calculate variance
+            if (N < 2) continue;
+
+            const mean = stats.pnl_sum / N; // E(x)
+            const mean_sq = stats.pnl_sum_sq / N; // E(x^2)
+            
+            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
+                };
+                continue;
+            }
+
+            const std_dev = Math.sqrt(variance); // "Risk"
+            
+            // Calculate Sharpe Ratio (Return / Risk)
+            // (Assuming 0 risk-free rate)
+            const sharpe_proxy = mean / std_dev;
+
+            results[ticker] = {
+                average_pnl: mean,
+                std_dev_pnl: std_dev,
+                sharpe_ratio_proxy: sharpe_proxy,
+                position_count: N
+            };
+        }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
 module.exports = CrowdSharpeRatioProxy;

package/calculations/meta/profit_cohort_divergence.js

@@ -1,92 +1,78 @@
-/**
- * @fileoverview Meta-calculation (Pass 3) that correlates the asset flow
- * of the "In Profit" cohort vs. the "In Loss" cohort to find
- * powerful divergence signals (e.g., profit-taking, capitulation).
- */
-
-class ProfitCohortDivergence {
-    constructor() {
-        this.flowThreshold = 0.005; // Min abs flow % to be considered a signal (formerly 0.5)
-    }
-
-    /**
-     * @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;
-        const resultsSub = config.resultsSubcollection || 'results';
-        const compsSub = config.computationsSubcollection || 'computations';
-
-        // 1. Define dependencies
-        const refsToGet = [
-            {
-                key: 'profit_flow',
-                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('in-profit-asset-crowd-flow')
-            },
-            {
-                key: 'loss_flow',
-                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('in-loss-asset-crowd-flow')
-            }
-        ];
-
-        // 2. Fetch
-        const snapshots = await db.getAll(...refsToGet.map(r => r.ref));
-        const profitFlowData = snapshots[0].exists ? snapshots[0].data() : null;
-        const lossFlowData = snapshots[1].exists ? snapshots[1].data() : null;
-
-        // 3. Handle "day-delay"
-        if (!profitFlowData || !lossFlowData) {
-            logger.log('WARN', `[ProfitCohortDivergence] Missing cohort flow data for ${dateStr}. Allowing backfill.`);
-            return null; // Let backfill handle it
-        }
-
-        const results = {};
-        const allTickers = new Set([...Object.keys(profitFlowData), ...Object.keys(lossFlowData)]);
-
-        // 4. Correlate
-        for (const ticker of allTickers) {
-            const profitFlow = profitFlowData[ticker]?.net_crowd_flow_pct || 0;
-            const lossFlow = lossFlowData[ticker]?.net_crowd_flow_pct || 0;
-
-            const profitSells = profitFlow <= -this.flowThreshold;
-            const profitBuys = profitFlow >= this.flowThreshold;
-            const lossSells = lossFlow <= -this.flowThreshold;
-            const lossBuys = lossFlow >= this.flowThreshold;
-
-            let status = 'No Divergence';
-            let detail = 'Both cohorts are acting similarly or flow is insignificant.';
-
-            if (profitSells && lossBuys) {
-                status = 'Profit Taking';
-                detail = 'The "in-profit" cohort is selling to the "in-loss" cohort, who are averaging down.';
-            } else if (profitBuys && lossSells) {
-                status = 'Capitulation';
-                detail = 'The "in-loss" cohort is panic-selling, and the "in-profit" cohort is buying the dip.';
-            } else if (profitBuys && lossBuys) {
-                status = 'High Conviction Buy';
-                detail = 'All cohorts are net-buying.';
-            } else if (profitSells && lossSells) {
-                status = 'High Conviction Sell';
-                detail = 'All cohorts are net-selling.';
-            }
-
-            results[ticker] = {
-                status: status,
-                detail: detail,
-                profit_cohort_flow: profitFlow,
-                loss_cohort_flow: lossFlow
-            };
-        }
-
-        return results;
-    }
-
-    async getResult() { return null; }
-    reset() {}
-}
-
+/**
+ * @fileoverview Meta-calculation (Pass 3) that correlates the asset flow
+ * of the "In Profit" cohort vs. the "In Loss" cohort to find
+ * powerful divergence signals (e.g., profit-taking, capitulation).
+ */
+
+class ProfitCohortDivergence {
+    constructor() {
+        this.flowThreshold = 0.005; // Min abs flow % to be considered a signal (formerly 0.5)
+    }
+
+    /**
+     * @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.
+     */
+    async process(dateStr, dependencies, config, computedDependencies) {
+        const { logger } = dependencies;
+
+        // 1. Get dependencies directly from the new argument
+        // Names are normalized to kebab-case by the orchestrator
+        const profitFlowData = computedDependencies['in-profit-asset-crowd-flow'];
+        const lossFlowData = computedDependencies['in-loss-asset-crowd-flow'];
+
+        // 2. Handle missing dependencies
+        if (!profitFlowData || !lossFlowData) {
+            logger.log('WARN', `[ProfitCohortDivergence] Missing computed dependency for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        const results = {};
+        const allTickers = new Set([...Object.keys(profitFlowData), ...Object.keys(lossFlowData)]);
+
+        // 4. Correlate
+        for (const ticker of allTickers) {
+            const profitFlow = profitFlowData[ticker]?.net_crowd_flow_pct || 0;
+            const lossFlow = lossFlowData[ticker]?.net_crowd_flow_pct || 0;
+
+            const profitSells = profitFlow <= -this.flowThreshold;
+            const profitBuys = profitFlow >= this.flowThreshold;
+            const lossSells = lossFlow <= -this.flowThreshold;
+            const lossBuys = lossFlow >= this.flowThreshold;
+
+            let status = 'No Divergence';
+            let detail = 'Both cohorts are acting similarly or flow is insignificant.';
+
+            if (profitSells && lossBuys) {
+                status = 'Profit Taking';
+                detail = 'The "in-profit" cohort is selling to the "in-loss" cohort, who are averaging down.';
+            } else if (profitBuys && lossSells) {
+                status = 'Capitulation';
+                detail = 'The "in-loss" cohort is panic-selling, and the "in-profit" cohort is buying the dip.';
+            } else if (profitBuys && lossBuys) {
+                status = 'High Conviction Buy';
+                detail = 'All cohorts are net-buying.';
+            } else if (profitSells && lossSells) {
+                status = 'High Conviction Sell';
+                detail = 'All cohorts are net-selling.';
+            }
+
+            results[ticker] = {
+                status: status,
+                detail: detail,
+                profit_cohort_flow: profitFlow,
+                loss_cohort_flow: lossFlow
+            };
+        }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
 module.exports = ProfitCohortDivergence;