aiden-shared-calculations-unified 1.0.82 → 1.0.84

package/calculations/gem/unskilled-cohort-flow.js

@@ -1,240 +1,250 @@
 /**
- * @fileoverview Calculation (Pass 2) for "Unskilled Cohort" flow.
- *
- * This metric calculates the "Net Crowd Flow Percentage" for the
- * "Unskilled Cohort" (bottom 20% by long-term skill score).
- *
- * This calculation *depends* on 'cohort-skill-definition'
- * to identify the cohort.
+ * @fileoverview GEM Product Line (Pass 2)
+ * --- FIX ---
+ * - Added defensive checks in '_loadDependencies' to prevent crash
+ * when dependencies fail to load (e.g., due to worker bug).
+ * - **FIXED:** Restored logic to calculate 'avg_position_change_pct'
+ * to resolve the hardcoded '0' value. This involves
+ * re-adding fields to '_initFlowData' and 'process'.
  */
-const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
-
 
 class UnskilledCohortFlow {
     constructor() {
-        this.assetData = new Map();
-        this.sectorData = new Map();
-        this.mappings = null;
-        this.unskilledCohortUserIds = null;
-    }
-
-    /**
-     * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
-     */
-    static getSchema() {
-        const flowSchema = {
-            "type": "object",
-            "properties": {
-                "net_flow_percentage": { "type": "number" },
-                "total_invested_today": { "type": "number" },
-                "total_invested_yesterday": { "type": "number" }
-            },
-            "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday"]
-        };
-
-        return {
-            "type": "object",
-            "description": "Calculates net capital flow % (price-adjusted) for the 'Unskilled Cohort' (bottom 20% by skill score), aggregated by asset and sector.",
-            "properties": {
-                "cohort_size": {
-                    "type": "number",
-                    "description": "The number of users identified as being in the Unskilled Cohort."
-                },
-                "assets": {
-                    "type": "object",
-                    "description": "Price-adjusted net flow per asset.",
-                    "patternProperties": { "^.*$": flowSchema }, // Ticker
-                    "additionalProperties": flowSchema
-                },
-                "sectors": {
-                    "type": "object",
-                    "description": "Price-adjusted net flow per sector.",
-                    "patternProperties": { "^.*$": flowSchema }, // Sector
-                    "additionalProperties": flowSchema
-                }
-            },
-            "required": ["cohort_size", "assets", "sectors"]
-        };
+        this.assetFlows = new Map();
+        this.cohortMap = new Map();
+        this.tickerMap = null;
+        this.dependenciesLoaded = false;
+        this.priceChangeMap = null; 
     }
 
-    /**
-     * Statically defines all metadata for the manifest builder.
-     */
     static getMetadata() {
         return {
             type: 'standard',
             rootDataDependencies: ['portfolio'],
-            isHistorical: true, // Compares today vs yesterday portfolio
+            isHistorical: true, 
             userType: 'all',
             category: 'gem'
         };
     }
 
-    /**
-     * Statically declare dependencies.
-     */
     static getDependencies() {
-        return ['cohort-skill-definition']; // Pass 1
+        return [
+            'cohort-skill-definition',     // from gem (Pass 1)
+            'instrument-price-change-1d' // from core (Pass 1)
+        ];
     }
 
-    _getPortfolioPositions(portfolio) {
-        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "net_flow_pct": { "type": "number" },
+                "net_flow_contribution": { "type": "number" },
+                "avg_position_change_pct": { "type": "number" },
+                "user_count": { "type": "number" }
+            },
+            "required": ["net_flow_pct", "net_flow_contribution", "avg_position_change_pct", "user_count"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates capital flow and conviction change for the 'Unskilled' cohort.",
+            "patternProperties": { "^.*$": tickerSchema },
+            "additionalProperties": tickerSchema
+        };
     }
 
-    _initAsset(instrumentId) {
-        if (!this.assetData.has(instrumentId)) {
-            this.assetData.set(instrumentId, {
-                total_invested_yesterday: 0,
-                total_invested_today: 0,
-                price_change_yesterday: 0,
-            });
-        }
+    _getPortfolioPositions(portfolio) {
+        // --- FIX: Support both Normal (Aggregated) and Speculator (Public) ---
+        return portfolio?.AggregatedPositions || portfolio?.PublicPositions;
     }
-    
-    _initSector(sector) {
-        if (!this.sectorData.has(sector)) {
-            this.sectorData.set(sector, {
+
+    // --- THIS IS THE FIX (Part 1) ---
+    _initFlowData(instrumentId) {
+        if (!this.assetFlows.has(instrumentId)) {
+            this.assetFlows.set(instrumentId, {
                 total_invested_yesterday: 0,
                 total_invested_today: 0,
                 price_change_yesterday: 0,
+                // Restore fields needed for avg_position_change_pct
+                total_pos_size_yesterday: 0, 
+                total_pos_size_today: 0, 
+                user_count_yesterday: 0, 
+                user_count_today: 0
             });
         }
     }
+    // --- END FIX (Part 1) ---
 
-    _getUnskilledCohort(fetchedDependencies) {
-        if (this.unskilledCohortUserIds) {
-            return this.unskilledCohortUserIds;
+    _loadDependencies(fetchedDependencies) {
+        if (this.dependenciesLoaded) return;
+
+        if (!fetchedDependencies) {
+            throw new Error(
+                `[unskilled-cohort-flow] CRITICAL ERROR: fetchedDependencies object was UNDEFINED. 
+                This means a dependency test (like 'cohort-skill-definition' or 'instrument-price-change-1d') 
+                failed to run or produced an invalid result.`
+            );
         }
-        
-        // FIX: Use normalized dependency name
+
         const cohortData = fetchedDependencies['cohort-skill-definition'];
-        if (!cohortData || !cohortData.unskilled_user_ids) {
-            return new Set();
+        if (!cohortData) {
+             throw new Error(
+                `[unskilled-cohort-flow] DEPENDENCY ERROR: 'cohort-skill-definition' was missing. 
+                Check logs for errors in that calculation.`
+             );
+        }
+
+        // This logic is correct for 'cohort-skill-definition' output
+        if (cohortData && cohortData.unskilled_user_ids) {
+            (cohortData.unskilled_user_ids || []).forEach(uid => this.cohortMap.set(String(uid), 'unskilled'));
         }
 
-        this.unskilledCohortUserIds = new Set(cohortData.unskilled_user_ids);
-        return this.unskilledCohortUserIds;
+        this.priceChangeMap = fetchedDependencies['instrument-price-change-1d'];
+        if (!this.priceChangeMap) {
+             throw new Error(
+                `[unskilled-cohort-flow] DEPENDENCY ERROR: 'instrument-price-change-1d' was missing. 
+                This is likely due to the worker bug for 'price' dependencies.`
+             );
+        }
+
+        this.dependenciesLoaded = true;
     }
 
+    // --- THIS IS THE FIX (Part 2) ---
     process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
-        const unskilledCohort = this._getUnskilledCohort(fetchedDependencies);
-        
-        if (!unskilledCohort.has(userId)) {
-            return; // This user is not in the "unskilled cohort", skip.
+        this._loadDependencies(fetchedDependencies);
+
+        if (!this.tickerMap) {
+            this.tickerMap = context.instrumentToTicker;
+        }
+
+        const cohortName = this.cohortMap.get(String(userId));
+        if (cohortName !== 'unskilled') {
+            return; // Not in unskilled cohort
         }
 
-        if (!todayPortfolio || !yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio || !this.priceChangeMap || !this.tickerMap) {
             return;
         }
 
-        // Logic from here is identical to smart-cohort-flow.js
         const yPos = this._getPortfolioPositions(yesterdayPortfolio);
         const tPos = this._getPortfolioPositions(todayPortfolio);
-        const yPosMap = new Map(yPos?.map(p => [p.InstrumentID, p]) || []);
-        const tPosMap = new Map(tPos?.map(p => [p.InstrumentID, p]) || []);
+        if (!yPos || !tPos) return;
+
+        const yPosMap = new Map(yPos.map(p => [p.InstrumentID, p]));
+        const tPosMap = new Map(tPos.map(p => [p.InstrumentID, p]));
         const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
-        
-        if (!this.mappings) {
-            this.mappings = context.mappings;
-        }
 
         for (const instrumentId of allInstrumentIds) {
             if (!instrumentId) continue;
-            
-            this._initAsset(instrumentId);
-            const asset = this.assetData.get(instrumentId);
+
+            this._initFlowData(instrumentId);
+            const asset = this.assetFlows.get(instrumentId);
+
             const yP = yPosMap.get(instrumentId);
             const tP = tPosMap.get(instrumentId);
+
+            // Get $ flow
+            const yInvested = yP?.Invested || yP?.Amount || 0; 
+            const tInvested = tP?.Invested || tP?.Amount || 0;
             
-            const yInvested = yP?.Invested || 0; 
-            const tInvested = tP?.Invested || 0;
-            
-            const sector = this.mappings.instrumentToSector[instrumentId] || 'Other';
-            this._initSector(sector);
-            const sectorAsset = this.sectorData.get(sector);
+            // Get position size (same as $ flow for these schemas)
+            const ySize = yP?.Invested || yP?.Amount || 0;
+            const tSize = tP?.Invested || tP?.Amount || 0;
 
             if (yInvested > 0) {
-                const yPriceChange = (yP?.NetProfit || 0) / (yP?.Invested || 1); 
-                
                 asset.total_invested_yesterday += yInvested;
-                asset.price_change_yesterday += yPriceChange * yInvested;
+
+                const ticker = this.tickerMap[instrumentId];
+                const yPriceChange_pct = (ticker && this.priceChangeMap[ticker]) 
+                                            ? this.priceChangeMap[ticker].price_change_1d_pct 
+                                            : 0;
+
+                const yPriceChange_decimal = (yPriceChange_pct || 0) / 100.0;
+                asset.price_change_yesterday += yPriceChange_decimal * yInvested;
                 
-                sectorAsset.total_invested_yesterday += yInvested;
-                sectorAsset.price_change_yesterday += yPriceChange * yInvested;
+                // Track yesterday's size and user count
+                asset.total_pos_size_yesterday += ySize;
+                asset.user_count_yesterday++;
             }
             if (tInvested > 0) {
                 asset.total_invested_today += tInvested;
-                sectorAsset.total_invested_today += tInvested;
-            }
-        }
-    }
-    
-    _calculateFlow(dataMap) {
-        // This helper is identical to the one in skilled-cohort-flow
-        const result = {};
-        for (const [key, data] of dataMap.entries()) {
-            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
-            
-            if (total_invested_yesterday > 0) {
-                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
-                const price_contribution = total_invested_yesterday * avg_price_change_pct;
-                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
-                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
+                asset.user_count_today++;
                 
-                result[key] = {
-                    net_flow_percentage: net_flow_percentage,
-                    total_invested_today: total_invested_today,
-                    total_invested_yesterday: total_invested_yesterday
-                };
+                // Track today's size
+                asset.total_pos_size_today += tSize;
             }
         }
-        return result;
     }
+    // --- END FIX (Part 2) ---
 
-    async getResult(fetchedDependencies) {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
+    // --- THIS IS THE FIX (Part 3) ---
+    async getResult() {
+        if (!this.tickerMap) {
+            return {}; 
         }
-        
-        const unskilledCohort = this._getUnskilledCohort(fetchedDependencies);
-
-        // 1. Calculate Asset Flow
-        const assetResult = {};
-        for (const [instrumentId, data] of this.assetData.entries()) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            const { total_invested_yesterday, total_invested_today, price_change_yesterday } = data;
-            
+
+        const finalResult = {};
+
+        for (const [instrumentId, data] of this.assetFlows.entries()) {
+            const ticker = this.tickerMap[instrumentId];
+            if (!ticker) continue;
+
+            const { 
+                total_invested_yesterday, total_invested_today, price_change_yesterday,
+                // Destructure the restored fields
+                total_pos_size_yesterday, total_pos_size_today,
+                user_count_yesterday, user_count_today
+            } = data;
+
+            let net_flow_percentage = 0;
+            let flow_contribution = 0;
+
             if (total_invested_yesterday > 0) {
-                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
-                const price_contribution = total_invested_yesterday * avg_price_change_pct;
-                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
-                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
-                
-                assetResult[ticker] = {
-                    net_flow_percentage: net_flow_percentage,
-                    total_invested_today: total_invested_today,
-                    total_invested_yesterday: total_invested_yesterday
+                const avg_price_change_decimal = (price_change_yesterday === 0) ? 0 : (price_change_yesterday / total_invested_yesterday);
+                const price_adjusted_yesterday_value = total_invested_yesterday * (1 + avg_price_change_decimal);
+
+                flow_contribution = total_invested_today - price_adjusted_yesterday_value;
+                net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
+            } else if (total_invested_today > 0) {
+                flow_contribution = total_invested_today;
+                net_flow_percentage = Infinity;
+            }
+
+            // Restore the calculation logic for conviction
+            let avg_position_change_pct = 0; 
+            if (user_count_yesterday > 0 && user_count_today > 0) {
+                const avg_pos_y = total_pos_size_yesterday / user_count_yesterday;
+                const avg_pos_t = total_pos_size_today / user_count_today;
+                if (avg_pos_y > 0) {
+                    avg_position_change_pct = ((avg_pos_t - avg_pos_y) / avg_pos_y) * 100;
+                }
+            } else if (user_count_today > 0) {
+                // Pure inflow, conviction is max
+                avg_position_change_pct = Infinity;
+            }
+
+            if (isFinite(net_flow_percentage) && isFinite(flow_contribution)) {
+                finalResult[ticker] = {
+                    net_flow_pct: net_flow_percentage,
+                    net_flow_contribution: flow_contribution,
+                    avg_position_change_pct: avg_position_change_pct, // Now correctly calculated
+                    user_count: user_count_today
                 };
             }
         }
-        
-        // 2. Calculate Sector Flow
-        const sectorResult = this._calculateFlow(this.sectorData);
 
-        return {
-            cohort_size: unskilledCohort.size,
-            assets: assetResult,
-            sectors: sectorResult
-        };
+        return finalResult;
     }
+    // --- END FIX (Part 3) ---
 
     reset() {
-        this.assetData.clear();
-        this.sectorData.clear();
-        this.mappings = null;
-        this.unskilledCohortUserIds = null;
+        this.assetFlows.clear();
+        this.cohortMap.clear();
+        this.tickerMap = null;
+        this.dependenciesLoaded = false;
+        this.priceChangeMap = null;
     }
 }
-
 module.exports = UnskilledCohortFlow;

package/calculations/helix/helix-contrarian-signal.js

@@ -1,20 +1,19 @@
 /**
  * @fileoverview HELIX Product Line (Pass 4)
  *
- * This metric answers: "What is the final HELIX contrarian signal?"
- *
- * It combines the 'Herd Consensus' with the 'Winner Cohort Flow'
- * to generate actionable signals.
- *
- * HYPOTHESIS:
- * - If Herd is in Euphoria (> +8) AND Winners are Selling = "Strong Sell"
- * - If Herd is in Capitulation (< -8) AND Winners are Buying = "Strong Buy"
+ * This is the final, stateless signal generator for the HELIX line.
+ * It answers: "Are 'Winners' (in-profit) and 'Losers'
+ * (in-loss) cohorts flowing in opposite directions?"
  */
 class HelixContrarianSignal {
 
+    // --- STANDARD 2: ADDED ---
+    constructor() {
+        this.result = {};
+    }
+
     /**
      * Defines the output schema for this calculation.
-     * @returns {object} JSON Schema object
      */
     static getSchema() {
         const tickerSchema = {
@@ -22,30 +21,22 @@ class HelixContrarianSignal {
             "properties": {
                 "signal": {
                     "type": "string",
-                    "enum": ["Capitulation (Strong Buy)", "Euphoria (Strong Sell)", "Confirmation (Buy)", "Confirmation (Sell)", "FOMO (Losers Buying)", "Panic (Losers Selling)", "Neutral"]
-                },
-                "consensus_score": {
-                    "type": "number",
-                    "description": "The Herd Consensus Score (-10 to +10)."
+                    "enum": ["Strong Contrarian", "Contrarian", "Neutral", "Consensus"]
                 },
-                "net_winner_flow": {
+                "helix_score": {
                     "type": "number",
-                    "description": "Net unique winners who joined/left the asset."
+                    "description": "Divergence score (-10 to +10). Positive = Contrarian (Winners sell, Losers buy), Negative = Consensus (Both buy/sell)."
                 },
-                "net_loser_flow": {
-                    "type": "number",
-                    "description": "Net unique losers who joined/left the asset."
-                }
+                "winner_net_flow": { "type": "number" },
+                "loser_net_flow": { "type": "number" }
             },
-            "required": ["signal", "consensus_score", "net_winner_flow", "net_loser_flow"]
+            "required": ["signal", "helix_score", "winner_net_flow", "loser_net_flow"]
         };
         
         return {
             "type": "object",
-            "description": "Generates final contrarian signals by comparing herd consensus to winner/loser cohort flows.",
-            "patternProperties": {
-                "^.*$": tickerSchema // Ticker
-            },
+            "description": "Generates a final contrarian signal based on Winner vs. Loser flow.",
+            "patternProperties": { "^.*$": tickerSchema },
             "additionalProperties": tickerSchema
         };
     }
@@ -68,86 +59,103 @@ class HelixContrarianSignal {
      */
     static getDependencies() {
         return [
-            'winner-loser-flow',    // from helix (Pass 2)
-            'herd-consensus-score'  // from helix (Pass 3)
+            'winner-loser-flow',     // from helix (Pass 2)
+            'herd-consensus-score'   // from helix (Pass 2)
         ];
     }
+    
+    /**
+     * Simple tanh normalization. Scales any number to a -10 to +10 range.
+     */
+    _normalize(score) {
+        // Scale input score to tune sensitivity
+        // A score of 50 will be ~9.9 (strong signal)
+        // A score of 20 will be ~9.6
+        // A score of 10 will be ~7.6
+        return Math.tanh(score / 10.0) * 10;
+    }
 
     /**
      * This is a 'meta' calculation. It runs once.
      */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
+    // --- STANDARD 1: UPDATED SIGNATURE (added rootData) ---
+    async process(dateStr, rootData, dependencies, config, fetchedDependencies) {
         const { logger } = dependencies;
         
-        const flowData = fetchedDependencies['winner-loser-flow'];
-        const consensusData = fetchedDependencies['herd-consensus-score'];
+        const cohortFlows = fetchedDependencies['winner-loser-flow'];
+        const herdConviction = fetchedDependencies['herd-consensus-score'];
 
-        if (!flowData || !consensusData) {
-            logger.log('WARN', `[helix/helix-contrarian-signal] Missing dependencies for ${dateStr}. Skipping.`);
-            return {};
+        if (!cohortFlows || !herdConviction) {
+            logger.log('WARN', `[helix/helix-contrarian-signal] Missing dependencies for ${dateStr}.`);
+            // --- STANDARD 2: DO NOT RETURN ---
+            this.result = {};
+            return;
         }
 
         const allTickers = new Set([
-            ...Object.keys(flowData),
-            ...Object.keys(consensusData)
+            ...Object.keys(cohortFlows),
+            ...Object.keys(herdConviction)
         ]);
-        
+
         const result = {};
-        const CONSENSUS_THRESHOLD = 8.0; // Score for "Extreme"
-        const FLOW_THRESHOLD = 5;      // Min 5 users moving
 
         for (const ticker of allTickers) {
-            const consensus = consensusData[ticker]?.consensus_score || 0;
-            const winner_flow = flowData[ticker]?.net_winner_flow || 0;
-            const loser_flow = flowData[ticker]?.net_loser_flow || 0;
-            
-            let signal = "Neutral";
+            const flow = cohortFlows[ticker];
+            const conviction = herdConviction[ticker];
 
-            // --- Primary Contrarian Signals ---
+            // 1. Get Winner Flow (using net_winner_flow)
+            const winner_flow = flow?.net_winner_flow || 0;
             
-            // 1. Capitulation: Herd is at extreme fear, but winners are buying.
-            if (consensus < -CONSENSUS_THRESHOLD && winner_flow > FLOW_THRESHOLD) {
-                signal = "Capitulation (Strong Buy)";
-            }
-            // 2. Euphoria: Herd is at extreme greed, but winners are selling.
-            else if (consensus > CONSENSUS_THRESHOLD && winner_flow < -FLOW_THRESHOLD) {
-                signal = "Euphoria (Strong Sell)";
-            }
-            
-            // --- Secondary Confirmation Signals ---
+            // 2. Get Loser Flow (using herd_conviction_score)
+            // This is a proxy for "Loser Flow".
+            // If conviction > 0, losers are buying.
+            // If conviction < 0, losers are selling.
+            const loser_flow = conviction?.herd_conviction_score || 0;
+
+            // --- Signal Logic ---
+            // A contrarian signal (positive score) happens when:
+            // 1. Winners SELL (flow < 0) and Losers BUY (flow > 0)
+            //
+            // A consensus signal (negative score) happens when:
+            // 2. Winners BUY (flow > 0) and Losers BUY (flow > 0)
+            // 3. Winners SELL (flow < 0) and Losers SELL (flow < 0)
             
-            // 3. Confirmation (Buy): Herd is bullish, winners are also buying.
-            else if (consensus > 0 && winner_flow > FLOW_THRESHOLD) {
-                signal = "Confirmation (Buy)";
-            }
-            // 4. Confirmation (Sell): Herd is bearish, winners are also selling.
-            else if (consensus < 0 && winner_flow < -FLOW_THRESHOLD) {
-                signal = "Confirmation (Sell)";
-            }
-
-            // --- Tertiary "Dumb Money" Signals (Warning signs) ---
+            // We can simplify this:
+            // Score = Loser Flow - Winner Flow
+            //
+            // Case 1: Loser (Buy, +50) - Winner (Sell, -20) = +70 (Strong Contrarian)
+            // Case 2: Loser (Buy, +50) - Winner (Buy, +20)  = +30 (Weak Contrarian)
+            // Case 3: Loser (Sell, -50) - Winner (Sell, -20) = -30 (Consensus)
+            // Case 4: Loser (Sell, -50) - Winner (Buy, +20)  = -70 (Strong Consensus)
             
-            // 5. FOMO: Herd is euphoric, and losers are piling in.
-            else if (consensus > CONSENSUS_THRESHOLD && loser_flow > FLOW_THRESHOLD) {
-                signal = "FOMO (Losers Buying)";
-            }
-            // 6. Panic: Herd is fearful, and losers are capitulating.
-            else if (consensus < -CONSENSUS_THRESHOLD && loser_flow < -FLOW_THRESHOLD) {
-                signal = "Panic (Losers Selling)";
-            }
-
-            // Add to result if not neutral
-            if (signal !== "Neutral") {
-                result[ticker] = {
-                    signal: signal,
-                    consensus_score: consensus,
-                    net_winner_flow: winner_flow,
-                    net_loser_flow: loser_flow
-                };
-            }
+            const divergence = loser_flow - winner_flow;
+            const helix_score = this._normalize(divergence);
+
+            let signal = "Neutral";
+            if (helix_score > 7.5) signal = "Strong Contrarian"; // Losers buying, Winners selling
+            else if (helix_score > 2.5) signal = "Contrarian";
+            else if (helix_score < -2.5) signal = "Consensus"; // Both moving same way
+
+            result[ticker] = {
+                signal: signal,
+                helix_score: helix_score,
+                winner_net_flow: winner_flow,
+                loser_net_flow: loser_flow // Using conviction as flow proxy
+            };
         }
         
-        return result;
+        // --- STANDARD 2: SET STATE, DO NOT RETURN ---
+        this.result = result;
+    }
+
+    // --- STANDARD 2: ADDED ---
+    async getResult(fetchedDependencies) {
+        return this.result;
+    }
+
+    // --- STANDARD 2: ADDED ---
+    reset() {
+        this.result = {};
     }
 }