bulltrackers-module 1.0.171 → 1.0.173

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

@@ -0,0 +1,747 @@
+/**
+ * @fileoverview Math Layer - Single Source of Truth (V3 Final)
+ * Encapsulates Schema Knowledge, Mathematical Primitives, and Signal Extractors.
+ * * STRICT COMPLIANCE:
+ * - Adheres to 'schema.md' definitions for Normal vs Speculator portfolios.
+ * - standardizes access to P&L, Weights, and Rates.
+ * - Provides safe fallbacks for all fields.
+ */
+
+const SCHEMAS = {
+    USER_TYPES: { NORMAL: 'normal', SPECULATOR: 'speculator' }
+};
+
+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) {            // TODO - VERIFY THIS WORKS FOR SPECULATORS,
+        return position ? (position.Value || 0) : 0; //  IS VALUE ACTUALLY THE VALUE OF POSITION AS A % OF TOTAL PORTFOLIO EQUITY? IS IT THE SAME FOR NORMAL USERS?
+    }
+
+    /**
+     * --- 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) ---> TODO : THIS IS FLAWED,
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {       //  SPECULATOR DATA DOES NOT CONTAIN THE ENTIRE PORTFOLIO DATA FOR THAT USER, IT CONTAINS A SNAPSHOT OF THE USERS' SPECIFIC ASSET WE REQUESTED FROM THE TASK ENGINE
+                                                                // You cannot ever infer the entire speculator portfolio daily / weekly / monthly or any time period value based on the data we have for speculators
+            return portfolio.NetProfit || 0;                    // Data for speculators only works when we are looking at the ticker-specific data, or the trade history data which is agnostic on user type
+        }
+        
+        // 2. Normal (Aggregated Calculation) ---> TODO : VERIFY THIS LOGIC, IT SHOULD BE OK
+        // Logic: Sum(Value - Invested) across the 'InstrumentType' breakdown
+        // This gives the net performance change for the day relative to the portfolio.
+        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; 
+        // Fix for eToro bug: SL disabled positions can return 0.01 or similar small values.
+        // If the rate is positive but extremely small (<= 0.01), treat as 0 (disabled).
+        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;
+        // Fix for eToro bug: TP disabled positions can return INF or small values.
+        // If the rate is positive but extremely small (<= 0.01), treat as 0 (disabled).
+        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
+    }
+
+    /**
+     * Extract Open Date Time.
+     * Used for bagholder calculations.
+     */
+    static getOpenDateTime(position) {
+        if (!position || !position.OpenDateTime) return null;        
+        return new Date(position.OpenDateTime);
+    }
+}
+
+/**
+ * --- NEW CLASS: priceExtractor ---
+ * Handles schema-aware extraction of asset price history.
+ * Mitigates typo risk by centralizing access to context.prices.
+ */
+class priceExtractor {
+    /**
+     * Retrieves the sorted price history for a specific instrument.
+     * @param {object} pricesContext - The global context.prices object.
+     * @param {string|number} tickerOrId - The Ticker or InstrumentID to fetch.
+     * @returns {Array<{date: string, price: number}>} Sorted array of price objects.
+     */
+    static getHistory(pricesContext, tickerOrId) {
+        if (!pricesContext || !pricesContext.history) return [];
+        
+        // The history map is keyed by InstrumentID (e.g., "10000")
+        // We iterate to find the entry matching the request (by ID or Ticker)
+        // Optimization: If input is ID, direct lookup. If ticker, search.
+        
+        let assetData = pricesContext.history[tickerOrId];
+        
+        // Fallback: If direct lookup failed, maybe it's a ticker symbol?
+        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 [];
+
+        // Convert Map<Date, Price> to Array<{date, price}> and sort
+        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);
+    }
+
+    /**
+     * Returns all available assets with their histories.
+     * Useful for computations iterating over the entire market.
+     * @param {object} pricesContext - The global context.prices object.
+     * @returns {Map<string, Array<{date: string, price: number}>>} Map<Ticker, HistoryArray>
+     */
+    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;
+            // Reuse the single-asset logic for consistency, though slightly less efficient
+            // than inlining the sort. For safety/DRY, we reuse.
+            const history = this.getHistory(pricesContext, id);
+            if (history.length > 0) {
+                results.set(ticker, history);
+            }
+        }
+        return results;
+    }
+}
+
+class HistoryExtractor {
+    // --- Schema Accessor (NEW) ---
+    /**
+     * Extracts the daily history snapshot from the User object.
+     * This decouples the computation from knowing 'user.history.today'.
+     */
+    static getDailyHistory(user) {
+        return user?.history?.today || null;
+    }
+
+    // --- Data Extractors ---
+    static getTradedAssets(historyDoc) {
+        if (!historyDoc || !Array.isArray(historyDoc.assets)) return [];
+        return historyDoc.assets;
+    }
+
+    static getInstrumentId(asset) { 
+        return asset ? asset.instrumentId : null;
+    }
+
+    static getAvgHoldingTimeMinutes(asset) { // Note, in minutes, we could convert values here into hours or days but we leave as-is for now.
+        return asset ? (asset.avgHoldingTimeInMinutes || 0) : 0;
+    }
+
+    static getSummary(historyDoc) { // This returns the top-level summary of trade history
+        const all = historyDoc?.all;
+        if (!all) return null;
+
+        return { // The all object contains instrumentid of -1 value, we do not include this, it's a junk backend-eToro placeholder.
+            totalTrades:             all.totalTrades             || 0,
+            winRatio:                all.winRatio                || 0,
+            avgProfitPct:            all.avgProfitPct            || 0,
+            avgLossPct:              all.avgLossPct              || 0,
+            avgHoldingTimeInMinutes: all.avgHoldingTimeInMinutes || 0
+        };
+    }
+}
+
+class SignalPrimitives {
+    /**
+     * Safely extracts a specific numeric field for a specific ticker from a dependency.
+     */
+    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;
+    }
+
+    /**
+     * Creates a unified Set of all keys (tickers) present across multiple dependency results.
+     */
+    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);
+    }
+
+    /**
+     * Hyperbolic Tangent Normalization.
+     * Maps inputs to a strict -Scale to +Scale range.
+     */
+    static normalizeTanh(value, scale = 10, sensitivity = 10.0) { // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/tanh
+        if (value === 0) return 0;
+        return Math.tanh(value / sensitivity) * scale;
+    }
+
+    /**
+     * Standard Z-Score normalization.
+     */
+    static normalizeZScore(value, mean, stdDev) { // https://gist.github.com/Restuta/5cbf1d186f17febe5e899febb63e1b86
+        if (!stdDev || stdDev === 0) return 0;
+        return (value - mean) / stdDev;
+    }
+
+    /**
+     * Simple Divergence (A - B).
+     */
+    static divergence(valueA, valueB) {
+        return (valueA || 0) - (valueB || 0);
+    }
+
+    static getPreviousState(previousComputed, calcName, ticker, fieldName = null) { // This is used for either fetching computations listed in getdependencies() OR self-history
+        if (!previousComputed || !previousComputed[calcName]) return null;          // Using this for self-history DOES NOT cause a circular dependency because we assign a special rule in orchestration_helpers
+                                                                                    // Which handles the self-reference, see 2. SMART SELF-FETCH in orchestration_helpers
+        const tickerData = previousComputed[calcName][ticker];
+        if (!tickerData) return null;
+
+        if (fieldName) {
+             return tickerData[fieldName];
+        }
+        return tickerData; // Return whole object (useful for _state)
+    }
+}
+
+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';
+    }
+
+    /**
+     * Calculates the probability of an asset hitting a specific price barrier (Stop Loss/Take Profit)
+     * within a given timeframe using the First Passage Time of Geometric Brownian Motion.
+     * * Formula: P(T < t) = Φ((b - vt) / σ√t) + exp(2vb/σ²) * Φ((b + vt) / σ√t)
+     * Where: 
+     * b = ln(Barrier/Price)
+     * v = drift - 0.5 * volatility^2
+     * * @param {number} currentPrice - The current price of the asset
+     * @param {number} barrierPrice - The target price (SL or TP)
+     * @param {number} volatility - Annualized volatility (e.g., 0.40 for 40%)
+     * @param {number} days - Number of days to forecast (e.g., 3)
+     * @param {number} drift - (Optional) Annualized drift. Default 0 (Risk Neutral).
+     * @returns {number} Probability (0.0 to 1.0)
+     */
+    static calculateHitProbability(currentPrice, barrierPrice, volatility, days, drift = 0) { // https://www.ma.ic.ac.uk/~bin06/M3A22/m3f22chVII.pdf
+        if (currentPrice <= 0 || barrierPrice <= 0 || volatility <= 0 || days <= 0) return 0;
+
+        const t = days / 365.0; // Convert days to years
+        const sigma = volatility;
+        const mu = drift;
+        
+        // The barrier in log-space
+        const b = Math.log(barrierPrice / currentPrice);
+        
+        // Adjusted drift (nu)
+        const nu = mu - 0.5 * Math.pow(sigma, 2);
+
+        const sqrtT = Math.sqrt(t);
+        const sigmaSqrtT = sigma * sqrtT;
+
+        // Helper for Standard Normal CDF (Φ)
+        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;
+        };
+
+        // Standard First Passage Time Formula parts
+        const term1 = (b - nu * t) / sigmaSqrtT;
+        const term2 = (2 * nu * b) / (sigma * sigma);
+        const term3 = (b + nu * t) / sigmaSqrtT;
+
+        // If barrier is below price (Stop Loss for Long), b is negative.
+        // If barrier is above price (Take Profit for Long), we flip the logic essentially,
+        // but the formula works for the distance. 
+        // However, for strict GBM hitting time, we usually treat 'b' as the distance.
+        // For this implementation, we check direction relative to barrier.
+        
+        // If we are already at or past the barrier, probability is 100%
+        if ((currentPrice > barrierPrice && barrierPrice > currentPrice) || 
+            (currentPrice < barrierPrice && barrierPrice < currentPrice)) {
+             return 1.0;
+        }
+
+        // Calculate Probability
+        // Note: If nu is 0, the second term simplifies significantly, but we keep full form.
+        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);
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Simulates future price paths using Geometric Brownian Motion (Monte Carlo).
+     * Used for testing portfolio resilience against potential market moves.
+     * @param {number} currentPrice - S0
+     * @param {number} volatility - Annualized volatility (sigma)
+     * @param {number} days - Time horizon in days (t)
+     * @param {number} simulations - Number of paths to generate (e.g., 1000)
+     * @param {number} drift - Annualized drift (mu), default 0
+     * @returns {Float32Array} Array of simulated end prices
+     */
+    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);
+        
+        // Use Float32Array for memory efficiency with large simulation counts
+        const results = new Float32Array(simulations);
+        
+        for (let i = 0; i < simulations; i++) {
+            // Box-Muller transform for efficient standard normal distribution generation
+            const u1 = Math.random();
+            const u2 = Math.random();
+            const z = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+            
+            // GBM Formula: St = S0 * exp((mu - 0.5*sigma^2)t + sigma*Wt)
+            results[i] = currentPrice * Math.exp(driftTerm + volTerm * z);
+        }
+        return results;
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Simulates "Population Breakdown" (Capitulation) Risk.
+     * Correlates simulated price drops with user pain thresholds.
+     * @param {Float32Array} pricePaths - Array of simulated prices (from simulateGBM).
+     * @param {Array<{entryPrice: number, thresholdPct: number}>} userProfiles - Array of user states.
+     * @returns {number} Expected % of population that capitulates (0.0 - 1.0).
+     */
+    static simulatePopulationBreakdown(pricePaths, userProfiles) {
+        if (!pricePaths.length || !userProfiles.length) return 0;
+        
+        let totalBreakdownEvents = 0;
+        const totalSims = pricePaths.length;
+        const totalUsers = userProfiles.length;
+
+        // For each simulated future price scenario...
+        for (let i = 0; i < totalSims; i++) {
+            const simPrice = pricePaths[i];
+            let capitulatedUsersInScenario = 0;
+
+            // ...check every user to see if they survive
+            for (let j = 0; j < totalUsers; j++) {
+                const user = userProfiles[j];
+                // Calculate hypothetical P&L for this user in this scenario
+                // P&L% = (CurrentValue - EntryValue) / EntryValue
+                const hypotheticalPnL = ((simPrice - user.entryPrice) / user.entryPrice) * 100;
+                
+                // If hypothetical P&L is worse (lower) than their historical pain threshold, they capitulate.
+                // Note: thresholdPct is typically negative (e.g., -15.0)
+                if (hypotheticalPnL < user.thresholdPct) {
+                    capitulatedUsersInScenario++;
+                }
+            }
+            
+            // Add the % of users who broke in this scenario to the accumulator
+            totalBreakdownEvents += (capitulatedUsersInScenario / totalUsers);
+        }
+        
+        // Return the average capitulation rate across all simulations
+        return totalBreakdownEvents / totalSims;
+    }
+}
+
+class Aggregators {
+    /**
+     * Helper to bucket users by P&L Status.
+     * Used by legacy systems or specific aggregators.
+     */
+    static bucketUsersByPnlPerAsset(usersData, tickerMap) { // https://www.geeksforgeeks.org/javascript/bucket-sort-visualization-using-javascript/
+        const buckets = new Map();
+        for (const [userId, portfolio] of Object.entries(usersData)) {
+            // Auto-detect type if not provided (Legacy compatibility) TODO : We do not need legacy compatability, legacy computations do not run.
+            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);
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Calculates Weighted Sentiment (Avg P&L) for a set of positions.
+     * Solves "Dirty Data" / Variable N issue by weighting by investment size.
+     * @param {Array} positions - Array of raw position objects.
+     * @returns {number} Weighted Average NetProfit %.
+     */
+    static getWeightedSentiment(positions) {
+        if (!positions || positions.length === 0) return 0;
+
+        let totalWeightedPnL = 0;
+        let totalWeight = 0;
+
+        for (const pos of positions) {
+            // Use DataExtractor to be safe and schema-agnostic
+            const pnl = DataExtractor.getNetProfit(pos);
+            const weight = DataExtractor.getPositionWeight(pos); // 'Invested' or 'Amount'
+
+            if (weight > 0) {
+                totalWeightedPnL += (pnl * weight);
+                totalWeight += weight;
+            }
+        }
+
+        if (totalWeight === 0) return 0;
+        return totalWeightedPnL / totalWeight;
+    }
+}
+
+// Validation layer -- Used to validate the data incoming 
+class Validators {
+    static validatePortfolio(portfolio, userType) {
+        if (!portfolio) return { valid: false, errors: ['Portfolio is null'] };
+        
+        // Handle both types of schema
+        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 {
+    /**
+     * Updates a Rolling Mean and Variance using Welford's Online Algorithm (EMA variant). // https://jonisalonen.com/2013/deriving-welfords-method-for-computing-variance/
+     * @param {number} value - New data point.
+     * @param {Object} state - { mean: number, variance: number }
+     * @param {number} alpha - Decay factor (e.g., 0.1 for ~20 days).
+     */
+    static updateEMAState(value, state, alpha = 0.1) {
+        const mean = state ? (state.mean || 0) : 0;
+        const variance = state ? (state.variance || 1) : 1; // Default variance 1 to avoid div/0
+
+        if (value === undefined || value === null || isNaN(value)) {
+            return { mean, variance };
+        }
+
+        // EMA Update for Mean
+        const diff = value - mean;
+        const newMean = mean + (alpha * diff);
+
+        // EMA Update for Variance
+        const newVariance = (1 - alpha) * (variance + (alpha * diff * diff));
+
+        return { mean: newMean, variance: newVariance };
+    }
+
+    /**
+     * Calculates Pearson Correlation between two arrays. https://gist.github.com/matt-west/6500993
+     */
+    static pearsonCorrelation(x, y) {
+        if (!x || !y || x.length !== y.length || x.length === 0) return 0;
+        
+        const n = x.length;
+        // Simple sums
+        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 {
+    /**
+     * Gaussian Kernel Density Estimation (KDE)
+     * Converts discrete price points into a continuous probability density curve.
+     * Optimized for memory: accepts pre-binned data.
+     * @param {Array<{value: number, weight: number}>} data - Points or Bins.
+     * @param {number} bandwidth - Smoothing factor (h).
+     * @param {number} steps - Resolution of the output curve.
+     */
+    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;
+        }
+        
+        // Pad range to capture tails
+        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;
+            // Vectorized-like summation https://cvw.cac.cornell.edu/vector/intro/how-vector-works#:~:text=Vectorization%20is%20a%20process%20by,performance%20increases%20obtained%20by%20vectorization.
+            for (const p of data) {
+                const diff = (x - p.value);
+                // Optimization: Skip calculation for points too far away (> 3 std devs)
+                if (Math.abs(diff) > bandwidth * 3) continue;
+                
+                const u = diff / bandwidth;
+                const k = 0.39894228 * Math.exp(-0.5 * u * u); // Standard Normal PDF
+                density += (p.weight * k) / bandwidth;
+            }
+            if (density > 0) curve.push({ price: x, density });
+        }
+        return curve;
+    }
+
+    static integrateProfile(curve, startPrice, endPrice) {
+        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) {
+                // Trapezoidal Rule https://www.khanacademy.org/math/ap-calculus-ab/ab-integration-new/ab-6-2/a/understanding-the-trapezoid-rule
+                sum += (p2.price - p1.price) * ((p1.density + p2.density) / 2);
+            }
+        }
+        return sum;
+    }
+
+    static linearRegression(xValues, yValues) { // https://hazlo.medium.com/linear-regression-from-scratch-in-js-first-foray-into-ml-for-web-developers-867cfcae8fde
+        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 };
+    }
+}
+
+
+// This block is dynamically generated. Do not edit manually.
+module.exports = {
+    Aggregators,
+    DataExtractor,
+    DistributionAnalytics,
+    HistoryExtractor,
+    MathPrimitives,
+    SCHEMAS,
+    SignalPrimitives,
+    TimeSeries,
+    Validators,
+    priceExtractor
+};