aiden-shared-calculations-unified 1.0.16 → 1.0.17

package/calculations/behavioural/historical/in_loss_asset_crowd_flow.js

@@ -0,0 +1,99 @@
+const { loadAllPriceData, getDailyPriceChange } = require('../../../utils/price_data_provider');
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+/**
+ * @fileoverview Calculates "Net Crowd Flow" for each asset, BUT
+ * *only* for the cohort of users who are currently IN LOSS
+ * on their positions for that asset.
+ */
+class InLossAssetCrowdFlow {
+    constructor() {
+        this.asset_values = {}; // Stores { day1_value_sum: 0, day2_value_sum: 0 }
+        this.user_count = 0;
+        this.priceMap = null;
+        this.mappings = null;
+        this.dates = {};
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.asset_values[instrumentId]) {
+            this.asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+        }
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+
+        if (!this.dates.today && context.todayDateStr && context.yesterdayDateStr) {
+            this.dates.today = context.todayDateStr;
+            this.dates.yesterday = context.yesterdayDateStr;
+        }
+
+        const yesterdayPositions = new Map(yesterdayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
+        const todayPositions = new Map(todayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
+        
+        const allInstrumentIds = new Set([
+            ...yesterdayPositions.keys(),
+            ...todayPositions.keys()
+        ]);
+
+        for (const instrumentId of allInstrumentIds) {
+            const yPos = yesterdayPositions.get(instrumentId);
+            const tPos = todayPositions.get(instrumentId);
+            
+            // --- COHORT LOGIC ---
+            // Only aggregate if the user is in LOSS on this asset.
+            const tNetProfit = tPos?.NetProfit || 0;
+            if (tNetProfit >= 0) { // Note: >= 0 (includes zero profit)
+                continue; // Skip this asset for this user
+            }
+            // --- END COHORT LOGIC ---
+
+            this._initAsset(instrumentId);
+            this.asset_values[instrumentId].day1_value_sum += (yPos?.Value || 0);
+            this.asset_values[instrumentId].day2_value_sum += (tPos?.Value || 0);
+        }
+        this.user_count++;
+    }
+
+    async getResult() {
+        if (this.user_count === 0 || !this.dates.today) return {};
+        if (!this.priceMap || !this.mappings) {
+            const [priceData, mappingData] = await Promise.all([
+                loadAllPriceData(),
+                loadInstrumentMappings()
+            ]);
+            this.priceMap = priceData;
+            this.mappings = mappingData;
+        }
+        
+        const finalResults = {};
+        const todayStr = this.dates.today;
+        const yesterdayStr = this.dates.yesterday;
+
+        for (const instrumentId in this.asset_values) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
+            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.priceMap);
+
+            if (priceChangePct === null) continue;
+
+            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
+            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+
+            finalResults[ticker] = {
+                net_crowd_flow_pct: net_crowd_flow_pct,
+                avg_value_day1_pct: avg_day1_value,
+                avg_value_day2_pct: avg_day2_value
+            };
+        }
+        return finalResults;
+    }
+
+    reset() { /*...reset all properties...*/ }
+}
+module.exports = InLossAssetCrowdFlow;

package/calculations/behavioural/historical/in_profit_asset_crowd_flow.js

@@ -0,0 +1,100 @@
+const { loadAllPriceData, getDailyPriceChange } = require('../../../utils/price_data_provider');
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+/**
+ * @fileoverview Calculates "Net Crowd Flow" for each asset, BUT
+ * *only* for the cohort of users who are currently IN PROFIT
+ * on their positions for that asset.
+ */
+class InProfitAssetCrowdFlow {
+    constructor() {
+        this.asset_values = {}; // Stores { day1_value_sum: 0, day2_value_sum: 0 }
+        this.user_count = 0;
+        this.priceMap = null;
+        this.mappings = null;
+        this.dates = {};
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.asset_values[instrumentId]) {
+            this.asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+        }
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context) {
+        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+
+        if (!this.dates.today && context.todayDateStr && context.yesterdayDateStr) {
+            this.dates.today = context.todayDateStr;
+            this.dates.yesterday = context.yesterdayDateStr;
+        }
+
+        const yesterdayPositions = new Map(yesterdayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
+        const todayPositions = new Map(todayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
+        
+        const allInstrumentIds = new Set([
+            ...yesterdayPositions.keys(),
+            ...todayPositions.keys()
+        ]);
+
+        for (const instrumentId of allInstrumentIds) {
+            const yPos = yesterdayPositions.get(instrumentId);
+            const tPos = todayPositions.get(instrumentId);
+            
+            // --- COHORT LOGIC ---
+            // Only aggregate if the user is in PROFIT on this asset.
+            // We check *today's* profit status as the primary signal.
+            const tNetProfit = tPos?.NetProfit || 0;
+            if (tNetProfit <= 0) {
+                continue; // Skip this asset for this user
+            }
+            // --- END COHORT LOGIC ---
+
+            this._initAsset(instrumentId);
+            this.asset_values[instrumentId].day1_value_sum += (yPos?.Value || 0);
+            this.asset_values[instrumentId].day2_value_sum += (tPos?.Value || 0);
+        }
+        this.user_count++; // Note: This is user_count of *all* users, which is fine for avg.
+    }
+
+    async getResult() {
+        if (this.user_count === 0 || !this.dates.today) return {};
+        if (!this.priceMap || !this.mappings) {
+            const [priceData, mappingData] = await Promise.all([
+                loadAllPriceData(),
+                loadInstrumentMappings()
+            ]);
+            this.priceMap = priceData;
+            this.mappings = mappingData;
+        }
+        
+        const finalResults = {};
+        const todayStr = this.dates.today;
+        const yesterdayStr = this.dates.yesterday;
+
+        for (const instrumentId in this.asset_values) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
+            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
+            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.priceMap);
+
+            if (priceChangePct === null) continue;
+
+            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
+            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+
+            finalResults[ticker] = {
+                net_crowd_flow_pct: net_crowd_flow_pct,
+                avg_value_day1_pct: avg_day1_value,
+                avg_value_day2_pct: avg_day2_value
+            };
+        }
+        return finalResults;
+    }
+
+    reset() { /*...reset all properties...*/ }
+}
+module.exports = InProfitAssetCrowdFlow;

package/calculations/meta/capital_deployment_strategy.js

@@ -0,0 +1,138 @@
+/**
+ * @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 = -1.0; // From crowd_cash_flow_proxy
+    }
+
+    _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() {}
+}
+
+module.exports = CapitalDeploymentStrategy;

package/calculations/meta/crowd_sharpe_ratio_proxy.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) to calculate a proxy for the
+ * crowd's "Sharpe Ratio" (risk-adjusted return) on a per-asset basis.
+ * It uses the components from 'pnl_distribution_per_stock' to calculate
+ * the standard deviation of P/L, which serves as the "risk".
+ */
+
+class CrowdSharpeRatioProxy {
+    constructor() {}
+
+    /**
+     * @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;
+
+        // 1. Define dependency
+        const dependency = { category: 'pnl', computation: 'pnl-distribution-per-stock' };
+
+        // 2. Build ref and fetch
+        const docRef = db.collection(collection).doc(dateStr)
+            .collection('results').doc(dependency.category)
+            .collection('computations').doc(dependency.computation);
+
+        const snapshot = await docRef.get();
+
+        // 3. Handle the "day-delay"
+        if (!snapshot.exists) {
+            logger.log('WARN', `[CrowdSharpeRatioProxy] Missing dependency 'pnl-distribution-per-stock' for ${dateStr}. Allowing backfill.`);
+            return null; // Let backfill handle it
+        }
+
+        const data = snapshot.data();
+        const pnlDistribution = data.pnl_distribution_by_asset;
+
+        if (!pnlDistribution) {
+             logger.log('WARN', `[CrowdSharpeRatioProxy] Dependency data for ${dateStr} is empty. Skipping.`);
+             return null;
+        }
+
+        const results = {};
+
+        // 4. Calculate Sharpe Proxy for each asset
+        for (const ticker in pnlDistribution) {
+            const stats = pnlDistribution[ticker];
+            const N = stats.position_count;
+            
+            // Need at least 2 data points to calculate variance
+            if (N < 2) continue;
+
+            const mean = stats.pnl_sum / N; // E(x)
+            const mean_sq = stats.pnl_sum_sq / N; // E(x^2)
+            
+            const variance = mean_sq - (mean * mean);
+
+            // If variance is negative (floating point error) or zero, we can't get std_dev
+            if (variance <= 0) {
+                results[ticker] = {
+                    average_pnl: mean,
+                    std_dev_pnl: 0,
+                    sharpe_ratio_proxy: 0,
+                    position_count: N
+                };
+                continue;
+            }
+
+            const std_dev = Math.sqrt(variance); // "Risk"
+            
+            // Calculate Sharpe Ratio (Return / Risk)
+            // (Assuming 0 risk-free rate)
+            const sharpe_proxy = mean / std_dev;
+
+            results[ticker] = {
+                average_pnl: mean,
+                std_dev_pnl: std_dev,
+                sharpe_ratio_proxy: sharpe_proxy,
+                position_count: N
+            };
+        }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = CrowdSharpeRatioProxy;

package/calculations/meta/profit_cohort_divergence.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Meta-calculation (Pass 3) 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).
+ */
+
+class ProfitCohortDivergence {
+    constructor() {
+        this.flowThreshold = 0.5; // Min abs flow % to be considered a signal
+    }
+
+    /**
+     * @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. Define dependencies
+        const refsToGet = [
+            {
+                key: 'profit_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('in-profit-asset-crowd-flow')
+            },
+            {
+                key: 'loss_flow',
+                ref: db.collection(collection).doc(dateStr).collection(resultsSub).doc('behavioural').collection(compsSub).doc('in-loss-asset-crowd-flow')
+            }
+        ];
+
+        // 2. Fetch
+        const snapshots = await db.getAll(...refsToGet.map(r => r.ref));
+        const profitFlowData = snapshots[0].exists ? snapshots[0].data() : null;
+        const lossFlowData = snapshots[1].exists ? snapshots[1].data() : null;
+
+        // 3. Handle "day-delay"
+        if (!profitFlowData || !lossFlowData) {
+            logger.log('WARN', `[ProfitCohortDivergence] Missing cohort flow data for ${dateStr}. Allowing backfill.`);
+            return null; // Let backfill handle it
+        }
+
+        const results = {};
+        const allTickers = new Set([...Object.keys(profitFlowData), ...Object.keys(lossFlowData)]);
+
+        // 4. Correlate
+        for (const ticker of allTickers) {
+            const profitFlow = profitFlowData[ticker]?.net_crowd_flow_pct || 0;
+            const lossFlow = lossFlowData[ticker]?.net_crowd_flow_pct || 0;
+
+            const profitSells = profitFlow <= -this.flowThreshold;
+            const profitBuys = profitFlow >= this.flowThreshold;
+            const lossSells = lossFlow <= -this.flowThreshold;
+            const lossBuys = lossFlow >= this.flowThreshold;
+
+            let status = 'No Divergence';
+            let detail = 'Both cohorts are acting similarly or flow is insignificant.';
+
+            if (profitSells && lossBuys) {
+                status = 'Profit Taking';
+                detail = 'The "in-profit" cohort is selling to the "in-loss" cohort, who are averaging down.';
+            } else if (profitBuys && lossSells) {
+                status = 'Capitulation';
+                detail = 'The "in-loss" cohort is panic-selling, and the "in-profit" cohort is buying the dip.';
+            } else if (profitBuys && lossBuys) {
+                status = 'High Conviction Buy';
+                detail = 'All cohorts are net-buying.';
+            } else if (profitSells && lossSells) {
+                status = 'High Conviction Sell';
+                detail = 'All cohorts are net-selling.';
+            }
+
+            results[ticker] = {
+                status: status,
+                detail: detail,
+                profit_cohort_flow: profitFlow,
+                loss_cohort_flow: lossFlow
+            };
+        }
+
+        return results;
+    }
+
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = ProfitCohortDivergence;

package/calculations/meta/social_flow_correlation.js

@@ -0,0 +1,123 @@
+/**
+ * @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.
+ */
+
+class SocialFlowCorrelation {
+    constructor() {
+        // Define sensitivity thresholds
+        this.bullishSentimentThreshold = 70.0; // % ratio
+        this.bearishSentimentThreshold = 30.0; // % ratio
+        this.positiveFlowThreshold = 0.5; // net_crowd_flow_pct
+        this.negativeFlowThreshold = -0.5; // net_crowd_flow_pct
+    }
+
+    /**
+     * @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;
+
+        // 1. Define dependencies for the *same day*
+        const dependenciesToFetch = [
+            { category: 'socialPosts', computation: 'social_sentiment_aggregation' },
+            { category: 'behavioural', computation: 'asset_crowd_flow' }
+        ];
+
+        // 2. Build refs and fetch
+        const refs = dependenciesToFetch.map(d =>
+            db.collection(collection).doc(dateStr)
+                .collection('results').doc(d.category)
+                .collection('computations').doc(d.computation)
+        );
+
+        const snapshots = await db.getAll(...refs);
+
+        // 3. Check for data and handle the "day-delay"
+        const socialData = snapshots[0].exists ? snapshots[0].data() : null;
+        const flowData = snapshots[1].exists ? snapshots[1].data() : null;
+
+        if (!socialData || !flowData) {
+            logger.log('WARN', `[SocialFlowCorrelation] Missing dependency data for ${dateStr}. Allowing backfill.`);
+            // Return null. This stops execution and does not save an empty doc.
+            // The Pass 3 backfill will pick this up tomorrow.
+            return null;
+        }
+
+        // 4. If data exists, perform the correlation
+        const sentimentMap = socialData.tickerSentiment || {};
+        const correlationResults = {};
+
+        // Use all tickers from the flow data as the primary loop
+        for (const ticker in flowData) {
+            if (!flowData[ticker] || typeof flowData[ticker].net_crowd_flow_pct === 'undefined') {
+                continue;
+            }
+
+            const flow = flowData[ticker].net_crowd_flow_pct;
+            const sentiment = sentimentMap[ticker]?.sentimentRatio; // e.g., 85.0 or 22.5
+
+            if (typeof sentiment === 'undefined') {
+                // No sentiment found, just record flow
+                correlationResults[ticker] = {
+                    status: 'no_social_sentiment',
+                    net_crowd_flow_pct: flow
+                };
+                continue;
+            }
+
+            // --- The "Jaw-Drop" Logic ---
+            if (sentiment >= this.bullishSentimentThreshold && flow <= this.negativeFlowThreshold) {
+                // Crowd is very bullish but is actively selling
+                correlationResults[ticker] = {
+                    status: 'Bullish Divergence',
+                    detail: 'Crowd is publicly bullish but is net-selling the asset.',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else if (sentiment <= this.bearishSentimentThreshold && flow >= this.positiveFlowThreshold) {
+                // Crowd is very bearish but is actively buying
+                correlationResults[ticker] = {
+                    status: 'Bearish Divergence',
+                    detail: 'Crowd is publicly bearish but is net-buying the asset.',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else if (sentiment >= this.bullishSentimentThreshold && flow >= this.positiveFlowThreshold) {
+                // Crowd is bullish and is buying
+                correlationResults[ticker] = {
+                    status: 'High Conviction Buy',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else if (sentiment <= this.bearishSentimentThreshold && flow <= this.negativeFlowThreshold) {
+                // Crowd is bearish and is selling
+                correlationResults[ticker] = {
+                    status: 'High Conviction Sell',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            } else {
+                // No strong signal or divergence
+                correlationResults[ticker] = {
+                    status: 'No Clear Signal',
+                    sentiment_ratio: sentiment,
+                    net_crowd_flow_pct: flow
+                };
+            }
+        }
+
+        return correlationResults;
+    }
+
+    // Must exist for the meta-computation runner
+    async getResult() { return null; }
+    reset() {}
+}
+
+module.exports = SocialFlowCorrelation;

package/package.json

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