aiden-shared-calculations-unified 1.0.95 → 1.0.96

package/calculations/legacy/capital_vintage_performance.js

@@ -1,136 +0,0 @@
-/**
- * @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.
- *
- * --- META REFACTOR (v2) ---
- * This calculation is now stateless. It declares its dependencies and
- * expects them to be passed to its `process` method.
- * It still loads its own price data.
- */
-
-class CapitalVintagePerformance {
-
-    /**
-     * (NEW) Statically declare dependencies.
-     */
-    static getDependencies() {
-        return ['cash-flow-deployment'];
-    }
-
-    constructor() {
-        this.PERFORMANCE_WINDOW_DAYS = 7; 
-        this.dependenciesLoaded = false;
-        this.priceMap = null;
-        this.tickerToIdMap = null;
-    }
-
-    async _loadDependencies(calculationUtils) {
-        if (this.dependenciesLoaded) return;
-        const { loadAllPriceData, loadInstrumentMappings } = calculationUtils;
-        const [priceData, mappings] = await Promise.all([
-            loadAllPriceData(),
-            loadInstrumentMappings()
-        ]);
-        this.priceMap = priceData;
-        this.tickerToIdMap = {};
-        if (mappings && mappings.instrumentToTicker) {
-            for (const [id, ticker] of Object.entries(mappings.instrumentToTicker)) {
-                this.tickerToIdMap[ticker] = id;
-            }
-        }
-        this.dependenciesLoaded = true;
-    }
-
-    _getDateStr(baseDateStr, daysOffset) {
-        const date = new Date(baseDateStr + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() + daysOffset);
-        return date.toISOString().slice(0, 10);
-    }
-
-    _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;
-            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;
-    }
-
-    /**
-     * REFACTORED PROCESS METHOD
-     * @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.
-     * @param {object} fetchedDependencies In-memory results from previous passes.
-     * @returns {Promise<object|null>} The analysis result or null.
-     */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { db, logger, calculationUtils } = dependencies;
-        
-        // 1. Load all price/mapping data
-        await this._loadDependencies(calculationUtils);
-
-        // 2. Get dependency from `fetchedDependencies`
-        const data = fetchedDependencies['cash-flow-deployment'];
-
-        if (!data || data.status !== 'analysis_complete') {
-            logger.log('WARN', `[CapitalVintage] Skipping ${dateStr}, no valid 'cash-flow-deployment' data found.`);
-            return null;
-        }
-
-        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
-        const preSignalStart = this._getDateStr(signalDate, -this.PERFORMANCE_WINDOW_DAYS);
-        const preSignalEnd = signalDate;
-        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/calculations/legacy/cash-flow-deployment.js

@@ -1,144 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 3) for cash flow deployment.
- *
- * This metric answers: "Following a net deposit event, what percentage
- * of that new capital is deployed *today*, and which assets are
- * receiving the most inflow?"
- *
- * It *depends* on 'crowd-cash-flow-proxy' (to know if it's a
- * deposit day) and 'asset_crowd_flow' (to see where flow went).
- */
-class CashFlowDeployment {
-    constructor() {
-        // No per-user processing
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const assetFlowSchema = {
-            "type": "object",
-            "properties": {
-                "ticker": { "type": "string" },
-                "net_flow_contribution": { "type": "number" },
-                "percent_of_total_inflow": { "type": "number" }
-            },
-            "required": ["ticker", "net_flow_contribution", "percent_of_total_inflow"]
-        };
-
-        return {
-            "type": "object",
-            "description": "On net deposit days, tracks % of new capital deployed and which assets received it.",
-            "properties": {
-                "is_net_deposit_day": {
-                    "type": "boolean",
-                    "description": "True if today was a net deposit day."
-                },
-                "net_cash_flow_proxy": {
-                    "type": "number",
-                    "description": "The total estimated net cash flow (positive)."
-                },
-                "total_net_capital_flow": {
-                    "type": "number",
-                    "description": "The sum of all *positive* net capital flows into assets."
-                },
-                "deployment_percentage": {
-                    "type": ["number", "null"],
-                    "description": "Percentage of net cash flow that was deployed (Total Net Flow / Net Cash Flow). Null if no cash flow."
-                },
-                "top_inflow_assets": {
-                    "type": "array",
-                    "description": "Top 5 assets receiving the most inflow.",
-                    "items": assetFlowSchema
-                },
-                "asset_flow_details": {
-                    "type": "array",
-                    "description": "Full list of all assets and their inflows.",
-                    "items": assetFlowSchema
-                }
-            },
-            "required": ["is_net_deposit_day", "net_cash_flow_proxy", "total_net_capital_flow", "deployment_percentage", "top_inflow_assets", "asset_flow_details"]
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'crowd-cash-flow-proxy', // Pass 2
-            'asset_crowd_flow'       // Pass 2
-        ];
-    }
-
-    process() {
-        // No-op
-    }
-
-    getResult(fetchedDependencies) {
-        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
-        const assetFlowData = fetchedDependencies['asset_crowd_flow'];
-
-        const defaults = {
-            is_net_deposit_day: false,
-            net_cash_flow_proxy: 0,
-            total_net_capital_flow: 0,
-            deployment_percentage: null,
-            top_inflow_assets: [],
-            asset_flow_details: []
-        };
-
-        if (!cashFlowData || !assetFlowData || cashFlowData.net_cash_flow_proxy <= 0) {
-            // Not a net deposit day
-            return defaults;
-        }
-
-        const netCashFlow = cashFlowData.net_cash_flow_proxy;
-        let totalNetInflow = 0;
-        const allFlows = [];
-
-        for (const [ticker, data] of Object.entries(assetFlowData)) {
-            // We only care about *positive* flow (deployment)
-            if (data.net_flow_contribution > 0) {
-                totalNetInflow += data.net_flow_contribution;
-                allFlows.push({
-                    ticker: ticker,
-                    net_flow_contribution: data.net_flow_contribution
-                });
-            }
-        }
-
-        if (totalNetInflow === 0) {
-            // Net deposit day, but no positive flow detected
-            return {
-                ...defaults,
-                is_net_deposit_day: true,
-                net_cash_flow_proxy: netCashFlow,
-                deployment_percentage: 0
-            };
-        }
-        
-        // Calculate percent_of_total_inflow for each
-        const asset_flow_details = allFlows.map(flow => ({
-            ...flow,
-            percent_of_total_inflow: (flow.net_flow_contribution / totalNetInflow) * 100
-        })).sort((a, b) => b.net_flow_contribution - a.net_flow_contribution);
-
-        return {
-            is_net_deposit_day: true,
-            net_cash_flow_proxy: netCashFlow,
-            total_net_capital_flow: totalNetInflow,
-            deployment_percentage: (netCashFlow > 0) ? (totalNetInflow / netCashFlow) * 100 : null,
-            top_inflow_assets: asset_flow_details.slice(0, 5),
-            asset_flow_details: asset_flow_details
-        };
-    }
-
-    reset() {
-        // No state
-    }
-}
-
-module.exports = CashFlowDeployment;

package/calculations/legacy/cash-flow-liquidation.js

@@ -1,146 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 3) for cash flow liquidation.
- *
- * This metric answers: "Following a net withdrawal event, what percentage
- * of that withdrawal was funded by selling *today*, and which assets
- * are being liquidated the most?"
- *
- * It *depends* on 'crowd-cash-flow-proxy' (to know if it's a
- * withdrawal day) and 'asset_crowd_flow' (to see where flow went).
- */
-class CashFlowLiquidation {
-    constructor() {
-        // No per-user processing
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const assetFlowSchema = {
-            "type": "object",
-            "properties": {
-                "ticker": { "type": "string" },
-                "net_flow_contribution": { "type": "number" },
-                "percent_of_total_outflow": { "type": "number" }
-            },
-            "required": ["ticker", "net_flow_contribution", "percent_of_total_outflow"]
-        };
-
-        return {
-            "type": "object",
-            "description": "On net withdrawal days, tracks % of withdrawal funded by selling and which assets were sold.",
-            "properties": {
-                "is_net_withdrawal_day": {
-                    "type": "boolean",
-                    "description": "True if today was a net withdrawal day."
-                },
-                "net_cash_flow_proxy": {
-                    "type": "number",
-                    "description": "The total estimated net cash flow (negative)."
-                },
-                "total_net_capital_flow": {
-                    "type": "number",
-                    "description": "The sum of all *negative* net capital flows from assets (total liquidation)."
-                },
-                "funding_percentage": {
-                    "type": ["number", "null"],
-                    "description": "Percentage of net cash flow funded by selling (Total Net Flow / Net Cash Flow). Null if no cash flow."
-                },
-                "top_outflow_assets": {
-                    "type": "array",
-                    "description": "Top 5 assets being liquidated.",
-                    "items": assetFlowSchema
-                },
-                "asset_flow_details": {
-                    "type": "array",
-                    "description": "Full list of all assets and their outflows.",
-                    "items": assetFlowSchema
-                }
-            },
-            "required": ["is_net_withdrawal_day", "net_cash_flow_proxy", "total_net_capital_flow", "funding_percentage", "top_outflow_assets", "asset_flow_details"]
-        };
-    }
-
-    /**
-     * Statically declare dependencies.
-     */
-    static getDependencies() {
-        return [
-            'crowd-cash-flow-proxy', // Pass 2
-            'asset_crowd_flow'       // Pass 2
-        ];
-    }
-
-    process() {
-        // No-op
-    }
-
-    getResult(fetchedDependencies) {
-        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
-        const assetFlowData = fetchedDependencies['asset_crowd_flow'];
-
-        const defaults = {
-            is_net_withdrawal_day: false,
-            net_cash_flow_proxy: 0,
-            total_net_capital_flow: 0,
-            funding_percentage: null,
-            top_outflow_assets: [],
-            asset_flow_details: []
-        };
-
-        if (!cashFlowData || !assetFlowData || cashFlowData.net_cash_flow_proxy >= 0) {
-            // Not a net withdrawal day
-            return defaults;
-        }
-
-        const netCashFlow = cashFlowData.net_cash_flow_proxy; // This is a negative number
-        let totalNetOutflow = 0;
-        const allFlows = [];
-
-        for (const [ticker, data] of Object.entries(assetFlowData)) {
-            // We only care about *negative* flow (liquidation)
-            if (data.net_flow_contribution < 0) {
-                totalNetOutflow += data.net_flow_contribution; // Summing negative numbers
-                allFlows.push({
-                    ticker: ticker,
-                    net_flow_contribution: data.net_flow_contribution
-                });
-            }
-        }
-
-        if (totalNetOutflow === 0) {
-            // Net withdrawal day, but no negative flow detected
-            return {
-                ...defaults,
-                is_net_withdrawal_day: true,
-                net_cash_flow_proxy: netCashFlow,
-                funding_percentage: 0
-            };
-        }
-        
-        // Calculate percent_of_total_outflow for each
-        const asset_flow_details = allFlows.map(flow => ({
-            ...flow,
-            // (Negative / Negative) * 100 = Positive %
-            percent_of_total_outflow: (flow.net_flow_contribution / totalNetOutflow) * 100
-        })).sort((a, b) => a.net_flow_contribution - b.net_flow_contribution); // Sort ascending (most negative first)
-
-        return {
-            is_net_withdrawal_day: true,
-            net_cash_flow_proxy: netCashFlow,
-            total_net_capital_flow: totalNetOutflow,
-            // (Negative / Negative) * 100 = Positive %
-            funding_percentage: (netCashFlow < 0) ? (totalNetOutflow / netCashFlow) * 100 : null,
-            top_outflow_assets: asset_flow_details.slice(0, 5),
-            asset_flow_details: asset_flow_details
-        };
-    }
-
-    reset() {
-        // No state
-    }
-}
-
-module.exports = CashFlowLiquidation;

package/calculations/legacy/crowd-cash-flow-proxy.js

@@ -1,128 +0,0 @@
-/**
- * @fileoverview Calculation (Pass 2) for crowd cash flow proxy.
- *
- * This metric estimates the net cash flow (deposits vs. withdrawals)
- * of the crowd by analyzing changes in 'Invested' vs. 'Cash' balances
- * in user portfolios.
- *
- * It's a proxy because it doesn't see real bank transactions, but
- * infers from the total portfolio value vs. the invested amount.
- */
-class CrowdCashFlowProxy {
-    constructor() {
-        this.total_portfolio_value_yesterday = 0;
-        this.total_invested_yesterday = 0;
-        
-        this.total_portfolio_value_today = 0;
-        this.total_invested_today = 0;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        return {
-            "type": "object",
-            "description": "Estimates net cash flow (deposits/withdrawals) by comparing changes in total portfolio value vs. invested capital.",
-            "properties": {
-                "total_portfolio_value_yesterday": {
-                    "type": "number",
-                    "description": "Sum of all users' total portfolio values from yesterday."
-                },
-                "total_invested_yesterday": {
-                    "type": "number",
-                    "description": "Sum of all users' invested capital from yesterday."
-                },
-                "total_portfolio_value_today": {
-                    "type": "number",
-                    "description": "Sum of all users' total portfolio values from today."
-                },
-                "total_invested_today": {
-                    "type": "number",
-                    "description": "Sum of all users' invested capital from today."
-                },
-                "total_pnl_contribution": {
-                    "type": "number",
-                    "description": "The estimated change in portfolio value attributable to P&L."
-                },
-                "net_cash_flow_proxy": {
-                    "type": "number",
-                    "description": "The estimated net cash flow (Deposits - Withdrawals). Positive indicates net deposits."
-                },
-                "net_cash_flow_proxy_pct": {
-                    "type": "number",
-                    "description": "The net cash flow proxy as a percentage of yesterday's total portfolio value."
-                }
-            },
-            "required": [
-                "total_portfolio_value_yesterday", "total_invested_yesterday",
-                "total_portfolio_value_today", "total_invested_today",
-                "total_pnl_contribution", "net_cash_flow_proxy", "net_cash_flow_proxy_pct"
-            ]
-        };
-    }
-
-    _getPortfolioValues(portfolio) {
-        if (!portfolio || !portfolio.Summary) {
-            return { portfolioValue: 0, invested: 0 };
-        }
-        
-        // Total value (Invested + Cash)
-        const portfolioValue = portfolio.Summary.PortfolioValue || 0;
-        // Total invested in positions
-        const invested = portfolio.Summary.Invested || 0;
-        
-        return { portfolioValue, invested };
-    }
-
-    process(todayPortfolio, yesterdayPortfolio) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yValues = this._getPortfolioValues(yesterdayPortfolio);
-        const tValues = this._getPortfolioValues(todayPortfolio);
-
-        this.total_portfolio_value_yesterday += yValues.portfolioValue;
-        this.total_invested_yesterday += yValues.invested;
-
-        this.total_portfolio_value_today += tValues.portfolioValue;
-        this.total_invested_today += tValues.invested;
-    }
-
-    getResult() {
-        // P&L is the change in *invested* value, not total value
-        const totalPnl = this.total_invested_today - this.total_invested_yesterday;
-
-        // The change in total value is (P&L + Net Cash Flow)
-        // So, Net Cash Flow = (Total Value Change) - P&L
-        const totalValueChange = this.total_portfolio_value_today - this.total_portfolio_value_yesterday;
-        
-        const netCashFlowProxy = totalValueChange - totalPnl;
-        
-        const netCashFlowProxyPct = (this.total_portfolio_value_yesterday > 0)
-            ? (netCashFlowProxy / this.total_portfolio_value_yesterday) * 100
-            : 0;
-
-        return {
-            total_portfolio_value_yesterday: this.total_portfolio_value_yesterday,
-            total_invested_yesterday: this.total_invested_yesterday,
-            total_portfolio_value_today: this.total_portfolio_value_today,
-            total_invested_today: this.total_invested_today,
-            
-            total_pnl_contribution: totalPnl,
-            net_cash_flow_proxy: netCashFlowProxy,
-            net_cash_flow_proxy_pct: netCashFlowProxyPct
-        };
-    }
-
-    reset() {
-        this.total_portfolio_value_yesterday = 0;
-        this.total_invested_yesterday = 0;
-        this.total_portfolio_value_today = 0;
-        this.total_invested_today = 0;
-    }
-}
-
-module.exports = CrowdCashFlowProxy;