aiden-shared-calculations-unified 1.0.12 → 1.0.13

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

@@ -0,0 +1,145 @@
+const { FieldValue } = require('@google-cloud/firestore');
+
+/**
+ * @fileoverview A "meta-calculation" that analyzes the results of
+ * 'crowd-cash-flow-proxy' and 'asset-crowd-flow' to correlate
+ * deposit events with subsequent asset purchases.
+ */
+class CashFlowDeployment {
+    constructor() {
+        // This calculation is stateless for `process()`, but `getResult()` is not used.
+        // All logic happens in `process()` which returns the result directly.
+        this.lookbackDays = 7; // How many days to look back for a signal
+        this.correlationWindow = 3; // How many days after the signal to track deployment
+        this.depositSignalThreshold = -1.0; // A -1.0% proxy value is a strong deposit signal
+    }
+
+    /**
+     * Helper to get a YYYY-MM-DD string for N days ago.
+     */
+    _getDateStr(baseDate, daysAgo) {
+        const date = new Date(baseDate + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() - daysAgo);
+        return date.toISOString().slice(0, 10);
+    }
+
+    /**
+     * Fetches a single calculation result from Firestore.
+     */
+    async _fetchCalc(db, collection, dateStr, category, computation) {
+        try {
+            const docRef = db.collection(collection).doc(dateStr)
+                             .collection('results').doc(category)
+                             .collection('computations').doc(computation);
+            const doc = await docRef.get();
+            if (!doc.exists) return null;
+            return doc.data();
+        } catch (e) {
+            return null;
+        }
+    }
+
+    /**
+     * This special `process` method is called by the computation orchestrator *after*
+     * all user-data-based calculations are complete.
+     *
+     * @param {string} dateStr - The "current" day being processed (e.g., "2025-10-30").
+     * @param {object} dependencies - The master dependencies object containing { db, logger }.
+     * @param {object} config - The computation system config.
+     * @returns {Promise<object|null>} The final result object for this day, or null.
+     */
+    async process(dateStr, dependencies, config) {
+        const { db, logger } = dependencies;
+        const collection = config.resultsCollection;
+        
+        let depositSignal = null;
+        let depositSignalDay = null;
+
+        // 1. Look back for a deposit signal
+        for (let i = 1; i <= this.lookbackDays; i++) {
+            const checkDate = this._getDateStr(dateStr, i);
+            const flowData = await this._fetchCalc(db, collection, checkDate, 'capital_flow', 'crowd-cash-flow-proxy');
+            
+            if (flowData && flowData.cash_flow_effect_proxy < this.depositSignalThreshold) {
+                depositSignal = flowData;
+                depositSignalDay = checkDate;
+                break; // Found the most recent strong signal
+            }
+        }
+
+        // If no signal was found in the lookback window, stop.
+        if (!depositSignal) {
+            return {
+                status: 'no_signal_found',
+                lookback_days: this.lookbackDays,
+                signal_threshold: this.depositSignalThreshold
+            };
+        }
+
+        // 2. A signal was found. Now, track the "spend" in the following days.
+        const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
+
+        // Only run this analysis for the N days *after* the signal
+        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
+            return {
+                status: 'outside_correlation_window',
+                signal_day: depositSignalDay,
+                days_since_signal: daysSinceSignal
+            };
+        }
+
+        // 3. We are INSIDE the correlation window. Let's analyze the deployment.
+        const [cashFlowData, assetFlowData] = await Promise.all([
+            this._fetchCalc(db, collection, dateStr, 'capital_flow', 'crowd-cash-flow-proxy'),
+            this._fetchCalc(db, collection, dateStr, 'behavioural', 'asset-crowd-flow')
+        ]);
+
+        if (!cashFlowData || !assetFlowData) {
+            logger.log('WARN', `[CashFlowDeployment] Missing dependency data for ${dateStr}. Skipping.`);
+            return null; // Missing data, can't run
+        }
+
+        // This is the "spend" (net move from cash to assets) on this day
+        const netSpendPct = cashFlowData.components?.trading_effect || 0;
+        
+        // This is the total deposit signal
+        const netDepositPct = Math.abs(depositSignal.cash_flow_effect_proxy);
+
+        // Filter asset flow to find the top 10 "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)
+            .slice(0, 10)
+            .map(([ticker, data]) => ({
+                ticker: ticker,
+                net_flow_pct: data.net_crowd_flow_pct
+            }));
+
+        // 4. Return the final result
+        return {
+            status: 'analysis_complete',
+            analysis_date: dateStr,
+            signal_date: depositSignalDay,
+            days_since_signal: daysSinceSignal,
+            signal_deposit_proxy_pct: netDepositPct,
+            day_net_spend_pct: netSpendPct,
+            // Calculate what percentage of the *total* deposit was spent *today*
+            pct_of_deposit_deployed_today: (netSpendPct / netDepositPct) * 100,
+            top_deployment_assets: topBuys
+        };
+    }
+
+    /**
+     * This calculation is stateless per-run, so getResult is not used.
+     * The orchestrator will call `process` and commit the result directly.
+     */
+    async getResult() {
+        return null;
+    }
+
+    reset() {
+        // Nothing to reset, as state is not carried
+    }
+}
+
+module.exports = CashFlowDeployment;

package/package.json

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