aiden-shared-calculations-unified 1.0.47 → 1.0.49

package/calculations/behavioural/historical/historical_performance_aggregator.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Pass 1: Aggregates each user's historical performance
+ * from the root history data feed.
+ */
+class HistoricalPerformanceAggregator {
+    constructor() {
+        this.allUserStats = {};
+    }
+
+    /**
+     * @param {object} todayPortfolio - Not used, but part of signature.
+     * @param {object} yesterdayPortfolio - Not used.
+     * @param {string} userId - The user's ID.
+     * @param {object} context - Shared context data.
+     * @param {null} todayInsights - Not used.
+     * @param {null} yesterdayInsights - Not used.
+     * @param {null} todaySocialPostInsights - Not used.
+     * @param {null} yesterdaySocialPostInsights - Not used.
+     * @param {object} todayHistoryData - The full map of { [userId]: history }
+     * @param {null} yesterdayHistoryData - Not used.
+     */
+    async process(
+        todayPortfolio, yesterdayPortfolio, userId, context, 
+        todayInsights, yesterdayInsights, 
+        todaySocialPostInsights, yesterdaySocialPostInsights,
+        todayHistoryData, yesterdayHistoryData
+    ) {
+        // This calc only runs if the history data was successfully loaded
+        if (!todayHistoryData || !userId) {
+            return;
+        }
+
+        const userHistory = todayHistoryData[userId];
+
+        // 'all' is the object where instrumentId === -1
+        if (!userHistory || !userHistory.all) {
+            return;
+        }
+
+        const stats = userHistory.all;
+        
+        // Ignore users who are only mirroring
+        if (stats.isMirror === true) {
+            return;
+        }
+
+        // We only care about users with a meaningful trade history
+        if (!stats.totalTrades || stats.totalTrades < 10) {
+            return;
+        }
+
+        this.allUserStats[userId] = {
+            winRatio: stats.winRatio,
+            avgProfitPct: stats.avgProfitPct,
+            avgLossPct: stats.avgLossPct,
+            totalTrades: stats.totalTrades,
+            avgHoldingTime: stats.avgHoldingTimeInMinutes
+        };
+    }
+
+    async getResult() {
+        return this.allUserStats;
+    }
+
+    reset() {
+        this.allUserStats = {};
+    }
+}
+
+module.exports = HistoricalPerformanceAggregator;

package/calculations/meta/negative_expectancy_cohort_flow.js

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview Calculates "Net Crowd Flow" and "Sector Rotation"
+ * *only* for the "Dumb Cohort" (Bottom 20% of Investor Scores).
+ *
+ * --- META REFACTOR (v2) ---
+ * This calculation is `type: "meta"` and expects its dependencies
+ * (the user-investment-profile results) to be fetched by the pass runner.
+ * It then streams root portfolio data.
+ */
+
+const { Firestore } = require('@google-cloud/firestore');
+const firestore = new Firestore();
+const { loadAllPriceData, getDailyPriceChange } = require('../../utils/price_data_provider');
+const { loadInstrumentMappings, getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+// NOTE: Corrected relative path for data_loader
+const { loadDataByRefs, getPortfolioPartRefs, loadFullDayMap } = require('../../../bulltrackers-module/functions/computation-system/utils/data_loader');
+
+const COHORT_PERCENTILE = 0.2; // Bottom 20%
+const PROFILE_CALC_ID = 'user-investment-profile'; // The calc to read IS scores from
+
+class DumbCohortFlow {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['user_expectancy_score'];
+    }
+
+    constructor() {
+        // Meta-calc, no constructor state needed
+    }
+
+    /**
+     * Loads the Investor Scores from the fetched dependency.
+     */
+    _loadCohort(logger, fetchedDependencies) {
+    logger.log('INFO', '[NegativeExpectancyCohortFlow] Loading Expectancy Scores from fetched dependency...');
+
+    const profileData = fetchedDependencies['user-expectancy-score'];
+
+    if (!profileData || Object.keys(profileData).length === 0) {
+        logger.log('WARN', `[NegativeExpectancyCohortFlow] Cannot find dependency 'user-expectancy-score'. Cohort will not be built.`);
+        return null;
+    }
+
+    const allScores = Object.entries(profileData).map(([userId, data]) => ({ 
+        userId, 
+        score: data.expectancy_score 
+    }));
+
+    allScores.sort((a, b) => a.score - b.score);
+
+    // Find the 20th percentile (Bottom 20%)
+    const thresholdIndex = Math.floor(allScores.length * 0.20);
+    const thresholdScore = allScores[thresholdIndex]?.score || 0;
+
+    // Filter for users with a *negative expectancy score* AND are in the bottom 20%
+    const cohortIds = new Set(
+        allScores.filter(s => s.score <= thresholdScore && s.score < 0) 
+                 .map(s => s.userId)
+    );
+
+    logger.log('INFO', `[NegativeExpectancyCohortFlow] Cohort built. ${cohortIds.size} users at or below ${thresholdScore.toFixed(2)} (20th percentile) and < 0.`);
+    return cohortIds;
+    }
+
+    // --- Asset Flow Helpers (unchanged) ---
+    _initAsset(asset_values, instrumentId) {
+        if (!asset_values[instrumentId]) {
+            asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+        }
+    }
+    _sumAssetValue(positions) {
+        const valueMap = {};
+        if (!positions || !Array.isArray(positions)) return valueMap;
+        for (const pos of positions) {
+            if (pos && pos.InstrumentID && pos.Value) {
+                valueMap[pos.InstrumentID] = (valueMap[pos.InstrumentID] || 0) + pos.Value;
+            }
+        }
+        return valueMap;
+    }
+    _accumulateSectorInvestment(portfolio, target, sectorMap) {
+        if (portfolio && portfolio.AggregatedPositions) {
+            for (const pos of portfolio.AggregatedPositions) {
+                const sector = sectorMap[pos.InstrumentID] || 'N/A';
+                target[sector] = (target[sector] || 0) + (pos.Invested || pos.Amount || 0);
+            }
+        }
+    }
+
+    /**
+     * 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, rootData, etc.).
+     * @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.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger, db, rootData, calculationUtils } = dependencies;
+        const { portfolioRefs } = rootData;
+        logger.log('INFO', '[DumbCohortFlow] Starting meta-process...');
+        
+        // 1. Load Cohort from in-memory dependency
+        const dumbCohortIds = this._loadCohort(logger, fetchedDependencies);
+        if (!dumbCohortIds) {
+            return null; // Dependency failed
+        }
+
+        // 2. Load external dependencies (prices, sectors)
+        const [priceMap, mappings, sectorMap] = await Promise.all([
+            loadAllPriceData(),
+            loadInstrumentMappings(),
+            getInstrumentSectorMap()
+        ]);
+        if (!priceMap || !mappings || !sectorMap || Object.keys(priceMap).length === 0) {
+            logger.log('ERROR', '[DumbCohortFlow] Failed to load critical price/mapping/sector data. Aborting.');
+            return null;
+        }
+
+        // 3. Load "yesterday's" portfolio data for comparison
+        const yesterdayDate = new Date(dateStr + 'T00:00:00Z');
+        yesterdayDate.setUTCDate(yesterdayDate.getUTCDate() - 1);
+        const yesterdayStr = yesterdayDate.toISOString().slice(0, 10);
+        const yesterdayRefs = await getPortfolioPartRefs(config, dependencies, yesterdayStr);
+        const yesterdayPortfolios = await loadFullDayMap(config, dependencies, yesterdayRefs);
+        logger.log('INFO', `[DumbCohortFlow] Loaded ${yesterdayRefs.length} part refs for yesterday.`);
+
+        // 4. Stream "today's" portfolio data and process
+        const asset_values = {};
+        const todaySectorInvestment = {};
+        const yesterdaySectorInvestment = {};
+        let user_count = 0;
+
+        const batchSize = config.partRefBatchSize || 10;
+        for (let i = 0; i < portfolioRefs.length; i += batchSize) {
+            const batchRefs = portfolioRefs.slice(i, i + batchSize);
+            const todayPortfoliosChunk = await loadDataByRefs(config, dependencies, batchRefs);
+
+            for (const uid in todayPortfoliosChunk) {
+                
+                if (!dumbCohortIds.has(uid)) continue; // --- Filter user ---
+                
+                const pToday = todayPortfoliosChunk[uid];
+                const pYesterday = yesterdayPortfolios[uid];
+                
+                if (!pToday || !pYesterday || !pToday.AggregatedPositions || !pYesterday.AggregatedPositions) {
+                    continue;
+                }
+                
+                // 4a. RUN ASSET FLOW LOGIC
+                const yesterdayValues = this._sumAssetValue(pYesterday.AggregatedPositions);
+                const todayValues = this._sumAssetValue(pToday.AggregatedPositions);
+                const allInstrumentIds = new Set([...Object.keys(yesterdayValues), ...Object.keys(todayValues)]);
+                
+                for (const instrumentId of allInstrumentIds) {
+                    this._initAsset(asset_values, instrumentId);
+                    asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
+                    asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
+                }
+
+                // 4b. RUN SECTOR ROTATION LOGIC
+                this._accumulateSectorInvestment(pToday, todaySectorInvestment, sectorMap);
+                this._accumulateSectorInvestment(pYesterday, yesterdaySectorInvestment, sectorMap);
+                user_count++;
+            }
+        }
+        
+        logger.log('INFO', `[DumbCohortFlow] Processed ${user_count} users in cohort.`);
+        
+        // --- 5. GETRESULT LOGIC ---
+        if (user_count === 0) {
+            logger.warn('[DumbCohortFlow] No users processed for dumb cohort. Returning null.');
+            return null;
+        }
+
+        // 5a. Calculate Asset Flow
+        const finalAssetFlow = {};
+        for (const instrumentId in asset_values) {
+            const ticker = mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const avg_day1_value = asset_values[instrumentId].day1_value_sum / user_count;
+            const avg_day2_value = asset_values[instrumentId].day2_value_sum / user_count;
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, dateStr, priceMap);
+
+            if (priceChangePct === null) continue;
+
+            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
+            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+
+            finalAssetFlow[ticker] = {
+                net_crowd_flow_pct: net_crowd_flow_pct,
+                avg_value_day1_pct: avg_day1_value,
+                avg_value_day2_pct: avg_day2_value
+            };
+        }
+        
+        // 5b. Calculate Sector Rotation
+        const finalSectorRotation = {};
+        const allSectors = new Set([...Object.keys(todaySectorInvestment), ...Object.keys(yesterdaySectorInvestment)]);
+        for (const sector of allSectors) {
+            const todayAmount = todaySectorInvestment[sector] || 0;
+            const yesterdayAmount = yesterdaySectorInvestment[sector] || 0;
+            finalSectorRotation[sector] = todayAmount - yesterdayAmount;
+        }
+
+        if (Object.keys(finalAssetFlow).length === 0) {
+            logger.warn('[DumbCohortFlow] No asset flow calculated (likely all price data missing). Returning null.');
+            return null;
+        }
+
+        return {
+            asset_flow: finalAssetFlow,
+            sector_rotation: finalSectorRotation,
+            user_sample_size: user_count
+        };
+    }
+
+    async getResult() { return null; }
+    reset() { }
+}
+
+module.exports = DumbCohortFlow;

package/calculations/meta/positive_expectancy_cohort_flow.js

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview Calculates "Net Crowd Flow" and "Sector Rotation"
+ * *only* for the "Smart Cohort" (Top 20% of Investor Scores).
+ *
+ * --- META REFACTOR (v2) ---
+ * This calculation is `type: "meta"` and expects its dependencies
+ * (the user-investment-profile results) to be fetched by the pass runner.
+ * It then streams root portfolio data.
+ */
+
+const { Firestore } = require('@google-cloud/firestore');
+const firestore = new Firestore();
+const { loadAllPriceData, getDailyPriceChange } = require('../../utils/price_data_provider');
+const { loadInstrumentMappings, getInstrumentSectorMap } = require('../../utils/sector_mapping_provider');
+// NOTE: Corrected relative path for data_loader
+const { loadDataByRefs, getPortfolioPartRefs, loadFullDayMap } = require('../../../bulltrackers-module/functions/computation-system/utils/data_loader');
+
+const COHORT_PERCENTILE = 0.8; // Top 20%
+const PROFILE_CALC_ID = 'user-investment-profile'; // The calc to read IS scores from
+
+class SmartCohortFlow {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+    return ['user_expectancy_score'];
+    }
+    
+    constructor() {
+        // Meta-calc, no constructor state needed
+    }
+
+    /**
+     * Loads the Investor Scores from the fetched dependency.
+     */
+    _loadCohort(logger, fetchedDependencies) {
+    logger.log('INFO', '[PositiveExpectancyCohortFlow] Loading Expectancy Scores from fetched dependency...');
+
+    // 1. Get the new dependency
+    const profileData = fetchedDependencies['user-expectancy-score'];
+
+    if (!profileData || Object.keys(profileData).length === 0) {
+        logger.log('WARN', `[PositiveExpectancyCohortFlow] Cannot find dependency 'user-expectancy-score'. Cohort will not be built.`);
+        return null;
+    }
+
+    // 2. The data is already the map we need: { [userId]: { expectancy_score: X } }
+    const allScores = Object.entries(profileData).map(([userId, data]) => ({ 
+        userId, 
+        score: data.expectancy_score 
+    }));
+
+    // 3. Sort by score, lowest to highest
+    allScores.sort((a, b) => a.score - b.score);
+
+    // 4. Find the 80th percentile (Top 20%)
+    const thresholdIndex = Math.floor(allScores.length * 0.80);
+    const thresholdScore = allScores[thresholdIndex]?.score || 999;
+
+    // 5. Filter for users with a *positive expectancy score* AND are in the top 20%
+    const cohortIds = new Set(
+        allScores.filter(s => s.score >= thresholdScore && s.score > 0) 
+                 .map(s => s.userId)
+    );
+
+    logger.log('INFO', `[PositiveExpectancyCohortFlow] Cohort built. ${cohortIds.size} users at or above ${thresholdScore.toFixed(2)} (80th percentile) and > 0.`);
+    return cohortIds;
+    }
+
+    // --- Asset Flow Helpers (unchanged) ---
+    _initAsset(asset_values, instrumentId) {
+        if (!asset_values[instrumentId]) {
+            asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+        }
+    }
+    _sumAssetValue(positions) {
+        const valueMap = {};
+        if (!positions || !Array.isArray(positions)) return valueMap;
+        for (const pos of positions) {
+            if (pos && pos.InstrumentID && pos.Value) {
+                valueMap[pos.InstrumentID] = (valueMap[pos.InstrumentID] || 0) + pos.Value;
+            }
+        }
+        return valueMap;
+    }
+    _accumulateSectorInvestment(portfolio, target, sectorMap) {
+        if (portfolio && portfolio.AggregatedPositions) {
+            for (const pos of portfolio.AggregatedPositions) {
+                const sector = sectorMap[pos.InstrumentID] || 'N/A';
+                target[sector] = (target[sector] || 0) + (pos.Invested || pos.Amount || 0);
+            }
+        }
+    }
+
+    /**
+     * 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, rootData, etc.).
+     * @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.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger, db, rootData, calculationUtils } = dependencies;
+        const { portfolioRefs } = rootData;
+        logger.log('INFO', '[SmartCohortFlow] Starting meta-process...');
+        
+        // 1. Load Cohort from in-memory dependency
+        const smartCohortIds = this._loadCohort(logger, fetchedDependencies);
+        if (!smartCohortIds) {
+            return null; // Dependency failed
+        }
+
+        // 2. Load external dependencies (prices, sectors)
+        const [priceMap, mappings, sectorMap] = await Promise.all([
+            loadAllPriceData(),
+            loadInstrumentMappings(),
+            getInstrumentSectorMap()
+        ]);
+        if (!priceMap || !mappings || !sectorMap || Object.keys(priceMap).length === 0) {
+            logger.log('ERROR', '[SmartCohortFlow] Failed to load critical price/mapping/sector data. Aborting.');
+            return null; 
+        }
+
+        // 3. Load "yesterday's" portfolio data for comparison
+        const yesterdayDate = new Date(dateStr + 'T00:00:00Z');
+        yesterdayDate.setUTCDate(yesterdayDate.getUTCDate() - 1);
+        const yesterdayStr = yesterdayDate.toISOString().slice(0, 10);
+        const yesterdayRefs = await getPortfolioPartRefs(config, dependencies, yesterdayStr);
+        const yesterdayPortfolios = await loadFullDayMap(config, dependencies, yesterdayRefs);
+        logger.log('INFO', `[SmartCohortFlow] Loaded ${yesterdayRefs.length} part refs for yesterday.`);
+
+        // 4. Stream "today's" portfolio data and process
+        const asset_values = {};
+        const todaySectorInvestment = {};
+        const yesterdaySectorInvestment = {};
+        let user_count = 0;
+
+        const batchSize = config.partRefBatchSize || 10;
+        for (let i = 0; i < portfolioRefs.length; i += batchSize) {
+            const batchRefs = portfolioRefs.slice(i, i + batchSize);
+            const todayPortfoliosChunk = await loadDataByRefs(config, dependencies, batchRefs);
+
+            for (const uid in todayPortfoliosChunk) {
+                
+                if (!smartCohortIds.has(uid)) continue; // --- Filter user ---
+                
+                const pToday = todayPortfoliosChunk[uid];
+                const pYesterday = yesterdayPortfolios[uid];
+                
+                if (!pToday || !pYesterday || !pToday.AggregatedPositions || !pYesterday.AggregatedPositions) {
+                    continue;
+                }
+                
+                // 4a. RUN ASSET FLOW LOGIC
+                const yesterdayValues = this._sumAssetValue(pYesterday.AggregatedPositions);
+                const todayValues = this._sumAssetValue(pToday.AggregatedPositions);
+                const allInstrumentIds = new Set([...Object.keys(yesterdayValues), ...Object.keys(todayValues)]);
+                
+                for (const instrumentId of allInstrumentIds) {
+                    this._initAsset(asset_values, instrumentId);
+                    asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
+                    asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
+                }
+
+                // 4b. RUN SECTOR ROTATION LOGIC
+                this._accumulateSectorInvestment(pToday, todaySectorInvestment, sectorMap);
+                this._accumulateSectorInvestment(pYesterday, yesterdaySectorInvestment, sectorMap);
+                user_count++;
+            }
+        }
+        
+        logger.log('INFO', `[SmartCohortFlow] Processed ${user_count} users in cohort.`);
+        
+        // --- 5. GETRESULT LOGIC ---
+        if (user_count === 0) {
+            logger.warn('[SmartCohortFlow] No users processed for smart cohort. Returning null.');
+            return null;
+        }
+
+        // 5a. Calculate Asset Flow
+        const finalAssetFlow = {};
+        for (const instrumentId in asset_values) {
+            const ticker = mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const avg_day1_value = asset_values[instrumentId].day1_value_sum / user_count;
+            const avg_day2_value = asset_values[instrumentId].day2_value_sum / user_count;
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, dateStr, priceMap);
+
+            if (priceChangePct === null) continue;
+
+            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
+            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+
+            finalAssetFlow[ticker] = {
+                net_crowd_flow_pct: net_crowd_flow_pct,
+                avg_value_day1_pct: avg_day1_value,
+                avg_value_day2_pct: avg_day2_value
+            };
+        }
+        
+        // 5b. Calculate Sector Rotation
+        const finalSectorRotation = {};
+        const allSectors = new Set([...Object.keys(todaySectorInvestment), ...Object.keys(yesterdaySectorInvestment)]);
+        for (const sector of allSectors) {
+            const todayAmount = todaySectorInvestment[sector] || 0;
+            const yesterdayAmount = yesterdaySectorInvestment[sector] || 0;
+            finalSectorRotation[sector] = todayAmount - yesterdayAmount;
+        }
+
+        if (Object.keys(finalAssetFlow).length === 0) {
+            logger.warn('[SmartCohortFlow] No asset flow calculated (likely all price data missing). Returning null.');
+            return null;
+        }
+
+        return {
+            asset_flow: finalAssetFlow,
+            sector_rotation: finalSectorRotation,
+            user_sample_size: user_count
+        };
+    }
+
+    async getResult() { return null; }
+    reset() { }
+}
+
+module.exports = SmartCohortFlow;

package/calculations/meta/shark_attack_signal.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Pass 4: Identifies "Shark Attack" signals where
+ * the positive expectancy cohort is buying what the in-loss cohort
+ * is panic-selling.
+ */
+class SharkAttackSignal {
+
+    static getDependencies() {
+        // Depends on Pass 3 "smart" flow and Pass 1 "in-loss" flow
+        return ['positive-expectancy-cohort-flow', 'in-loss-asset-crowd-flow'];
+    }
+    
+    constructor() {
+        this.buyThreshold = 0.005;  // Min "smart" buy-in
+        this.sellThreshold = -0.005; // Min "in-loss" capitulation
+    }
+
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+
+        const smartData = fetchedDependencies['positive-expectancy-cohort-flow'];
+        const lossData = fetchedDependencies['in-loss-asset-crowd-flow'];
+
+        if (!smartData || !smartData.asset_flow || !lossData) {
+            logger.log('WARN', `[SharkAttack] Missing computed dependency data for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        const smartFlow = smartData.asset_flow;
+        const lossFlow = lossData; // This is the root object
+        const signals = {};
+        
+        const allTickers = new Set([...Object.keys(smartFlow), ...Object.keys(lossFlow)]);
+
+        for (const ticker of allTickers) {
+            const sFlow = smartFlow[ticker]?.net_crowd_flow_pct || 0;
+            const lFlow = lossFlow[ticker]?.net_crowd_flow_pct || 0;
+
+            // Check for the divergence: Smart is buying, In-Loss is selling
+            if (sFlow >= this.buyThreshold && lFlow <= this.sellThreshold) {
+                
+                signals[ticker] = {
+                    status: "SHARK_ATTACK",
+                    detail: "Positive expectancy cohort is buying from the capitulating in-loss cohort.",
+                    smart_flow: sFlow,
+                    loss_flow: lFlow,
+                    // Calculate a simple conviction score
+                    conviction: sFlow + Math.abs(lFlow) 
+                };
+            }
+        }
+
+        return signals;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = SharkAttackSignal;

package/calculations/meta/smart_dumb_divergence_index_v2.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Meta-calculation (Pass 4) that correlates the asset/sector flow
+ * of the "Smart Cohort" vs. the "Dumb Cohort" to find divergence signals.
+ *
+ * --- META REFACTOR (v2) ---
+ * This calculation is now stateless. It declares its dependencies and
+ * expects them to be passed to its `process` method.
+ */
+
+class SmartDumbDivergenceIndex {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['positive-expectancy-cohort-flow', 'negative-expectancy-cohort-flow'];
+    }
+
+    constructor() {
+        // Minimum net flow (as a percentage) to be considered a signal
+        this.FLOW_THRESHOLD = 0.005; // Formerly 0.5
+    }
+
+    /**
+     * 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.
+     * e.g., { 'smart-cohort-flow': ..., 'dumb-cohort-flow': ... }
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+    const { logger } = dependencies;
+
+        // 1. Get dependencies from the new argument
+        const smartData = fetchedDependencies['positive-expectancy-cohort-flow'];
+        const dumbData = fetchedDependencies['negative-expectancy-cohort-flow'];
+        
+        // 2. Handle missing dependencies
+        if (!smartData || !dumbData) {
+            logger.log('WARN', `[SmartDumbDivergence] Missing cohort flow data dependency for ${dateStr}. Skipping.`);
+            return null;
+        }
+        
+        const results = {
+            assets: {},
+            sectors: {}
+        };
+        
+        const smartAssetFlow = smartData.asset_flow;
+        const dumbAssetFlow = dumbData.asset_flow;
+        const smartSectorFlow = smartData.sector_rotation;
+        const dumbSectorFlow = dumbData.sector_rotation;
+
+        if (!smartAssetFlow || !dumbAssetFlow || !smartSectorFlow || !dumbSectorFlow) {
+             logger.log('WARN', `[SmartDumbDivergence] Dependency data for ${dateStr} is incomplete (missing asset_flow or sector_rotation). Skipping.`);
+            return null;
+        }
+
+        // 3. Correlate Assets
+        const allTickers = new Set([...Object.keys(smartAssetFlow), ...Object.keys(dumbAssetFlow)]);
+        for (const ticker of allTickers) {
+            const sFlow = smartAssetFlow[ticker]?.net_crowd_flow_pct || 0;
+            const dFlow = dumbAssetFlow[ticker]?.net_crowd_flow_pct || 0;
+
+            const smartBuys = sFlow >= this.FLOW_THRESHOLD;
+            const smartSells = sFlow <= -this.FLOW_THRESHOLD;
+            const dumbBuys = dFlow >= this.FLOW_THRESHOLD;
+            const dumbSells = dFlow <= -this.FLOW_THRESHOLD;
+
+            let status = 'No_Divergence';
+            let detail = 'Cohorts are aligned or flow is insignificant.';
+
+            if (smartBuys && dumbSells) {
+                status = 'Capitulation';
+                detail = 'Smart cohort is buying the dip from the panic-selling dumb cohort.';
+            } else if (smartSells && dumbBuys) {
+                status = 'Euphoria';
+                detail = 'Smart cohort is selling into the FOMO-buying dumb cohort.';
+            } else if (smartBuys && dumbBuys) {
+                status = 'Aligned_Buy';
+            } else if (smartSells && dumbSells) {
+                status = 'Aligned_Sell';
+            }
+
+            if (status !== 'No_Divergence') {
+                results.assets[ticker] = {
+                    status: status,
+                    detail: detail,
+                    smart_cohort_flow_pct: sFlow,
+                    dumb_cohort_flow_pct: dFlow
+                };
+            }
+        }
+        
+        // 4. Correlate Sectors
+        const allSectors = new Set([...Object.keys(smartSectorFlow), ...Object.keys(dumbSectorFlow)]);
+         for (const sector of allSectors) {
+             const sFlow = smartSectorFlow[sector] || 0;
+             const dFlow = dumbSectorFlow[sector] || 0;
+
+             let status = 'No_Divergence';
+             
+             if (sFlow > 0 && dFlow < 0) {
+                 status = 'Capitulation';
+             } else if (sFlow < 0 && dFlow > 0) {
+                 status = 'Euphoria';
+             }
+
+            if (status !== 'No_Divergence') {
+                 results.sectors[sector] = {
+                    status: status,
+                    smart_cohort_flow_usd: sFlow,
+                    dumb_cohort_flow_usd: dFlow
+                };
+            }
+         }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = SmartDumbDivergenceIndex;

package/calculations/meta/user_expectancy_score.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Pass 2: Calculates the "Expectancy Score" for each user
+ * based on their historical trading performance.
+ * Expectancy = (WinRatio * AvgProfitPct) + (LossRatio * AvgLossPct)
+ */
+class UserExpectancyScore {
+
+    static getDependencies() {
+        // Depends on our new Pass 1 calculation
+        return ['historical-performance-aggregator'];
+    }
+
+    constructor() {}
+
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        const performanceData = fetchedDependencies['historical-performance-aggregator'];
+
+        if (!performanceData) {
+            logger.log('WARN', `[UserExpectancyScore] Missing dependency 'historical-performance-aggregator' for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        const expectancyScores = {};
+
+        for (const userId in performanceData) {
+            const stats = performanceData[userId];
+
+            // Ensure we have all the data needed
+            if (typeof stats.winRatio !== 'number' || typeof stats.avgProfitPct !== 'number' || typeof stats.avgLossPct !== 'number') {
+                continue;
+            }
+
+            const winRatio = stats.winRatio / 100.0;
+            const lossRatio = 1.0 - winRatio;
+
+            // Expectancy formula
+            const expectancy = (winRatio * stats.avgProfitPct) + (lossRatio * stats.avgLossPct);
+
+            expectancyScores[userId] = {
+                expectancy_score: expectancy,
+                winRatio: stats.winRatio, // Pass through for debugging/filtering
+                totalTrades: stats.totalTrades
+            };
+        }
+
+        return expectancyScores;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = UserExpectancyScore;

package/package.json

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