aiden-shared-calculations-unified 1.0.17 → 1.0.19

package/calculations/backtests/strategy-performance.js

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Backtest (Pass 4) calculation.
+ * Runs a full historical simulation of a trading strategy
+ * based on meta-signals.
+ */
+
+// Note: Ensure this path is correct relative to your 'calculations' dir
+const { loadAllPriceData } = require('../../utils/price_data_provider');
+
+class StrategyPerformance {
+    constructor() {
+        this.INITIAL_CASH = 100000;
+        this.TRADE_SIZE_USD = 5000;
+        
+        // --- Strategy Configuration ---
+        // Defines which signals from which computations trigger a BUY or SELL
+        this.strategySignals = {
+            'smart-dumb-divergence-index': {
+                'Capitulation': 'BUY',
+                'Euphoria': 'SELL'
+            },
+            'profit_cohort_divergence': {
+                'Capitulation': 'BUY',
+                'Profit Taking': 'SELL'
+            }
+        };
+        // --- End Configuration ---
+        
+        this.priceMap = null;
+    }
+
+    /**
+     * Helper to find the first date a computation was stored.
+     * This determines the start date of the backtest.
+     * @param {object} db - Firestore instance
+     * @param {string} collection - resultsCollection
+     * @param {string} computation - computation name (e.g., 'smart-dumb-divergence-index')
+     * @param {string} category - computation category (e.g., 'meta')
+     * @returns {Promise<string|null>} YYYY-MM-DD string or null
+     */
+    async _findSignalInceptionDate(db, collection, computation, category) {
+        // Query for the oldest doc. This is a bit slow but runs once.
+        const snapshot = await db.collection(collection)
+            .where(`${category}.${computation}`, '==', true)
+            .orderBy(db.FieldPath.documentId(), 'asc')
+            .limit(1)
+            .get();
+            
+        if (snapshot.empty) return null;
+        return snapshot.docs[0].id;
+    }
+    
+    /**
+     * Fetches all required signals for the entire backtest period in one go.
+     */
+    async _fetchAllSignals(db, collection, resultsSub, compsSub, dates) {
+        const refs = [];
+        const signalMap = new Map();
+
+        for (const date of dates) {
+            for (const computation in this.strategySignals) {
+                const key = `${date}_${computation}`;
+                
+                // Dynamically find category (this is a bit brittle, but works for your structure)
+                let category = 'meta'; // default
+                if (computation.includes('cohort')) category = 'behavioural'; 
+                
+                const docRef = db.collection(collection).doc(date)
+                               .collection(resultsSub).doc(category)
+                               .collection(compsSub).doc(computation);
+                refs.push({ key, ref: docRef });
+            }
+        }
+        
+        // This will be a large db.getAll call, but it's very efficient.
+        const snapshots = await db.getAll(...refs.map(r => r.ref));
+        snapshots.forEach((snap, idx) => {
+            if (snap.exists) signalMap.set(refs[idx].key, snap.data());
+        });
+        return signalMap;
+    }
+    
+    /**
+     * Helper to find an instrument ID from a ticker.
+     * This is a simplified lookup from the priceMap.
+     */
+    _findInstrumentId(ticker) {
+        // This is inefficient, but will work. A reverse map would be faster.
+        for (const instrumentId in this.priceMap) {
+            const priceData = this.priceMap[instrumentId];
+            if (priceData && priceData.ticker && priceData.ticker === ticker) {
+                return instrumentId;
+            }
+        }
+        // Fallback for tickers that might have suffixes (e.g., from asset-crowd-flow)
+        for (const instrumentId in this.priceMap) {
+            const priceData = this.priceMap[instrumentId];
+            if (priceData && priceData.ticker && ticker.startsWith(priceData.ticker)) {
+                return instrumentId;
+            }
+        }
+        return null;
+    }
+
+
+    /**
+     * Main "meta-style" process function.
+     * @param {string} dateStr - Today's date.
+     * @param {object} dependencies - db, logger.
+     * @param {object} config - Computation config.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const { resultsCollection, resultsSubcollection, computationsSubcollection } = config;
+
+        // 1. Load Price Data
+        if (!this.priceMap) {
+            logger.log('INFO', '[Backtest] Loading all price data for simulation...');
+            this.priceMap = await loadAllPriceData();
+        }
+
+        // 2. Find Backtest Start Date
+        // We find the oldest signal. In a real system, you'd find the *newest* of the "oldest" dates.
+        const inceptionDateStr = await this._findSignalInceptionDate(
+            db, 
+            resultsCollection, 
+            'smart-dumb-divergence-index', // Our core signal
+            'meta' // The category of this signal
+        );
+        
+        if (!inceptionDateStr) {
+            logger.log('WARN', '[Backtest] No signal history found for smart-dumb-divergence-index. Skipping.');
+            return null;
+        }
+        logger.log('INFO', `[Backtest] Found signal inception date: ${inceptionDateStr}`);
+
+        // 3. Build Date Range
+        const allDates = [];
+        const current = new Date(inceptionDateStr + 'T00:00:00Z');
+        const end = new Date(dateStr + 'T00:00:00Z');
+        while (current <= end) {
+            allDates.push(current.toISOString().slice(0, 10));
+            current.setUTCDate(current.getUTCDate() + 1);
+        }
+        
+        if (allDates.length < 2) {
+            logger.log('WARN', '[Backtest] Not enough history to run simulation.');
+            return null;
+        }
+
+        // 4. Fetch ALL signals for ALL dates in one go
+        logger.log('INFO', `[Backtest] Fetching ${allDates.length} days of signal data...`);
+        const signalDataMap = await this._fetchAllSignals(
+            db, resultsCollection, resultsSubcollection, computationsSubcollection, allDates
+        );
+
+        // 5. --- Run the Simulation Loop ---
+        const portfolio = { cash: this.INITIAL_CASH, positions: {} }; // { ticker: { shares, instrumentId, marketValue } }
+        const history = []; // To store daily portfolio value
+
+        for (const date of allDates) {
+            // A. Mark-to-Market existing positions
+            let portfolioValue = portfolio.cash;
+            for (const ticker in portfolio.positions) {
+                const pos = portfolio.positions[ticker];
+                const price = this.priceMap[pos.instrumentId]?.[date];
+                
+                if (price) {
+                    pos.marketValue = price * pos.shares;
+                    portfolioValue += pos.marketValue;
+                } else {
+                    portfolioValue += pos.marketValue; // Use last known value if price missing
+                }
+            }
+            history.push({ date, portfolioValue });
+            
+            // B. Generate trades for *this* date
+            const tradesToMake = {}; // { 'AAPL': 'BUY', 'TSLA': 'SELL' }
+            for (const computation in this.strategySignals) {
+                const signalData = signalDataMap.get(`${date}_${computation}`);
+                if (!signalData) continue;
+                
+                const signalRules = this.strategySignals[computation];
+                // The signalData is the *entire doc* (e.g., { "AAPL": { status: "Capitulation", ... } })
+                for (const ticker in signalData) {
+                    const signal = signalData[ticker]?.status; // e.g., "Capitulation"
+                    if (signalRules[signal]) {
+                        tradesToMake[ticker] = signalRules[signal]; // 'BUY' or 'SELL'
+                    }
+                }
+            }
+
+            // C. Execute Trades
+            for (const ticker in tradesToMake) {
+                const action = tradesToMake[ticker];
+                
+                const instrumentId = this._findInstrumentId(ticker);
+                if (!instrumentId) {
+                    // logger.log('WARN', `[Backtest] No instrumentId for ${ticker}`);
+                    continue;
+                }
+                
+                const price = this.priceMap[instrumentId]?.[date];
+                if (!price || price <= 0) {
+                    // logger.log('WARN', `[Backtest] No price for ${ticker} on ${date}`);
+                    continue;
+                }
+
+                if (action === 'BUY' && portfolio.cash >= this.TRADE_SIZE_USD) {
+                    if (!portfolio.positions[ticker]) { // Only buy if not already holding
+                        const shares = this.TRADE_SIZE_USD / price;
+                        portfolio.cash -= this.TRADE_SIZE_USD;
+                        portfolio.positions[ticker] = {
+                            shares: shares,
+                            instrumentId: instrumentId,
+                            marketValue: this.TRADE_SIZE_USD
+                        };
+                    }
+                } else if (action === 'SELL' && portfolio.positions[ticker]) {
+                    // Simple: sell all
+                    portfolio.cash += portfolio.positions[ticker].marketValue;
+                    delete portfolio.positions[ticker];
+                }
+            }
+        } // --- End Simulation Loop ---
+
+        const finalValue = history[history.length - 1]?.portfolioValue || this.INITIAL_CASH;
+        const totalReturnPct = ((finalValue - this.INITIAL_CASH) / this.INITIAL_CASH) * 100;
+        
+        logger.log('INFO', `[Backtest] Simulation complete. Final Value: ${finalValue}, Return: ${totalReturnPct.toFixed(2)}%`);
+        
+        return {
+            strategyName: 'SmartDumbDivergence_v1',
+            inceptionDate: inceptionDateStr,
+            endDate: dateStr,
+            finalPortfolioValue: finalValue,
+            totalReturnPercent: totalReturnPct,
+            dailyHistory: history // This can be plotted on the frontend
+        };
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = StrategyPerformance;

package/calculations/behavioural/historical/dumb-cohort-flow.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Calculates "Net Crowd Flow" and "Sector Rotation"
+ * *only* for the "Dumb Cohort" (Bottom 20% of Investor Scores).
+ *
+ * This calc depends on 'user-investment-profile.js' being run first for the same day.
+ */
+
+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');
+
+const COHORT_PERCENTILE = 0.2; // Bottom 20%
+const PROFILE_CALC_ID = 'user-investment-profile'; // The calc to read IS scores from
+
+class DumbCohortFlow {
+    constructor() {
+        // Asset Flow
+        this.asset_values = {}; // { instrumentId: { day1_value_sum: 0, day2_value_sum: 0 } }
+        // Sector Rotation
+        this.todaySectorInvestment = {};
+        this.yesterdaySectorInvestment = {};
+        
+        this.dumbCohortIds = null; // Set of user IDs
+        this.user_count = 0; // Number of *cohort* users
+        this.priceMap = null;
+        this.mappings = null;
+        this.sectorMap = null;
+        this.dates = {};
+    }
+
+    /**
+     * Loads the Investor Scores, calculates the cohort threshold, and builds the Set of user IDs.
+     */
+    async _loadCohort(context, dependencies) {
+        const { db, logger } = dependencies;
+        logger.log('INFO', '[DumbCohortFlow] Loading Investor Scores to build cohort...');
+        
+        try {
+            const scoreMapRef = db.collection(context.config.resultsCollection).doc(context.todayDateStr)
+                .collection(context.config.resultsSubcollection).doc('behavioural')
+                .collection(context.config.computationsSubcollection).doc(PROFILE_CALC_ID);
+                
+            const doc = await scoreMapRef.get();
+            if (!doc.exists || !doc.data().daily_investor_scores) {
+                logger.log('WARN', '[DumbCohortFlow] Cannot find dependency: daily_investor_scores. Cohort will be empty.');
+                this.dumbCohortIds = new Set();
+                return;
+            }
+            
+            const scores = doc.data().daily_investor_scores;
+            const allScores = Object.entries(scores).map(([userId, score]) => ({ userId, score }));
+            allScores.sort((a, b) => a.score - b.score);
+            
+            const thresholdIndex = Math.floor(allScores.length * COHORT_PERCENTILE);
+            const thresholdScore = allScores[thresholdIndex]?.score || 0; // Get 20th percentile score
+            
+            this.dumbCohortIds = new Set(
+                allScores.filter(s => s.score <= thresholdScore).map(s => s.userId) // Get users *at or below*
+            );
+            
+            logger.log('INFO', `[DumbCohortFlow] Cohort built. ${this.dumbCohortIds.size} users at or below ${thresholdScore.toFixed(2)} (20th percentile).`);
+            
+        } catch (e) {
+            logger.log('ERROR', '[DumbCohortFlow] Failed to load cohort.', { error: e.message });
+            this.dumbCohortIds = new Set();
+        }
+    }
+
+    // --- Asset Flow Helpers ---
+    _initAsset(instrumentId) {
+        if (!this.asset_values[instrumentId]) {
+            this.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;
+    }
+    // --- Sector Rotation Helper ---
+    _accumulateSectorInvestment(portfolio, target) {
+        if (portfolio && portfolio.AggregatedPositions) {
+            for (const pos of portfolio.AggregatedPositions) {
+                const sector = this.sectorMap[pos.InstrumentID] || 'N/A';
+                target[sector] = (target[sector] || 0) + (pos.Invested || pos.Amount || 0);
+            }
+        }
+    }
+
+    /**
+     * PROCESS: Runs daily for each user.
+     */
+    async process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        // 1. Load cohort on first run
+        if (!this.dumbCohortIds) {
+            await this._loadCohort(context, context.dependencies);
+            this.dates.today = context.todayDateStr;
+            this.dates.yesterday = context.yesterdayDateStr;
+        }
+
+        // 2. Filter user
+        if (!this.dumbCohortIds.has(userId) || !todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+        
+        // 3. User is in the cohort, load maps if needed
+        if (!this.sectorMap) {
+            this.sectorMap = await getInstrumentSectorMap();
+        }
+
+        // --- 4. RUN ASSET FLOW LOGIC ---
+        const yesterdayValues = this._sumAssetValue(yesterdayPortfolio.AggregatedPositions);
+        const todayValues = this._sumAssetValue(todayPortfolio.AggregatedPositions);
+        const allInstrumentIds = new Set([...Object.keys(yesterdayValues), ...Object.keys(todayValues)]);
+        
+        for (const instrumentId of allInstrumentIds) {
+            this._initAsset(instrumentId);
+            this.asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
+            this.asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
+        }
+
+        // --- 5. RUN SECTOR ROTATION LOGIC ---
+        this._accumulateSectorInvestment(todayPortfolio, this.todaySectorInvestment);
+        this._accumulateSectorInvestment(yesterdayPortfolio, this.yesterdaySectorInvestment);
+
+        this.user_count++;
+    }
+
+    /**
+     * GETRESULT: Aggregates and returns the flow data for the cohort.
+     */
+    async getResult() {
+        if (this.user_count === 0 || !this.dates.today) {
+            return { asset_flow: {}, sector_rotation: {}, user_sample_size: 0 };
+        }
+
+        // 1. Load dependencies
+        if (!this.priceMap || !this.mappings) {
+            const [priceData, mappingData] = await Promise.all([
+                loadAllPriceData(),
+                loadInstrumentMappings()
+            ]);
+            this.priceMap = priceData;
+            this.mappings = mappingData;
+        }
+
+        // --- 2. Calculate Asset Flow ---
+        const finalAssetFlow = {};
+        const todayStr = this.dates.today;
+        const yesterdayStr = this.dates.yesterday;
+
+        for (const instrumentId in this.asset_values) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
+            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.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
+            };
+        }
+        
+        // --- 3. Calculate Sector Rotation ---
+        const finalSectorRotation = {};
+        const allSectors = new Set([...Object.keys(this.todaySectorInvestment), ...Object.keys(this.yesterdaySectorInvestment)]);
+        for (const sector of allSectors) {
+            const todayAmount = this.todaySectorInvestment[sector] || 0;
+            const yesterdayAmount = this.yesterdaySectorInvestment[sector] || 0;
+            finalSectorRotation[sector] = todayAmount - yesterdayAmount;
+        }
+
+        // 4. Return combined result
+        return {
+            asset_flow: finalAssetFlow,
+            sector_rotation: finalSectorRotation,
+            user_sample_size: this.user_count
+        };
+    }
+
+    reset() { /* ... reset all constructor properties ... */ }
+}
+
+module.exports = DumbCohortFlow;

package/calculations/behavioural/historical/smart-cohort-flow.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Calculates "Net Crowd Flow" and "Sector Rotation"
+ * *only* for the "Smart Cohort" (Top 20% of Investor Scores).
+ *
+ * This calc depends on 'user-investment-profile.js' being run first for the same day.
+ */
+
+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');
+
+const COHORT_PERCENTILE = 0.8; // Top 20%
+const PROFILE_CALC_ID = 'user-investment-profile'; // The calc to read IS scores from
+
+class SmartCohortFlow {
+    constructor() {
+        // Asset Flow
+        this.asset_values = {}; // { instrumentId: { day1_value_sum: 0, day2_value_sum: 0 } }
+        // Sector Rotation
+        this.todaySectorInvestment = {};
+        this.yesterdaySectorInvestment = {};
+        
+        this.smartCohortIds = null; // Set of user IDs
+        this.user_count = 0; // Number of *cohort* users
+        this.priceMap = null;
+        this.mappings = null;
+        this.sectorMap = null;
+        this.dates = {};
+    }
+
+    /**
+     * Loads the Investor Scores, calculates the cohort threshold, and builds the Set of user IDs.
+     */
+    async _loadCohort(context, dependencies) {
+        const { db, logger } = dependencies;
+        logger.log('INFO', '[SmartCohortFlow] Loading Investor Scores to build cohort...');
+        
+        try {
+            const scoreMapRef = db.collection(context.config.resultsCollection).doc(context.todayDateStr)
+                .collection(context.config.resultsSubcollection).doc('behavioural')
+                .collection(context.config.computationsSubcollection).doc(PROFILE_CALC_ID);
+                
+            const doc = await scoreMapRef.get();
+            if (!doc.exists || !doc.data().daily_investor_scores) {
+                logger.log('WARN', '[SmartCohortFlow] Cannot find dependency: daily_investor_scores. Cohort will be empty.');
+                this.smartCohortIds = new Set();
+                return;
+            }
+            
+            const scores = doc.data().daily_investor_scores;
+            const allScores = Object.entries(scores).map(([userId, score]) => ({ userId, score }));
+            allScores.sort((a, b) => a.score - b.score);
+            
+            const thresholdIndex = Math.floor(allScores.length * COHORT_PERCENTILE);
+            const thresholdScore = allScores[thresholdIndex]?.score || 999;
+            
+            this.smartCohortIds = new Set(
+                allScores.filter(s => s.score >= thresholdScore).map(s => s.userId)
+            );
+            
+            logger.log('INFO', `[SmartCohortFlow] Cohort built. ${this.smartCohortIds.size} users at or above ${thresholdScore.toFixed(2)} (80th percentile).`);
+            
+        } catch (e) {
+            logger.log('ERROR', '[SmartCohortFlow] Failed to load cohort.', { error: e.message });
+            this.smartCohortIds = new Set();
+        }
+    }
+
+    // --- Asset Flow Helpers ---
+    _initAsset(instrumentId) {
+        if (!this.asset_values[instrumentId]) {
+            this.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;
+    }
+    // --- Sector Rotation Helper ---
+    _accumulateSectorInvestment(portfolio, target) {
+        if (portfolio && portfolio.AggregatedPositions) {
+            for (const pos of portfolio.AggregatedPositions) {
+                const sector = this.sectorMap[pos.InstrumentID] || 'N/A';
+                target[sector] = (target[sector] || 0) + (pos.Invested || pos.Amount || 0);
+            }
+        }
+    }
+
+    /**
+     * PROCESS: Runs daily for each user.
+     */
+    async process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        // 1. Load cohort on first run
+        if (!this.smartCohortIds) {
+            await this._loadCohort(context, context.dependencies);
+            this.dates.today = context.todayDateStr;
+            this.dates.yesterday = context.yesterdayDateStr;
+        }
+
+        // 2. Filter user
+        if (!this.smartCohortIds.has(userId) || !todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+        
+        // 3. User is in the cohort, load maps if needed
+        if (!this.sectorMap) {
+            this.sectorMap = await getInstrumentSectorMap();
+        }
+
+        // --- 4. RUN ASSET FLOW LOGIC ---
+        const yesterdayValues = this._sumAssetValue(yesterdayPortfolio.AggregatedPositions);
+        const todayValues = this._sumAssetValue(todayPortfolio.AggregatedPositions);
+        const allInstrumentIds = new Set([...Object.keys(yesterdayValues), ...Object.keys(todayValues)]);
+        
+        for (const instrumentId of allInstrumentIds) {
+            this._initAsset(instrumentId);
+            this.asset_values[instrumentId].day1_value_sum += (yesterdayValues[instrumentId] || 0);
+            this.asset_values[instrumentId].day2_value_sum += (todayValues[instrumentId] || 0);
+        }
+
+        // --- 5. RUN SECTOR ROTATION LOGIC ---
+        this._accumulateSectorInvestment(todayPortfolio, this.todaySectorInvestment);
+        this._accumulateSectorInvestment(yesterdayPortfolio, this.yesterdaySectorInvestment);
+
+        this.user_count++;
+    }
+
+    /**
+     * GETRESULT: Aggregates and returns the flow data for the cohort.
+     */
+    async getResult() {
+        if (this.user_count === 0 || !this.dates.today) {
+            return { asset_flow: {}, sector_rotation: {}, user_sample_size: 0 };
+        }
+
+        // 1. Load dependencies
+        if (!this.priceMap || !this.mappings) {
+            const [priceData, mappingData] = await Promise.all([
+                loadAllPriceData(),
+                loadInstrumentMappings()
+            ]);
+            this.priceMap = priceData;
+            this.mappings = mappingData;
+        }
+
+        // --- 2. Calculate Asset Flow ---
+        const finalAssetFlow = {};
+        const todayStr = this.dates.today;
+        const yesterdayStr = this.dates.yesterday;
+
+        for (const instrumentId in this.asset_values) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
+            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.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
+            };
+        }
+        
+        // --- 3. Calculate Sector Rotation ---
+        const finalSectorRotation = {};
+        const allSectors = new Set([...Object.keys(this.todaySectorInvestment), ...Object.keys(this.yesterdaySectorInvestment)]);
+        for (const sector of allSectors) {
+            const todayAmount = this.todaySectorInvestment[sector] || 0;
+            const yesterdayAmount = this.yesterdaySectorInvestment[sector] || 0;
+            finalSectorRotation[sector] = todayAmount - yesterdayAmount; // Note: This is total $, not avg.
+        }
+
+        // 4. Return combined result
+        return {
+            asset_flow: finalAssetFlow,
+            sector_rotation: finalSectorRotation,
+            user_sample_size: this.user_count
+        };
+    }
+
+    reset() { /* ... reset all constructor properties ... */ }
+}
+
+module.exports = SmartCohortFlow;

package/calculations/behavioural/historical/user-investment-profile.js

@@ -0,0 +1,393 @@
+/**
+ * @fileoverview Calculates a rolling 90-day "Investor Score" (IS) for each normal user.
+ * Heuristic engine (not an academic finance model).  Outputs:
+ *  - sharded_user_profile: { <shardKey>: { profiles: { userId: [history...] }, lastUpdated } }
+ *  - daily_investor_scores: { userId: finalIS }
+ *
+ * Notes:
+ *  - NetProfit / ProfitAndLoss fields are assumed to be percent returns in decimal (e.g. 0.03 = +3%).
+ *  - The "Sharpe" used here is a cross-sectional dispersion proxy computed over position returns,
+ *    weighted by invested amounts. It's renamed/treated as a dispersionRiskProxy in comments.
+ */
+
+const { Firestore } = require('@google-cloud/firestore');
+const firestore = new Firestore();
+const { loadAllPriceData } = require('../../../utils/price_data_provider');
+const { getInstrumentSectorMap, loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+// Config
+const NUM_SHARDS = 50; // Must match the number of shards to read/write
+const ROLLING_DAYS = 90;
+const SHARD_COLLECTION_NAME = 'user_profile_history'; // The collection to store sharded history
+const PNL_TRACKER_CALC_ID = 'user-profitability-tracker'; // The calc to read PNL from
+
+// Helper: stable shard index for numeric or string IDs
+function getShardIndex(id) {
+    const n = parseInt(id, 10);
+    if (!Number.isNaN(n)) return Math.abs(n) % NUM_SHARDS;
+    // simple deterministic string hash fallback for non-numeric IDs (UUIDs)
+    let h = 0;
+    for (let i = 0; i < id.length; i++) {
+        h = ((h << 5) - h) + id.charCodeAt(i);
+        h |= 0; // keep 32-bit
+    }
+    return Math.abs(h) % NUM_SHARDS;
+}
+
+class UserInvestmentProfile {
+    constructor() {
+        // will hold today's per-user raw heuristic scores
+        this.dailyUserScores = {}; // { userId: { score_rd, score_disc, score_time } }
+
+        // cached dependencies
+        this.priceMap = null;
+        this.sectorMap = null;
+        this.pnlScores = null; // { userId: dailyPnlDecimal }
+        this.dates = {};
+        this.dependenciesLoaded = false;
+    }
+
+    /**
+     * Loads external dependencies once per run.
+     */
+    async _loadDependencies(context, dependencies) {
+        if (this.dependenciesLoaded) return;
+
+        const { db, logger } = dependencies;
+        const { todayDateStr } = context;
+
+        if (logger) logger.log('INFO', '[UserInvestmentProfile] Loading dependencies...');
+
+        // load price data and sector mapping in parallel
+        const [priceData, sectorData] = await Promise.all([
+            loadAllPriceData(),
+            getInstrumentSectorMap()
+        ]);
+        this.priceMap = priceData || {};
+        this.sectorMap = sectorData || {};
+
+        // load PNL map (daily percent returns per user) from PNL calc
+        this.pnlScores = {};
+        try {
+            const pnlCalcRef = db.collection(context.config.resultsCollection).doc(todayDateStr)
+                .collection(context.config.resultsSubcollection).doc('pnl')
+                .collection(context.config.computationsSubcollection).doc(PNL_TRACKER_CALC_ID);
+
+            const pnlSnap = await pnlCalcRef.get();
+            if (pnlSnap.exists) {
+                this.pnlScores = pnlSnap.data().daily_pnl_map || {};
+                if (logger) logger.log('INFO', `[UserInvestmentProfile] Loaded ${Object.keys(this.pnlScores).length} PNL scores.`);
+            } else {
+                if (logger) logger.log('WARN', `[UserInvestmentProfile] Could not find PNL scores dependency for ${todayDateStr}. PNL score will be 0.`);
+            }
+        } catch (e) {
+            if (logger) logger.log('ERROR', `[UserInvestmentProfile] Failed to load PNL scores.`, { error: e.message });
+        }
+
+        this.dependenciesLoaded = true;
+        if (logger) logger.log('INFO', '[UserInvestmentProfile] All dependencies loaded.');
+    }
+
+    /**
+     * HEURISTIC 1: Risk & Diversification Score (0-10).
+     *
+     * Implementation notes:
+     * - NetProfit is assumed to be a percent return in decimal per position (e.g. 0.03 = +3%).
+     * - We compute a weighted mean/std of returns across positions (weights = invested amounts).
+     *   This gives a cross-sectional dispersion proxy (not a time-series Sharpe).
+     */
+    _calculateRiskAndDivScore(todayPortfolio) {
+        if (!todayPortfolio.AggregatedPositions || todayPortfolio.AggregatedPositions.length === 0) {
+            return 5; // neutral
+        }
+
+        const positions = todayPortfolio.AggregatedPositions;
+        let totalInvested = 0;
+        let weightedRetSum = 0;
+        let weightedRetSqSum = 0;
+        let maxPosition = 0;
+        const sectors = new Set();
+
+        for (const pos of positions) {
+            const invested = pos.InvestedAmount || pos.Amount || 0;
+            const netProfit = ('NetProfit' in pos) ? pos.NetProfit : (pos.ProfitAndLoss || 0); // decimal % return
+            const ret = invested > 0 ? (netProfit) : netProfit; // if invested==0 we still include ret but weight 0
+
+            weightedRetSum += ret * invested;
+            weightedRetSqSum += (ret * ret) * invested;
+            totalInvested += invested;
+            if (invested > maxPosition) maxPosition = invested;
+
+            sectors.add(this.sectorMap[pos.InstrumentID] || 'N/A');
+        }
+
+        // Weighted mean & variance of returns
+        const meanReturn = totalInvested > 0 ? (weightedRetSum / totalInvested) : 0;
+        const meanReturnSq = totalInvested > 0 ? (weightedRetSqSum / totalInvested) : (meanReturn * meanReturn);
+        const variance = Math.max(0, meanReturnSq - (meanReturn * meanReturn));
+        const stdReturn = Math.sqrt(variance);
+
+        // dispersion proxy: mean / std (if std is zero we treat as neutral 0)
+        let dispersionRiskProxy = stdReturn > 0 ? meanReturn / stdReturn : 0;
+
+        // cap and map dispersion proxy to [0..10].
+        // dispersionRiskProxy can be outside [-2..4], clamp to reasonable bounds first.
+        const capped = Math.max(-2, Math.min(4, dispersionRiskProxy));
+        const scoreSharpe = ((capped + 2) / 6) * 10; // maps [-2..4] -> [0..10]
+
+        // Sector diversification (monotonic - diminishing returns)
+        const sectorCount = sectors.size;
+        let scoreDiversification = 0;
+        if (sectorCount === 1) scoreDiversification = 0;
+        else if (sectorCount <= 4) scoreDiversification = 5;
+        else if (sectorCount <= 7) scoreDiversification = 8;
+        else scoreDiversification = 10;
+
+        // Position sizing / concentration penalty
+        const concentrationRatio = totalInvested > 0 ? (maxPosition / totalInvested) : 0;
+        let scoreSizing = 0;
+        if (concentrationRatio > 0.8) scoreSizing = 0;
+        else if (concentrationRatio > 0.5) scoreSizing = 2;
+        else if (concentrationRatio > 0.3) scoreSizing = 5;
+        else if (concentrationRatio > 0.15) scoreSizing = 8;
+        else scoreSizing = 10;
+
+        const final = (scoreSharpe * 0.4) + (scoreDiversification * 0.3) + (scoreSizing * 0.3);
+        return Math.max(0, Math.min(10, final));
+    }
+
+    /**
+     * HEURISTIC 2: Discipline Score (0-10).
+     *
+     * Uses yesterday's positions to evaluate closes, averaging down, holding losers/winners.
+     * Defensive: uses safe field fallbacks and guards against division by zero.
+     */
+    _calculateDisciplineScore(yesterdayPortfolio = {}, todayPortfolio = {}) {
+        const yPositions = yesterdayPortfolio.AggregatedPositions || [];
+        const tPositions = new Map((todayPortfolio.AggregatedPositions || []).map(p => [p.PositionID, p]));
+
+        if (yPositions.length === 0) {
+            return 5; // neutral if nothing to judge
+        }
+
+        let eventPoints = 0;
+        let eventCount = 0;
+
+        for (const yPos of yPositions) {
+            const profitAndLoss = ('ProfitAndLoss' in yPos) ? yPos.ProfitAndLoss : (yPos.NetProfit || 0);
+            const invested = yPos.InvestedAmount || yPos.Amount || 0;
+            const pnlPercent = profitAndLoss; // This is already the decimal % return
+
+            const tPos = tPositions.get(yPos.PositionID);
+
+            if (!tPos) {
+                // Closed position
+                eventCount++;
+                if (pnlPercent < -0.05) eventPoints += 10;         // cut loser (good)
+                else if (pnlPercent > 0.20) eventPoints += 8;     // took big profit (good)
+                else if (pnlPercent > 0 && pnlPercent < 0.05) eventPoints += 2; // paper hands (bad)
+                else eventPoints += 5; // neutral close
+            } else {
+                // Held or modified
+                if (pnlPercent < -0.10) {
+                    eventCount++;
+                    const tInvested = tPos.InvestedAmount || tPos.Amount || 0;
+                    if (tInvested > invested) eventPoints += 0; // averaged down (very poor)
+                    else eventPoints += 3; // held loser (poor)
+                } else if (pnlPercent > 0.15) {
+                    eventCount++;
+                    eventPoints += 10; // held/added to winner (good)
+                }
+            }
+        }
+
+        const avg = (eventCount > 0) ? (eventPoints / eventCount) : 5;
+        return Math.max(0, Math.min(10, avg));
+    }
+
+    /**
+     * HEURISTIC 3: Market Timing Score (0-10).
+     *
+     * For new positions opened today (not present yesterday), measure proximity of openRate to
+     * the last 30-day low/high. Uses date-sorted price history and clamps.
+     */
+    _calculateMarketTimingScore(yesterdayPortfolio = {}, todayPortfolio = {}) {
+        const yIds = new Set((yesterdayPortfolio.AggregatedPositions || []).map(p => p.PositionID));
+        const newPositions = (todayPortfolio.AggregatedPositions || []).filter(p => !yIds.has(p.PositionID));
+
+        if (newPositions.length === 0) return 5;
+
+        let timingPoints = 0;
+        let timingCount = 0;
+
+        for (const tPos of newPositions) {
+            const prices = this.priceMap[tPos.InstrumentID];
+            if (!prices) continue;
+
+            // Accept prices as either array or {date:price} map; build sorted array of prices
+            let historyPrices = [];
+            if (Array.isArray(prices)) {
+                // assume array of numbers or objects with .price/.close
+                historyPrices = prices
+                    .map(p => (typeof p === 'number' ? p : (p.price || p.close || null)))
+                    .filter(v => v != null);
+            } else {
+                // object keyed by date -> price
+                const entries = Object.keys(prices)
+                    .map(d => ({ d, p: prices[d] }))
+                    .filter(e => e.p != null)
+                    .sort((a, b) => new Date(a.d) - new Date(b.d));
+                historyPrices = entries.map(e => e.p);
+            }
+
+            const last30 = historyPrices.slice(-30);
+            if (last30.length < 2) continue;
+
+            const minPrice = Math.min(...last30);
+            const maxPrice = Math.max(...last30);
+            const openRate = tPos.OpenRate;
+            const range = maxPrice - minPrice;
+            if (!isFinite(range) || range === 0) continue;
+
+            let proximity = (openRate - minPrice) / range; // 0 = at low, 1 = at high
+            proximity = Math.max(0, Math.min(1, proximity)); // clamp to [0,1]
+
+            timingCount++;
+            if (proximity < 0.2) timingPoints += 10;
+            else if (proximity < 0.4) timingPoints += 8;
+            else if (proximity > 0.9) timingPoints += 1;
+            else if (proximity > 0.7) timingPoints += 3;
+            else timingPoints += 5;
+        }
+
+        const avg = (timingCount > 0) ? (timingPoints / timingCount) : 5;
+        return Math.max(0, Math.min(10, avg));
+    }
+
+    /**
+     * PROCESS: called per-user per-day to compute and store today's heuristics.
+     */
+    async process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, todaySocial, yesterdaySocial) {
+        // run only for normal users with portfolios
+        if (!todayPortfolio || !todayPortfolio.AggregatedPositions) return;
+
+        if (!this.dependenciesLoaded) {
+            await this._loadDependencies(context, context.dependencies);
+            this.dates.today = context.todayDateStr;
+        }
+
+        const yPort = yesterdayPortfolio || {};
+
+        const score_rd = this._calculateRiskAndDivScore(todayPortfolio);
+        const score_disc = this._calculateDisciplineScore(yPort, todayPortfolio);
+        const score_time = this._calculateMarketTimingScore(yPort, todayPortfolio);
+
+        this.dailyUserScores[userId] = {
+            score_rd,
+            score_disc,
+            score_time
+        };
+    }
+
+    /**
+     * GETRESULT: Aggregate into rolling 90-day history, compute avg components and final IS.
+     *
+     * Returns a structure prepared for writing where each shardKey maps to:
+     *   { profiles: { userId: historyArray, ... }, lastUpdated: todayStr }
+     *
+     * This must match how existing shards are read (snap.data().profiles).
+     */
+    async getResult() {
+        if (Object.keys(this.dailyUserScores).length === 0) return {};
+
+        const todayStr = this.dates.today || (new Date()).toISOString().slice(0, 10);
+
+        // prepare sharded output objects with profiles container (Option A)
+        const shardedResults = {};
+        for (let i = 0; i < NUM_SHARDS; i++) {
+            const shardKey = `${SHARD_COLLECTION_NAME}_shard_${i}`;
+            shardedResults[shardKey] = { profiles: {}, lastUpdated: todayStr };
+        }
+
+        const dailyInvestorScoreMap = {};
+
+        // fetch existing shards in parallel
+        const shardPromises = [];
+        for (let i = 0; i < NUM_SHARDS; i++) {
+            const docRef = firestore.collection(SHARD_COLLECTION_NAME).doc(`${SHARD_COLLECTION_NAME}_shard_${i}`);
+            shardPromises.push(docRef.get());
+        }
+        const shardSnapshots = await Promise.all(shardPromises);
+
+        // Build existingShards map of profiles for quick access
+        const existingShards = shardSnapshots.map((snap, idx) => {
+            if (!snap.exists) return {}; // no profiles
+            const data = snap.data() || {};
+            return data.profiles || {};
+        });
+
+        // process users
+        for (const userId of Object.keys(this.dailyUserScores)) {
+            const shardIndex = getShardIndex(userId);
+            const scores = this.dailyUserScores[userId];
+
+            // fetch existing history for this user (if present)
+            const existingProfiles = existingShards[shardIndex] || {};
+            // clone to avoid mutating snapshot data directly
+            const history = (existingProfiles[userId] || []).slice();
+
+            history.push({
+                date: todayStr,
+                ...scores,
+                pnl: (this.pnlScores && (userId in this.pnlScores)) ? this.pnlScores[userId] : 0
+            });
+
+            const newHistory = history.slice(-ROLLING_DAYS);
+
+            // compute rolling averages
+            let avg_rd = 0, avg_disc = 0, avg_time = 0, avg_pnl = 0;
+            for (const entry of newHistory) {
+                avg_rd += (entry.score_rd || 0);
+                avg_disc += (entry.score_disc || 0);
+                avg_time += (entry.score_time || 0);
+                avg_pnl += (entry.pnl || 0);
+            }
+            const N = newHistory.length || 1;
+            avg_rd /= N;
+            avg_disc /= N;
+            avg_time /= N;
+            avg_pnl /= N;
+
+            // Normalize PNL: avg_pnl is decimal percent (0.005 -> 0.5%). Map to 0-10 scale:
+            // multiply by 1000 (0.005 -> 5). Clamp to [-10, 10] to avoid outliers.
+            const normalizedPnl = Math.max(-10, Math.min(10, avg_pnl * 1000));
+
+            // Final IS (weights): discipline 40%, risk/div 30%, timing 20%, pnl 10%
+            const finalISRaw = (avg_disc * 0.4) + (avg_rd * 0.3) + (avg_time * 0.2) + (normalizedPnl * 0.1);
+            const finalIS = Math.max(0, Math.min(10, finalISRaw));
+
+            // store in prepared shard result under 'profiles'
+            const shardKey = `${SHARD_COLLECTION_NAME}_shard_${shardIndex}`;
+            shardedResults[shardKey].profiles[userId] = newHistory;
+
+            // also set the daily investor score
+            dailyInvestorScoreMap[userId] = finalIS;
+        }
+
+        return {
+            sharded_user_profile: shardedResults,
+            daily_investor_scores: dailyInvestorScoreMap
+        };
+    }
+
+    reset() {
+        this.dailyUserScores = {};
+        this.dependenciesLoaded = false;
+        this.priceMap = null;
+        this.sectorMap = null;
+        this.pnlScores = null;
+        this.dates = {};
+    }
+}
+
+module.exports = UserInvestmentProfile;

package/calculations/meta/smart-dumb-divergence-index.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) that correlates the asset/sector flow
+ * of the "Smart Cohort" vs. the "Dumb Cohort" to find divergence signals.
+ *
+ * This identifies:
+ * 1. "Capitulation": Smart cohort is buying what the dumb cohort is panic-selling.
+ * 2. "Euphoria": Smart cohort is selling what the dumb cohort is FOMO-buying.
+ */
+
+class SmartDumbDivergenceIndex {
+    constructor() {
+        // Minimum net flow (as a percentage) to be considered a signal
+        this.FLOW_THRESHOLD = 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: 'smart_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('smart-cohort-flow')
+            },
+            {
+                key: 'dumb_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('dumb-cohort-flow')
+            }
+        ];
+
+        // 2. Fetch
+        const snapshots = await db.getAll(...refsToGet.map(r => r.ref));
+        const smartData = snapshots[0].exists ? snapshots[0].data() : null;
+        const dumbData = snapshots[1].exists ? snapshots[1].data() : null;
+
+        // 3. Handle "day-delay"
+        if (!smartData || !dumbData) {
+            logger.log('WARN', `[SmartDumbDivergence] Missing cohort flow data for ${dateStr}. Allowing backfill.`);
+            return null; // Let backfill handle it
+        }
+        
+        const results = {
+            assets: {},
+            sectors: {}
+        };
+        
+        const smartAssetFlow = smartData.asset_flow || {};
+        const dumbAssetFlow = dumbData.asset_flow || {};
+        const smartSectorFlow = smartData.sector_rotation || {};
+        const dumbSectorFlow = dumbData.sector_rotation || {};
+
+        // 4. 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
+                };
+            }
+        }
+        
+        // 5. Correlate Sectors (Note: flow is total $, not %)
+        // We can just check for opposing signs
+        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/pnl/historical/user_profitability_tracker.js

@@ -1,47 +1,68 @@
 /**
  * @fileoverview Tracks user profitability over a 7-day rolling window.
- * This version shards the output to avoid Firestore's "too many index entries" error.
+ * This version shards the output AND calculates the user's *weighted average daily PNL (as a decimal %)*.
  */
 
 const { Firestore } = require('@google-cloud/firestore');
 const firestore = new Firestore();
 
-// Define a constant for the number of shards
 const NUM_SHARDS = 50;
 
 class UserProfitabilityTracker {
     constructor() {
-        this.dailyProfits = {};
+        // This will store { userId: { weightedPnlSum: 0, totalInvested: 0 } }
+        this.dailyData = {}; 
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio) return;
+    /**
+     * Calculates the weighted PNL for the day.
+     * NetProfit is a decimal % return (e.g., 0.03)
+     * Invested is a decimal % weight (e.g., 0.05)
+     */
+    calculateWeightedDailyPnl(portfolio) {
+        if (!portfolio || !portfolio.AggregatedPositions || portfolio.AggregatedPositions.length === 0) {
+            return { weightedPnl: 0, totalInvested: 0 };
+        }
+
+        let weightedPnlSum = 0;
+        let totalInvested = 0;
 
-        const todayPnl = this.calculateTotalPnl(todayPortfolio);
-        if (todayPnl !== null) {
-            this.dailyProfits[userId] = todayPnl;
+        for (const pos of portfolio.AggregatedPositions) {
+            // Use NetProfit (the % return)
+            const netProfit = ('NetProfit' in pos) ? pos.NetProfit : (pos.ProfitAndLoss || 0); 
+            // Use InvestedAmount (the % portfolio weight)
+            const invested = pos.InvestedAmount || pos.Amount || 0; 
+
+            if (invested > 0) {
+                weightedPnlSum += netProfit * invested;
+                totalInvested += invested;
+            }
         }
+
+        return { weightedPnlSum, totalInvested };
     }
 
-    calculateTotalPnl(portfolio) {
-        if (portfolio && portfolio.AggregatedPositions) {
-            return portfolio.AggregatedPositions.reduce((sum, pos) => sum + pos.NetProfit, 0);
-        } else if (portfolio && portfolio.PublicPositions) {
-            return portfolio.PublicPositions.reduce((sum, pos) => sum + pos.NetProfit, 0);
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio) return;
+
+        const { weightedPnlSum, totalInvested } = this.calculateWeightedDailyPnl(todayPortfolio);
+
+        if (totalInvested > 0) {
+            this.dailyData[userId] = { weightedPnlSum, totalInvested };
         }
-        return null;
     }
 
     async getResult() {
         const today = new Date().toISOString().slice(0, 10);
-        const results = {};
+        const results = {}; // For sharded history
+        const dailyPnlMap = {}; // For the new profile calc
 
         // Prepare sharded data structure
         for (let i = 0; i < NUM_SHARDS; i++) {
             results[`user_profitability_shard_${i}`] = {};
         }
 
-        // Fetch all existing shards in parallel for efficiency
+        // ... (Fetch existing shards logic, same as your file) ...
         const shardPromises = [];
         for (let i = 0; i < NUM_SHARDS; i++) {
             const docRef = firestore.collection('historical_insights').doc(`user_profitability_shard_${i}`);
@@ -50,18 +71,38 @@ class UserProfitabilityTracker {
         const shardSnapshots = await Promise.all(shardPromises);
         const existingData = shardSnapshots.map(snap => (snap.exists ? snap.data().profits : {}));
 
-        // Process users and assign them to shards
-        for (const userId in this.dailyProfits) {
+
+        for (const userId in this.dailyData) {
+            const { weightedPnlSum, totalInvested } = this.dailyData[userId];
+
+            // Calculate the final weighted average % return for the day
+            // We cap totalInvested at 1.0 (100%) in case of data issues
+            const totalWeight = Math.min(1.0, totalInvested);
+            const dailyAvgPnl = (totalWeight > 0) ? (weightedPnlSum / totalWeight) : 0;
+
+            // Store this for the profile calc dependency
+            dailyPnlMap[userId] = dailyAvgPnl;
+
+            // --- Now, update the sharded history ---
             const shardIndex = parseInt(userId, 10) % NUM_SHARDS;
             const userHistory = existingData[shardIndex][userId] || [];
             
-            userHistory.push({ date: today, pnl: this.dailyProfits[userId] });
+            // Store the decimal % pnl in the history
+            userHistory.push({ date: today, pnl: dailyAvgPnl }); 
             
-            // Ensure we only keep the last 7 days of data
-            results[`user_profitability_shard_${shardIndex}`][userId] = userHistory.slice(-7);
+            const shardKey = `user_profitability_shard_${shardIndex}`;
+            if (!results[shardKey]) results[shardKey] = {};
+            results[shardKey][userId] = userHistory.slice(-7);
         }
 
-        return { sharded_user_profitability: results };
+        return {
+            sharded_user_profitability: results,
+            daily_pnl_map: dailyPnlMap // <-- This now correctly outputs the weighted avg % PNL
+        };
+    }
+
+    reset() {
+        this.dailyData = {};
     }
 }
 

package/package.json

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