aiden-shared-calculations-unified 1.0.34 → 1.0.36

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

@@ -1,413 +1,413 @@
-/**
- * @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;
-        
-        // --- START MODIFICATION ---
-        // Flag to track if dependencies loaded successfully
-        this.dependencyLoadedSuccess = false;
-        // --- END MODIFICATION ---
-    }
-
-    /**
-     * 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();
-            
-            // --- START MODIFICATION ---
-            // Check for existence of the doc AND the data within it
-            if (pnlSnap.exists && pnlSnap.data().daily_pnl_map) {
-                this.pnlScores = pnlSnap.data().daily_pnl_map || {};
-                if (logger) logger.log('INFO', `[UserInvestmentProfile] Loaded ${Object.keys(this.pnlScores).length} PNL scores.`);
-                this.dependencyLoadedSuccess = true; // Set success flag
-            } else {
-                if (logger) logger.log('WARN', `[UserInvestmentProfile] Could not find PNL scores dependency for ${todayDateStr}. PNL score will be 0. Aborting profile calculation.`);
-                this.dependencyLoadedSuccess = false; // Set failure flag
-            }
-            // --- END MODIFICATION ---
-
-        } catch (e) {
-            if (logger) logger.log('ERROR', `[UserInvestmentProfile] Failed to load PNL scores.`, { error: e.message });
-            this.dependencyLoadedSuccess = false; // Set failure flag on error
-        }
-
-        this.dependenciesLoaded = true;
-        if (logger) logger.log('INFO', '[UserInvestmentProfile] All dependencies loaded.');
-    }
-
-    // ... [Heuristic calculation functions _calculateRiskAndDivScore, _calculateDisciplineScore, _calculateMarketTimingScore are unchanged] ...
-
-    /**
-     * HEURISTIC 1: Risk & Diversification Score (0-10).
-     */
-    _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).
-     */
-    _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).
-     */
-    _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;
-        }
-        
-        // --- START MODIFICATION ---
-        // If dependencies failed to load (e.g., PNL doc was missing), stop processing.
-        if (!this.dependencyLoadedSuccess) {
-            return;
-        }
-        // --- END MODIFICATION ---
-
-        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.
-     */
-    async getResult() {
-        // --- START MODIFICATION ---
-        // If dependencies failed, return null to trigger backfill.
-        if (!this.dependencyLoadedSuccess) {
-            // Logger might not be available here, use console.warn
-            console.warn('[UserInvestmentProfile] Skipping getResult as dependency (pnl-tracker) failed.');
-            return null;
-        }
-        
-        // If no users were processed (e.g., all were filtered out), return null.
-        if (Object.keys(this.dailyUserScores).length === 0) {
-            console.warn('[UserInvestmentProfile] No daily user scores were calculated. Returning null for backfill.');
-            return null;
-        }
-        // --- END MODIFICATION ---
-
-        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 = {};
-        this.dependencyLoadedSuccess = false; // <-- MODIFICATION
-    }
-}
-
+/**
+ * @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;
+        
+        // --- START MODIFICATION ---
+        // Flag to track if dependencies loaded successfully
+        this.dependencyLoadedSuccess = false;
+        // --- END MODIFICATION ---
+    }
+
+    /**
+     * 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();
+            
+            // --- START MODIFICATION ---
+            // Check for existence of the doc AND the data within it
+            if (pnlSnap.exists && pnlSnap.data().daily_pnl_map) {
+                this.pnlScores = pnlSnap.data().daily_pnl_map || {};
+                if (logger) logger.log('INFO', `[UserInvestmentProfile] Loaded ${Object.keys(this.pnlScores).length} PNL scores.`);
+                this.dependencyLoadedSuccess = true; // Set success flag
+            } else {
+                if (logger) logger.log('WARN', `[UserInvestmentProfile] Could not find PNL scores dependency for ${todayDateStr}. PNL score will be 0. Aborting profile calculation.`);
+                this.dependencyLoadedSuccess = false; // Set failure flag
+            }
+            // --- END MODIFICATION ---
+
+        } catch (e) {
+            if (logger) logger.log('ERROR', `[UserInvestmentProfile] Failed to load PNL scores.`, { error: e.message });
+            this.dependencyLoadedSuccess = false; // Set failure flag on error
+        }
+
+        this.dependenciesLoaded = true;
+        if (logger) logger.log('INFO', '[UserInvestmentProfile] All dependencies loaded.');
+    }
+
+    // ... [Heuristic calculation functions _calculateRiskAndDivScore, _calculateDisciplineScore, _calculateMarketTimingScore are unchanged] ...
+
+    /**
+     * HEURISTIC 1: Risk & Diversification Score (0-10).
+     */
+    _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).
+     */
+    _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).
+     */
+    _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;
+        }
+        
+        // --- START MODIFICATION ---
+        // If dependencies failed to load (e.g., PNL doc was missing), stop processing.
+        if (!this.dependencyLoadedSuccess) {
+            return;
+        }
+        // --- END MODIFICATION ---
+
+        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.
+     */
+    async getResult() {
+        // --- START MODIFICATION ---
+        // If dependencies failed, return null to trigger backfill.
+        if (!this.dependencyLoadedSuccess) {
+            // Logger might not be available here, use console.warn
+            console.warn('[UserInvestmentProfile] Skipping getResult as dependency (pnl-tracker) failed.');
+            return null;
+        }
+        
+        // If no users were processed (e.g., all were filtered out), return null.
+        if (Object.keys(this.dailyUserScores).length === 0) {
+            console.warn('[UserInvestmentProfile] No daily user scores were calculated. Returning null for backfill.');
+            return null;
+        }
+        // --- END MODIFICATION ---
+
+        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 = {};
+        this.dependencyLoadedSuccess = false; // <-- MODIFICATION
+    }
+}
+
 module.exports = UserInvestmentProfile;