aiden-shared-calculations-unified 1.0.44 → 1.0.45

package/calculations/meta/capital_deployment_strategy.js

@@ -1,21 +1,31 @@
 /**
- * @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.
+ * @fileoverview Meta-calculation (Pass 2) that analyzes "what" the crowd does
+ * following a net deposit signal.
+ *
+ * --- META REFACTOR (v2) ---
+ * This calc fetches *today's* dependencies from the runner, but still
+ * performs its own historical lookback for the *signal*.
  */
 
-// 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 {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'crowd-cash-flow-proxy', 
+            'new-allocation-percentage', 
+            'reallocation-increase-percentage'
+        ];
+    }
+    
     constructor() {
         this.lookbackDays = 7;
         this.correlationWindow = 3; // How many days after a signal to link behavior
-        this.depositSignalThreshold = -0.005; // Formerly -1.0
+        this.depositSignalThreshold = -0.005; 
     }
 
     _getDateStr(baseDate, daysAgo) {
@@ -25,13 +35,14 @@ class CapitalDeploymentStrategy {
     }
 
     /**
+     * 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).
      * @param {object} config The computation system configuration.
-     * @param {object} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    async process(dateStr, dependencies, config, fetchedDependencies) {
         const { db, logger } = dependencies;
         const collection = config.resultsCollection;
         const resultsSub = config.resultsSubcollection || 'results';
@@ -85,9 +96,9 @@ class CapitalDeploymentStrategy {
             };
         }
 
-        // 3. Fetch deployment data for *today* FROM IN-MEMORY CACHE
-        const newAllocData = computedDependencies['new-allocation-percentage'];
-        const reAllocData = computedDependencies['reallocation-increase-percentage'];
+        // 3. Fetch deployment data for *today* FROM `fetchedDependencies`
+        const newAllocData = fetchedDependencies['new-allocation-percentage'];
+        const reAllocData = fetchedDependencies['reallocation-increase-percentage'];
 
         // 4. Handle missing dependencies
         if (!newAllocData || !reAllocData) {
@@ -122,7 +133,6 @@ class CapitalDeploymentStrategy {
         };
     }
 
-    // Must exist for the meta-computation runner
     async getResult() { return null; }
     reset() {}
 }

package/calculations/meta/capital_liquidation_performance.js

@@ -2,9 +2,22 @@
  * @fileoverview Meta-calculation (Pass 3) that tracks the performance
  * of assets that were heavily liquidated (sold) by the crowd to fund
  * a withdrawal event.
+ *
+ * --- 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 CapitalLiquidationPerformance {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['cash-flow-liquidation'];
+    }
+
     constructor() {
         this.PERFORMANCE_WINDOW_DAYS = 7;
         this.dependenciesLoaded = false;
@@ -56,20 +69,21 @@ class CapitalLiquidationPerformance {
     }
 
     /**
+     * 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} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    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 in-memory cache
-        const data = computedDependencies['cash-flow-liquidation'];
+        // 2. Get dependency from `fetchedDependencies`
+        const data = fetchedDependencies['cash-flow-liquidation'];
 
         if (!data || data.status !== 'analysis_complete') {
             logger.log('WARN', `[CapitalLiquidation] Skipping ${dateStr}, no valid 'cash-flow-liquidation' data found.`);

package/calculations/meta/capital_vintage_performance.js

@@ -2,9 +2,22 @@
  * @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;
@@ -56,20 +69,21 @@ class CapitalVintagePerformance {
     }
 
     /**
+     * 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} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    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 in-memory cache
-        const data = computedDependencies['cash-flow-deployment'];
+        // 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.`);

package/calculations/meta/cash-flow-deployment.js

@@ -1,10 +1,27 @@
+/**
+ * @fileoverview Correlates a crowd-wide deposit signal with the specific assets
+ * that are being bought with that new capital.
+ *
+ * --- META REFACTOR (v2) ---
+ * This calc fetches *today's* dependencies from the runner, but still
+ * performs its own historical lookback for the *signal*.
+ */
+
 const { FieldValue } = require('@google-cloud/firestore');
 
 class CashFlowDeployment {
+    
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['crowd-cash-flow-proxy', 'asset-crowd-flow'];
+    }
+
     constructor() {
         this.lookbackDays = 7;
         this.correlationWindow = 3;
-        this.depositSignalThreshold = -0.005; // Formerly -1.0
+        this.depositSignalThreshold = -0.005; // Negative value = deposit
     }
 
     _getDateStr(baseDate, daysAgo) {
@@ -13,21 +30,30 @@ class CashFlowDeployment {
         return date.toISOString().slice(0, 10);
     }
 
-    async process(dateStr, dependencies, config, computedDependencies) {
+    /**
+     * 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).
+     * @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 } = dependencies;
         const collection = config.resultsCollection;
+        const resultsSub = config.resultsSubcollection || 'results';
+        const compsSub = config.computationsSubcollection || 'computations';
 
-        // --- MODIFICATION: Get same-day dependencies from cache ---
-        const cashFlowData = computedDependencies['crowd-cash-flow-proxy'];
-        const assetFlowData = computedDependencies['asset-crowd-flow'];
+        // 1. Get same-day dependencies from `fetchedDependencies`
+        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
+        const assetFlowData = fetchedDependencies['asset-crowd-flow'];
 
         if (!cashFlowData || !assetFlowData) {
             logger.log('WARN', `[CashFlowDeployment] Missing critical in-memory dependency data for ${dateStr}. Skipping.`);
             return null;
         }
-        // --- END MODIFICATION ---
 
-        // --- Historical lookback for signal still uses Firestore ---
+        // 2. Historical lookback for signal (still uses Firestore)
         const refs = [];
         const dates = [];
         for (let i = 1; i <= this.lookbackDays; i++) {
@@ -36,18 +62,16 @@ class CashFlowDeployment {
         }
         const histRefs = dates.map(d =>
             db.collection(collection).doc(d.date)
-                .collection('results').doc(d.category)
-                .collection('computations').doc(d.computation)
+                .collection(resultsSub).doc(d.category)
+                .collection(compsSub).doc(d.computation)
         );
         const snapshots = await db.getAll(...histRefs);
         const dataMap = new Map();
         snapshots.forEach((snap, idx) => {
             if (snap.exists) dataMap.set(idx, snap.data());
         });
-        // --- End historical lookback ---
-
 
-        // find deposit signal
+        // 3. Find deposit signal
         let depositSignal = null;
         let depositSignalDay = null;
 
@@ -69,6 +93,7 @@ class CashFlowDeployment {
             };
         }
 
+        // 4. Check correlation window
         const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
 
         if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
@@ -79,13 +104,14 @@ class CashFlowDeployment {
             };
         }
 
-        // Use the in-memory data for today
+        // 5. Use the in-memory data for today's analysis
         const netSpendPct = cashFlowData.components?.trading_effect || 0;
         const netDepositPct = Math.abs(depositSignal.cash_flow_effect_proxy);
 
+        // Find top *buys*
         const topBuys = Object.entries(assetFlowData)
-            .filter(([ticker, data]) => data.net_crowd_flow_pct > 0)
-            .sort(([, a], [, b]) => b.net_crowd_flow_pct - a.net_crowd_flow_pct)
+            .filter(([ticker, data]) => data.net_crowd_flow_pct > 0) // Find positive flow
+            .sort(([, a], [, b]) => b.net_crowd_flow_pct - a.net_crowd_flow_pct) // Sort descending
             .slice(0, 10)
             .map(([ticker, data]) => ({
                 ticker,
@@ -98,7 +124,7 @@ class CashFlowDeployment {
             signal_date: depositSignalDay,
             days_since_signal: daysSinceSignal,
             signal_deposit_proxy_pct: netDepositPct,
-            day_net_spend_pct: netSpendPct,
+            day_net_spend_pct: netSpendPct, // This value should be positive
             pct_of_deposit_deployed_today: (netSpendPct / netDepositPct) * 100,
             top_deployment_assets: topBuys
         };

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

@@ -1,17 +1,28 @@
 /**
  * @fileoverview Correlates a crowd-wide withdrawal signal with the specific assets
  * that are being sold (liquidated) to fund those withdrawals.
- * This is a meta-calculation that runs in Pass 3.
+ *
+ * --- META REFACTOR (v2) ---
+ * This calc fetches *today's* dependencies from the runner, but still
+ * performs its own historical lookback for the *signal*.
  */
 
 const { FieldValue } = require('@google-cloud/firestore');
 
 class CashFlowLiquidation {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['crowd-cash-flow-proxy', 'asset-crowd-flow'];
+    }
+    
     constructor() {
         this.lookbackDays = 7;
         this.correlationWindow = 3;
         // A positive value signals a net crowd withdrawal
-        this.withdrawalSignalThreshold = 0.005; // Formerly 1.0
+        this.withdrawalSignalThreshold = 0.005;
     }
 
     _getDateStr(baseDate, daysAgo) {
@@ -21,27 +32,29 @@ class CashFlowLiquidation {
     }
 
     /**
+     * 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).
      * @param {object} config The computation system configuration.
-     * @param {object} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    async process(dateStr, dependencies, config, fetchedDependencies) {
         const { db, logger } = dependencies;
         const collection = config.resultsCollection;
+        const resultsSub = config.resultsSubcollection || 'results';
+        const compsSub = config.computationsSubcollection || 'computations';
 
-        // --- MODIFICATION: Get same-day dependencies from cache ---
-        const cashFlowData = computedDependencies['crowd-cash-flow-proxy'];
-        const assetFlowData = computedDependencies['asset-crowd-flow'];
+        // 1. Get same-day dependencies from `fetchedDependencies`
+        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
+        const assetFlowData = fetchedDependencies['asset-crowd-flow'];
 
         if (!cashFlowData || !assetFlowData) {
             logger.log('WARN', `[CashFlowLiquidation] Missing critical in-memory dependency data for ${dateStr}. Skipping.`);
             return null;
         }
-        // --- END MODIFICATION ---
 
-        // --- Historical lookback for signal still uses Firestore ---
+        // 2. Historical lookback for signal (still uses Firestore)
         const dates = [];
         for (let i = 1; i <= this.lookbackDays; i++) {
             const checkDate = this._getDateStr(dateStr, i);
@@ -49,16 +62,14 @@ class CashFlowLiquidation {
         }
         const refs = dates.map(d =>
             db.collection(collection).doc(d.date)
-                .collection('results').doc(d.category)
-                .collection('computations').doc(d.computation)
+                .collection(resultsSub).doc(d.category)
+                .collection(compsSub).doc(d.computation)
         );
         const snapshots = await db.getAll(...refs);
         const dataMap = new Map();
         snapshots.forEach((snap, idx) => {
             if (snap.exists) dataMap.set(idx, snap.data());
         });
-        // --- End historical lookback ---
-
 
         // 2. Find the withdrawal signal
         let withdrawalSignal = null;
@@ -82,7 +93,8 @@ class CashFlowLiquidation {
                 signal_threshold: this.withdrawalSignalThreshold
             };
         }
-
+        
+        // 3. Check correlation window
         const daysSinceSignal = (new Date(dateStr) - new Date(withdrawalSignalDay)) / (1000 * 60 * 60 * 24);
 
         if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
@@ -93,6 +105,7 @@ class CashFlowLiquidation {
             };
         }
 
+        // 4. Use in-memory data for today's analysis
         // 'trading_effect' will be negative if the crowd is net-selling
         const netSellPct = cashFlowData.components?.trading_effect || 0;
         const netWithdrawalPct = Math.abs(withdrawalSignal.cash_flow_effect_proxy);
@@ -119,7 +132,6 @@ class CashFlowLiquidation {
         };
     }
 
-    // Must exist for the meta-computation runner
     async getResult() { return null; }
     reset() {}
 }

package/calculations/meta/profit_cohort_divergence.js

@@ -1,28 +1,41 @@
 /**
- * @fileoverview Meta-calculation (Pass 3) that correlates the asset flow
+ * @fileoverview Meta-calculation (Pass 2) that correlates the asset flow
  * of the "In Profit" cohort vs. the "In Loss" cohort to find
  * powerful divergence signals (e.g., profit-taking, capitulation).
+ *
+ * --- META REFACTOR (v2) ---
+ * This calculation is now stateless. It declares its dependencies and
+ * expects them to be passed to its `process` method.
  */
 
 class ProfitCohortDivergence {
+    
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['in-profit-asset-crowd-flow', 'in-loss-asset-crowd-flow'];
+    }
+    
     constructor() {
-        this.flowThreshold = 0.005; // Min abs flow % to be considered a signal (formerly 0.5)
+        this.flowThreshold = 0.005; // Min abs flow %
     }
 
     /**
+     * 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).
      * @param {object} config The computation system configuration.
-     * @param {object} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
+     * e.g., { 'in-profit-asset-crowd-flow': ..., 'in-loss-asset-crowd-flow': ... }
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    async process(dateStr, dependencies, config, fetchedDependencies) {
         const { logger } = dependencies;
 
-        // 1. Get dependencies directly from the new argument
-        // Names are normalized to kebab-case by the orchestrator
-        const profitFlowData = computedDependencies['in-profit-asset-crowd-flow'];
-        const lossFlowData = computedDependencies['in-loss-asset-crowd-flow'];
+        // 1. Get dependencies
+        const profitFlowData = fetchedDependencies['in-profit-asset-crowd-flow'];
+        const lossFlowData = fetchedDependencies['in-loss-asset-crowd-flow'];
 
         // 2. Handle missing dependencies
         if (!profitFlowData || !lossFlowData) {
@@ -33,7 +46,7 @@ class ProfitCohortDivergence {
         const results = {};
         const allTickers = new Set([...Object.keys(profitFlowData), ...Object.keys(lossFlowData)]);
 
-        // 4. Correlate
+        // 3. Correlate
         for (const ticker of allTickers) {
             const profitFlow = profitFlowData[ticker]?.net_crowd_flow_pct || 0;
             const lossFlow = lossFlowData[ticker]?.net_crowd_flow_pct || 0;

package/calculations/meta/smart-dumb-divergence-index.js

@@ -1,31 +1,41 @@
 /**
- * @fileoverview Meta-calculation (Pass 3) that correlates the asset/sector flow
+ * @fileoverview Meta-calculation (Pass 4) that correlates the asset/sector flow
  * of the "Smart Cohort" vs. the "Dumb Cohort" to find divergence signals.
  *
- * This identifies:
- * 1. "Capitulation": Smart cohort is buying what the dumb cohort is panic-selling.
- * 2. "Euphoria": Smart cohort is selling what the dumb cohort is FOMO-buying.
+ * --- META REFACTOR (v2) ---
+ * This calculation is now stateless. It declares its dependencies and
+ * expects them to be passed to its `process` method.
  */
 
 class SmartDumbDivergenceIndex {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['smart-cohort-flow', 'dumb-cohort-flow'];
+    }
+
     constructor() {
         // Minimum net flow (as a percentage) to be considered a signal
         this.FLOW_THRESHOLD = 0.005; // Formerly 0.5
     }
 
     /**
+     * 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).
      * @param {object} config The computation system configuration.
-     * @param {object} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
+     * e.g., { 'smart-cohort-flow': ..., 'dumb-cohort-flow': ... }
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    async process(dateStr, dependencies, config, fetchedDependencies) {
         const { logger } = dependencies;
 
-        // 1. Get dependencies from in-memory cache
-        const smartData = computedDependencies['smart-cohort-flow'];
-        const dumbData = computedDependencies['dumb-cohort-flow'];
+        // 1. Get dependencies from the new argument
+        const smartData = fetchedDependencies['smart-cohort-flow'];
+        const dumbData = fetchedDependencies['dumb-cohort-flow'];
         
         // 2. Handle missing dependencies
         if (!smartData || !dumbData) {

package/calculations/meta/social_flow_correlation.js

@@ -1,10 +1,21 @@
 /**
- * @fileoverview Meta-calculation (Pass 3) to correlate daily social sentiment with
- * the actual crowd asset flow. It identifies divergences between what the crowd
- * says and what they do.
+ * @fileoverview Meta-calculation (Pass 2) to correlate daily social sentiment with
+ * the actual crowd asset flow.
+ *
+ * --- META REFACTOR (v2) ---
+ * This calculation is now stateless. It declares its dependencies and
+ * expects them to be passed to its `process` method.
  */
 
 class SocialFlowCorrelation {
+
+    /**
+     * (NEW) Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['social-sentiment-aggregation', 'asset-crowd-flow'];
+    }
+    
     constructor() {
         this.bullishSentimentThreshold = 70.0;
         this.bearishSentimentThreshold = 30.0;
@@ -13,18 +24,20 @@ class SocialFlowCorrelation {
     }
 
     /**
+     * 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).
      * @param {object} config The computation system configuration.
-     * @param {object} computedDependencies In-memory results from previous passes.
+     * @param {object} fetchedDependencies In-memory results from previous passes.
+     * e.g., { 'social-sentiment-aggregation': ..., 'asset-crowd-flow': ... }
      * @returns {Promise<object|null>} The analysis result or null.
      */
-    async process(dateStr, dependencies, config, computedDependencies) {
+    async process(dateStr, dependencies, config, fetchedDependencies) {
         const { logger } = dependencies;
 
         // 1. Get dependencies from in-memory cache
-        const socialData = computedDependencies['social-sentiment-aggregation'];
-        const flowData = computedDependencies['asset-crowd-flow'];
+        const socialData = fetchedDependencies['social-sentiment-aggregation'];
+        const flowData = fetchedDependencies['asset-crowd-flow'];
 
         // 2. Handle missing dependencies
         if (!socialData || !flowData) {
@@ -92,7 +105,6 @@ class SocialFlowCorrelation {
         return correlationResults;
     }
 
-    // Must exist for the meta-computation runner
     async getResult() { return null; }
     reset() {}
 }