aiden-shared-calculations-unified 1.0.23 → 1.0.25

package/calculations/activity/historical/activity_by_pnl_status.js

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Analyzes *why* users were active by checking the P&L status
+ * of positions just before they were closed.
+ * This measures "Profit Taking" vs. "Capitulation".
+ */
+class ActivityByPnlStatus {
+    constructor() {
+        this.total_positions_yesterday = {
+            in_profit: 0,
+            in_loss: 0
+        };
+        this.closed_positions_today = {
+            profit_taken: 0,
+            loss_realized: 0
+        };
+    }
+
+    _getPortfolioMap(portfolio) {
+        // We MUST use PositionID here to track specific trades, not just the asset
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
+        }
+        // Map<PositionID, NetProfit>
+        return new Map(positions.map(p => [p.PositionID, p.NetProfit || 0]));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yPosMap = this._getPortfolioMap(yesterdayPortfolio);
+        const tPosMap = this._getPortfolioMap(todayPortfolio);
+
+        if (yPosMap.size === 0) {
+            return; // No positions yesterday to analyze
+        }
+
+        for (const [yPosId, yNetProfit] of yPosMap.entries()) {
+            // 1. Bucket yesterday's P&L state
+            if (yNetProfit > 0) {
+                this.total_positions_yesterday.in_profit++;
+            } else if (yNetProfit < 0) {
+                this.total_positions_yesterday.in_loss++;
+            }
+
+            // 2. Check if this position was closed
+            if (!tPosMap.has(yPosId)) {
+                // Position was closed. Check its P&L from yesterday.
+                if (yNetProfit > 0) {
+                    this.closed_positions_today.profit_taken++;
+                } else if (yNetProfit < 0) {
+                    this.closed_positions_today.loss_realized++;
+                }
+            }
+        }
+    }
+
+    getResult() {
+        const { in_profit, in_loss } = this.total_positions_yesterday;
+        const { profit_taken, loss_realized } = this.closed_positions_today;
+
+        // Calculate rates to normalize the data
+        const profit_taking_rate = (in_profit > 0) ? (profit_taken / in_profit) * 100 : 0;
+        const capitulation_rate = (in_loss > 0) ? (loss_realized / in_loss) * 100 : 0;
+
+        return {
+            profit_taking_rate_pct: profit_taking_rate, // % of profitable positions that were closed
+            capitulation_rate_pct: capitulation_rate,   // % of losing positions that were closed
+            raw_counts: {
+                profit_positions_closed: profit_taken,
+                loss_positions_closed: loss_realized,
+                total_profit_positions_available: in_profit,
+                total_loss_positions_available: in_loss
+            }
+        };
+    }
+
+    reset() {
+        this.total_positions_yesterday = { in_profit: 0, in_loss: 0 };
+        this.closed_positions_today = { profit_taken: 0, loss_realized: 0 };
+    }
+}
+
+module.exports = ActivityByPnlStatus;

package/calculations/activity/historical/daily_asset_activity.js

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Tracks the flow of unique users opening or closing positions
+ * on a per-asset basis. This measures the "focus" of the crowd's activity.
+ */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+class DailyAssetActivity {
+    constructor() {
+        // We will store { [instrumentId]: { new_users: Set(), closed_users: Set() } }
+        this.assetActivity = new Map();
+        this.mappings = null;
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assetActivity.has(instrumentId)) {
+            this.assetActivity.set(instrumentId, {
+                new_users: new Set(),
+                closed_users: new Set()
+            });
+        }
+    }
+
+    _getInstrumentIds(portfolio) {
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Set();
+        }
+        return new Set(positions.map(p => p.InstrumentID).filter(Boolean));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yIds = this._getInstrumentIds(yesterdayPortfolio);
+        const tIds = this._getInstrumentIds(todayPortfolio);
+
+        // Find new positions (in today but not yesterday)
+        for (const tId of tIds) {
+            if (!yIds.has(tId)) {
+                this._initAsset(tId);
+                this.assetActivity.get(tId).new_users.add(userId);
+            }
+        }
+
+        // Find closed positions (in yesterday but not today)
+        for (const yId of yIds) {
+            if (!tIds.has(yId)) {
+                this._initAsset(yId);
+                this.assetActivity.get(yId).closed_users.add(userId);
+            }
+        }
+    }
+
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+        for (const [instrumentId, data] of this.assetActivity.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const openCount = data.new_users.size;
+            const closeCount = data.closed_users.size;
+            
+            if (openCount > 0 || closeCount > 0) {
+                result[ticker] = {
+                    opened_by_user_count: openCount,
+                    closed_by_user_count: closeCount,
+                    // "Net User Flow" - positive means more users joined than left
+                    net_user_flow: openCount - closeCount 
+                };
+            }
+        }
+        return result;
+    }
+
+    reset() {
+        this.assetActivity.clear();
+        this.mappings = null;
+    }
+}
+
+module.exports = DailyAssetActivity;

package/calculations/activity/historical/speculator_adjustment_activity.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Tracks "tinkering" activity from speculators.
+ * Instead of just opening/closing, this counts how many users
+ * actively *adjusted* the SL, TP, or TSL on existing trades.
+ */
+class SpeculatorAdjustmentActivity {
+    constructor() {
+        // Use Sets to count unique users
+        this.sl_adjusted_users = new Set();
+        this.tp_adjusted_users = new Set();
+        this.tsl_toggled_users = new Set();
+    }
+
+    _getPublicPositionsMap(portfolio) {
+        const positions = portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
+        }
+        // Map<PositionID, PositionObject>
+        return new Map(positions.map(p => [p.PositionID, p]));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        // This calculation is only for speculators
+        if (todayPortfolio?.context?.userType !== 'speculator' || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yPosMap = this._getPublicPositionsMap(yesterdayPortfolio);
+        const tPosMap = this._getPublicPositionsMap(todayPortfolio);
+
+        if (yPosMap.size === 0 || tPosMap.size === 0) {
+            return; // No positions to compare
+        }
+
+        for (const [tPosId, tPos] of tPosMap.entries()) {
+            // Check if this position existed yesterday
+            if (yPosMap.has(tPosId)) {
+                const yPos = yPosMap.get(tPosId);
+
+                // 1. Check for Stop Loss adjustment
+                if (tPos.StopLossRate !== yPos.StopLossRate) {
+                    this.sl_adjusted_users.add(userId);
+                }
+
+                // 2. Check for Take Profit adjustment
+                if (tPos.TakeProfitRate !== yPos.TakeProfitRate) {
+                    this.tp_adjusted_users.add(userId);
+                }
+                
+                // 3. Check if TSL was toggled on or off
+                if (tPos.IsTslEnabled !== yPos.IsTslEnabled) {
+                    this.tsl_toggled_users.add(userId);
+                }
+            }
+        }
+    }
+
+    getResult() {
+        return {
+            // Count of unique users who adjusted at least one trade's SL
+            unique_users_adjusted_sl: this.sl_adjusted_users.size,
+            // Count of unique users who adjusted at least one trade's TP
+            unique_users_adjusted_tp: this.tp_adjusted_users.size,
+            // Count of unique users who toggled TSL on or off
+            unique_users_toggled_tsl: this.tsl_toggled_users.size
+        };
+    }
+
+    reset() {
+        this.sl_adjusted_users.clear();
+        this.tp_adjusted_users.clear();
+        this.tsl_toggled_users.clear();
+    }
+}
+
+module.exports = SpeculatorAdjustmentActivity;

package/calculations/meta/capital_vintage_performance.js

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) that tracks the performance 
+ * of capital "vintages" by analyzing the market returns of assets 
+ * that were bought following a crowd-wide deposit signal.
+ *
+ * This answers: "Does capital deployed from a fresh deposit event 
+ * outperform capital deployed earlier?"
+ */
+
+class CapitalVintagePerformance {
+    constructor() {
+        // How many days to look back/forward to measure performance
+        this.PERFORMANCE_WINDOW_DAYS = 7; 
+        this.dependenciesLoaded = false;
+        this.priceMap = null;
+        this.tickerToIdMap = null;
+    }
+
+    /**
+     * Helper to load all dependencies in parallel
+     */
+    async _loadDependencies(calculationUtils) {
+        if (this.dependenciesLoaded) return;
+        
+        const { loadAllPriceData, loadInstrumentMappings } = calculationUtils;
+        
+        const [priceData, mappings] = await Promise.all([
+            loadAllPriceData(),
+            loadInstrumentMappings()
+        ]);
+
+        this.priceMap = priceData;
+        
+        // Create a reverse map for easy lookup
+        this.tickerToIdMap = {};
+        if (mappings && mappings.instrumentToTicker) {
+            for (const [id, ticker] of Object.entries(mappings.instrumentToTicker)) {
+                this.tickerToIdMap[ticker] = id;
+            }
+        }
+        
+        this.dependenciesLoaded = true;
+    }
+
+    /**
+     * Helper to get a date string X days from a base date
+     */
+    _getDateStr(baseDateStr, daysOffset) {
+        const date = new Date(baseDateStr + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() + daysOffset);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * Helper to calculate the average return of a basket of assets
+     * over a specified period.
+     */
+    _calculateBasketPerformance(assets, startDateStr, endDateStr) {
+        if (!assets || assets.length === 0) {
+            return 0;
+        }
+
+        let totalReturn = 0;
+        let validAssets = 0;
+
+        for (const asset of assets) {
+            const ticker = asset.ticker;
+            const instrumentId = this.tickerToIdMap[ticker];
+
+            if (!instrumentId || !this.priceMap[instrumentId]) {
+                continue; // No price data for this ticker
+            }
+
+            const startPrice = this.priceMap[instrumentId][startDateStr];
+            const endPrice = this.priceMap[instrumentId][endDateStr];
+
+            if (startPrice && endPrice && startPrice > 0) {
+                const assetReturn = (endPrice - startPrice) / startPrice;
+                totalReturn += assetReturn;
+                validAssets++;
+            }
+        }
+
+        if (validAssets === 0) return 0;
+        return (totalReturn / validAssets) * 100; // Return as percentage
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger, calculationUtils).
+     * @param {object} config The computation system configuration.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger, calculationUtils } = dependencies;
+        
+        // 1. Load all price/mapping data
+        await this._loadDependencies(calculationUtils);
+
+        // 2. Define and fetch dependency: cash-flow-deployment
+        const depRef = db.collection(config.resultsCollection).doc(dateStr)
+            .collection('results').doc('meta')
+            .collection('computations').doc('cash-flow-deployment');
+            
+        const snapshot = await depRef.get();
+
+        if (!snapshot.exists || snapshot.data().status !== 'analysis_complete') {
+            logger.log('WARN', `[CapitalVintage] Skipping ${dateStr}, no valid 'cash-flow-deployment' data found.`);
+            return null;
+        }
+
+        const data = snapshot.data();
+        const topAssets = data.top_deployment_assets; // [{ ticker: 'AAPL', ... }]
+        const signalDate = data.signal_date; // The day the deposit signal occurred
+        const deploymentDate = data.analysis_date; // The day the capital was spent (dateStr)
+
+        if (!topAssets || topAssets.length === 0) {
+             logger.log('INFO', `[CapitalVintage] No top assets deployed on ${dateStr}.`);
+             return { status: 'no_deployment' };
+        }
+
+        // 3. Define performance windows
+        // "Before" window: 7 days leading up to the signal
+        const preSignalStart = this._getDateStr(signalDate, -this.PERFORMANCE_WINDOW_DAYS);
+        const preSignalEnd = signalDate;
+        
+        // "After" window: 7 days starting from the deployment
+        const postDeployStart = deploymentDate;
+        const postDeployEnd = this._getDateStr(deploymentDate, this.PERFORMANCE_WINDOW_DAYS);
+
+        // 4. Calculate performance
+        const preSignalReturnPct = this._calculateBasketPerformance(
+            topAssets, preSignalStart, preSignalEnd
+        );
+        
+        const postDeploymentReturnPct = this._calculateBasketPerformance(
+            topAssets, postDeployStart, postDeployEnd
+        );
+        
+        const momentum = postDeploymentReturnPct - preSignalReturnPct;
+
+        return {
+            status: 'analysis_complete',
+            signal_date: signalDate,
+            deployment_date: deploymentDate,
+            performance_window_days: this.PERFORMANCE_WINDOW_DAYS,
+            deployed_assets: topAssets.map(a => a.ticker),
+            pre_signal_return_pct: preSignalReturnPct,
+            post_deployment_return_pct: postDeploymentReturnPct,
+            return_momentum: momentum,
+            interpretation: "Measures the 7-day return of deployed assets *after* deployment vs. 7-days *before* the signal."
+        };
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = CapitalVintagePerformance;

package/package.json

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