bulltrackers-module 1.0.210 → 1.0.212

package/functions/computation-system/layers/math_primitives.js

@@ -1,744 +1,744 @@
-/**
- * @fileoverview Math Layer - Single Source of Truth (V3 Final)
- * Encapsulates Schema Knowledge, Mathematical Primitives, and Signal Extractors.
- * * STRICT COMPLIANCE:
- * - Adheres to 'schema.md' definitions.
- * - standardizes access to P&L, Weights, and Rates.
- */
-
-const SCHEMAS = {
-    USER_TYPES: { NORMAL: 'normal', SPECULATOR: 'speculator' },
-    STYLES: { DAY_TRADER: 'Day Trader', SWING_TRADER: 'Swing Trader', INVESTOR: 'Investor' },
-    LABELS: { SMART: 'Smart Money', DUMB: 'Dumb Money', NEUTRAL: 'Neutral' }
-};
-
-class InsightsExtractor {
-    /**
-     * Extracts the raw array of insight objects from the context.
-     * Checks for standard context injection paths.
-     */
-    static getInsights(context) {
-        // Support multiple potential injection paths depending on controller version
-        return context.insights || context.daily_instrument_insights || [];
-    }
-
-    /**
-     * returns the specific insight object for a given instrument ID.
-     */
-    static getInsightForInstrument(insights, instrumentId) {
-        if (!insights || !Array.isArray(insights)) return null;
-        return insights.find(i => i.instrumentId === instrumentId) || null;
-    }
-
-    // --- Standard Metrics ---
-
-    static getTotalOwners(insight) {
-        return insight ? (insight.total || 0) : 0;
-    }
-
-    static getLongPercent(insight) {
-        return insight ? (insight.buy || 0) : 0;
-    }
-
-    static getShortPercent(insight) {
-        return insight ? (insight.sell || 0) : 0;
-    }
-
-    static getGrowthPercent(insight) {
-        return insight ? (insight.growth || 0) : 0;
-    }
-
-    // --- Derived Counts (Estimated) ---
-
-    static getLongCount(insight) {
-        const total = this.getTotalOwners(insight);
-        const buyPct = this.getLongPercent(insight);
-        return Math.floor(total * (buyPct / 100));
-    }
-
-    static getShortCount(insight) {
-        const total = this.getTotalOwners(insight);
-        const sellPct = this.getShortPercent(insight);
-        return Math.floor(total * (sellPct / 100));
-    }
-
-    /**
-     * Calculates the net change in users from yesterday based on growth %.
-     * Formula: NetChange = Total - (Total / (1 + Growth/100))
-     */
-    static getNetOwnershipChange(insight) {
-        const total = this.getTotalOwners(insight);
-        const growth = this.getGrowthPercent(insight);
-        if (total === 0) return 0;
-        
-        // Reverse engineer yesterday's count
-        // Today = Yesterday * (1 + growth)
-        // Yesterday = Today / (1 + growth)
-        const prevTotal = total / (1 + (growth / 100)); // TODO: Check precision issues
-        return Math.round(total - prevTotal);
-    }
-}
-
-class UserClassifier {
-    /**
-     * Classifies a user as Smart/Dumb based on Win Rate and Profitability.
-     * @param {Object} historySummary - Result from HistoryExtractor.getSummary()
-     */
-    static classifySmartDumb(historySummary) {
-        if (!historySummary || historySummary.totalTrades < 5) return SCHEMAS.LABELS.NEUTRAL; // Insufficient data
-
-        const { winRatio, avgProfitPct, avgLossPct } = historySummary;
-
-        // 1. The "Consistent Winner" (Smart)
-        if (winRatio > 60 && avgProfitPct > Math.abs(avgLossPct)) return SCHEMAS.LABELS.SMART;
-
-        // 2. The "Sniper" (Smart - Low Win Rate but huge winners)
-        if (winRatio > 30 && avgProfitPct > (Math.abs(avgLossPct) * 2.5)) return SCHEMAS.LABELS.SMART;
-
-        // 3. The "Bagholder" (Dumb - High win rate but one loss wipes them out)
-        if (winRatio > 80 && (Math.abs(avgLossPct) > avgProfitPct * 4)) return SCHEMAS.LABELS.DUMB;
-
-        // 4. The "Gambler" (Dumb - Losing money consistently)
-        if (winRatio < 40 && avgProfitPct < Math.abs(avgLossPct)) return SCHEMAS.LABELS.DUMB;
-
-        return SCHEMAS.LABELS.NEUTRAL;
-    }
-
-    /**
-     * Classifies trading style based on average holding time.
-     * @param {number} avgHoldingMinutes 
-     */
-    static classifyStyle(avgHoldingMinutes) {
-        if (avgHoldingMinutes <= 0) return SCHEMAS.STYLES.INVESTOR; // Default
-        
-        if (avgHoldingMinutes < 60 * 24) return SCHEMAS.STYLES.DAY_TRADER; // < 1 Day
-        if (avgHoldingMinutes < 60 * 24 * 30) return SCHEMAS.STYLES.SWING_TRADER; // < 1 Month
-        return SCHEMAS.STYLES.INVESTOR; // > 1 Month
-    }
-}
-
-class DataExtractor { // For generic access of data types
-    // ========================================================================
-    // 1. COLLECTION ACCESSORS
-    // ========================================================================
-    
-    /**
-     * Extract positions array based on User Type.
-     * - Normal: Uses 'AggregatedPositions' (Grouped by Asset + Direction)
-     * - Speculator: Uses 'PublicPositions' (Individual Trades)
-     */
-    static getPositions(portfolio, userType) {
-        if (!portfolio) return []; // Handle empty portfolio
-        
-        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) { 
-            return portfolio.PublicPositions || []; // SPECULATOR SCHEMA
-        }
-        
-        // Default to Normal User Schema
-        return portfolio.AggregatedPositions || [];
-    }
-
-    // ========================================================================
-    // 2. IDENTITY & KEYS
-    // ========================================================================
-
-    /**
-     * Extract standardized Instrument ID.
-     */
-    static getInstrumentId(position) {
-        if (!position) return null; // Handle empty position data
-        // Handle string or number variations safely
-        return position.InstrumentID || position.instrumentId || null;
-    }
-
-    /**
-     * Extract a unique Identifier for the position.
-     * - Speculator: Uses 'PositionID'.
-     * - Normal: Generates Composite Key (InstrumentID_Direction) since they lack unique Trade IDs.
-     */
-    static getPositionId(position) {
-        if (!position) return null; // Handle empty position data
-        
-        // 1. Try Explicit ID (Speculators)
-        if (position.PositionID) return String(position.PositionID);
-        if (position.PositionId) return String(position.PositionId);
-
-        // 2. Fallback to Composite Key (Normal Users)
-        const instId = this.getInstrumentId(position);
-        const dir    = this.getDirection(position);
-        if (instId) return `${instId}_${dir}`;
-
-        return null;
-    }
-
-    // ========================================================================
-    // 3. FINANCIAL METRICS (WEIGHTS & P&L)
-    // ========================================================================
-
-    /**
-     * Extract Net Profit %.
-     * Schema: 'NetProfit' is the percentage profit relative to invested capital.
-     */
-    static getNetProfit(position) { 
-        return position ? (position.NetProfit || 0) : 0;
-    }
-
-    /**
-     * Extract Position Weight (Allocation %).
-     * Schema: 
-     * - Normal: 'Invested' is % of initial capital.
-     * - Speculator: 'Invested' (or 'Amount' in some contexts) is % of initial capital.
-     */
-    static getPositionWeight(position, userType) { // Agnostic on user type, unused.
-        if (!position) return 0;
-        
-        // Both schemas use 'Invested' to represent the allocation percentage.
-        // Speculators might optionally have 'Amount', we prioritize 'Invested' for consistency.
-        return position.Invested || position.Amount || 0;
-    }
-
-    /**
-     * Extract Current Equity Value %.
-     * Schema: 'Value' is the current value as a % of total portfolio equity.
-     */
-    static getPositionValuePct(position) {            
-        return position ? (position.Value || 0) : 0; 
-    }
-
-    /**
-     * --- NEW PRIMITIVE ---
-     * Derives the approximate Entry Price of a position based on Current Price and Net Profit %.
-     * Formula: Entry = Current / (1 + (NetProfit / 100))
-     * @param {number} currentPrice - The current market price of the asset.
-     * @param {number} netProfitPct - The Net Profit percentage (e.g., -20.5).
-     * @returns {number} Estimated Entry Price.
-     */
-    static deriveEntryPrice(currentPrice, netProfitPct) {
-        if (!currentPrice || currentPrice <= 0) return 0;
-        // Avoid division by zero if P&L is -100% (unlikely but possible in crypto/options)
-        if (netProfitPct <= -100) return Number.MAX_SAFE_INTEGER; // Effectively infinite entry price (lost everything)
-        return currentPrice / (1 + (netProfitPct / 100.0));
-    }
-
-    // ========================================================================
-    // 4. PORTFOLIO LEVEL SUMMARY
-    // ========================================================================
-
-    /**
-     * Calculate/Extract Daily Portfolio P&L %.
-     */
-    static getPortfolioDailyPnl(portfolio, userType) {
-        if (!portfolio) return 0;
-        
-        // 1. Speculator (Explicit 'NetProfit' field on root)
-        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {       
-            return portfolio.NetProfit || 0;                    
-        }
-        
-        // 2. Normal (Aggregated Calculation)
-        if (portfolio.AggregatedPositionsByInstrumentTypeID) {
-            return portfolio.AggregatedPositionsByInstrumentTypeID.reduce((sum, agg) => {
-                return sum + ((agg.Value || 0) - (agg.Invested || 0));
-            }, 0);
-        }
-        
-        return 0;
-    }
-
-    // ========================================================================
-    // 5. TRADE DETAILS (SPECULATOR SPECIFIC)
-    // ========================================================================
-
-    static getDirection(position) {
-        if (!position) return "Buy";
-        if (position.Direction) return position.Direction;
-        if (typeof position.IsBuy === 'boolean') return position.IsBuy ? "Buy" : "Sell";
-        return "Buy"; // Default
-    }
-
-    static getLeverage(position) {
-        return position ? (position.Leverage || 1) : 1; // Default 1 IF NOT FOUND
-    }
-
-    static getOpenRate(position) {
-        return position ? (position.OpenRate || 0) : 0; // Default 0 IF NOT FOUND
-    }
-
-    static getCurrentRate(position) {
-        return position ? (position.CurrentRate || 0) : 0; // Default 0 IF NOT FOUND
-    }
-
-    static getStopLossRate(position) {
-        const rate = position ? (position.StopLossRate || 0) : 0; 
-        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 0
-        if (rate < 0) return 0;
-        return rate;
-    }                                                       
-
-    static getTakeProfitRate(position) {
-        const rate = position ? (position.TakeProfitRate || 0) : 0;
-        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 0
-        return rate;
-    }
-
-    static getHasTSL(position) {
-        return position ? (position.HasTrailingStopLoss === true) : false; // Default false IF NOT FOUND
-    }
-
-    static getOpenDateTime(position) {
-        if (!position || !position.OpenDateTime) return null;        
-        return new Date(position.OpenDateTime);
-    }
-}
-
-class priceExtractor {
-    static getHistory(pricesContext, tickerOrId) {
-        if (!pricesContext || !pricesContext.history) return [];
-        let assetData = pricesContext.history[tickerOrId];
-        
-        if (!assetData) {
-            const id = Object.keys(pricesContext.history).find(key => {
-                const data = pricesContext.history[key];
-                return data.ticker === tickerOrId;
-            });
-            if (id) assetData = pricesContext.history[id];
-        }
-
-        if (!assetData || !assetData.prices) return [];
-
-        const priceMap = assetData.prices;
-        const sortedDates = Object.keys(priceMap).sort((a, b) => a.localeCompare(b));
-        
-        return sortedDates.map(date => ({
-            date: date,
-            price: priceMap[date]
-        })).filter(item => item.price > 0);
-    }
-
-    static getAllHistories(pricesContext) {
-        if (!pricesContext || !pricesContext.history) return new Map();
-        
-        const results = new Map();
-        for (const [id, data] of Object.entries(pricesContext.history)) {
-            const ticker = data.ticker || id;
-            const history = this.getHistory(pricesContext, id);
-            if (history.length > 0) {
-                results.set(ticker, history);
-            }
-        }
-        return results;
-    }
-}
-
-class HistoryExtractor {
-    static getDailyHistory(user) {
-        return user?.history?.today || null;
-    }
-
-    static getTradedAssets(historyDoc) {
-        const trades = historyDoc?.PublicHistoryPositions || [];
-        if (!trades.length) return [];
-        
-        const assetsMap = new Map();
-        
-        for (const t of trades) {
-            const instId = t.InstrumentID;
-            if (!instId) continue;
-            
-            if (!assetsMap.has(instId)) {
-                assetsMap.set(instId, { 
-                    instrumentId: instId, 
-                    totalDuration: 0, 
-                    count: 0 
-                });
-            }
-            
-            const asset = assetsMap.get(instId);
-            const open = new Date(t.OpenDateTime);
-            const close = new Date(t.CloseDateTime);
-            const durationMins = (close - open) / 60000;
-            
-            if (durationMins > 0) {
-                asset.totalDuration += durationMins;
-                asset.count++;
-            }
-        }
-        
-        return Array.from(assetsMap.values()).map(a => ({
-            instrumentId: a.instrumentId,
-            avgHoldingTimeInMinutes: a.count > 0 ? (a.totalDuration / a.count) : 0
-        }));
-    }
-
-    static getInstrumentId(asset) { 
-        return asset ? asset.instrumentId : null;
-    }
-
-    static getAvgHoldingTimeMinutes(asset) { 
-        return asset ? (asset.avgHoldingTimeInMinutes || 0) : 0;
-    }
-
-    static getSummary(historyDoc) { 
-        const trades = historyDoc?.PublicHistoryPositions || [];
-        if (!trades.length) return null;
-
-        let totalTrades = trades.length;
-        let wins = 0;
-        let totalProf = 0;
-        let totalLoss = 0;
-        let profCount = 0;
-        let lossCount = 0;
-        let totalDur = 0;
-
-        for (const t of trades) {
-            if (t.NetProfit > 0) {
-                wins++;
-                totalProf += t.NetProfit;
-                profCount++;
-            } else if (t.NetProfit < 0) {
-                totalLoss += t.NetProfit;
-                lossCount++;
-            }
-            
-            const open = new Date(t.OpenDateTime);
-            const close = new Date(t.CloseDateTime);
-            totalDur += (close - open) / 60000;
-        }
-
-        return { 
-            totalTrades:             totalTrades,
-            winRatio:                totalTrades > 0 ? (wins / totalTrades) * 100 : 0,
-            avgProfitPct:            profCount > 0 ? totalProf / profCount : 0,
-            avgLossPct:              lossCount > 0 ? totalLoss / lossCount : 0,
-            avgHoldingTimeInMinutes: totalTrades > 0 ? totalDur / totalTrades : 0
-        };
-    }
-}
-
-class SignalPrimitives {
-    static getMetric(dependencies, calcName, ticker, fieldName, fallback = 0) {
-        if (!dependencies || !dependencies[calcName]) return fallback;
-        const tickerData = dependencies[calcName][ticker];
-        if (!tickerData) return fallback;
-        
-        const val = tickerData[fieldName];
-        return (typeof val === 'number') ? val : fallback;
-    }
-
-    static getUnionKeys(dependencies, calcNames) {
-        const keys = new Set();
-        if (!dependencies) return [];
-        for (const name of calcNames) {
-            const resultObj = dependencies[name];
-            if (resultObj && typeof resultObj === 'object') {
-                Object.keys(resultObj).forEach(k => keys.add(k));
-            }
-        }
-        return Array.from(keys);
-    }
-
-    static normalizeTanh(value, scale = 10, sensitivity = 10.0) {
-        if (value === 0) return 0;
-        return Math.tanh(value / sensitivity) * scale;
-    }
-
-    static normalizeZScore(value, mean, stdDev) {
-        if (!stdDev || stdDev === 0) return 0;
-        return (value - mean) / stdDev;
-    }
-
-    static divergence(valueA, valueB) {
-        return (valueA || 0) - (valueB || 0);
-    }
-
-    static getPreviousState(previousComputed, calcName, ticker, fieldName = null) {
-        if (!previousComputed || !previousComputed[calcName]) return null;
-        const tickerData = previousComputed[calcName][ticker];
-        if (!tickerData) return null;
-
-        if (fieldName) {
-             return tickerData[fieldName];
-        }
-        return tickerData; 
-    }
-}
-
-class MathPrimitives {
-    static average(values) {
-        if (!values || !values.length) return 0;
-        return values.reduce((a, b) => a + b, 0) / values.length;
-    }
-    
-    static median(values) {
-        if (!values || !values.length) return 0;
-        const sorted = [...values].sort((a, b) => a - b);
-        const mid    = Math.floor(sorted.length / 2);
-        return sorted.length % 2 === 0
-            ? (sorted[mid - 1] + sorted[mid]) / 2
-            : sorted[mid];
-    }
-
-    static standardDeviation(values) {
-        if (!values || !values.length) return 0;
-        const avg         = this.average(values);
-        const squareDiffs = values.map(val => Math.pow((val || 0) - avg, 2));
-        return Math.sqrt(this.average(squareDiffs));
-    }
-
-    static bucketBinary(value, threshold = 0) {
-        return value > threshold ? 'winner' : 'loser';
-    }
-
-    static calculateHitProbability(currentPrice, barrierPrice, volatility, days, drift = 0) {
-        if (currentPrice <= 0 || barrierPrice <= 0 || volatility <= 0 || days <= 0) return 0;
-
-        const t     = days / 365.0; 
-        const sigma = volatility;
-        const mu    = drift;
-        const b = Math.log(barrierPrice / currentPrice);
-        const nu = mu - 0.5 * Math.pow(sigma, 2);
-        const sqrtT      = Math.sqrt(t);
-        const sigmaSqrtT = sigma * sqrtT;
-
-        const normCDF = (x) => {
-            const t = 1 / (1 + 0.2316419 * Math.abs(x));
-            const d = 0.3989423 * Math.exp(-x * x / 2);
-            const prob = d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
-            return x > 0 ? 1 - prob : prob;
-        };
-
-        const term1 = (b - nu * t) / sigmaSqrtT;
-        const term2 = (2 * nu * b) / (sigma * sigma);
-        const term3 = (b + nu * t) / sigmaSqrtT;
-
-        if ((currentPrice > barrierPrice && barrierPrice > currentPrice) || 
-            (currentPrice < barrierPrice && barrierPrice < currentPrice)) {
-             return 1.0;
-        }
-
-        const probability = normCDF(( -Math.abs(b) - nu * t ) / sigmaSqrtT) +  Math.exp((2 * nu * Math.abs(b)) / (sigma * sigma)) * normCDF(( -Math.abs(b) + nu * t ) / sigmaSqrtT);
-
-        return Math.min(Math.max(probability, 0), 1);
-    }
-
-    static simulateGBM(currentPrice, volatility, days, simulations = 1000, drift = 0) {
-        if (currentPrice <= 0 || volatility <= 0 || days <= 0) return new Float32Array(0);
-        
-        const t         = days / 365.0;
-        const sigma     = volatility;
-        const mu        = drift;
-        const driftTerm = (mu - 0.5 * sigma * sigma) * t;
-        const volTerm   = sigma * Math.sqrt(t);
-        
-        const results = new Float32Array(simulations);
-        
-        for (let i = 0; i < simulations; i++) {
-            const u1 = Math.random();
-            const u2 = Math.random();
-            const z  = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
-            results[i] = currentPrice * Math.exp(driftTerm + volTerm * z);
-        }
-        return results;
-    }
-
-    static simulatePopulationBreakdown(pricePaths, userProfiles) {
-        if (!pricePaths.length || !userProfiles.length) return 0;
-        
-        let totalBreakdownEvents = 0;
-        const totalSims = pricePaths.length;
-        const totalUsers = userProfiles.length;
-
-        for (let i = 0; i < totalSims; i++) {
-            const simPrice = pricePaths[i];
-            let capitulatedUsersInScenario = 0;
-
-            for (let j = 0; j < totalUsers; j++) {
-                const user = userProfiles[j];
-                const hypotheticalPnL = ((simPrice - user.entryPrice) / user.entryPrice) * 100;
-                
-                if (hypotheticalPnL < user.thresholdPct) {
-                    capitulatedUsersInScenario++;
-                }
-            }
-            
-            totalBreakdownEvents += (capitulatedUsersInScenario / totalUsers);
-        }
-        
-        return totalBreakdownEvents / totalSims;
-    }
-}
-
-class Aggregators {
-    static bucketUsersByPnlPerAsset(usersData, tickerMap) {
-        const buckets = new Map();
-        for (const [userId, portfolio] of Object.entries(usersData)) {
-            const userType  = portfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
-            const positions = DataExtractor.getPositions(portfolio, userType);
-            
-            for (const pos of positions) {
-                const id = DataExtractor.getInstrumentId(pos);
-                const pnl = DataExtractor.getNetProfit(pos);
-                if (!id || pnl === 0) continue;
-                
-                const ticker = tickerMap[id];
-                if (!ticker) continue;
-
-                if (!buckets.has(ticker)) buckets.set(ticker, { winners: [], losers: [] });
-                const b = buckets.get(ticker);
-                
-                if (pnl > 0) b.winners.push(userId);
-                else b.losers.push(userId);
-            }
-        }
-        return Object.fromEntries(buckets);
-    }
-
-    static getWeightedSentiment(positions) {
-        if (!positions || positions.length === 0) return 0;
-
-        let totalWeightedPnL = 0;
-        let totalWeight = 0;
-
-        for (const pos of positions) {
-            const pnl = DataExtractor.getNetProfit(pos);
-            const weight = DataExtractor.getPositionWeight(pos);
-
-            if (weight > 0) {
-                totalWeightedPnL += (pnl * weight);
-                totalWeight += weight;
-            }
-        }
-
-        if (totalWeight === 0) return 0;
-        return totalWeightedPnL / totalWeight;
-    }
-}
-
-class Validators {
-    static validatePortfolio(portfolio, userType) {
-        if (!portfolio) return { valid: false, errors: ['Portfolio is null'] };
-        
-        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
-             if (!portfolio.PublicPositions) return { valid: false, errors: ['Missing PublicPositions'] };
-        } else {
-             if (!portfolio.AggregatedPositions) return { valid: false, errors: ['Missing AggregatedPositions'] };
-        }
-        
-        return { valid: true, errors: [] };
-    }
-}
-
-class TimeSeries {
-    static updateEMAState(value, state, alpha = 0.1) {
-        const mean = state ? (state.mean || 0) : 0;
-        const variance = state ? (state.variance || 1) : 1; 
-
-        if (value === undefined || value === null || isNaN(value)) {
-            return { mean, variance };
-        }
-
-        const diff = value - mean;
-        const newMean = mean + (alpha * diff);
-        const newVariance = (1 - alpha) * (variance + (alpha * diff * diff));
-
-        return { mean: newMean, variance: newVariance };
-    }
-
-    static pearsonCorrelation(x, y) {
-        if (!x || !y || x.length !== y.length || x.length === 0) return 0;
-        
-        const n = x.length;
-        let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0, sumY2 = 0;
-
-        for (let i = 0; i < n; i++) {
-            sumX  += x[i];
-            sumY  += y[i];
-            sumXY += x[i] * y[i];
-            sumX2 += x[i] * x[i];
-            sumY2 += y[i] * y[i];
-        }
-
-        const numerator   = (n * sumXY) - (sumX * sumY);
-        const denominator = Math.sqrt(((n * sumX2) - (sumX * sumX)) * ((n * sumY2) - (sumY * sumY)));
-
-        return (denominator === 0) ? 0 : numerator / denominator;
-    }
-}
-
-
-class DistributionAnalytics {
-    static computeKDE(data, bandwidth, steps = 60) {
-        if (!data || data.length === 0) return [];
-
-        let min = Infinity, max = -Infinity;
-        for (const p of data) {
-            if (p.value < min) min = p.value;
-            if (p.value > max) max = p.value;
-        }
-        
-        min -= bandwidth * 3;
-        max += bandwidth * 3;
-        const stepSize = (max - min) / steps;
-        const curve = [];
-
-        for (let i = 0; i <= steps; i++) {
-            const x = min + (i * stepSize);
-            let density = 0;
-            for (const p of data) {
-                const diff = (x - p.value);
-                if (Math.abs(diff) > bandwidth * 3) continue;
-                
-                const u = diff / bandwidth;
-                const k = 0.39894228 * Math.exp(-0.5 * u * u); 
-                density += (p.weight * k) / bandwidth;
-            }
-            if (density > 0) curve.push({ price: x, density });
-        }
-        return curve;
-    }
-
-    static integrateProfile(curve, startPrice, endPrice) {
-        if (!curve || !Array.isArray(curve)) return 0; // Fix for potential crash
-        let sum = 0;
-        for (let i = 0; i < curve.length - 1; i++) {
-            const p1 = curve[i];
-            const p2 = curve[i+1];
-            if (p1.price >= startPrice && p2.price <= endPrice) {
-                sum += (p2.price - p1.price) * ((p1.density + p2.density) / 2);
-            }
-        }
-        return sum;
-    }
-
-    static linearRegression(xValues, yValues) {
-        const n = xValues.length;
-        if (n !== yValues.length || n < 2) return { slope: 0, r2: 0 };
-        
-        let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0, sumYY = 0;
-        for (let i = 0; i < n; i++) {
-            sumX  += xValues[i];
-            sumY  += yValues[i];
-            sumXY += xValues[i] * yValues[i];
-            sumXX += xValues[i] * xValues[i];
-            sumYY += yValues[i] * yValues[i];
-        }
-        
-        const slope = (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
-        return { slope, n };
-    }
-}
-
-module.exports = {
-    Aggregators,
-    DataExtractor,
-    DistributionAnalytics,
-    HistoryExtractor,
-    InsightsExtractor, // Exported
-    MathPrimitives,
-    SCHEMAS,
-    SignalPrimitives,
-    TimeSeries,
-    UserClassifier, // Exported
-    Validators,
-    priceExtractor
+/**
+ * @fileoverview Math Layer - Single Source of Truth (V3 Final)
+ * Encapsulates Schema Knowledge, Mathematical Primitives, and Signal Extractors.
+ * * STRICT COMPLIANCE:
+ * - Adheres to 'schema.md' definitions.
+ * - standardizes access to P&L, Weights, and Rates.
+ */
+
+const SCHEMAS = {
+    USER_TYPES: { NORMAL: 'normal', SPECULATOR: 'speculator' },
+    STYLES: { DAY_TRADER: 'Day Trader', SWING_TRADER: 'Swing Trader', INVESTOR: 'Investor' },
+    LABELS: { SMART: 'Smart Money', DUMB: 'Dumb Money', NEUTRAL: 'Neutral' }
+};
+
+class InsightsExtractor {
+    /**
+     * Extracts the raw array of insight objects from the context.
+     * Checks for standard context injection paths.
+     */
+    static getInsights(context) {
+        // Support multiple potential injection paths depending on controller version
+        return context.insights || context.daily_instrument_insights || [];
+    }
+
+    /**
+     * returns the specific insight object for a given instrument ID.
+     */
+    static getInsightForInstrument(insights, instrumentId) {
+        if (!insights || !Array.isArray(insights)) return null;
+        return insights.find(i => i.instrumentId === instrumentId) || null;
+    }
+
+    // --- Standard Metrics ---
+
+    static getTotalOwners(insight) {
+        return insight ? (insight.total || 0) : 0;
+    }
+
+    static getLongPercent(insight) {
+        return insight ? (insight.buy || 0) : 0;
+    }
+
+    static getShortPercent(insight) {
+        return insight ? (insight.sell || 0) : 0;
+    }
+
+    static getGrowthPercent(insight) {
+        return insight ? (insight.growth || 0) : 0;
+    }
+
+    // --- Derived Counts (Estimated) ---
+
+    static getLongCount(insight) {
+        const total = this.getTotalOwners(insight);
+        const buyPct = this.getLongPercent(insight);
+        return Math.floor(total * (buyPct / 100));
+    }
+
+    static getShortCount(insight) {
+        const total = this.getTotalOwners(insight);
+        const sellPct = this.getShortPercent(insight);
+        return Math.floor(total * (sellPct / 100));
+    }
+
+    /**
+     * Calculates the net change in users from yesterday based on growth %.
+     * Formula: NetChange = Total - (Total / (1 + Growth/100))
+     */
+    static getNetOwnershipChange(insight) {
+        const total = this.getTotalOwners(insight);
+        const growth = this.getGrowthPercent(insight);
+        if (total === 0) return 0;
+        
+        // Reverse engineer yesterday's count
+        // Today = Yesterday * (1 + growth)
+        // Yesterday = Today / (1 + growth)
+        const prevTotal = total / (1 + (growth / 100)); // TODO: Check precision issues
+        return Math.round(total - prevTotal);
+    }
+}
+
+class UserClassifier {
+    /**
+     * Classifies a user as Smart/Dumb based on Win Rate and Profitability.
+     * @param {Object} historySummary - Result from HistoryExtractor.getSummary()
+     */
+    static classifySmartDumb(historySummary) {
+        if (!historySummary || historySummary.totalTrades < 5) return SCHEMAS.LABELS.NEUTRAL; // Insufficient data
+
+        const { winRatio, avgProfitPct, avgLossPct } = historySummary;
+
+        // 1. The "Consistent Winner" (Smart)
+        if (winRatio > 60 && avgProfitPct > Math.abs(avgLossPct)) return SCHEMAS.LABELS.SMART;
+
+        // 2. The "Sniper" (Smart - Low Win Rate but huge winners)
+        if (winRatio > 30 && avgProfitPct > (Math.abs(avgLossPct) * 2.5)) return SCHEMAS.LABELS.SMART;
+
+        // 3. The "Bagholder" (Dumb - High win rate but one loss wipes them out)
+        if (winRatio > 80 && (Math.abs(avgLossPct) > avgProfitPct * 4)) return SCHEMAS.LABELS.DUMB;
+
+        // 4. The "Gambler" (Dumb - Losing money consistently)
+        if (winRatio < 40 && avgProfitPct < Math.abs(avgLossPct)) return SCHEMAS.LABELS.DUMB;
+
+        return SCHEMAS.LABELS.NEUTRAL;
+    }
+
+    /**
+     * Classifies trading style based on average holding time.
+     * @param {number} avgHoldingMinutes 
+     */
+    static classifyStyle(avgHoldingMinutes) {
+        if (avgHoldingMinutes <= 0) return SCHEMAS.STYLES.INVESTOR; // Default
+        
+        if (avgHoldingMinutes < 60 * 24) return SCHEMAS.STYLES.DAY_TRADER; // < 1 Day
+        if (avgHoldingMinutes < 60 * 24 * 30) return SCHEMAS.STYLES.SWING_TRADER; // < 1 Month
+        return SCHEMAS.STYLES.INVESTOR; // > 1 Month
+    }
+}
+
+class DataExtractor { // For generic access of data types
+    // ========================================================================
+    // 1. COLLECTION ACCESSORS
+    // ========================================================================
+    
+    /**
+     * Extract positions array based on User Type.
+     * - Normal: Uses 'AggregatedPositions' (Grouped by Asset + Direction)
+     * - Speculator: Uses 'PublicPositions' (Individual Trades)
+     */
+    static getPositions(portfolio, userType) {
+        if (!portfolio) return []; // Handle empty portfolio
+        
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) { 
+            return portfolio.PublicPositions || []; // SPECULATOR SCHEMA
+        }
+        
+        // Default to Normal User Schema
+        return portfolio.AggregatedPositions || [];
+    }
+
+    // ========================================================================
+    // 2. IDENTITY & KEYS
+    // ========================================================================
+
+    /**
+     * Extract standardized Instrument ID.
+     */
+    static getInstrumentId(position) {
+        if (!position) return null; // Handle empty position data
+        // Handle string or number variations safely
+        return position.InstrumentID || position.instrumentId || null;
+    }
+
+    /**
+     * Extract a unique Identifier for the position.
+     * - Speculator: Uses 'PositionID'.
+     * - Normal: Generates Composite Key (InstrumentID_Direction) since they lack unique Trade IDs.
+     */
+    static getPositionId(position) {
+        if (!position) return null; // Handle empty position data
+        
+        // 1. Try Explicit ID (Speculators)
+        if (position.PositionID) return String(position.PositionID);
+        if (position.PositionId) return String(position.PositionId);
+
+        // 2. Fallback to Composite Key (Normal Users)
+        const instId = this.getInstrumentId(position);
+        const dir    = this.getDirection(position);
+        if (instId) return `${instId}_${dir}`;
+
+        return null;
+    }
+
+    // ========================================================================
+    // 3. FINANCIAL METRICS (WEIGHTS & P&L)
+    // ========================================================================
+
+    /**
+     * Extract Net Profit %.
+     * Schema: 'NetProfit' is the percentage profit relative to invested capital.
+     */
+    static getNetProfit(position) { 
+        return position ? (position.NetProfit || 0) : 0;
+    }
+
+    /**
+     * Extract Position Weight (Allocation %).
+     * Schema: 
+     * - Normal: 'Invested' is % of initial capital.
+     * - Speculator: 'Invested' (or 'Amount' in some contexts) is % of initial capital.
+     */
+    static getPositionWeight(position, userType) { // Agnostic on user type, unused.
+        if (!position) return 0;
+        
+        // Both schemas use 'Invested' to represent the allocation percentage.
+        // Speculators might optionally have 'Amount', we prioritize 'Invested' for consistency.
+        return position.Invested || position.Amount || 0;
+    }
+
+    /**
+     * Extract Current Equity Value %.
+     * Schema: 'Value' is the current value as a % of total portfolio equity.
+     */
+    static getPositionValuePct(position) {            
+        return position ? (position.Value || 0) : 0; 
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Derives the approximate Entry Price of a position based on Current Price and Net Profit %.
+     * Formula: Entry = Current / (1 + (NetProfit / 100))
+     * @param {number} currentPrice - The current market price of the asset.
+     * @param {number} netProfitPct - The Net Profit percentage (e.g., -20.5).
+     * @returns {number} Estimated Entry Price.
+     */
+    static deriveEntryPrice(currentPrice, netProfitPct) {
+        if (!currentPrice || currentPrice <= 0) return 0;
+        // Avoid division by zero if P&L is -100% (unlikely but possible in crypto/options)
+        if (netProfitPct <= -100) return Number.MAX_SAFE_INTEGER; // Effectively infinite entry price (lost everything)
+        return currentPrice / (1 + (netProfitPct / 100.0));
+    }
+
+    // ========================================================================
+    // 4. PORTFOLIO LEVEL SUMMARY
+    // ========================================================================
+
+    /**
+     * Calculate/Extract Daily Portfolio P&L %.
+     */
+    static getPortfolioDailyPnl(portfolio, userType) {
+        if (!portfolio) return 0;
+        
+        // 1. Speculator (Explicit 'NetProfit' field on root)
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {       
+            return portfolio.NetProfit || 0;                    
+        }
+        
+        // 2. Normal (Aggregated Calculation)
+        if (portfolio.AggregatedPositionsByInstrumentTypeID) {
+            return portfolio.AggregatedPositionsByInstrumentTypeID.reduce((sum, agg) => {
+                return sum + ((agg.Value || 0) - (agg.Invested || 0));
+            }, 0);
+        }
+        
+        return 0;
+    }
+
+    // ========================================================================
+    // 5. TRADE DETAILS (SPECULATOR SPECIFIC)
+    // ========================================================================
+
+    static getDirection(position) {
+        if (!position) return "Buy";
+        if (position.Direction) return position.Direction;
+        if (typeof position.IsBuy === 'boolean') return position.IsBuy ? "Buy" : "Sell";
+        return "Buy"; // Default
+    }
+
+    static getLeverage(position) {
+        return position ? (position.Leverage || 1) : 1; // Default 1 IF NOT FOUND
+    }
+
+    static getOpenRate(position) {
+        return position ? (position.OpenRate || 0) : 0; // Default 0 IF NOT FOUND
+    }
+
+    static getCurrentRate(position) {
+        return position ? (position.CurrentRate || 0) : 0; // Default 0 IF NOT FOUND
+    }
+
+    static getStopLossRate(position) {
+        const rate = position ? (position.StopLossRate || 0) : 0; 
+        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 0
+        if (rate < 0) return 0;
+        return rate;
+    }                                                       
+
+    static getTakeProfitRate(position) {
+        const rate = position ? (position.TakeProfitRate || 0) : 0;
+        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 0
+        return rate;
+    }
+
+    static getHasTSL(position) {
+        return position ? (position.HasTrailingStopLoss === true) : false; // Default false IF NOT FOUND
+    }
+
+    static getOpenDateTime(position) {
+        if (!position || !position.OpenDateTime) return null;        
+        return new Date(position.OpenDateTime);
+    }
+}
+
+class priceExtractor {
+    static getHistory(pricesContext, tickerOrId) {
+        if (!pricesContext || !pricesContext.history) return [];
+        let assetData = pricesContext.history[tickerOrId];
+        
+        if (!assetData) {
+            const id = Object.keys(pricesContext.history).find(key => {
+                const data = pricesContext.history[key];
+                return data.ticker === tickerOrId;
+            });
+            if (id) assetData = pricesContext.history[id];
+        }
+
+        if (!assetData || !assetData.prices) return [];
+
+        const priceMap = assetData.prices;
+        const sortedDates = Object.keys(priceMap).sort((a, b) => a.localeCompare(b));
+        
+        return sortedDates.map(date => ({
+            date: date,
+            price: priceMap[date]
+        })).filter(item => item.price > 0);
+    }
+
+    static getAllHistories(pricesContext) {
+        if (!pricesContext || !pricesContext.history) return new Map();
+        
+        const results = new Map();
+        for (const [id, data] of Object.entries(pricesContext.history)) {
+            const ticker = data.ticker || id;
+            const history = this.getHistory(pricesContext, id);
+            if (history.length > 0) {
+                results.set(ticker, history);
+            }
+        }
+        return results;
+    }
+}
+
+class HistoryExtractor {
+    static getDailyHistory(user) {
+        return user?.history?.today || null;
+    }
+
+    static getTradedAssets(historyDoc) {
+        const trades = historyDoc?.PublicHistoryPositions || [];
+        if (!trades.length) return [];
+        
+        const assetsMap = new Map();
+        
+        for (const t of trades) {
+            const instId = t.InstrumentID;
+            if (!instId) continue;
+            
+            if (!assetsMap.has(instId)) {
+                assetsMap.set(instId, { 
+                    instrumentId: instId, 
+                    totalDuration: 0, 
+                    count: 0 
+                });
+            }
+            
+            const asset = assetsMap.get(instId);
+            const open = new Date(t.OpenDateTime);
+            const close = new Date(t.CloseDateTime);
+            const durationMins = (close - open) / 60000;
+            
+            if (durationMins > 0) {
+                asset.totalDuration += durationMins;
+                asset.count++;
+            }
+        }
+        
+        return Array.from(assetsMap.values()).map(a => ({
+            instrumentId: a.instrumentId,
+            avgHoldingTimeInMinutes: a.count > 0 ? (a.totalDuration / a.count) : 0
+        }));
+    }
+
+    static getInstrumentId(asset) { 
+        return asset ? asset.instrumentId : null;
+    }
+
+    static getAvgHoldingTimeMinutes(asset) { 
+        return asset ? (asset.avgHoldingTimeInMinutes || 0) : 0;
+    }
+
+    static getSummary(historyDoc) { 
+        const trades = historyDoc?.PublicHistoryPositions || [];
+        if (!trades.length) return null;
+
+        let totalTrades = trades.length;
+        let wins = 0;
+        let totalProf = 0;
+        let totalLoss = 0;
+        let profCount = 0;
+        let lossCount = 0;
+        let totalDur = 0;
+
+        for (const t of trades) {
+            if (t.NetProfit > 0) {
+                wins++;
+                totalProf += t.NetProfit;
+                profCount++;
+            } else if (t.NetProfit < 0) {
+                totalLoss += t.NetProfit;
+                lossCount++;
+            }
+            
+            const open = new Date(t.OpenDateTime);
+            const close = new Date(t.CloseDateTime);
+            totalDur += (close - open) / 60000;
+        }
+
+        return { 
+            totalTrades:             totalTrades,
+            winRatio:                totalTrades > 0 ? (wins / totalTrades) * 100 : 0,
+            avgProfitPct:            profCount > 0 ? totalProf / profCount : 0,
+            avgLossPct:              lossCount > 0 ? totalLoss / lossCount : 0,
+            avgHoldingTimeInMinutes: totalTrades > 0 ? totalDur / totalTrades : 0
+        };
+    }
+}
+
+class SignalPrimitives {
+    static getMetric(dependencies, calcName, ticker, fieldName, fallback = 0) {
+        if (!dependencies || !dependencies[calcName]) return fallback;
+        const tickerData = dependencies[calcName][ticker];
+        if (!tickerData) return fallback;
+        
+        const val = tickerData[fieldName];
+        return (typeof val === 'number') ? val : fallback;
+    }
+
+    static getUnionKeys(dependencies, calcNames) {
+        const keys = new Set();
+        if (!dependencies) return [];
+        for (const name of calcNames) {
+            const resultObj = dependencies[name];
+            if (resultObj && typeof resultObj === 'object') {
+                Object.keys(resultObj).forEach(k => keys.add(k));
+            }
+        }
+        return Array.from(keys);
+    }
+
+    static normalizeTanh(value, scale = 10, sensitivity = 10.0) {
+        if (value === 0) return 0;
+        return Math.tanh(value / sensitivity) * scale;
+    }
+
+    static normalizeZScore(value, mean, stdDev) {
+        if (!stdDev || stdDev === 0) return 0;
+        return (value - mean) / stdDev;
+    }
+
+    static divergence(valueA, valueB) {
+        return (valueA || 0) - (valueB || 0);
+    }
+
+    static getPreviousState(previousComputed, calcName, ticker, fieldName = null) {
+        if (!previousComputed || !previousComputed[calcName]) return null;
+        const tickerData = previousComputed[calcName][ticker];
+        if (!tickerData) return null;
+
+        if (fieldName) {
+             return tickerData[fieldName];
+        }
+        return tickerData; 
+    }
+}
+
+class MathPrimitives {
+    static average(values) {
+        if (!values || !values.length) return 0;
+        return values.reduce((a, b) => a + b, 0) / values.length;
+    }
+    
+    static median(values) {
+        if (!values || !values.length) return 0;
+        const sorted = [...values].sort((a, b) => a - b);
+        const mid    = Math.floor(sorted.length / 2);
+        return sorted.length % 2 === 0
+            ? (sorted[mid - 1] + sorted[mid]) / 2
+            : sorted[mid];
+    }
+
+    static standardDeviation(values) {
+        if (!values || !values.length) return 0;
+        const avg         = this.average(values);
+        const squareDiffs = values.map(val => Math.pow((val || 0) - avg, 2));
+        return Math.sqrt(this.average(squareDiffs));
+    }
+
+    static bucketBinary(value, threshold = 0) {
+        return value > threshold ? 'winner' : 'loser';
+    }
+
+    static calculateHitProbability(currentPrice, barrierPrice, volatility, days, drift = 0) {
+        if (currentPrice <= 0 || barrierPrice <= 0 || volatility <= 0 || days <= 0) return 0;
+
+        const t          = days / 365.0; 
+        const sigma      = volatility;
+        const mu         = drift;
+        const b          = Math.log(barrierPrice / currentPrice);
+        const nu         = mu - 0.5 * Math.pow(sigma, 2);
+        const sqrtT      = Math.sqrt(t);
+        const sigmaSqrtT = sigma * sqrtT;
+
+        const normCDF = (x) => {
+            const t    = 1 / (1 + 0.2316419 * Math.abs(x));
+            const d    = 0.3989423 * Math.exp(-x * x / 2);
+            const prob = d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
+            return x > 0 ? 1 - prob : prob;
+        };
+
+        const term1 = (b - nu * t) / sigmaSqrtT;
+        const term2 = (2 * nu * b) / (sigma * sigma);
+        const term3 = (b + nu * t) / sigmaSqrtT;
+
+        if ((currentPrice > barrierPrice && barrierPrice > currentPrice) || 
+            (currentPrice < barrierPrice && barrierPrice < currentPrice)) {
+             return 1.0;
+        }
+
+        const probability = normCDF(( -Math.abs(b) - nu * t ) / sigmaSqrtT) +  Math.exp((2 * nu * Math.abs(b)) / (sigma * sigma)) * normCDF(( -Math.abs(b) + nu * t ) / sigmaSqrtT);
+
+        return Math.min(Math.max(probability, 0), 1);
+    }
+
+    static simulateGBM(currentPrice, volatility, days, simulations = 1000, drift = 0) {
+        if (currentPrice <= 0 || volatility <= 0 || days <= 0) return new Float32Array(0);
+        
+        const t         = days / 365.0;
+        const sigma     = volatility;
+        const mu        = drift;
+        const driftTerm = (mu - 0.5 * sigma * sigma) * t;
+        const volTerm   = sigma * Math.sqrt(t);
+        
+        const results = new Float32Array(simulations);
+        
+        for (let i = 0; i < simulations; i++) {
+            const u1 = Math.random();
+            const u2 = Math.random();
+            const z  = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+            results[i] = currentPrice * Math.exp(driftTerm + volTerm * z);
+        }
+        return results;
+    }
+
+    static simulatePopulationBreakdown(pricePaths, userProfiles) {
+        if (!pricePaths.length || !userProfiles.length) return 0;
+        
+        let totalBreakdownEvents = 0;
+        const totalSims = pricePaths.length;
+        const totalUsers = userProfiles.length;
+
+        for (let i = 0; i < totalSims; i++) {
+            const simPrice = pricePaths[i];
+            let capitulatedUsersInScenario = 0;
+
+            for (let j = 0; j < totalUsers; j++) {
+                const user = userProfiles[j];
+                const hypotheticalPnL = ((simPrice - user.entryPrice) / user.entryPrice) * 100;
+                
+                if (hypotheticalPnL < user.thresholdPct) {
+                    capitulatedUsersInScenario++;
+                }
+            }
+            
+            totalBreakdownEvents += (capitulatedUsersInScenario / totalUsers);
+        }
+        
+        return totalBreakdownEvents / totalSims;
+    }
+}
+
+class Aggregators {
+    static bucketUsersByPnlPerAsset(usersData, tickerMap) {
+        const buckets = new Map();
+        for (const [userId, portfolio] of Object.entries(usersData)) {
+            const userType  = portfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
+            const positions = DataExtractor.getPositions(portfolio, userType);
+            
+            for (const pos of positions) {
+                const id = DataExtractor.getInstrumentId(pos);
+                const pnl = DataExtractor.getNetProfit(pos);
+                if (!id || pnl === 0) continue;
+                
+                const ticker = tickerMap[id];
+                if (!ticker) continue;
+
+                if (!buckets.has(ticker)) buckets.set(ticker, { winners: [], losers: [] });
+                const b = buckets.get(ticker);
+                
+                if (pnl > 0) b.winners.push(userId);
+                else b.losers.push(userId);
+            }
+        }
+        return Object.fromEntries(buckets);
+    }
+
+    static getWeightedSentiment(positions) {
+        if (!positions || positions.length === 0) return 0;
+
+        let totalWeightedPnL = 0;
+        let totalWeight = 0;
+
+        for (const pos of positions) {
+            const pnl = DataExtractor.getNetProfit(pos);
+            const weight = DataExtractor.getPositionWeight(pos);
+
+            if (weight > 0) {
+                totalWeightedPnL += (pnl * weight);
+                totalWeight += weight;
+            }
+        }
+
+        if (totalWeight === 0) return 0;
+        return totalWeightedPnL / totalWeight;
+    }
+}
+
+class Validators {
+    static validatePortfolio(portfolio, userType) {
+        if (!portfolio) return { valid: false, errors: ['Portfolio is null'] };
+        
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
+             if (!portfolio.PublicPositions) return { valid: false, errors: ['Missing PublicPositions'] };
+        } else {
+             if (!portfolio.AggregatedPositions) return { valid: false, errors: ['Missing AggregatedPositions'] };
+        }
+        
+        return { valid: true, errors: [] };
+    }
+}
+
+class TimeSeries {
+    static updateEMAState(value, state, alpha = 0.1) {
+        const mean = state ? (state.mean || 0) : 0;
+        const variance = state ? (state.variance || 1) : 1; 
+
+        if (value === undefined || value === null || isNaN(value)) {
+            return { mean, variance };
+        }
+
+        const diff = value - mean;
+        const newMean = mean + (alpha * diff);
+        const newVariance = (1 - alpha) * (variance + (alpha * diff * diff));
+
+        return { mean: newMean, variance: newVariance };
+    }
+
+    static pearsonCorrelation(x, y) {
+        if (!x || !y || x.length !== y.length || x.length === 0) return 0;
+        
+        const n = x.length;
+        let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0, sumY2 = 0;
+
+        for (let i = 0; i < n; i++) {
+            sumX  += x[i];
+            sumY  += y[i];
+            sumXY += x[i] * y[i];
+            sumX2 += x[i] * x[i];
+            sumY2 += y[i] * y[i];
+        }
+
+        const numerator   = (n * sumXY) - (sumX * sumY);
+        const denominator = Math.sqrt(((n * sumX2) - (sumX * sumX)) * ((n * sumY2) - (sumY * sumY)));
+
+        return (denominator === 0) ? 0 : numerator / denominator;
+    }
+}
+
+
+class DistributionAnalytics {
+    static computeKDE(data, bandwidth, steps = 60) {
+        if (!data || data.length === 0) return [];
+
+        let min = Infinity, max = -Infinity;
+        for (const p of data) {
+            if (p.value < min) min = p.value;
+            if (p.value > max) max = p.value;
+        }
+        
+        min -= bandwidth * 3;
+        max += bandwidth * 3;
+        const stepSize = (max - min) / steps;
+        const curve = [];
+
+        for (let i = 0; i <= steps; i++) {
+            const x = min + (i * stepSize);
+            let density = 0;
+            for (const p of data) {
+                const diff = (x - p.value);
+                if (Math.abs(diff) > bandwidth * 3) continue;
+                
+                const u = diff / bandwidth;
+                const k = 0.39894228 * Math.exp(-0.5 * u * u); 
+                density += (p.weight * k) / bandwidth;
+            }
+            if (density > 0) curve.push({ price: x, density });
+        }
+        return curve;
+    }
+
+    static integrateProfile(curve, startPrice, endPrice) {
+        if (!curve || !Array.isArray(curve)) return 0; // Fix for potential crash
+        let sum = 0;
+        for (let i = 0; i < curve.length - 1; i++) {
+            const p1 = curve[i];
+            const p2 = curve[i+1];
+            if (p1.price >= startPrice && p2.price <= endPrice) {
+                sum += (p2.price - p1.price) * ((p1.density + p2.density) / 2);
+            }
+        }
+        return sum;
+    }
+
+    static linearRegression(xValues, yValues) {
+        const n = xValues.length;
+        if (n !== yValues.length || n < 2) return { slope: 0, r2: 0 };
+        
+        let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0, sumYY = 0;
+        for (let i = 0; i < n; i++) {
+            sumX  += xValues[i];
+            sumY  += yValues[i];
+            sumXY += xValues[i] * yValues[i];
+            sumXX += xValues[i] * xValues[i];
+            sumYY += yValues[i] * yValues[i];
+        }
+        
+        const slope = (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
+        return { slope, n };
+    }
+}
+
+module.exports = {
+    Aggregators,
+    DataExtractor,
+    DistributionAnalytics,
+    HistoryExtractor,
+    InsightsExtractor, // Exported
+    MathPrimitives,
+    SCHEMAS,
+    SignalPrimitives,
+    TimeSeries,
+    UserClassifier, // Exported
+    Validators,
+    priceExtractor
 };