aiden-shared-calculations-unified 1.0.108 → 1.0.110

package/calculations/core/platform-daily-ownership-delta.js

@@ -1,10 +1,6 @@
-/**
- * @fileoverview Calculation (Pass 1) for ownership delta (users added/lost per asset).
- * REFACTORED: Tracks net change in number of owners. ---> TODO IN TEST ENVIRONMENT THE VALUE OF NUMBER OF CLOSURES ALWAYS RETURNS 0, IS THIS A COMPUTATION BUG OR A TEST HARNESS BUG?
- */
 class PlatformDailyOwnershipDelta {
     constructor() {
-        this.assetChanges = new Map(); // { instId: { added: 0, removed: 0 } }
+        this.assetChanges = new Map();
         this.tickerMap = null;
     }
 
@@ -26,16 +22,17 @@ class PlatformDailyOwnershipDelta {
             "properties": {
                 "owners_added": { "type": "number" },
                 "owners_removed": { "type": "number" },
-                "net_ownership_change": { "type": "number" }
+                "net_ownership_change": { "type": "number" },
+                "total_owners_today": { "type": "number" }
             },
-            "required": ["owners_added", "owners_removed", "net_ownership_change"]
+            "required": ["owners_added", "owners_removed", "net_ownership_change", "total_owners_today"]
         };
         return { "type": "object", "patternProperties": { "^.*$": tickerSchema } };
     }
 
     _initAsset(instId) {
         if (!this.assetChanges.has(instId)) {
-            this.assetChanges.set(instId, { added: 0, removed: 0 });
+            this.assetChanges.set(instId, { added: 0, removed: 0, total: 0 });
         }
     }
 
@@ -53,28 +50,29 @@ class PlatformDailyOwnershipDelta {
         const { mappings, user } = context;
         if (!this.tickerMap) this.tickerMap = mappings.instrumentToTicker;
 
-        // If either portfolio is missing, we can't calculate delta for this user
-        if (!user.portfolio.today || !user.portfolio.yesterday) return;
-
         const todayPositions = extract.getPositions(user.portfolio.today, user.type);
-        const yesterdayPositions = extract.getPositions(user.portfolio.yesterday, user.type);
-
         const tSet = this._getOwnedInstruments(todayPositions, extract);
-        const ySet = this._getOwnedInstruments(yesterdayPositions, extract);
 
-        // Added: In Today, Not Yesterday
+        // Establish current total for Baseline
         for (const instId of tSet) {
-            if (!ySet.has(instId)) {
-                this._initAsset(instId);
-                this.assetChanges.get(instId).added++;
-            }
+            this._initAsset(instId);
+            this.assetChanges.get(instId).total++;
         }
 
-        // Removed: In Yesterday, Not Today
-        for (const instId of ySet) {
-            if (!tSet.has(instId)) {
-                this._initAsset(instId);
-                this.assetChanges.get(instId).removed++;
+        if (user.portfolio.yesterday) {
+            const yesterdayPositions = extract.getPositions(user.portfolio.yesterday, user.type);
+            const ySet = this._getOwnedInstruments(yesterdayPositions, extract);
+            for (const instId of tSet) {
+                if (!ySet.has(instId)) {
+                    this._initAsset(instId);
+                    this.assetChanges.get(instId).added++;
+                }
+            }
+            for (const instId of ySet) {
+                if (!tSet.has(instId)) {
+                    this._initAsset(instId);
+                    this.assetChanges.get(instId).removed++;
+                }
             }
         }
     }
@@ -84,13 +82,12 @@ class PlatformDailyOwnershipDelta {
         const result = {};
         for (const [instId, data] of this.assetChanges.entries()) {
             const ticker = this.tickerMap[instId] || `id_${instId}`;
-            if (data.added > 0 || data.removed > 0) {
-                result[ticker] = {
-                    owners_added: data.added,
-                    owners_removed: data.removed,
-                    net_ownership_change: data.added - data.removed
-                };
-            }
+            result[ticker] = {
+                owners_added: data.added,
+                owners_removed: data.removed,
+                net_ownership_change: data.added - data.removed,
+                total_owners_today: data.total
+            };
         }
         return result;
     }

package/calculations/core/price-metrics.js

@@ -1,15 +1,9 @@
-/**
- * @fileoverview Calculation (Pass 1 - Meta) for historical price metrics.
- * FIXED: Supports Sharded/Batched Execution.
- * MOVED: Sector aggregation logic moved to getResult() to handle sharding correctly.
- */
 const RANGES = [7, 30, 90, 365];
 const TRADING_DAYS_PER_YEAR = 252;
 
 class CorePriceMetrics {
     constructor() {
         this.result = { by_instrument: {}, by_sector: {} };
-        // We persist mappings here because we process shard-by-shard
         this.mappings = null; 
     }
 
@@ -49,13 +43,11 @@ class CorePriceMetrics {
         const prices = [];
         let currentDate = new Date(endDateStr + 'T00:00:00Z');
         let lastPrice = null;
-
         for (let i = 0; i < numDays; i++) {
             const targetDateStr = currentDate.toISOString().slice(0, 10);
             let price = this._findPriceOnOrBefore(priceHistoryObj, targetDateStr);
             if (price === null) price = lastPrice; 
             else lastPrice = price;
-
             if (price !== null) prices.push(price);
             currentDate.setUTCDate(currentDate.getUTCDate() - 1);
         }
@@ -63,9 +55,9 @@ class CorePriceMetrics {
     }
 
     _calculateStats(priceArray) {
-        if (priceArray.length < 2) return { stdDev: 0, mean: 0, drawdown: 0 };
+        const currentPrice = priceArray[priceArray.length - 1] || null;
+        if (priceArray.length < 2) return { stdDev: null, mean: null, drawdown: null, currentPrice };
 
-        // Drawdown
         let maxDrawdown = 0, peak = -Infinity;
         for (const price of priceArray) {
             if (price > peak) peak = price;
@@ -74,8 +66,6 @@ class CorePriceMetrics {
                 if (dd < maxDrawdown) maxDrawdown = dd;
             }
         }
-
-        // Returns & StdDev
         const returns = [];
         for (let i = 1; i < priceArray.length; i++) {
             const prev = priceArray[i - 1];
@@ -84,78 +74,53 @@ class CorePriceMetrics {
         }
         const mean = returns.reduce((a, b) => a + b, 0) / returns.length;
         const variance = returns.reduce((a, b) => a + (b - mean) ** 2, 0) / (returns.length - 1);
-
-        return { stdDev: Math.sqrt(variance), mean, drawdown: maxDrawdown };
+        return { stdDev: Math.sqrt(variance), mean, drawdown: maxDrawdown, currentPrice };
     }
 
     process(context) {
         const { mappings, prices, date } = context;
         const { instrumentToTicker } = mappings;
-        
-        // Save mappings for the final aggregation step
         if (!this.mappings) this.mappings = mappings;
-        
         const priceData = prices?.history;
         const todayDateStr = date.today;
+        if (!priceData || !todayDateStr) return;
 
-        if (!priceData || !todayDateStr) {
-            return;
-        }
-
-        // Iterate over THIS SHARD'S data
         for (const p of Object.values(priceData)) {
             const ticker = instrumentToTicker[p.instrumentId];
             if (!ticker) continue;
-
-            const metrics = {};
+            const metrics = { baseline_price: null };
             for (const range of RANGES) {
                 const priceArray = this._getHistoricalPriceArray(p, todayDateStr, range + 1);
                 const stats = this._calculateStats(priceArray);
-
-                metrics[`stdev_${range}d`] = stats.stdDev;
-                metrics[`max_drawdown_${range}d`] = stats.drawdown;
-                metrics[`volatility_annualized_${range}d`] = stats.stdDev * Math.sqrt(TRADING_DAYS_PER_YEAR);
-                metrics[`sharpe_ratio_${range}d`] = stats.stdDev > 0 
-                    ? (stats.mean / stats.stdDev) * Math.sqrt(TRADING_DAYS_PER_YEAR) 
-                    : 0;
+                metrics.baseline_price = stats.currentPrice;
+                metrics[`stdev_${range}d`] = (stats.stdDev !== null && isFinite(stats.stdDev)) ? stats.stdDev : null;
+                metrics[`max_drawdown_${range}d`] = (stats.drawdown !== null && isFinite(stats.drawdown)) ? stats.drawdown : null;
+                metrics[`volatility_annualized_${range}d`] = (stats.stdDev !== null) ? stats.stdDev * Math.sqrt(TRADING_DAYS_PER_YEAR) : null;
+                metrics[`sharpe_ratio_${range}d`] = (stats.stdDev > 0) ? (stats.mean / stats.stdDev) * Math.sqrt(TRADING_DAYS_PER_YEAR) : null;
             }
-            // Accumulate into by_instrument
             this.result.by_instrument[ticker] = metrics;
         }
     }
 
     async getResult() { 
-        // Perform Sector Aggregation HERE (after all shards are processed)
         const by_instrument = this.result.by_instrument;
         const instrumentToSector = this.mappings?.instrumentToSector || {};
         const instrumentToTicker = this.mappings?.instrumentToTicker || {};
-        
-        // Reverse map ticker -> instrumentId
         const tickerToInstrument = {};
-        for(const [id, tick] of Object.entries(instrumentToTicker)) {
-            tickerToInstrument[tick] = id;
-        }
+        for(const [id, tick] of Object.entries(instrumentToTicker)) tickerToInstrument[tick] = id;
 
         const sectorAggs = {};
         for (const ticker in by_instrument) {
             const instId = tickerToInstrument[ticker];
             const sector = instrumentToSector[instId] || "Unknown"; 
-            
             if (!sectorAggs[sector]) sectorAggs[sector] = { metrics: {}, counts: {} };
-
             const data = by_instrument[ticker];
             for (const key in data) {
-                if (!sectorAggs[sector].metrics[key]) {
-                    sectorAggs[sector].metrics[key] = 0;
-                    sectorAggs[sector].counts[key] = 0;
-                }
-                if (data[key] !== null) {
-                    sectorAggs[sector].metrics[key] += data[key];
-                    sectorAggs[sector].counts[key]++;
-                }
+                if (key === 'baseline_price') continue;
+                if (!sectorAggs[sector].metrics[key]) { sectorAggs[sector].metrics[key] = 0; sectorAggs[sector].counts[key] = 0; }
+                if (data[key] !== null) { sectorAggs[sector].metrics[key] += data[key]; sectorAggs[sector].counts[key]++; }
             }
         }
-
         const by_sector = {};
         for (const sector in sectorAggs) {
             by_sector[sector] = {};
@@ -164,14 +129,10 @@ class CorePriceMetrics {
                 by_sector[sector][`average_${key}`] = count > 0 ? sectorAggs[sector].metrics[key] / count : null;
             }
         }
-        
         this.result.by_sector = by_sector;
         return this.result; 
     }
 
-    reset() { 
-        this.result = { by_instrument: {}, by_sector: {} }; 
-        this.mappings = null;
-    }
+    reset() { this.result = { by_instrument: {}, by_sector: {} }; this.mappings = null; }
 }
 module.exports = CorePriceMetrics;

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

@@ -19,7 +19,7 @@ class ShortInterestGrowth {
             "TICKER": {
                 "shortCount": 0,
                 "shortSparkline": [0, 0, 0, 0, 0, 0, 0],
-                "growth7d": 0.0
+                "growth7d": { "type": ["number", "null"] }
             }
         };
     }
@@ -27,7 +27,6 @@ class ShortInterestGrowth {
     async process(context) {
         const { insights: insightsHelper } = context.math;
         const { previousComputed, mappings } = context;
-        
         const dailyInsights = insightsHelper.getInsights(context, 'today');
         const previousState = previousComputed['short-interest-growth'] || {};
 
@@ -36,34 +35,28 @@ class ShortInterestGrowth {
             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) {
+            let growth7d = null;
+            if (sparkline.length >= 7) {
                 const start = sparkline[0];
                 const end = sparkline[sparkline.length - 1];
-                if (start > 0) {
-                    growth7d = ((end - start) / start) * 100;
-                }
+                if (start > 0) growth7d = ((end - start) / start) * 100;
             }
 
             this.results[ticker] = {
                 shortCount,
                 shortSparkline: sparkline,
-                growth7d
+                growth7d: (growth7d !== null && isFinite(growth7d)) ? growth7d : null
             };
         }
     }
 
     async getResult() { return this.results; }
+    reset() { this.results = {}; }
 }
-
 module.exports = ShortInterestGrowth;

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

@@ -7,7 +7,7 @@ class TrendingOwnershipMomentum {
             type: 'meta',
             category: 'core',
             userType: 'n/a',
-            isHistorical: true, // Needed for rolling history
+            isHistorical: true, 
             rootDataDependencies: ['insights']
         };
     }
@@ -18,9 +18,9 @@ class TrendingOwnershipMomentum {
         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'
+                "sparkline": [0, 0, 0, 0, 0, 0, 0],
+                "momentumScore": { "type": ["number", "null"] },
+                "trend": "string"
             }
         };
     }
@@ -28,12 +28,8 @@ class TrendingOwnershipMomentum {
     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)
+        if (!dailyInsights || !dailyInsights.length) return;
         const previousState = previousComputed['trending-ownership-momentum'] || {};
 
         for (const insight of dailyInsights) {
@@ -43,45 +39,37 @@ class TrendingOwnershipMomentum {
 
             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) {
+            let momentumScore = null;
+            let trend = 'WARM_UP';
+
+            if (sparkline.length >= 7) {
                 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;
+                    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;
+                
+                trend = 'STABLE';
+                if (momentumScore > 0.5) trend = 'RISING';
+                if (momentumScore < -0.5) trend = 'FALLING';
             }
 
-            let trend = 'STABLE';
-            if (momentumScore > 0.5) trend = 'RISING';
-            if (momentumScore < -0.5) trend = 'FALLING';
-
             this.results[ticker] = {
                 currentOwners: currentCount,
                 sparkline,
-                momentumScore,
+                momentumScore: (momentumScore !== null && isFinite(momentumScore)) ? momentumScore : null,
                 trend
             };
         }
     }
 
     async getResult() { return this.results; }
+    reset() { this.results = {}; }
 }
-
 module.exports = TrendingOwnershipMomentum;

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

@@ -1,6 +1,9 @@
 /**
  * @fileoverview Reconstructs a user's full trading history timeline from a single snapshot.
- * Uses a Scan-Line algorithm to replay history and generate daily stats (Holders, Buys, Sells).
+ * Uses a Scan-Line algorithm to replay history and generate daily stats.
+ * * FEATURES:
+ * 1. Auto-Backfill: If running on the EARLIEST available root data date, it generates the full 365-day history.
+ * 2. Incremental Mode: If running on any later date, it only saves that specific date to save I/O.
  */
 
 class UserHistoryReconstructor {
@@ -14,16 +17,16 @@ class UserHistoryReconstructor {
             type: 'standard', 
             category: 'History Reconstruction',
             userType: 'all',
-            // False because we generate history internally from the snapshot
             isHistorical: false, 
-            rootDataDependencies: ['history']
+            rootDataDependencies: ['history'],
+            // [NEW] Request system injection for Date Boundaries
+            requiresEarliestDataDate: true 
         };
     }
 
     static getDependencies() { return []; }
 
     static getSchema() {
-        // Schema for a single Ticker's stats for a single Day
         const tickerDailyStats = {
             "type": "object",
             "properties": {
@@ -40,16 +43,13 @@ class UserHistoryReconstructor {
             }
         };
 
-        // Output is now: Date -> Ticker -> Stats
         return {
             "type": "object",
             "patternProperties": {
-                // Key is YYYY-MM-DD
-                "^\\d{4}-\\d{2}-\\d{2}$": {
+                "^\\d{4}-\\d{2}-\\d{2}$": { // Date Key
                     "type": "object",
                     "patternProperties": {
-                        // Key is Ticker
-                        "^.*$": tickerDailyStats
+                        "^.*$": tickerDailyStats // Ticker Key
                     }
                 }
             }
@@ -57,16 +57,31 @@ class UserHistoryReconstructor {
     }
 
     async process(context) {
-        const { user, math, mappings } = context;
+        const { user, math, mappings, date, system } = context;
+        const currentExecutionDateStr = date.today;
         
-        // 1. Get History (Granular V2 Format)
+        // 1. Determine Execution Mode (Backfill vs Incremental)
+        // We use the INJECTED value from context.system (provided by StandardExecutor)
+        let isEarliestRun = false;
+
+        if (system && system.earliestHistoryDate) {
+            const earliestHistoryStr = system.earliestHistoryDate.toISOString().slice(0, 10);
+            if (currentExecutionDateStr <= earliestHistoryStr) {
+                isEarliestRun = true;
+            }
+        } else {
+             // Fallback: If system context is missing, default to Incremental to prevent explosion
+             // console.warn(`[UserHistoryReconstructor] System context missing. Defaulting to Incremental mode.`);
+        }
+
+        // 2. Get History (Granular V2 Format)
         const history = math.history.getDailyHistory(user);
         const allTrades = history?.PublicHistoryPositions || [];
         
         if (allTrades.length === 0) return;
 
-        // 2. Identify all relevant tickers and dates
-        const events = []; // { time, type, trade, ticker }
+        // 3. Identify all relevant tickers and events
+        const events = []; 
         const tickerSet = new Set();
         
         for (const trade of allTrades) {
@@ -78,42 +93,34 @@ class UserHistoryReconstructor {
             const openTime = new Date(trade.OpenDateTime).getTime();
             const closeTime = trade.CloseDateTime ? new Date(trade.CloseDateTime).getTime() : null;
 
-            // Add OPEN event
             events.push({ time: openTime, type: 'OPEN', trade, ticker });
-
-            // Add CLOSE event (if closed)
             if (closeTime) { events.push({ time: closeTime, type: 'CLOSE', trade, ticker }); }
         }
 
-        // Sort events by time
         events.sort((a, b) => a.time - b.time);
-
         if (events.length === 0) return;
 
-        // 3. Scan-Line Execution (Replay History)
-        const userTimeline = {}; // { "2024-01-01": { "AAPL": {...} } }
+        // 4. Scan-Line Execution (Replay History)
+        const userTimeline = {}; 
+        const activePositions = new Map(); 
         
-        // Tracking State
-        const activePositions = new Map(); // Map<PositionID, Trade>
-        
-        // Determine Start and End dates for the loop
         const firstEventTime = events[0].time;
         const lastEventTime = events[events.length - 1].time;
         
         const startDate = new Date(firstEventTime); startDate.setUTCHours(0,0,0,0);
-        const endDate   = new Date(lastEventTime);   endDate.setUTCHours(0,0,0,0);
+        const endDate   = new Date(lastEventTime);  endDate.setUTCHours(0,0,0,0);
 
         let currentEventIdx = 0;
         const oneDayMs = 86400000;
 
-        // Iterate day by day from first trade to last trade
+        // Iterate day by day
         for (let d = startDate.getTime(); d <= endDate.getTime(); d += oneDayMs) {
             const dateStr = new Date(d).toISOString().slice(0, 10);
             const dayEnd = d + oneDayMs - 1;
 
-            const dayStats = {}; // Ticker -> Stats
+            const dayStats = {}; 
 
-            // Process all events that happened TODAY (before EOD)
+            // Process events for TODAY
             while (currentEventIdx < events.length && events[currentEventIdx].time <= dayEnd) {
                 const event = events[currentEventIdx];
                 const { ticker, trade, type } = event;
@@ -135,7 +142,7 @@ class UserHistoryReconstructor {
                 currentEventIdx++;
             }
 
-            // Snapshot the "Held" State at EOD
+            // Snapshot "Held" State at EOD
             for (const [posId, trade] of activePositions) {
                 const ticker = mappings.instrumentToTicker[trade.InstrumentID];
                 if (!ticker) continue;
@@ -143,16 +150,15 @@ class UserHistoryReconstructor {
                 if (!dayStats[ticker]) this.initTickerStats(dayStats, ticker);
                 
                 const stats = dayStats[ticker];
-                stats.isHolder = 1; // User is a holder today
+                stats.isHolder = 1; 
                 stats.holdCount++;
                 stats.sumEntry += (trade.OpenRate || 0);
                 stats.sumLev += (trade.Leverage || 1);
             }
 
-            // Finalize Averages for this Day
+            // Finalize Averages
             for (const ticker in dayStats) {
                 const stats = dayStats[ticker];
-                
                 if (stats.holdCount > 0) {
                     stats.avgEntry = stats.sumEntry / stats.holdCount;
                     stats.avgLeverage = stats.sumLev / stats.holdCount;
@@ -160,34 +166,27 @@ class UserHistoryReconstructor {
                 if (stats.didBuy > 0) {
                     stats.buyLeverage = stats.sumBuyLev / stats.didBuy;
                 }
-
-                // Cleanup temp sums
-                delete stats.sumEntry;
-                delete stats.sumLev;
-                delete stats.sumBuyLev;
-                delete stats.holdCount;
+                delete stats.sumEntry; delete stats.sumLev; delete stats.sumBuyLev; delete stats.holdCount;
             }
 
-            // Store in timeline if any activity exists for this day
+            // [LOGIC UPDATE] Selective Storage
+            // 1. If this is the EARLIEST run (Backfill), we save ALL calculated days.
+            // 2. If this is a normal run, we ONLY save the stats for the execution date.
             if (Object.keys(dayStats).length > 0) {
-                userTimeline[dateStr] = dayStats;
+                if (isEarliestRun) {
+                    userTimeline[dateStr] = dayStats;
+                } else if (dateStr === currentExecutionDateStr) {
+                    userTimeline[dateStr] = dayStats;
+                }
             }
         }
 
-        // 4. Output the full timeline for this user
-        // The ResultCommitter will handle splitting this into date buckets.
         this.results[user.id] = userTimeline;
     }
 
     initTickerStats(dayStats, ticker) {
         dayStats[ticker] = {
-            isHolder: 0,
-            didBuy: 0,
-            didSell: 0,
-            sumEntry: 0,
-            sumLev: 0,
-            holdCount: 0,
-            sumBuyLev: 0,
+            isHolder: 0, didBuy: 0, didSell: 0, sumEntry: 0, sumLev: 0, holdCount: 0, sumBuyLev: 0,
             closeReasons: { "0": 0, "1": 0, "5": 0 }
         };
     }