aiden-shared-calculations-unified 1.0.34 → 1.0.36

package/calculations/meta/capital_deployment_strategy.js

@@ -1,138 +1,130 @@
-/**
- * @fileoverview Meta-calculation (Pass 3) that analyzes "what" the crowd does
- * following a net deposit signal. It determines if the new capital is used to
- * buy *new* assets or *add* to existing ones.
- */
-
-const { FieldValue } = require('@google-cloud/firestore');
-
-class CapitalDeploymentStrategy {
-    constructor() {
-        this.lookbackDays = 7;
-        this.correlationWindow = 3; // How many days after a signal to link behavior
-        this.depositSignalThreshold = -0.005; // Formerly -1.0
-    }
-
-    _getDateStr(baseDate, daysAgo) {
-        const date = new Date(baseDate + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() - daysAgo);
-        return date.toISOString().slice(0, 10);
-    }
-
-    /**
-     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
-     * @param {object} dependencies The shared dependencies (db, logger).
-     * @param {object} config The computation system configuration.
-     * @returns {Promise<object|null>} The analysis result or null.
-     */
-    async process(dateStr, dependencies, config) {
-        const { db, logger } = dependencies;
-        const collection = config.resultsCollection;
-        const resultsSub = config.resultsSubcollection || 'results';
-        const compsSub = config.computationsSubcollection || 'computations';
-
-        // 1. Find the most recent deposit signal
-        let depositSignal = null;
-        let depositSignalDay = null;
-        let refsToGet = [];
-
-        for (let i = 1; i <= this.lookbackDays; i++) {
-            const checkDate = this._getDateStr(dateStr, i);
-            refsToGet.push({
-                date: checkDate,
-                key: `signal_${checkDate}`,
-                ref: db.collection(collection).doc(checkDate).collection(resultsSub).doc('capital_flow').collection(compsSub).doc('crowd-cash-flow-proxy')
-            });
-        }
-
-        const signalSnapshots = await db.getAll(...refsToGet.map(r => r.ref));
-        const dataMap = new Map();
-        signalSnapshots.forEach((snap, idx) => {
-            if (snap.exists) dataMap.set(refsToGet[idx].key, snap.data());
-        });
-
-        for (let i = 1; i <= this.lookbackDays; i++) {
-            const checkDate = this._getDateStr(dateStr, i);
-            const flowData = dataMap.get(`signal_${checkDate}`);
-            if (flowData && flowData.cash_flow_effect_proxy < this.depositSignalThreshold) {
-                depositSignal = flowData;
-                depositSignalDay = checkDate;
-                break; // Found the most recent signal
-            }
-        }
-
-        if (!depositSignal) {
-            return {
-                status: 'no_deposit_signal_found',
-                lookback_days: this.lookbackDays
-            };
-        }
-
-        // 2. Check if today is within the correlation window
-        const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
-
-        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
-            return {
-                status: 'outside_correlation_window',
-                signal_day: depositSignalDay,
-                days_since_signal: daysSinceSignal
-            };
-        }
-
-        // 3. Fetch deployment data for *today*
-        // We are correlating the *past signal* with *today's action*
-        refsToGet = [
-            {
-                key: 'new_alloc',
-                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('capital_flow').collection(compsSub).doc('new-allocation-percentage')
-            },
-            {
-                key: 're_alloc',
-                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('capital_flow').collection(compsSub).doc('reallocation-increase-percentage')
-            }
-        ];
-
-        const deploymentSnapshots = await db.getAll(...refsToGet.map(r => r.ref));
-        const newAllocData = deploymentSnapshots[0].exists ? deploymentSnapshots[0].data() : null;
-        const reAllocData = deploymentSnapshots[1].exists ? deploymentSnapshots[1].data() : null;
-
-        // 4. Handle "day-delay" for *this* data
-        if (!newAllocData || !reAllocData) {
-            logger.log('WARN', `[CapitalDeploymentStrategy] Missing deployment data for ${dateStr}. Allowing backfill.`);
-            // This is a "same-day" meta-calc, so we return null to let backfill run
-            return null;
-        }
-
-        // 5. Calculate deployment bias
-        const newAlloc = newAllocData.average_new_allocation_percentage || 0;
-        const reAlloc = reAllocData.average_reallocation_increase_percentage || 0;
-
-        const totalDeployment = newAlloc + reAlloc;
-        let newAssetBias = 0;
-        let existingAssetBias = 0;
-
-        if (totalDeployment > 0) {
-            newAssetBias = (newAlloc / totalDeployment) * 100;
-            existingAssetBias = (reAlloc / totalDeployment) * 100;
-        }
-
-        return {
-            status: 'analysis_complete',
-            analysis_date: dateStr,
-            signal_date: depositSignalDay,
-            days_since_signal: daysSinceSignal,
-            signal_deposit_proxy_pct: Math.abs(depositSignal.cash_flow_effect_proxy),
-            deployment_new_alloc_pct: newAlloc,
-            deployment_existing_alloc_pct: reAlloc,
-            total_deployment_pct: totalDeployment,
-            new_asset_bias: newAssetBias,
-            existing_asset_bias: existingAssetBias
-        };
-    }
-
-    // Must exist for the meta-computation runner
-    async getResult() { return null; }
-    reset() {}
-}
-
+/**
+ * @fileoverview Meta-calculation (Pass 3) that analyzes "what" the crowd does
+ * following a net deposit signal. It determines if the new capital is used to
+ * buy *new* assets or *add* to existing ones.
+ */
+
+// Note: This calculation still needs to read *historical* data for the signal.
+// Only same-day dependencies can be passed in-memory.
+// A full refactor would involve the orchestrator passing historical results
+// into the cache, but for now we leave the historical lookback.
+
+const { FieldValue } = require('@google-cloud/firestore');
+
+class CapitalDeploymentStrategy {
+    constructor() {
+        this.lookbackDays = 7;
+        this.correlationWindow = 3; // How many days after a signal to link behavior
+        this.depositSignalThreshold = -0.005; // Formerly -1.0
+    }
+
+    _getDateStr(baseDate, daysAgo) {
+        const date = new Date(baseDate + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() - daysAgo);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
+     * @param {object} dependencies The shared dependencies (db, logger).
+     * @param {object} config The computation system configuration.
+     * @param {object} computedDependencies In-memory results from previous passes.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, computedDependencies) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+        const resultsSub = config.resultsSubcollection || 'results';
+        const compsSub = config.computationsSubcollection || 'computations';
+
+        // 1. Find the most recent deposit signal (Still requires historical lookback)
+        let depositSignal = null;
+        let depositSignalDay = null;
+        let refsToGet = [];
+
+        for (let i = 1; i <= this.lookbackDays; i++) {
+            const checkDate = this._getDateStr(dateStr, i);
+            refsToGet.push({
+                date: checkDate,
+                key: `signal_${checkDate}`,
+                ref: db.collection(collection).doc(checkDate).collection(resultsSub).doc('capital_flow').collection(compsSub).doc('crowd-cash-flow-proxy')
+            });
+        }
+
+        const signalSnapshots = await db.getAll(...refsToGet.map(r => r.ref));
+        const dataMap = new Map();
+        signalSnapshots.forEach((snap, idx) => {
+            if (snap.exists) dataMap.set(refsToGet[idx].key, snap.data());
+        });
+
+        for (let i = 1; i <= this.lookbackDays; i++) {
+            const checkDate = this._getDateStr(dateStr, i);
+            const flowData = dataMap.get(`signal_${checkDate}`);
+            if (flowData && flowData.cash_flow_effect_proxy < this.depositSignalThreshold) {
+                depositSignal = flowData;
+                depositSignalDay = checkDate;
+                break; // Found the most recent signal
+            }
+        }
+
+        if (!depositSignal) {
+            return {
+                status: 'no_deposit_signal_found',
+                lookback_days: this.lookbackDays
+            };
+        }
+
+        // 2. Check if today is within the correlation window
+        const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
+
+        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
+            return {
+                status: 'outside_correlation_window',
+                signal_day: depositSignalDay,
+                days_since_signal: daysSinceSignal
+            };
+        }
+
+        // 3. Fetch deployment data for *today* FROM IN-MEMORY CACHE
+        const newAllocData = computedDependencies['new-allocation-percentage'];
+        const reAllocData = computedDependencies['reallocation-increase-percentage'];
+
+        // 4. Handle missing dependencies
+        if (!newAllocData || !reAllocData) {
+            logger.log('WARN', `[CapitalDeploymentStrategy] Missing in-memory deployment data for ${dateStr}. Skipping.`);
+            return null;
+        }
+
+        // 5. Calculate deployment bias
+        const newAlloc = newAllocData.average_new_allocation_percentage || 0;
+        const reAlloc = reAllocData.average_reallocation_increase_percentage || 0;
+
+        const totalDeployment = newAlloc + reAlloc;
+        let newAssetBias = 0;
+        let existingAssetBias = 0;
+
+        if (totalDeployment > 0) {
+            newAssetBias = (newAlloc / totalDeployment) * 100;
+            existingAssetBias = (reAlloc / totalDeployment) * 100;
+        }
+
+        return {
+            status: 'analysis_complete',
+            analysis_date: dateStr,
+            signal_date: depositSignalDay,
+            days_since_signal: daysSinceSignal,
+            signal_deposit_proxy_pct: Math.abs(depositSignal.cash_flow_effect_proxy),
+            deployment_new_alloc_pct: newAlloc,
+            deployment_existing_alloc_pct: reAlloc,
+            total_deployment_pct: totalDeployment,
+            new_asset_bias: newAssetBias,
+            existing_asset_bias: existingAssetBias
+        };
+    }
+
+    // Must exist for the meta-computation runner
+    async getResult() { return null; }
+    reset() {}
+}
+
 module.exports = CapitalDeploymentStrategy;

package/calculations/meta/capital_liquidation_performance.js

@@ -1,164 +1,122 @@
-/**
- * @fileoverview Meta-calculation (Pass 3) that tracks the performance
- * of assets that were heavily liquidated (sold) by the crowd to fund
- * a withdrawal event.
- *
- * This answers: "After the crowd sold an asset to withdraw cash,
- * did that asset recover (implying a panic-sell) or
- * continue to fall (implying a smart exit)?"
- */
-
-class CapitalLiquidationPerformance {
-    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-liquidation
-        const depRef = db.collection(config.resultsCollection).doc(dateStr)
-            .collection('results').doc('meta')
-            .collection('computations').doc('cash-flow-liquidation'); // <-- This is the dependency
-
-        const snapshot = await depRef.get();
-
-        if (!snapshot.exists || snapshot.data().status !== 'analysis_complete') {
-            logger.log('WARN', `[CapitalLiquidation] Skipping ${dateStr}, no valid 'cash-flow-liquidation' data found.`);
-            return null;
-        }
-
-        const data = snapshot.data();
-        // This is the key change: we get the list of *sold* assets
-        const topAssets = data.top_liquidation_assets; // [{ ticker: 'MSFT', ... }]
-        const signalDate = data.signal_date; // The day the withdrawal signal occurred
-        const liquidationDate = data.analysis_date; // The day the capital was sold (dateStr)
-
-        if (!topAssets || topAssets.length === 0) {
-             logger.log('INFO', `[CapitalLiquidation] No top assets liquidated on ${dateStr}.`);
-             return { status: 'no_liquidation' };
-        }
-
-        // 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 liquidation
-        const postLiquidationStart = liquidationDate;
-        const postLiquidationEnd = this._getDateStr(liquidationDate, this.PERFORMANCE_WINDOW_DAYS);
-
-        // 4. Calculate performance
-        const preSignalReturnPct = this._calculateBasketPerformance(
-            topAssets, preSignalStart, preSignalEnd
-        );
-        
-        const postLiquidationReturnPct = this._calculateBasketPerformance(
-            topAssets, postLiquidationStart, postLiquidationEnd
-        );
-        
-        // This answers the question:
-        // A positive value means the assets RECOVERED (crowd panic-sold at the bottom).
-        // A negative value means the assets CONTINUED TO FALL (crowd made a good exit).
-        const crowdTimingError = postLiquidationReturnPct; 
-
-        return {
-            status: 'analysis_complete',
-            signal_date: signalDate,
-            liquidation_date: liquidationDate,
-            performance_window_days: this.PERFORMANCE_WINDOW_DAYS,
-            liquidated_assets: topAssets.map(a => a.ticker),
-            pre_signal_return_pct: preSignalReturnPct,
-            post_liquidation_return_pct: postLiquidationReturnPct,
-            crowd_timing_error: crowdTimingError,
-            interpretation: "Measures the 7-day return of liquidated assets *after* being sold. Positive = asset recovered (bad timing). Negative = asset kept falling (good timing)."
-        };
-    }
-
-    async getResult() { return null; }
-    reset() {}
-}
-
+/**
+ * @fileoverview Meta-calculation (Pass 3) that tracks the performance
+ * of assets that were heavily liquidated (sold) by the crowd to fund
+ * a withdrawal event.
+ */
+
+class CapitalLiquidationPerformance {
+    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;
+    }
+
+    /**
+     * @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} computedDependencies In-memory results from previous passes.
+     * @returns {Promise<object|null>} The analysis result or null.
+     */
+    async process(dateStr, dependencies, config, computedDependencies) {
+        const { db, logger, calculationUtils } = dependencies;
+
+        // 1. Load all price/mapping data
+        await this._loadDependencies(calculationUtils);
+
+        // 2. Get dependency from in-memory cache
+        const data = computedDependencies['cash-flow-liquidation'];
+
+        if (!data || data.status !== 'analysis_complete') {
+            logger.log('WARN', `[CapitalLiquidation] Skipping ${dateStr}, no valid 'cash-flow-liquidation' data found.`);
+            return null;
+        }
+        
+        const topAssets = data.top_liquidation_assets; // [{ ticker: 'MSFT', ... }]
+        const signalDate = data.signal_date;
+        const liquidationDate = data.analysis_date;
+
+        if (!topAssets || topAssets.length === 0) {
+             logger.log('INFO', `[CapitalLiquidation] No top assets liquidated on ${dateStr}.`);
+             return { status: 'no_liquidation' };
+        }
+
+        // 3. Define performance windows
+        const preSignalStart = this._getDateStr(signalDate, -this.PERFORMANCE_WINDOW_DAYS);
+        const preSignalEnd = signalDate;
+        const postLiquidationStart = liquidationDate;
+        const postLiquidationEnd = this._getDateStr(liquidationDate, this.PERFORMANCE_WINDOW_DAYS);
+
+        // 4. Calculate performance
+        const preSignalReturnPct = this._calculateBasketPerformance(
+            topAssets, preSignalStart, preSignalEnd
+        );
+        
+        const postLiquidationReturnPct = this._calculateBasketPerformance(
+            topAssets, postLiquidationStart, postLiquidationEnd
+        );
+        
+        const crowdTimingError = postLiquidationReturnPct; 
+
+        return {
+            status: 'analysis_complete',
+            signal_date: signalDate,
+            liquidation_date: liquidationDate,
+            performance_window_days: this.PERFORMANCE_WINDOW_DAYS,
+            liquidated_assets: topAssets.map(a => a.ticker),
+            pre_signal_return_pct: preSignalReturnPct,
+            post_liquidation_return_pct: postLiquidationReturnPct,
+            crowd_timing_error: crowdTimingError,
+            interpretation: "Measures the 7-day return of liquidated assets *after* being sold. Positive = asset recovered (bad timing). Negative = asset kept falling (good timing)."
+        };
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
 module.exports = CapitalLiquidationPerformance;