aiden-shared-calculations-unified 1.0.72 → 1.0.73

package/calculations/behavioural/historical/asset_crowd_flow.js

@@ -102,8 +102,8 @@ class AssetCrowdFlow {
             const yP = yPosMap.get(instrumentId);
             const tP = tPosMap.get(instrumentId);
 
-            const yInvested = yP?.InvestedAmount || yP?.Amount || 0;
-            const tInvested = tP?.InvestedAmount || tP?.Amount || 0;
+            const yInvested = yP?.Invested || 0;
+            const tInvested = tP?.Invested || 0;
 
             if (yInvested > 0) {
                 asset.total_invested_yesterday += yInvested;

package/calculations/behavioural/historical/gem_cohort-skill-definition.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Calculation (Pass 1) for defining skill-based cohorts.
+ *
+ * This metric calculates a long-term "Skill Score" for each user based on
+ * their closed trade history (win rate, profit/loss ratio, and trade count).
+ *
+ * To remain compact, it processes all users, ranks them, and returns
+ * only the list of user IDs for the top and bottom 20% cohorts.
+ */
+class CohortSkillDefinition {
+    constructor() {
+        // { userId: { skill_score: 12.3 } }
+        this.userScores = new Map();
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Provides the user ID lists for the 'Skilled' (top 20%) and 'Unskilled' (bottom 20%) cohorts based on historical trade performance.",
+            "properties": {
+                "skilled_user_ids": {
+                    "type": "array",
+                    "description": "List of user IDs in the top 20% 'Skilled' cohort.",
+                    "items": { "type": "string" }
+                },
+                "unskilled_user_ids": {
+                    "type": "array",
+                    "description": "List of user IDs in the bottom 20% 'Unskilled' cohort.",
+                    "items": { "type": "string" }
+                },
+                "skilled_cohort_size": { "type": "number" },
+                "unskilled_cohort_size": { "type": "number" }
+            },
+            "required": ["skilled_user_ids", "unskilled_user_ids", "skilled_cohort_size", "unskilled_cohort_size"]
+        };
+    }
+
+    /**
+     * This is a Pass 1 calculation and has no dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+
+    /**
+     * Process data from the 'history' root data source.
+     * @param {object} rootData - The root data object from the runner.
+     * @param {string} userId - The user ID.
+     */
+    process(rootData, userId) {
+        const history = rootData?.history?.all;
+        if (!history) {
+            return; // Skip user if they have no history data
+        }
+
+        const { winRatio, avgProfitPct, avgLossPct, totalTrades } = history;
+
+        if (!totalTrades || totalTrades < 10) {
+            return; // Skip users with too few trades for a reliable score
+        }
+
+        // Calculate Expectancy: (Win % * Avg Win %) - (Loss % * Avg Loss %)
+        const winRate = winRatio / 100.0;
+        const lossRate = 1.0 - winRate;
+        const avgWin = avgProfitPct; // Already in %
+        const avgLoss = Math.abs(avgLossPct); // Already in %
+        
+        // This score is "percentage points gained per trade"
+        const expectancy = (winRate * avgWin) - (lossRate * avgLoss);
+        
+        // Weight by log(trades) to value experience, clamped to avoid log(0)
+        const skillScore = expectancy * Math.log10(Math.max(1, totalTrades));
+
+        if (isFinite(skillScore)) {
+            this.userScores.set(userId, skillScore);
+        }
+    }
+
+    getResult() {
+        const sortedUsers = Array.from(this.userScores.entries())
+            // Sort descending by skill score
+            .sort((a, b) => b[1] - a[1]);
+
+        const cohortSize = Math.floor(sortedUsers.length * 0.20);
+        if (cohortSize === 0) {
+            return { skilled_user_ids: [], unskilled_user_ids: [], skilled_cohort_size: 0, unskilled_cohort_size: 0 };
+        }
+
+        const skilled_user_ids = sortedUsers.slice(0, cohortSize).map(u => u[0]);
+        const unskilled_user_ids = sortedUsers.slice(-cohortSize).map(u => u[0]);
+
+        return {
+            skilled_user_ids: skilled_user_ids,
+            unskilled_user_ids: unskilled_user_ids,
+            skilled_cohort_size: skilled_user_ids.length,
+            unskilled_cohort_size: unskilled_user_ids.length
+        };
+    }
+
+    reset() {
+        this.userScores.clear();
+    }
+}
+
+module.exports = CohortSkillDefinition;

package/calculations/behavioural/historical/gem_skilled-cohort-flow.js

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Calculation (Pass 2) for "Skilled Cohort" flow.
+ *
+ * This metric calculates the "Net Crowd Flow Percentage" for the
+ * "Skilled Cohort" (top 20% by long-term skill score).
+ *
+ * This calculation *depends* on 'cohort-skill-definition'
+ * to identify the cohort.
+ */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+class SkilledCohortFlow {
+    constructor() {
+        this.assetData = new Map();
+        this.sectorData = new Map();
+        this.mappings = null;
+        this.skilledCohortUserIds = 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 'Skilled Cohort' (top 20% by skill score), aggregated by asset and sector.",
+            "properties": {
+                "cohort_size": {
+                    "type": "number",
+                    "description": "The number of users identified as being in the Skilled 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"]
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['gem_cohort-skill-definition']; // Pass 1
+    }
+
+    _getPortfolioPositions(portfolio) {
+        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assetData.has(instrumentId)) {
+            this.assetData.set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+            });
+        }
+    }
+    
+    _initSector(sector) {
+        if (!this.sectorData.has(sector)) {
+            this.sectorData.set(sector, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+            });
+        }
+    }
+
+    _getSkilledCohort(fetchedDependencies) {
+        if (this.skilledCohortUserIds) {
+            return this.skilledCohortUserIds;
+        }
+        
+        const cohortData = fetchedDependencies['cohort-skill-definition'];
+        if (!cohortData || !cohortData.skilled_user_ids) {
+            return new Set();
+        }
+
+        this.skilledCohortUserIds = new Set(cohortData.skilled_user_ids);
+        return this.skilledCohortUserIds;
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        const skilledCohort = this._getSkilledCohort(fetchedDependencies);
+        
+        if (!skilledCohort.has(userId)) {
+            return; // This user is not in the "skilled cohort", skip.
+        }
+
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            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]) || []);
+        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);
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
+            
+            // Use 'Invested' for % portfolio, not 'Amount'
+            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);
+
+            if (yInvested > 0) {
+                // Use P&L % from portfolio 'NetProfit'
+                const yPriceChange = (yP?.NetProfit || 0) / (yP?.Invested || 1); 
+                
+                asset.total_invested_yesterday += yInvested;
+                asset.price_change_yesterday += yPriceChange * yInvested;
+                
+                sectorAsset.total_invested_yesterday += yInvested;
+                sectorAsset.price_change_yesterday += yPriceChange * yInvested;
+            }
+            if (tInvested > 0) {
+                asset.total_invested_today += tInvested;
+                sectorAsset.total_invested_today += tInvested;
+            }
+        }
+    }
+    
+    _calculateFlow(dataMap) {
+        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;
+                
+                result[key] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday
+                };
+            }
+        }
+        return result;
+    }
+
+    async getResult(fetchedDependencies) {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+        
+        const skilledCohort = this._getSkilledCohort(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;
+            
+            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
+                };
+            }
+        }
+        
+        // 2. Calculate Sector Flow
+        const sectorResult = this._calculateFlow(this.sectorData);
+
+        return {
+            cohort_size: skilledCohort.size,
+            assets: assetResult,
+            sectors: sectorResult
+        };
+    }
+
+    reset() {
+        this.assetData.clear();
+        this.sectorData.clear();
+        this.mappings = null;
+        this.skilledCohortUserIds = null;
+    }
+}
+
+module.exports = SkilledCohortFlow;

package/calculations/behavioural/historical/gem_unskilled-cohort-flow.js

@@ -0,0 +1,225 @@
+/**
+ * @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.
+ */
+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"]
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['gem_cohort-skill-definition']; // Pass 1
+    }
+
+    _getPortfolioPositions(portfolio) {
+        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assetData.has(instrumentId)) {
+            this.assetData.set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+            });
+        }
+    }
+    
+    _initSector(sector) {
+        if (!this.sectorData.has(sector)) {
+            this.sectorData.set(sector, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+            });
+        }
+    }
+
+    _getUnskilledCohort(fetchedDependencies) {
+        if (this.unskilledCohortUserIds) {
+            return this.unskilledCohortUserIds;
+        }
+        
+        const cohortData = fetchedDependencies['cohort-skill-definition'];
+        if (!cohortData || !cohortData.unskilled_user_ids) {
+            return new Set();
+        }
+
+        this.unskilledCohortUserIds = new Set(cohortData.unskilled_user_ids);
+        return this.unskilledCohortUserIds;
+    }
+
+    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.
+        }
+
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            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]) || []);
+        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);
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
+            
+            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);
+
+            if (yInvested > 0) {
+                const yPriceChange = (yP?.NetProfit || 0) / (yP?.Invested || 1); 
+                
+                asset.total_invested_yesterday += yInvested;
+                asset.price_change_yesterday += yPriceChange * yInvested;
+                
+                sectorAsset.total_invested_yesterday += yInvested;
+                sectorAsset.price_change_yesterday += yPriceChange * yInvested;
+            }
+            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;
+                
+                result[key] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday
+                };
+            }
+        }
+        return result;
+    }
+
+    async getResult(fetchedDependencies) {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+        
+        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;
+            
+            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
+                };
+            }
+        }
+        
+        // 2. Calculate Sector Flow
+        const sectorResult = this._calculateFlow(this.sectorData);
+
+        return {
+            cohort_size: unskilledCohort.size,
+            assets: assetResult,
+            sectors: sectorResult
+        };
+    }
+
+    reset() {
+        this.assetData.clear();
+        this.sectorData.clear();
+        this.mappings = null;
+        this.unskilledCohortUserIds = null;
+    }
+}
+
+module.exports = UnskilledCohortFlow;

package/calculations/meta/gem_cohort-momentum-state.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Calculation (Pass 3) for cohort momentum state.
+ *
+ * This metric answers: "Are the 'Skilled' and 'Unskilled' cohorts
+ * trend-following or acting as contrarians?"
+ *
+ * It multiplies cohort flow by price momentum.
+ * - High positive score = Buying into a rally (FOMO)
+ * - High negative score = Buying into a dip, or Selling into a rally
+ *
+ * It *depends* on Pass 2 cohort flows and Pass 1 price momentum.
+ */
+class CohortMomentumState {
+    constructor() {
+        // No per-user processing
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "skilled_momentum_score": {
+                    "type": "number",
+                    "description": "Skilled Flow % * 20d Momentum %. High positive = trend-following."
+                },
+                "unskilled_momentum_score": {
+                    "type": "number",
+                    "description": "Unskilled Flow % * 20d Momentum %. High positive = trend-following (FOMO)."
+                },
+                "skilled_flow_pct": { "type": "number" },
+                "unskilled_flow_pct": { "type": "number" },
+                "momentum_20d_pct": { "type": ["number", "null"] }
+            },
+            "required": ["skilled_momentum_score", "unskilled_momentum_score"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates a momentum-following score for Skilled and Unskilled cohorts.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'gem_skilled-cohort-flow',       // Pass 2
+            'gem_unskilled-cohort-flow',     // Pass 2
+            'gem_instrument-price-momentum'  // Pass 1
+        ];
+    }
+
+    process() {
+        // No-op
+    }
+
+    /**
+     * This is a 'meta' calculation.
+     * @param {object} fetchedDependencies - Results from previous passes.
+     */
+    getResult(fetchedDependencies) {
+        const skilledFlowData = fetchedDependencies['skilled-cohort-flow']?.assets;
+        const unskilledFlowData = fetchedDependencies['unskilled-cohort-flow']?.assets;
+        const momentumData = fetchedDependencies['instrument-price-momentum'];
+
+        if (!skilledFlowData || !unskilledFlowData || !momentumData) {
+            return {};
+        }
+
+        const result = {};
+        const allTickers = new Set([
+            ...Object.keys(skilledFlowData),
+            ...Object.keys(unskilledFlowData)
+        ]);
+
+        for (const ticker of allTickers) {
+            const sFlow = skilledFlowData[ticker]?.net_flow_percentage || 0;
+            const uFlow = unskilledFlowData[ticker]?.net_flow_percentage || 0;
+            const mom = momentumData[ticker]?.momentum_20d_pct || 0;
+
+            const skilled_momentum_score = sFlow * mom;
+            const unskilled_momentum_score = uFlow * mom;
+            
+            result[ticker] = {
+                skilled_momentum_score: skilled_momentum_score,
+                unskilled_momentum_score: unskilled_momentum_score,
+                skilled_flow_pct: sFlow,
+                unskilled_flow_pct: uFlow,
+                momentum_20d_pct: mom
+            };
+        }
+        
+        return result;
+    }
+
+    reset() {
+        // No state
+    }
+}
+
+module.exports = CohortMomentumState;

package/calculations/meta/gem_instrument-price-momentum.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Calculation (Pass 1 - Meta) for 20-day price momentum.
+ *
+ * This metric answers: "What is the 20-day percentage price change for
+ * every instrument?"
+ *
+ * It is a 'meta' calculation that runs once, loads all price data,
+ * and provides a reusable momentum signal for downstream passes.
+ */
+const { loadAllPriceData } = require('../../utils/price_data_provider');
+
+class InstrumentPriceMomentum {
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "momentum_20d_pct": {
+                    "type": ["number", "null"],
+                    "description": "The 20-day rolling price change percentage."
+                }
+            },
+            "required": ["momentum_20d_pct"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates the 20-day price momentum for all instruments.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * This is a Pass 1 calculation and has no dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+    
+    // Helper to get date string N days ago
+    _getDateStr(baseDateStr, daysOffset) {
+        const date = new Date(baseDateStr + 'T00:00:00Z');
+        date.setUTCDate(date.getUTCDate() + daysOffset);
+        return date.toISOString().slice(0, 10);
+    }
+    
+    // Helper to find the last available price on or before a date
+    _findPrice(priceHistory, dateStr, maxLookback = 5) {
+        if (!priceHistory) return null;
+        let checkDate = new Date(dateStr + 'T00:00:00Z');
+        for (let i = 0; i < maxLookback; i++) {
+            const checkDateStr = checkDate.toISOString().slice(0, 10);
+            const price = priceHistory[checkDateStr];
+            if (price !== undefined && price !== null && price > 0) {
+                return price;
+            }
+            checkDate.setUTCDate(checkDate.getUTCDate() - 1);
+        }
+        return null;
+    }
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} dependencies - The shared dependencies (e.g., logger, calculationUtils).
+     * @param {object} config - The computation system configuration.
+     * @param {object} fetchedDependencies - (Unused)
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, dependencies, config, fetchedDependencies) {
+        const { logger, calculationUtils, mappings } = dependencies;
+        
+        // Load all price data and mappings
+        const priceMap = await loadAllPriceData();
+        const tickerMap = await calculationUtils.loadInstrumentMappings();
+        
+        if (!priceMap || !tickerMap || !tickerMap.instrumentToTicker) {
+            logger.log('ERROR', '[instrument-price-momentum] Failed to load priceMap or mappings.');
+            return {};
+        }
+
+        const dateStrT20 = this._getDateStr(dateStr, -20);
+        const result = {};
+
+        for (const instrumentId in priceMap) {
+            const instrumentPrices = priceMap[instrumentId];
+            const ticker = tickerMap.instrumentToTicker[instrumentId];
+            
+            if (!ticker) continue; // Skip if we can't map ID to ticker
+
+            const priceT = this._findPrice(instrumentPrices, dateStr);
+            const priceT20 = this._findPrice(instrumentPrices, dateStrT20);
+
+            let momentum = null;
+            if (priceT && priceT20 && priceT20 > 0) {
+                momentum = ((priceT - priceT20) / priceT20) * 100; // As percentage
+            }
+
+            result[ticker] = {
+                momentum_20d_pct: momentum
+            };
+        }
+        
+        return result;
+    }
+}
+
+module.exports = InstrumentPriceMomentum;

package/calculations/meta/gem_skilled-unskilled-divergence.js

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Calculation (Pass 3) for skilled-unskilled divergence.
+ *
+ * This metric answers: "What divergence signals (e.g., capitulation,
+ * euphoria) can be found by comparing the net asset and sector flow
+ * of the 'Skilled Cohort' vs. the 'Unskilled Cohort'?"
+ *
+ * It *depends* on 'skilled-cohort-flow' and 'unskilled-cohort-flow'.
+ */
+class SkilledUnskilledDivergence {
+    constructor() {
+        // No per-user processing
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const signalSchema = {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "enum": ["Capitulation", "Euphoria", "Confirmation (Buy)", "Confirmation (Sell)", "Divergence (Skilled Buy)", "Divergence (Skilled Sell)", "Neutral"]
+                },
+                "skilled_flow_pct": { "type": "number" },
+                "unskilled_flow_pct": { "type": "number" }
+            },
+            "required": ["status", "skilled_flow_pct", "unskilled_flow_pct"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Generates divergence signals by comparing net flow of 'Skilled' vs. 'Unskilled' cohorts, by asset and sector.",
+            "properties": {
+                "assets": {
+                    "type": "object",
+                    "description": "Divergence signals per asset.",
+                    "patternProperties": { "^.*$": signalSchema }, // Ticker
+                    "additionalProperties": signalSchema
+                },
+                "sectors": {
+                    "type": "object",
+                    "description": "Divergence signals per sector.",
+                    "patternProperties": { "^.*$": signalSchema }, // Sector
+                    "additionalProperties": signalSchema
+                }
+            },
+            "required": ["assets", "sectors"]
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return [
+            'gem_skilled-cohort-flow', // Pass 2
+            'gem_unskilled-cohort-flow'   // Pass 2
+        ];
+    }
+
+    process() {
+        // No-op
+    }
+    
+    _calculateDivergence(skilledFlow, unskilledFlow) {
+        const result = {};
+        if (!skilledFlow || !unskilledFlow) {
+            return result;
+        }
+        
+        const allKeys = new Set([...Object.keys(skilledFlow), ...Object.keys(unskilledFlow)]);
+        const THRESHOLD = 1.0; // Min flow % to register as a signal
+
+        for (const key of allKeys) {
+            const sFlow = skilledFlow[key]?.net_flow_percentage || 0;
+            const dFlow = unskilledFlow[key]?.net_flow_percentage || 0;
+
+            let status = 'Neutral';
+
+            // Both buying
+            if (sFlow > THRESHOLD && dFlow > THRESHOLD) {
+                status = 'Confirmation (Buy)';
+            }
+            // Both selling
+            else if (sFlow < -THRESHOLD && dFlow < -THRESHOLD) {
+                status = 'Confirmation (Sell)';
+            }
+            // Skilled buying, Unskilled selling
+            else if (sFlow > THRESHOLD && dFlow < -THRESHOLD) {
+                status = 'Capitulation'; // Skilled buying the dip from unskilled
+            }
+            // Skilled selling, Unskilled buying
+            else if (sFlow < -THRESHOLD && dFlow > THRESHOLD) {
+                status = 'Euphoria'; // Skilled selling into unskilled fomo
+            }
+            // Skilled buying, Unskilled neutral
+            else if (sFlow > THRESHOLD && Math.abs(dFlow) < THRESHOLD) {
+                status = 'Divergence (Skilled Buy)';
+            }
+            // Skilled selling, Unskilled neutral
+            else if (sFlow < -THRESHOLD && Math.abs(dFlow) < THRESHOLD) {
+                status = 'Divergence (Skilled Sell)';
+            }
+            
+            result[key] = {
+                status: status,
+                skilled_flow_pct: sFlow,
+                unskilled_flow_pct: dFlow
+            };
+        }
+        return result;
+    }
+
+    /**
+     * This is a 'meta' calculation.
+     * @param {object} fetchedDependencies - Results from Pass 2.
+     */
+    getResult(fetchedDependencies) {
+        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);
+
+        return {
+            assets: assetResult,
+            sectors: sectorResult
+        };
+    }
+
+    reset() {
+        // No state
+    }
+}
+
+module.exports = SkilledUnskilledDivergence;

package/calculations/meta/quant-skill-alpha-signal.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Calculation (Pass 4) for the "Quant-Skill Alpha Signal".
+ *
+ * This metric synthesizes multiple Pass 1, 2, and 3 signals into a
+ * single, actionable "raw score" for each asset. It is designed to
+ * be the final, tradable signal from this computation branch.
+ *
+ * It weights:
+ * 1. Skilled/Unskilled Divergence (Pass 3)
+ * 2. Unskilled "FOMO" (from Cohort Momentum, Pass 3)
+ * 3. Platform vs. Sample Divergence (Pass 1)
+ * 4. Social Media Sentiment (Pass 1)
+ */
+class QuantSkillAlphaSignal {
+    constructor() {
+        // Define the weights for the model.
+        // These would be optimized via backtesting.
+        this.W_DIVERGENCE = 0.40; // Skilled vs Unskilled
+        this.W_FOMO = 0.30;       // Unskilled Momentum (faded)
+        this.W_PLATFORM = 0.15;   // Sample vs Platform
+        this.W_SOCIAL = 0.15;   // Social Sentiment
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "raw_alpha_score": {
+                    "type": "number",
+                    "description": "The final weighted signal score. > 0 is bullish, < 0 is bearish."
+                },
+                "signal_status": {
+                    "type": "string",
+                    "description": "A human-readable signal (e.g., 'Strong Buy', 'Neutral')."
+                },
+                "component_divergence_score": { "type": "number" },
+                "component_unskilled_fomo_score": { "type": "number" },
+                "component_platform_divergence_score": { "type": "number" },
+                "component_social_sentiment_score": { "type": "number" }
+            },
+            "required": ["raw_alpha_score", "signal_status"]
+        };
+
+        return {
+            "type": "object",
+            "description": "A final, weighted alpha signal combining skill divergence, momentum, and sentiment.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * 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
+        ];
+    }
+
+    process() {
+        // No-op
+    }
+
+    /**
+     * This is a 'meta' calculation.
+     * @param {object} fetchedDependencies - Results from previous passes.
+     */
+    getResult(fetchedDependencies) {
+        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
+        }
+
+        const result = {};
+        const allTickers = new Set([
+            ...Object.keys(divergenceData),
+            ...Object.keys(momentumData),
+            ...Object.keys(platformData),
+            ...Object.keys(socialData)
+        ]);
+
+        for (const ticker of allTickers) {
+            // 1. Get Divergence Signal (Buy = +1, Sell = -1)
+            const divStatus = divergenceData[ticker]?.status;
+            const divScore = divStatus === 'Capitulation' ? 1.0 : (divStatus === 'Euphoria' ? -1.0 : 0);
+            
+            // 2. Get Unskilled FOMO Signal (We fade this, so we use -1)
+            // 'unskilled_momentum_score' is high positive when they buy a rally
+            const fomoScore = momentumData[ticker]?.unskilled_momentum_score || 0;
+
+            // 3. Get Platform Divergence Signal
+            // 'divergence' is positive when our sample is more bullish than the platform
+            const platformScore = platformData[ticker]?.divergence || 0;
+            
+            // 4. Get Social Sentiment Signal
+            // 'net_sentiment_pct' is positive when social is bullish
+            const socialScore = socialData[ticker]?.net_sentiment_pct || 0;
+
+            // Normalize scores to a similar range (approx -100 to 100)
+            // (This is a simple normalization; a z-score would be more robust)
+            const s_div = divScore * 100.0;
+            const s_fomo = -1 * fomoScore; // Fading the signal
+            const s_plat = platformScore; // Already 0-100
+            const s_soc = socialScore;  // Already 0-100
+
+            // Calculate final weighted score
+            const raw_alpha_score = 
+                (s_div * this.W_DIVERGENCE) +
+                (s_fomo * this.W_FOMO) +
+                (s_plat * this.W_PLATFORM) +
+                (s_soc * this.W_SOCIAL);
+
+            // Determine human-readable status
+            let status = 'Neutral';
+            if (raw_alpha_score > 30) status = 'Strong Buy';
+            else if (raw_alpha_score > 10) status = 'Buy';
+            else if (raw_alpha_score < -30) status = 'Strong Sell';
+            else if (raw_alpha_score < -10) status = 'Sell';
+
+            result[ticker] = {
+                raw_alpha_score: raw_alpha_score,
+                signal_status: status,
+                component_divergence_score: s_div,
+                component_unskilled_fomo_score: s_fomo,
+                component_platform_divergence_score: s_plat,
+                component_social_sentiment_score: s_soc
+            };
+        }
+        
+        return result;
+    }
+
+    reset() {
+        // No state
+    }
+}
+
+module.exports = QuantSkillAlphaSignal;

package/calculations/sentiment/gem_platform-conviction-divergence.js

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Calculation (Pass 1) for platform conviction divergence.
+ *
+ * This metric answers: "Is our 20,000-user sample more bullish or bearish
+ * on an asset than the entire eToro platform?"
+ *
+ * It compares the long/short ratio of our sample (from 'portfolio' data)
+ * against the platform-wide 'buy'/'sell' % (from 'insights' data).
+ */
+const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
+
+class PlatformConvictionDivergence {
+    constructor() {
+        // { [instrumentId]: { long: 0, short: 0 } }
+        this.sampledCounts = new Map();
+        this.mappings = null;
+        this.todayInsightsData = null;
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "platform_long_pct": {
+                    "type": "number",
+                    "description": "Percentage of holders on the entire platform who are long."
+                },
+                "sampled_long_pct": {
+                    "type": ["number", "null"],
+                    "description": "Percentage of holders in our sample who are long. Null if no sample."
+                },
+                "divergence": {
+                    "type": ["number", "null"],
+                    "description": "The difference (Sampled % - Platform %). Positive means our sample is more bullish."
+                }
+            },
+            "required": ["platform_long_pct", "sampled_long_pct", "divergence"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Calculates the divergence between the sample's long/short ratio and the platform's.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    /**
+     * This is a Pass 1 calculation and has no dependencies.
+     */
+    static getDependencies() {
+        return [];
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.sampledCounts.has(instrumentId)) {
+            this.sampledCounts.set(instrumentId, { long: 0, short: 0 });
+        }
+    }
+
+    process(portfolioData, yesterdayPortfolio, userId, context, todayInsights) {
+        // Capture insights data on the first user processed
+        if (!this.todayInsightsData && todayInsights) {
+            this.todayInsightsData = todayInsights;
+        }
+
+        const positions = portfolioData.PublicPositions || portfolioData.AggregatedPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const assetData = this.sampledCounts.get(instrumentId);
+
+            if (pos.IsBuy) {
+                assetData.long++;
+            } else {
+                assetData.short++;
+            }
+        }
+    }
+
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+        const insights = this.todayInsightsData?.insights;
+
+        if (!insights || !Array.isArray(insights)) {
+            return {}; // No platform data to compare against
+        }
+
+        for (const instrument of insights) {
+            const instrumentId = instrument.instrumentId;
+            const ticker = this.mappings.instrumentToTicker[instrumentId];
+            if (!ticker) continue;
+            
+            const platform_long_pct = instrument.buy || 0; // e.g., 51
+            
+            const sampledData = this.sampledCounts.get(instrumentId);
+            const sampled_long = sampledData?.long || 0;
+            const sampled_short = sampledData?.short || 0;
+            const totalSampled = sampled_long + sampled_short;
+
+            let sampled_long_pct = null;
+            let divergence = null;
+
+            if (totalSampled > 0) {
+                sampled_long_pct = (sampled_long / totalSampled) * 100;
+                divergence = sampled_long_pct - platform_long_pct;
+            }
+
+            result[ticker] = {
+                platform_long_pct: platform_long_pct,
+                sampled_long_pct: sampled_long_pct,
+                divergence: divergence
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.sampledCounts.clear();
+        this.mappings = null;
+        this.todayInsightsData = null;
+    }
+}
+
+module.exports = PlatformConvictionDivergence;

package/package.json

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