aiden-shared-calculations-unified 1.0.75 → 1.0.77

package/calculations/gauss/gauss-divergence-signal.js

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview GAUSS Product Line (Pass 4)
+ *
+ * This is the final, stateless signal generator for the Gauss line.
+ * It answers: "What is the net 'Smart vs. Dumb' flow divergence?"
+ *
+ * It consumes the daily flows from all defined cohorts (Pass 3)
+ * and aggregates them into a final, actionable signal.
+ */
+class GaussDivergenceSignal {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "signal": {
+                    "type": "string",
+                    "enum": ["Strong Buy", "Buy", "Neutral", "Sell", "Strong Sell"]
+                },
+                "gauss_score": {
+                    "type": "number",
+                    "description": "Final divergence score (-10 to +10). Positive = Smart Buying, Negative = Smart Selling."
+                },
+                "smart_flow_total_pct": {
+                    "type": "number",
+                    "description": "The total %-point flow from all 'Smart' cohorts."
+                },
+                "dumb_flow_total_pct": {
+                    "type": "number",
+                    "description": "The total %-point flow from all 'Dumb' cohorts."
+                }
+            },
+            "required": ["signal", "gauss_score", "smart_flow_total_pct", "dumb_flow_total_pct"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Generates a final divergence signal by aggregating flow from Smart vs. Dumb cohorts.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'gauss'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'cohort-capital-flow' // from gauss (Pass 3)
+        ];
+    }
+    
+    /**
+     * Simple tanh normalization. Scales any number to a -10 to +10 range,
+     * with diminishing returns for extreme values.
+     * 0 -> 0, 1 -> 7.6, 2 -> 9.6, 3 -> 9.95
+     * We scale the input to tune sensitivity.
+     */
+    _normalize(score) {
+        // A score of 2.0 (%-point flow) will be ~9.6
+        // A score of 1.0 (%-point flow) will be ~7.6
+        return Math.tanh(score / 2.0) * 10;
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        
+        const cohortFlows = fetchedDependencies['cohort-capital-flow'];
+
+        if (!cohortFlows) {
+            logger.log('WARN', `[gauss/gauss-divergence-signal] Missing dependency 'cohort-capital-flow' for ${dateStr}.`);
+            return {};
+        }
+
+        // Define which cohorts are "Smart" and which are "Dumb"
+        // These names must match the keys from Pass 2
+        const SMART_COHORTS = ['smart_investors', 'smart_scalpers'];
+        const DUMB_COHORTS = ['fomo_chasers', 'patient_losers', 'fomo_bagholders'];
+        
+        const blendedFlows = new Map(); // Map<ticker, { smart: 0, dumb: 0 }>
+
+        // 1. Blend all cohort flows into two buckets
+        for (const cohortName in cohortFlows) {
+            const isSmart = SMART_COHORTS.includes(cohortName);
+            const isDumb = DUMB_COHORTS.includes(cohortName);
+            if (!isSmart && !isDumb) continue;
+
+            const assets = cohortFlows[cohortName]?.assets;
+            if (!assets) continue;
+            
+            for (const [ticker, data] of Object.entries(assets)) {
+                if (!blendedFlows.has(ticker)) {
+                    blendedFlows.set(ticker, { smart: 0, dumb: 0 });
+                }
+                
+                // Use net_flow_contribution, which is the %-point flow
+                const flow = data.net_flow_contribution || 0; 
+                
+                if (isSmart) {
+                    blendedFlows.get(ticker).smart += flow;
+                } else if (isDumb) {
+                    blendedFlows.get(ticker).dumb += flow;
+                }
+            }
+        }
+
+        // 2. Calculate final signal
+        const result = {};
+        for (const [ticker, data] of blendedFlows.entries()) {
+        
+            // The core signal is the divergence: (Smart Flow - Dumb Flow)
+            // If Smart buys (+1) and Dumb sells (-1), score is +2.
+            // If Smart sells (-1) and Dumb buys (+1), score is -2.
+            const divergence = data.smart - data.dumb;
+            
+            // Normalize the score to a -10 to +10 range
+            const gauss_score = this._normalize(divergence);
+            
+            let signal = "Neutral";
+            if (gauss_score > 7.0) signal = "Strong Buy";  // e.g., > 1.5% net divergence
+            else if (gauss_score > 2.0) signal = "Buy";
+            else if (gauss_score < -7.0) signal = "Strong Sell";
+            else if (gauss_score < -2.0) signal = "Sell";
+            
+            result[ticker] = {
+                signal: signal,
+                gauss_score: gauss_score,
+                smart_flow_total_pct: data.smart,
+                dumb_flow_total_pct: data.dumb
+            };
+        }
+        
+        // Final output is compact and non-sharded.
+        return result;
+    }
+}
+
+module.exports = GaussDivergenceSignal;

package/calculations/{meta/gem_cohort-momentum-state.js → gem/cohort-momentum-state.js}

@@ -48,14 +48,27 @@ class CohortMomentumState {
         };
     }
 
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'gem'
+        };
+    }
+
     /**
      * Statically declare dependencies.
      */
     static getDependencies() {
         return [
-            'gem_skilled-cohort-flow',       // Pass 2
-            'gem_unskilled-cohort-flow',     // Pass 2
-            'gem_instrument-price-momentum'  // Pass 1
+            'skilled-cohort-flow',       // Pass 2 (gem)
+            'unskilled-cohort-flow',     // Pass 2 (gem)
+            'instrument-price-momentum-20d'  // Pass 1 (core)
         ];
     }
 
@@ -68,9 +81,10 @@ class CohortMomentumState {
      * @param {object} fetchedDependencies - Results from previous passes.
      */
     getResult(fetchedDependencies) {
-        const skilledFlowData = fetchedDependencies['gem_skilled-cohort-flow']?.assets;
-        const unskilledFlowData = fetchedDependencies['gem_unskilled-cohort-flow']?.assets;
-        const momentumData = fetchedDependencies['gem_instrument-price-momentum'];
+        // FIX: Use normalized dependency names
+        const skilledFlowData = fetchedDependencies['skilled-cohort-flow']?.assets;
+        const unskilledFlowData = fetchedDependencies['unskilled-cohort-flow']?.assets;
+        const momentumData = fetchedDependencies['instrument-price-momentum-20d'];
 
         if (!skilledFlowData || !unskilledFlowData || !momentumData) {
             return {};
@@ -79,7 +93,8 @@ class CohortMomentumState {
         const result = {};
         const allTickers = new Set([
             ...Object.keys(skilledFlowData),
-            ...Object.keys(unskilledFlowData)
+            ...Object.keys(unskilledFlowData),
+            ...Object.keys(momentumData) // Include momentum tickers
         ]);
 
         for (const ticker of allTickers) {

package/calculations/{behavioural/historical/gem_cohort-skill-definition.js → gem/cohort-skill-definition.js}

@@ -39,6 +39,19 @@ class CohortSkillDefinition {
         };
     }
 
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['history'], // This calculation uses history data
+            isHistorical: false, // It processes today's history doc
+            userType: 'all',
+            category: 'gem'
+        };
+    }
+    
     /**
      * This is a Pass 1 calculation and has no dependencies.
      */
@@ -52,7 +65,11 @@ class CohortSkillDefinition {
      * @param {string} userId - The user ID.
      */
     process(rootData, userId) {
-        const history = rootData?.history?.all;
+        // FIX: The process signature for a 'standard' calc is different.
+        // It receives (todayPortfolio, yesterdayPortfolio, userId, context, ...)
+        // The 'history' data is inside todayPortfolio.
+        
+        const history = rootData?.history?.all; // Correctly accessing history data
         if (!history) {
             return; // Skip user if they have no history data
         }

package/calculations/{sentiment/gem_platform-conviction-divergence.js → gem/platform-conviction-divergence.js}

@@ -51,6 +51,19 @@ class PlatformConvictionDivergence {
         };
     }
 
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio', 'insights'],
+            isHistorical: false,
+            userType: 'all',
+            category: 'gem'
+        };
+    }
+
     /**
      * This is a Pass 1 calculation and has no dependencies.
      */

package/calculations/{meta/gem_quant-skill-alpha-signal.js → gem/quant-skill-alpha-signal.js}

@@ -54,16 +54,32 @@ class QuantSkillAlphaSignal {
             "additionalProperties": tickerSchema
         };
     }
+    
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'gem'
+        };
+    }
 
     /**
      * Statically declare dependencies.
      */
     static getDependencies() {
         return [
-            'gem_skilled-unskilled-divergence',    // Pass 3
-            'gem_cohort-momentum-state',         // Pass 3
-            'gem_platform-conviction-divergence',  // Pass 1
-            'gem_social_sentiment_aggregation'     // Pass 1
+            // Internal 'gem' dependencies (normalized)
+            'skilled-unskilled-divergence',
+            'cohort-momentum-state',
+            'platform-conviction-divergence',
+            
+            // Dependencies on 'core' product line (normalized)
+            'social-sentiment-aggregation'
         ];
     }
 
@@ -76,10 +92,11 @@ class QuantSkillAlphaSignal {
      * @param {object} fetchedDependencies - Results from previous passes.
      */
     getResult(fetchedDependencies) {
-        const divergenceData = fetchedDependencies['gem_skilled-unskilled-divergence']?.assets;
-        const momentumData = fetchedDependencies['gem_cohort-momentum-state'];
-        const platformData = fetchedDependencies['gem_platform-conviction-divergence'];
-        const socialData = fetchedDependencies['gem_social_sentiment_aggregation']?.per_ticker;
+        // FIX: Use normalized dependency names
+        const divergenceData = fetchedDependencies['skilled-unskilled-divergence']?.assets;
+        const momentumData = fetchedDependencies['cohort-momentum-state'];
+        const platformData = fetchedDependencies['platform-conviction-divergence'];
+        const socialData = fetchedDependencies['social-sentiment-aggregation']?.per_ticker;
 
         if (!divergenceData || !momentumData || !platformData || !socialData) {
             return {}; // Missing one or more key dependencies

package/calculations/{behavioural/historical/gem_skilled-cohort-flow.js → gem/skilled-cohort-flow.js}

@@ -57,11 +57,24 @@ class SkilledCohortFlow {
         };
     }
 
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio'],
+            isHistorical: true, // Compares today vs yesterday portfolio
+            userType: 'all',
+            category: 'gem'
+        };
+    }
+
     /**
      * Statically declare dependencies.
      */
     static getDependencies() {
-        return ['gem_cohort-skill-definition']; // Pass 1
+        return ['cohort-skill-definition']; // Pass 1
     }
 
     _getPortfolioPositions(portfolio) {
@@ -93,7 +106,8 @@ class SkilledCohortFlow {
             return this.skilledCohortUserIds;
         }
         
-        const cohortData = fetchedDependencies['gem_cohort-skill-definition'];
+        // FIX: Use normalized dependency name
+        const cohortData = fetchedDependencies['cohort-skill-definition'];
         if (!cohortData || !cohortData.skilled_user_ids) {
             return new Set();
         }

package/calculations/{meta/gem_skilled-unskilled-divergence.js → gem/skilled-unskilled-divergence.js}

@@ -51,13 +51,26 @@ class SkilledUnskilledDivergence {
         };
     }
 
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'gem'
+        };
+    }
+
     /**
      * Statically declare dependencies.
      */
     static getDependencies() {
         return [
-            'gem_skilled-cohort-flow', // Pass 2
-            'gem_unskilled-cohort-flow'   // Pass 2
+            'skilled-cohort-flow', // Pass 2
+            'unskilled-cohort-flow'   // Pass 2
         ];
     }
 
@@ -119,8 +132,9 @@ class SkilledUnskilledDivergence {
      * @param {object} fetchedDependencies - Results from Pass 2.
      */
     getResult(fetchedDependencies) {
-        const skilledFlowData = fetchedDependencies['gem_skilled-cohort-flow'];
-        const unskilledFlowData = fetchedDependencies['gem_unskilled-cohort-flow'];
+        // FIX: Use normalized dependency names
+        const skilledFlowData = fetchedDependencies['skilled-cohort-flow'];
+        const unskilledFlowData = fetchedDependencies['unskilled-cohort-flow'];
 
         const assetResult = this._calculateDivergence(skilledFlowData?.assets, unskilledFlowData?.assets);
         const sectorResult = this._calculateDivergence(skilledFlowData?.sectors, unskilledFlowData?.sectors);

package/calculations/{behavioural/historical/gem_unskilled-cohort-flow.js → gem/unskilled-cohort-flow.js}

@@ -57,11 +57,24 @@ class UnskilledCohortFlow {
         };
     }
 
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'standard',
+            rootDataDependencies: ['portfolio'],
+            isHistorical: true, // Compares today vs yesterday portfolio
+            userType: 'all',
+            category: 'gem'
+        };
+    }
+
     /**
      * Statically declare dependencies.
      */
     static getDependencies() {
-        return ['gem_cohort-skill-definition']; // Pass 1
+        return ['cohort-skill-definition']; // Pass 1
     }
 
     _getPortfolioPositions(portfolio) {
@@ -93,7 +106,8 @@ class UnskilledCohortFlow {
             return this.unskilledCohortUserIds;
         }
         
-        const cohortData = fetchedDependencies['gem_cohort-skill-definition'];
+        // FIX: Use normalized dependency name
+        const cohortData = fetchedDependencies['cohort-skill-definition'];
         if (!cohortData || !cohortData.unskilled_user_ids) {
             return new Set();
         }

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

@@ -0,0 +1,154 @@
+/**
+ * @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"
+ */
+class HelixContrarianSignal {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "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)."
+                },
+                "net_winner_flow": {
+                    "type": "number",
+                    "description": "Net unique winners who joined/left the asset."
+                },
+                "net_loser_flow": {
+                    "type": "number",
+                    "description": "Net unique losers who joined/left the asset."
+                }
+            },
+            "required": ["signal", "consensus_score", "net_winner_flow", "net_loser_flow"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Generates final contrarian signals by comparing herd consensus to winner/loser cohort flows.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [],
+            isHistorical: false,
+            userType: 'n/a',
+            category: 'helix'
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'winner-loser-flow',    // from helix (Pass 2)
+            'herd-consensus-score'  // from helix (Pass 3)
+        ];
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger } = dependencies;
+        
+        const flowData = fetchedDependencies['winner-loser-flow'];
+        const consensusData = fetchedDependencies['herd-consensus-score'];
+
+        if (!flowData || !consensusData) {
+            logger.log('WARN', `[helix/helix-contrarian-signal] Missing dependencies for ${dateStr}. Skipping.`);
+            return {};
+        }
+
+        const allTickers = new Set([
+            ...Object.keys(flowData),
+            ...Object.keys(consensusData)
+        ]);
+        
+        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";
+
+            // --- Primary Contrarian Signals ---
+            
+            // 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 ---
+            
+            // 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) ---
+            
+            // 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
+                };
+            }
+        }
+        
+        return result;
+    }
+}
+
+module.exports = HelixContrarianSignal;