aiden-shared-calculations-unified 1.0.94 → 1.0.96

package/calculations/capitulation/asset-volatility-estimator.js

@@ -13,8 +13,7 @@ class AssetVolatilityEstimator {
             type: 'meta',
             rootDataDependencies: ['price'], 
             isHistorical: false,
-            userType: 'n/a',
-            category: 'market_stats'
+            userType: 'n/a'
         };
     }
 

package/calculations/capitulation/retail-capitulation-risk-forecast.js

@@ -21,8 +21,7 @@ class RetailCapitulationRiskForecast {
             type: 'standard',
             rootDataDependencies: ['portfolio', 'history'],
             isHistorical: false,
-            userType: 'all',
-            category: 'risk_models'
+            userType: 'all'
         };
     }
 

package/calculations/gauss/cohort-definer.js

@@ -24,10 +24,32 @@ class CohortDefiner {
     }
 
     static getSchema() {
-        const cohortSchema = { "type": "array", "items": { "type": "string" } };
+        const cohortList = { 
+            "type": "array", 
+            "items": { "type": "string" },
+            "description": "List of User IDs belonging to this behavioral cohort" 
+        };
+
         return {
             "type": "object",
-            "patternProperties": { "^.*$": cohortSchema }
+            "required": [
+                "smart_investors",
+                "smart_scalpers",
+                "uncategorized_smart",
+                "fomo_chasers",
+                "patient_losers",
+                "fomo_bagholders",
+                "uncategorized_dumb"
+            ],
+            "properties": {
+                "smart_investors": cohortList,
+                "smart_scalpers": cohortList,
+                "uncategorized_smart": cohortList,
+                "fomo_chasers": cohortList,
+                "patient_losers": cohortList,
+                "fomo_bagholders": cohortList,
+                "uncategorized_dumb": cohortList
+            }
         };
     }
     

package/calculations/ghost-book/cost-basis-density.js

@@ -8,8 +8,7 @@ class CostBasisDensity {
     static getMetadata() {
         return {
             type: 'meta', // Runs ONCE per day
-            dependencies: ['asset-cost-basis-profile'],
-            category: 'ghost_book'
+            dependencies: ['asset-cost-basis-profile']
         };
     }
     

package/calculations/ghost-book/liquidity-vacuum.js

@@ -4,8 +4,7 @@ class LiquidityVacuum {
     static getMetadata() {
         return {
             type: 'meta',
-            dependencies: ['asset-cost-basis-profile'],
-            category: 'ghost_book'
+            dependencies: ['asset-cost-basis-profile']
         };
     }
 

package/calculations/ghost-book/retail-gamma-exposure.js

@@ -10,7 +10,6 @@ class RetailGammaExposure {
             type: 'meta',
             dependencies: ['skilled-cohort-flow', 'instrument-price-change-1d'],
             isHistorical: true, // Requires t-1, t-2... for rolling regression
-            category: 'ghost_book'
         };
     }
 

package/calculations/predicative-alpha/cognitive-dissonance.js

@@ -13,8 +13,7 @@ class CognitiveDissonance {
             type: 'meta', // Runs after standard calculations
             rootDataDependencies: [],
             isHistorical: true, // Requires t-1 state
-            userType: 'aggregate',
-            category: 'predictive_alpha'
+            userType: 'aggregate'
         };
     }
 

package/calculations/predicative-alpha/diamond-hand-fracture.js

@@ -10,8 +10,7 @@ class DiamondHandFracture {
             type: 'meta',
             rootDataDependencies: [],
             isHistorical: true,
-            userType: 'aggregate',
-            category: 'predictive_alpha'
+            userType: 'aggregate'
         };
     }
 

package/calculations/predicative-alpha/mimetic-latency.js

@@ -15,8 +15,7 @@ class MimeticLatencyOscillator {
             type: 'meta',
             rootDataDependencies: [],
             isHistorical: true,
-            userType: 'aggregate',
-            category: 'predictive_alpha'
+            userType: 'aggregate'
         };
     }
 

package/package.json

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

package/calculations/legacy/activity_by_pnl_status.js

@@ -1,119 +0,0 @@
-/**
- * @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
-        };
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Measures profit-taking vs. capitulation by analyzing the P&L of closed positions.",
-            "properties": {
-                "profit_taking_rate_pct": {
-                    "type": "number",
-                    "description": "The percentage of profitable positions (from yesterday) that were closed today."
-                },
-                "capitulation_rate_pct": {
-                    "type": "number",
-                    "description": "The percentage of losing positions (from yesterday) that were closed today."
-                },
-                "raw_counts": {
-                    "type": "object",
-                    "description": "Raw counts used to calculate the rates.",
-                    "properties": {
-                        "profit_positions_closed": { "type": "number" },
-                        "loss_positions_closed": { "type": "number" },
-                        "total_profit_positions_available": { "type": "number" },
-                        "total_loss_positions_available": { "type": "number" }
-                    },
-                    "required": ["profit_positions_closed", "loss_positions_closed", "total_profit_positions_available", "total_loss_positions_available"]
-                }
-            },
-            "required": ["profit_taking_rate_pct", "capitulation_rate_pct", "raw_counts"]
-        };
-    }
-
-    _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/legacy/asset_crowd_flow.js

@@ -1,163 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for asset crowd flow.
- *
- * This metric calculates the "Net Crowd Flow Percentage" for each asset.
- * It's defined as the net percentage of the crowd's capital flowing in or out
- * of an asset, *adjusted for the asset's own price movement*.
- *
- * This isolates true buying/selling pressure from simple value changes.
- */
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
-
-class AssetCrowdFlow {
-    constructor() {
-        this.assetData = new Map();
-        this.mappings = null;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Calculates the net capital flow % per asset, adjusted for price movements.",
-            "patternProperties": {
-                // Ticker
-                "^.*$": {
-                    "type": "object",
-                    "description": "Net crowd flow metrics for a specific asset ticker.",
-                    "properties": {
-                        "net_flow_percentage": {
-                            "type": "number",
-                            "description": "Net capital flow (buying/selling) as a percentage of total holdings, adjusted for price changes."
-                        },
-                        "total_invested_today": {
-                            "type": "number",
-                            "description": "Total USD value invested in this asset today by the sample."
-                        },
-                        "total_invested_yesterday": {
-                            "type": "number",
-                            "description": "Total USD value invested in this asset yesterday by the sample."
-                        },
-                        "price_change_contribution": {
-                            "type": "number",
-                            "description": "The portion of the value change attributable to the asset's price movement."
-                        },
-                        "net_flow_contribution": {
-                            "type": "number",
-                            "description": "The portion of the value change attributable to net buying or selling."
-                        }
-                    },
-                    "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday"]
-                }
-            },
-            "additionalProperties": {
-                "type": "object",
-                "properties": {
-                    "net_flow_percentage": { "type": "number" },
-                    "total_invested_today": { "type": "number" },
-                    "total_invested_yesterday": { "type": "number" },
-                    "price_change_contribution": { "type": "number" },
-                    "net_flow_contribution": { "type": "number" }
-                }
-            }
-        };
-    }
-
-    _getPortfolioPositions(portfolio) {
-        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
-    }
-
-    _initAsset(instrumentId) {
-        if (!this.assetData.has(instrumentId)) {
-            this.assetData.set(instrumentId, {
-                total_invested_yesterday: 0,
-                total_invested_today: 0,
-                price_change_yesterday: 0, // Used to calculate weighted avg price change
-            });
-        }
-    }
-
-    process(todayPortfolio, yesterdayPortfolio) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
-        const tPos = this._getPortfolioPositions(todayPortfolio);
-
-        const yPosMap = new Map(yPos?.map(p => [p.InstrumentID, p]) || []);
-        const tPosMap = new Map(tPos?.map(p => [p.InstrumentID, p]) || []);
-
-        const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
-
-        for (const instrumentId of allInstrumentIds) {
-            if (!instrumentId) continue;
-            
-            this._initAsset(instrumentId);
-            const asset = this.assetData.get(instrumentId);
-
-            const yP = yPosMap.get(instrumentId);
-            const tP = tPosMap.get(instrumentId);
-
-            const yInvested = yP?.Invested || 0;
-            const tInvested = tP?.Invested || 0;
-
-            if (yInvested > 0) {
-                asset.total_invested_yesterday += yInvested;
-                // Get price change from *yesterday's* portfolio
-                const yPriceChange = (yP?.PipsRate || 0) / (yP?.OpenRate || 1); // PipsRate holds 1-day change
-                asset.price_change_yesterday += yPriceChange * yInvested; // Weighted sum
-            }
-            if (tInvested > 0) {
-                asset.total_invested_today += tInvested;
-            }
-        }
-    }
-
-    async getResult() {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
-        }
-
-        const result = {};
-
-        for (const [instrumentId, data] of this.assetData.entries()) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-
-            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
-
-            if (total_invested_yesterday > 0) {
-                // Calculate the weighted average price change %
-                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
-                
-                // Estimate the value change *due to price*
-                const price_contribution = total_invested_yesterday * avg_price_change_pct;
-                
-                // Estimate the value change *due to net flow* (buy/sell)
-                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
-
-                // Calculate Net Flow as a percentage of yesterday's holdings
-                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
-
-                result[ticker] = {
-                    net_flow_percentage: net_flow_percentage,
-                    total_invested_today: total_invested_today,
-                    total_invested_yesterday: total_invested_yesterday,
-                    price_change_contribution: price_contribution,
-                    net_flow_contribution: flow_contribution
-                };
-            }
-        }
-        return result;
-    }
-
-    reset() {
-        this.assetData.clear();
-        this.mappings = null;
-    }
-}
-
-module.exports = AssetCrowdFlow;

package/calculations/legacy/capital_deployment_strategy.js

@@ -1,108 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 3) for capital deployment strategy.
- *
- * This metric answers: "Following a net deposit event, does the crowd
- * tend to deploy new capital into new assets or add to existing ones?"
- *
- * It *depends* on 'crowd-cash-flow-proxy', 'new_allocation_percentage',
- * and 'reallocation_increase_percentage'.
- */
-class CapitalDeploymentStrategy {
-    constructor() {
-        // This class only aggregates results from other calculations.
-        // No per-user processing is needed.
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Analyzes if the crowd deploys new capital into new or existing assets, triggered by a net deposit event.",
-            "properties": {
-                "is_net_deposit_day": {
-                    "type": "boolean",
-                    "description": "True if today was a net deposit day for the crowd."
-                },
-                "net_cash_flow_proxy": {
-                    "type": "number",
-                    "description": "The estimated net cash flow (from 'crowd-cash-flow-proxy')."
-                },
-                "total_deployed_to_new_positions_pct": {
-                    "type": "number",
-                    "description": "The total % portfolio allocation deployed to new positions (from 'new_allocation_percentage')."
-                },
-                "total_deployed_to_existing_positions_pct": {
-                    "type": "number",
-                    "description": "The total % portfolio allocation added to existing positions (from 'reallocation_increase_percentage')."
-                },
-                "deployment_ratio_new_vs_existing": {
-                    "type": ["number", "null"],
-                    "description": "Ratio of (New / Existing) deployment. Null if no deployment to existing positions."
-                }
-            },
-            "required": ["is_net_deposit_day", "net_cash_flow_proxy", "total_deployed_to_new_positions_pct", "total_deployed_to_existing_positions_pct", "deployment_ratio_new_vs_existing"]
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'crowd-cash-flow-proxy',
-            'new_allocation_percentage',
-            'reallocation_increase_percentage'
-        ];
-    }
-
-    /**
-     * process() is a no-op. All logic is in getResult().
-     */
-    process() {
-        // No-op
-    }
-
-    /**
-     * Aggregates results from dependencies.
-     */
-    getResult(fetchedDependencies) {
-        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
-        const newAllocData = fetchedDependencies['new_allocation_percentage'];
-        const reallocData = fetchedDependencies['reallocation_increase_percentage'];
-
-        if (!cashFlowData || !newAllocData || !reallocData) {
-            // Return a default "non-event" state if dependencies are missing
-            return {
-                is_net_deposit_day: false,
-                net_cash_flow_proxy: 0,
-                total_deployed_to_new_positions_pct: 0,
-                total_deployed_to_existing_positions_pct: 0,
-                deployment_ratio_new_vs_existing: null
-            };
-        }
-
-        const netCashFlow = cashFlowData.net_cash_flow_proxy || 0;
-        const isNetDepositDay = netCashFlow > 0;
-
-        // We only report deployment stats IF it was a deposit day.
-        const newAllocSum = isNetDepositDay ? newAllocData.total_new_allocation_pct_sum : 0;
-        const reallocSum = isNetDepositDay ? reallocData.total_reallocation_increase_pct_sum : 0;
-
-        return {
-            is_net_deposit_day: isNetDepositDay,
-            net_cash_flow_proxy: netCashFlow,
-            total_deployed_to_new_positions_pct: newAllocSum,
-            total_deployed_to_existing_positions_pct: reallocSum,
-            deployment_ratio_new_vs_existing: (reallocSum > 0) ? (newAllocSum / reallocSum) : null
-        };
-    }
-
-    reset() {
-        // No state to reset
-    }
-}
-
-module.exports = CapitalDeploymentStrategy;

package/calculations/legacy/capital_liquidation_performance.js

@@ -1,139 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 4) for capital liquidation performance.
- *
- * This metric answers: "When users liquidate assets (net withdrawal),
- * do they tend to sell winners or losers?"
- *
- * It *depends* on 'cash-flow-liquidation' (to get the list of
- * liquidated assets) and 'asset_pnl_status' (to check the P&L
- * status of those assets).
- */
-class CapitalLiquidationPerformance {
-    constructor() {
-        // No per-user processing needed
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Analyzes if users sell winners or losers during net withdrawal events.",
-            "properties": {
-                "is_net_withdrawal_day": {
-                    "type": "boolean",
-                    "description": "True if today was a net withdrawal day."
-                },
-                "total_assets_liquidated": {
-                    "type": "number",
-                    "description": "The number of assets that saw net liquidation."
-                },
-                "assets_sold_at_profit_count": {
-                    "type": "number",
-                    "description": "Count of liquidated assets where the majority of users were in profit."
-                },
-                "assets_sold_at_loss_count": {
-                    "type": "number",
-                    "description": "Count of liquidated assets where the majority of users were in loss."
-                },
-                "winner_loser_sell_ratio": {
-                    "type": ["number", "null"],
-                    "description": "Ratio of (Assets Sold at Profit / Assets Sold at Loss). Null if no assets sold at loss."
-                },
-                "details": {
-                    "type": "array",
-                    "description": "List of liquidated assets and their P&L status.",
-                    "items": {
-                        "type": "object",
-                        "properties": {
-                            "ticker": { "type": "string" },
-                            "net_flow_contribution": { "type": "number" },
-                            "status": { "type": "string", "enum": ["profit", "loss", "neutral"] },
-                            "profit_ratio": { "type": "number" }
-                        },
-                        "required": ["ticker", "net_flow_contribution", "status", "profit_ratio"]
-                    }
-                }
-            },
-            "required": ["is_net_withdrawal_day", "total_assets_liquidated", "assets_sold_at_profit_count", "assets_sold_at_loss_count", "winner_loser_sell_ratio", "details"]
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'cash-flow-liquidation', // Pass 3
-            'asset_pnl_status'       // Pass 1
-        ];
-    }
-
-    process() {
-        // No-op
-    }
-
-    getResult(fetchedDependencies) {
-        const liquidationData = fetchedDependencies['cash-flow-liquidation'];
-        const pnlStatusData = fetchedDependencies['asset_pnl_status'];
-
-        const defaults = {
-            is_net_withdrawal_day: false,
-            total_assets_liquidated: 0,
-            assets_sold_at_profit_count: 0,
-            assets_sold_at_loss_count: 0,
-            winner_loser_sell_ratio: null,
-            details: []
-        };
-
-        if (!liquidationData || !pnlStatusData || !liquidationData.is_net_withdrawal_day) {
-            return defaults;
-        }
-
-        let profitCount = 0;
-        let lossCount = 0;
-        const details = [];
-
-        for (const asset of liquidationData.asset_flow_details) {
-            // We only care about assets that were *sold* (negative flow)
-            if (asset.net_flow_contribution < 0) {
-                const ticker = asset.ticker;
-                const pnlInfo = pnlStatusData[ticker];
-                
-                if (pnlInfo) {
-                    let status = 'neutral';
-                    if (pnlInfo.profit_ratio > 50) {
-                        status = 'profit';
-                        profitCount++;
-                    } else if (pnlInfo.profit_ratio < 50) {
-                        status = 'loss';
-                        lossCount++;
-                    }
-                    details.push({
-                        ticker: ticker,
-                        net_flow_contribution: asset.net_flow_contribution,
-                        status: status,
-                        profit_ratio: pnlInfo.profit_ratio
-                    });
-                }
-            }
-        }
-
-        return {
-            is_net_withdrawal_day: true,
-            total_assets_liquidated: details.length,
-            assets_sold_at_profit_count: profitCount,
-            assets_sold_at_loss_count: lossCount,
-            winner_loser_sell_ratio: (lossCount > 0) ? (profitCount / lossCount) : null,
-            details: details
-        };
-    }
-
-    reset() {
-        // No state
-    }
-}
-
-module.exports = CapitalLiquidationPerformance;