aiden-shared-calculations-unified 1.0.102 → 1.0.104

package/calculations/core/crowd-cost-basis.js

@@ -0,0 +1,72 @@
+class CrowdCostBasis {
+    constructor() {
+        this.results = {}; 
+    }
+
+    static getMetadata() {
+        return {
+            name: 'crowd-cost-basis',
+            type: 'meta',
+            category: 'History Reconstruction',
+            userType: 'n/a', // <--- Works on dependency results
+            isHistorical: false,
+            rootDataDependencies: ['price']
+        };
+    }
+
+    static getDependencies() {
+        return ['user-history-reconstructor'];
+    }
+
+    async process(context) {
+        const { computed, prices, math } = context;
+        
+        // 1. Access the output of the Standard calculation
+        const userReconstructions = computed['user-history-reconstructor'];
+        if (!userReconstructions) return;
+
+        const aggregator = {}; // { AAPL: { sumEntry: 0, count: 0 } }
+
+        // 2. Iterate over all users' reconstructed states
+        for (const userId in userReconstructions) {
+            const userPortfolio = userReconstructions[userId];
+            
+            for (const ticker in userPortfolio) {
+                const position = userPortfolio[ticker];
+                
+                if (!aggregator[ticker]) aggregator[ticker] = { sumEntry: 0, count: 0 };
+                
+                // Aggregating global average entry
+                aggregator[ticker].sumEntry += position.avgEntry;
+                aggregator[ticker].count++;
+            }
+        }
+
+        // 3. Compute Global Average vs Current Price
+        for (const ticker in aggregator) {
+            const data = aggregator[ticker];
+            if (data.count < 10) continue; // Noise filter
+
+            const globalAvgEntry = data.sumEntry / data.count;
+            
+            // Get today's closing price
+            const priceHistory = math.priceExtractor.getHistory(prices, ticker);
+            // The last item in price history for this context is "Today"
+            const lastPriceObj = priceHistory[priceHistory.length - 1];
+            const currentPrice = lastPriceObj ? lastPriceObj.price : globalAvgEntry;
+
+            const diffPct = ((currentPrice - globalAvgEntry) / globalAvgEntry) * 100;
+
+            this.results[ticker] = {
+                avgEntry: globalAvgEntry,
+                holderCount: data.count,
+                profitabilityPct: diffPct,
+                state: diffPct > 0 ? 'PROFIT_SUPPORT' : 'LOSS_RESISTANCE'
+            };
+        }
+    }
+
+    async getResult() { return this.results; }
+}
+
+module.exports = CrowdCostBasis;

package/calculations/core/leverage-divergence.js

@@ -0,0 +1,78 @@
+class LeverageDivergence {
+    constructor() { this.results = {}; }
+
+    static getMetadata() {
+        return {
+            name: 'leverage-divergence',
+            type: 'meta',
+            category: 'History Reconstruction',
+            userType: 'n/a',
+            isHistorical: true, // <--- Needs yesterday's result
+            rootDataDependencies: []
+        };
+    }
+
+    static getDependencies() {
+        return ['user-history-reconstructor'];
+    }
+
+    async process(context) {
+        const { computed, previousComputed } = context;
+        
+        const currentReconstruction = computed['user-history-reconstructor'];
+        // Access SELF from yesterday
+        const previousResult = previousComputed['leverage-divergence']; 
+
+        const currentAgg = {}; // { AAPL: { levHolders: 0, spotHolders: 0 } }
+
+        // 1. Build Today's Aggregates
+        for (const userId in currentReconstruction) {
+            const userPortfolio = currentReconstruction[userId];
+            for (const ticker in userPortfolio) {
+                const pos = userPortfolio[ticker];
+                
+                if (!currentAgg[ticker]) currentAgg[ticker] = { levHolders: 0, spotHolders: 0 };
+                
+                // If avg leverage > 1.1, count as "Leveraged Holder"
+                if (pos.avgLeverage > 1.1) {
+                    currentAgg[ticker].levHolders++;
+                } else {
+                    currentAgg[ticker].spotHolders++;
+                }
+            }
+        }
+
+        // 2. Compare with Yesterday
+        for (const ticker in currentAgg) {
+            const curr = currentAgg[ticker];
+            const prev = previousResult ? previousResult[ticker] : null;
+
+            if (!prev) {
+                this.results[ticker] = { ...curr, levDelta: 0, spotDelta: 0, signal: 'NEW' };
+                continue;
+            }
+
+            const levDelta = curr.levHolders - prev.levHolders;
+            const spotDelta = curr.spotHolders - prev.spotHolders;
+
+            let signal = 'NEUTRAL';
+            
+            // Retail (Spot) Buying + Speculators (Lev) Selling = Smart Money Exit
+            if (spotDelta > 0 && levDelta < 0) signal = 'SMART_EXIT'; 
+            
+            // Retail (Spot) Selling + Speculators (Lev) Buying = High Conviction Pump
+            if (spotDelta < 0 && levDelta > 0) signal = 'SPECULATIVE_PUMP';
+
+            this.results[ticker] = {
+                ...curr,
+                levDelta,
+                spotDelta,
+                signal
+            };
+        }
+    }
+
+    async getResult() { return this.results; }
+}
+
+module.exports = LeverageDivergence;

package/calculations/core/liquidation-cascade.js

@@ -0,0 +1,61 @@
+class LiquidationCascade {
+    constructor() { this.results = {}; }
+
+    static getMetadata() {
+        return {
+            name: 'liquidation-cascade',
+            type: 'meta',
+            category: 'History Reconstruction',
+            userType: 'n/a',
+            isHistorical: false,
+            rootDataDependencies: [] 
+        };
+    }
+
+    static getDependencies() {
+        return ['user-history-reconstructor'];
+    }
+
+    async process(context) {
+        const { computed } = context;
+        const userReconstructions = computed['user-history-reconstructor'];
+        if (!userReconstructions) return;
+
+        const aggregator = {}; 
+
+        // 1. Aggregate Forced Exits
+        for (const userId in userReconstructions) {
+            const userPortfolio = userReconstructions[userId];
+            
+            for (const ticker in userPortfolio) {
+                const position = userPortfolio[ticker];
+                
+                if (position.closedToday > 0) {
+                    if (!aggregator[ticker]) aggregator[ticker] = { closed: 0, forced: 0 };
+                    
+                    aggregator[ticker].closed += position.closedToday;
+                    aggregator[ticker].forced += position.forcedExits;
+                }
+            }
+        }
+
+        // 2. Calculate Pain Index
+        for (const ticker in aggregator) {
+            const data = aggregator[ticker];
+            if (data.closed < 5) continue;
+
+            const forcedRatio = data.forced / data.closed;
+
+            this.results[ticker] = {
+                totalClosures: data.closed,
+                forcedClosures: data.forced,
+                painIndex: forcedRatio, // 0.0 to 1.0
+                isFlushEvent: forcedRatio > 0.3 // Flag if >30% of selling was forced
+            };
+        }
+    }
+
+    async getResult() { return this.results; }
+}
+
+module.exports = LiquidationCascade;

package/calculations/core/ownership-vs-performance-ytd.js

@@ -0,0 +1,90 @@
+class OwnershipVsPerformanceYTD {
+    constructor() { this.results = {}; }
+
+    static getMetadata() {
+        return {
+            name: 'ownership-vs-performance-ytd',
+            type: 'meta',
+            category: 'core',
+            userType: 'n/a',
+            isHistorical: true, // Required to carry forward Jan 1st baseline
+            rootDataDependencies: ['insights', 'price']
+        };
+    }
+
+    static getDependencies() { return []; }
+
+    async process(context) {
+        const { insights: insightsHelper, priceExtractor } = context.math;
+        const { previousComputed, mappings, prices, date } = context;
+        
+        const dailyInsights = insightsHelper.getInsights(context, 'today');
+        
+        // 1. Manage Baseline State (Jan 1st snapshot)
+        // If today is Jan 1st (or first run), we reset. Otherwise, we load from yesterday.
+        let baselineState = previousComputed['ownership-vs-performance-ytd']?.baselines || {};
+        const isStartOfYear = date.today.endsWith('-01-01') || date.today.endsWith('-01-02');
+        
+        if (isStartOfYear) {
+            baselineState = {}; // Reset for new year
+        }
+
+        const currentMetrics = {};
+
+        for (const insight of dailyInsights) {
+            const instId = insight.instrumentId;
+            const ticker = mappings.instrumentToTicker[instId];
+            if (!ticker) continue;
+
+            const currentOwners = insightsHelper.getTotalOwners(insight);
+            
+            // Get Price History
+            const priceHist = priceExtractor.getHistory(prices, ticker);
+            if (!priceHist.length) continue;
+            
+            const currentPrice = priceHist[priceHist.length - 1].price;
+
+            // 2. Set Baseline if missing
+            if (!baselineState[ticker]) {
+                baselineState[ticker] = {
+                    startPrice: currentPrice,
+                    startOwners: currentOwners,
+                    date: date.today
+                };
+            }
+
+            const base = baselineState[ticker];
+
+            // 3. Calculate Deltas
+            const priceYtd = base.startPrice > 0 
+                ? ((currentPrice - base.startPrice) / base.startPrice) * 100 
+                : 0;
+            
+            const ownersYtd = base.startOwners > 0 
+                ? ((currentOwners - base.startOwners) / base.startOwners) * 100 
+                : 0;
+
+            currentMetrics[ticker] = {
+                priceYtd,
+                ownersYtd,
+                currentPrice,
+                currentOwners
+            };
+        }
+
+        // 4. Output structure includes the baselines so they are saved for tomorrow
+        this.results = {
+            metrics: currentMetrics,
+            baselines: baselineState 
+        };
+    }
+
+    async getResult() { 
+        // We flatten the 'metrics' for easy API consumption, 
+        // but we must ensure 'baselines' is preserved in the stored document 
+        // so 'previousComputed' picks it up tomorrow.
+        return { ...this.results.metrics, baselines: this.results.baselines }; 
+    }
+}
+
+module.exports = OwnershipVsPerformanceYTD;

package/calculations/core/ownership-vs-volatility.js

@@ -0,0 +1,69 @@
+class OwnershipVsVolatility {
+    constructor() { this.results = {}; }
+
+    static getMetadata() {
+        return {
+            name: 'ownership-vs-volatility',
+            type: 'meta',
+            category: 'core',
+            userType: 'n/a',
+            isHistorical: true, // To calculate ownership change over window
+            rootDataDependencies: ['insights', 'price']
+        };
+    }
+
+    static getDependencies() { return []; }
+
+    async process(context) {
+        const { insights: insightsHelper, priceExtractor, compute } = context.math;
+        const { previousComputed, mappings, prices } = context;
+        
+        const dailyInsights = insightsHelper.getInsights(context, 'today');
+        
+        // Use 7-day lookback for ownership change
+        const prevState = previousComputed['ownership-vs-volatility'] || {};
+
+        for (const insight of dailyInsights) {
+            const instId = insight.instrumentId;
+            const ticker = mappings.instrumentToTicker[instId];
+            if (!ticker) continue;
+
+            // 1. Calculate Recent Volatility (14 Day StdDev of Returns)
+            const priceHist = priceExtractor.getHistory(prices, ticker);
+            if (priceHist.length < 14) continue;
+
+            const recentPrices = priceHist.slice(-14);
+            const returns = [];
+            for (let i = 1; i < recentPrices.length; i++) {
+                returns.push((recentPrices[i].price - recentPrices[i-1].price) / recentPrices[i-1].price);
+            }
+            
+            const volatility = compute.standardDeviation(returns); // Raw std dev
+
+            // 2. Calculate Ownership Change (Current vs 7 days ago stored state)
+            const currentOwners = insightsHelper.getTotalOwners(insight);
+            const prevOwners = prevState[ticker]?.laggedOwners || currentOwners;
+            
+            const ownerChangePct = prevOwners > 0 
+                ? ((currentOwners - prevOwners) / prevOwners) * 100 
+                : 0;
+
+            this.results[ticker] = {
+                volatilityScore: volatility,
+                ownerChange7d: ownerChangePct,
+                // Store current owners as 'laggedOwners' for next week? 
+                // Actually, for daily rolling 7d change, we need a queue. 
+                // Simplified: We store today's value, and the API/UI compares.
+                // Better: Use a simple rolling queue like the Momentum calc.
+                _history: [...(prevState[ticker]?._history || []), currentOwners].slice(-7),
+                
+                // For the output: Calculate change vs the oldest in history (approx 7d ago)
+                laggedOwners: (prevState[ticker]?._history?.[0] || currentOwners)
+            };
+        }
+    }
+
+    async getResult() { return this.results; }
+}
+
+module.exports = OwnershipVsVolatility;

package/calculations/core/short-interest-growth.js

@@ -0,0 +1,69 @@
+class ShortInterestGrowth {
+    constructor() { this.results = {}; }
+
+    static getMetadata() {
+        return {
+            name: 'short-interest-growth',
+            type: 'meta',
+            category: 'core',
+            userType: 'n/a',
+            isHistorical: true,
+            rootDataDependencies: ['insights']
+        };
+    }
+
+    static getDependencies() { return []; }
+
+    static getSchema() {
+        return {
+            "TICKER": {
+                "shortCount": 0,
+                "shortSparkline": [0, 0, 0, 0, 0, 0, 0],
+                "growth7d": 0.0
+            }
+        };
+    }
+
+    async process(context) {
+        const { insights: insightsHelper } = context.math;
+        const { previousComputed, mappings } = context;
+        
+        const dailyInsights = insightsHelper.getInsights(context, 'today');
+        const previousState = previousComputed['short-interest-growth'] || {};
+
+        for (const insight of dailyInsights) {
+            const instId = insight.instrumentId;
+            const ticker = mappings.instrumentToTicker[instId];
+            if (!ticker) continue;
+
+            // Calculate Short Count: Total Owners * (Sell % / 100)
+            const shortCount = insightsHelper.getShortCount(insight);
+            
+            const prevState = previousState[ticker] || { shortSparkline: [] };
+            const sparkline = [...(prevState.shortSparkline || [])];
+            
+            sparkline.push(shortCount);
+            if (sparkline.length > 7) sparkline.shift();
+
+            // Calculate simple 7-day growth %
+            let growth7d = 0;
+            if (sparkline.length > 1) {
+                const start = sparkline[0];
+                const end = sparkline[sparkline.length - 1];
+                if (start > 0) {
+                    growth7d = ((end - start) / start) * 100;
+                }
+            }
+
+            this.results[ticker] = {
+                shortCount,
+                shortSparkline: sparkline,
+                growth7d
+            };
+        }
+    }
+
+    async getResult() { return this.results; }
+}
+
+module.exports = ShortInterestGrowth;

package/calculations/core/trending-ownership-momentum.js

@@ -0,0 +1,87 @@
+class TrendingOwnershipMomentum {
+    constructor() { this.results = {}; }
+
+    static getMetadata() {
+        return {
+            name: 'trending-ownership-momentum',
+            type: 'meta',
+            category: 'core',
+            userType: 'n/a',
+            isHistorical: true, // Needed for rolling history
+            rootDataDependencies: ['insights']
+        };
+    }
+
+    static getDependencies() { return []; }
+
+    static getSchema() {
+        return {
+            "TICKER": {
+                "currentOwners": 0,
+                "sparkline": [0, 0, 0, 0, 0, 0, 0], // 7-Day History
+                "momentumScore": 0.0, // Slope of the trend
+                "trend": "string" // 'RISING', 'FALLING', 'STABLE'
+            }
+        };
+    }
+
+    async process(context) {
+        const { insights: insightsHelper } = context.math;
+        const { previousComputed, mappings } = context;
+        
+        // 1. Get Today's Data
+        const dailyInsights = insightsHelper.getInsights(context, 'today');
+        if (!dailyInsights.length) return;
+
+        // 2. Get Yesterday's State (for rolling history)
+        const previousState = previousComputed['trending-ownership-momentum'] || {};
+
+        for (const insight of dailyInsights) {
+            const instId = insight.instrumentId;
+            const ticker = mappings.instrumentToTicker[instId];
+            if (!ticker) continue;
+
+            const currentCount = insightsHelper.getTotalOwners(insight);
+            const prevState = previousState[ticker] || { sparkline: [] };
+            
+            // 3. Update Rolling Window (Last 7 Days)
+            // Create new array copy to avoid mutation issues
+            const sparkline = [...(prevState.sparkline || [])];
+            sparkline.push(currentCount);
+            
+            // Keep only last 7 entries
+            if (sparkline.length > 7) sparkline.shift();
+
+            // 4. Calculate Momentum Score (Linear Regression Slope)
+            let momentumScore = 0;
+            if (sparkline.length >= 2) {
+                const n = sparkline.length;
+                let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0;
+                for (let i = 0; i < n; i++) {
+                    sumX += i;
+                    sumY += sparkline[i];
+                    sumXY += i * sparkline[i];
+                    sumXX += i * i;
+                }
+                const slope = (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
+                // Normalize slope by current count to get percentage-like momentum
+                momentumScore = currentCount > 0 ? (slope / currentCount) * 100 : 0;
+            }
+
+            let trend = 'STABLE';
+            if (momentumScore > 0.5) trend = 'RISING';
+            if (momentumScore < -0.5) trend = 'FALLING';
+
+            this.results[ticker] = {
+                currentOwners: currentCount,
+                sparkline,
+                momentumScore,
+                trend
+            };
+        }
+    }
+
+    async getResult() { return this.results; }
+}
+
+module.exports = TrendingOwnershipMomentum;

package/calculations/core/user-history-reconstructor.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Reconstructs a user's portfolio state for a specific date from their trade history.
+ * Acts as the "Map" phase for downstream Meta aggregations.
+ */
+class UserHistoryReconstructor {
+    constructor() {
+        this.results = {}; // Output: { "user_id": { "AAPL": { ...stats... } } }
+    }
+
+    static getMetadata() {
+        return {
+            name: 'user-history-reconstructor',
+            type: 'standard', 
+            category: 'History Reconstruction', // <--- Specific Category
+            userType: 'all',                    // <--- Processes User Data
+            isHistorical: false,
+            rootDataDependencies: ['history']
+        };
+    }
+
+    static getDependencies() { return []; }
+
+    static getSchema() {
+        return {
+            "USER_ID": {
+                "TICKER": {
+                    "activeCount": 1,
+                    "avgEntry": 0.0,
+                    "avgLeverage": 1.0,
+                    "closedToday": 0,
+                    "forcedExits": 0
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        const { user, math, mappings, date } = context;
+        
+        // 1. Get History
+        const history = math.history.getDailyHistory(user);
+        const allTrades = history?.PublicHistoryPositions || [];
+        
+        if (allTrades.length === 0) return;
+
+        // 2. Filter for Active Trades on this Date
+        const activeTrades = math.history.getActiveTradesForDate(allTrades, date.today);
+        if (activeTrades.length === 0) return;
+
+        // 3. Initialize User State
+        this.results[user.id] = {};
+        const userState = this.results[user.id];
+
+        const dayStart = new Date(date.today + "T00:00:00.000Z").getTime();
+        const dayEnd   = new Date(date.today + "T23:59:59.999Z").getTime();
+
+        for (const trade of activeTrades) {
+            const instId = trade.InstrumentID;
+            const ticker = mappings.instrumentToTicker[instId];
+            if (!ticker) continue;
+
+            if (!userState[ticker]) {
+                userState[ticker] = { 
+                    activeCount: 0, 
+                    totalEntry: 0, 
+                    totalLev: 0,
+                    closedToday: 0,
+                    forcedExits: 0
+                };
+            }
+
+            const stats = userState[ticker];
+            
+            // Accumulate Holding State
+            stats.activeCount++;
+            stats.totalEntry += (trade.OpenRate || 0);
+            stats.totalLev += (trade.Leverage || 1);
+
+            // Check for Closure Events happening TODAY
+            if (trade.CloseDateTime) {
+                const closeTime = new Date(trade.CloseDateTime).getTime();
+                if (closeTime >= dayStart && closeTime <= dayEnd) {
+                    stats.closedToday++;
+                    // CloseReason: 1 = Stop Loss, 5 = Take Profit, 0 = Manual
+                    if (trade.CloseReason === 1) stats.forcedExits++; 
+                }
+            }
+        }
+
+        // 4. Finalize Averages for this User
+        for (const ticker in userState) {
+            const stats = userState[ticker];
+            if (stats.activeCount > 0) {
+                stats.avgEntry = stats.totalEntry / stats.activeCount;
+                stats.avgLeverage = stats.totalLev / stats.activeCount;
+            }
+            // Cleanup intermediate sums
+            delete stats.totalEntry;
+            delete stats.totalLev;
+        }
+    }
+
+    async getResult() {
+        return this.results;
+    }
+}
+
+module.exports = UserHistoryReconstructor;

package/package.json

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