aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/insights/historical/daily_bought_vs_sold_count.js

@@ -1,61 +1,126 @@
 /**
- * @fileoverview Calculates the total number of positions 'bought' vs 'sold' based on daily owner delta.
- * Uses the 'daily_instrument_insights' collection (truth of source).
- * 'Bought' = sum of positive deltas, 'Sold' = sum of absolute negative deltas.
+ * @fileoverview Calculation (Pass 2) for daily bought vs. sold count.
+ *
+ * This metric tracks the total number of positions 'bought' (new)
+ * and 'sold' (closed) today, based on daily ownership change.
+ *
+ * This is different from 'daily_asset_activity' because it counts
+ * *positions*, not *unique users*.
  */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 class DailyBoughtVsSoldCount {
     constructor() {
-        this.totalBought = 0;
-        this.totalSold = 0;
-        this.processedDay = false; // Flag to run logic only once per day
+        // We will store { [instrumentId]: { new: 0, closed: 0 } }
+        this.assetActivity = new Map();
+        this.mappings = null;
     }
 
-    // Needs insights from today and yesterday
-    async process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights) {
-        if (this.processedDay) return;
-        this.processedDay = true;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "description": "Daily trade activity for a specific asset.",
+            "properties": {
+                "positions_bought": {
+                    "type": "number",
+                    "description": "Total new positions opened for this asset."
+                },
+                "positions_sold": {
+                    "type": "number",
+                    "description": "Total positions closed for this asset."
+                },
+                "net_change": {
+                    "type": "number",
+                    "description": "Net change in positions (bought - sold)."
+                }
+            },
+            "required": ["positions_bought", "positions_sold", "net_change"]
+        };
 
-        if (!todayInsights || !todayInsights.insights || !yesterdayInsights || !yesterdayInsights.insights) {
-            console.warn('[DailyBoughtVsSoldCount] Missing insights data for today or yesterday.');
-            return;
+        return {
+            "type": "object",
+            "description": "Tracks new positions (bought) and closed positions (sold) per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Matches any string key (ticker)
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assetActivity.has(instrumentId)) {
+            this.assetActivity.set(instrumentId, {
+                new: 0,
+                closed: 0
+            });
+        }
+    }
+
+    _getInstrumentIds(portfolio) {
+        // This MUST use PositionID to be accurate
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
         }
+        // Map<PositionID, InstrumentID>
+        return new Map(positions.map(p => [p.PositionID, p.InstrumentID]).filter(p => p[0] && p[1]));
+    }
 
-        const yesterdayTotals = new Map(yesterdayInsights.insights.map(i => [i.instrumentId, i.total]));
+    process(todayPortfolio, yesterdayPortfolio) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
 
-        for (const instrument of todayInsights.insights) {
-            const instrumentId = instrument.instrumentId;
-            const todayTotal = instrument.total || 0;
-            const yesterdayTotal = yesterdayTotals.get(instrumentId) || 0;
+        const yPosMap = this._getInstrumentIds(yesterdayPortfolio); // Map<PosID, InstID>
+        const tPosMap = this._getInstrumentIds(todayPortfolio); // Map<PosID, InstID>
 
-            const delta = todayTotal - yesterdayTotal;
+        // Find new positions (in today but not yesterday)
+        for (const [tPosId, tInstId] of tPosMap.entries()) {
+            if (!yPosMap.has(tPosId)) {
+                this._initAsset(tInstId);
+                this.assetActivity.get(tInstId).new++;
+            }
+        }
 
-            if (delta > 0) {
-                this.totalBought += delta;
-            } else if (delta < 0) {
-                this.totalSold += Math.abs(delta); // Sum of absolute decreases
+        // Find closed positions (in yesterday but not today)
+        for (const [yPosId, yInstId] of yPosMap.entries()) {
+            if (!tPosMap.has(yPosId)) {
+                this._initAsset(yInstId);
+                this.assetActivity.get(yInstId).closed++;
             }
         }
     }
 
-    getResult() {
-        // --- ADD THIS CHECK ---
-        if (!this.processedDay) {
-            console.warn('[DailyBoughtVsSoldCount] getResult called but process never ran (missing insights). Returning null for backfill.');
-            return null;
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
-        // --- END ADD ---
 
-        return {
-            total_positions_bought_delta: this.totalBought,
-            total_positions_sold_delta: this.totalSold
-        };
+        const result = {};
+        for (const [instrumentId, data] of this.assetActivity.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const openCount = data.new;
+            const closeCount = data.closed;
+            
+            if (openCount > 0 || closeCount > 0) {
+                result[ticker] = {
+                    positions_bought: openCount,
+                    positions_sold: closeCount,
+                    net_change: openCount - closeCount 
+                };
+            }
+        }
+        return result;
     }
 
     reset() {
-        this.totalBought = 0;
-        this.totalSold = 0;
-        this.processedDay = false;
+        this.assetActivity.clear();
+        this.mappings = null;
     }
 }
 

package/calculations/insights/historical/daily_ownership_delta.js

@@ -1,60 +1,123 @@
 /**
- * @fileoverview Calculates the daily change (delta) in total owners for each instrument.
- * Uses the 'daily_instrument_insights' collection (truth of source).
+ * @fileoverview Calculation (Pass 2) for daily ownership delta.
+ *
+ * This metric calculates the daily change in the total number of *owners*
+ * (unique users) for each instrument.
+ *
+ * This measures the broadening or narrowing of an asset's holder base.
  */
 const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
 
 class DailyOwnershipDelta {
     constructor() {
-        this.deltaByTicker = {};
+        // We will store { [instrumentId]: { owners_yesterday: Set(), owners_today: Set() } }
+        this.assetOwnership = new Map();
         this.mappings = null;
     }
 
-    // This calculation only needs insights data, not portfolio data.
-    // It runs daily but needs 'yesterday's insights to calculate the delta.
-    async process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights) {
-        // We only need to run the core logic once per day, not per user.
-        // Use a flag to ensure it runs only on the first user processed for the day.
-        if (this.processedDay) return;
-        this.processedDay = true; // Set flag
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "description": "Daily change in unique owners for a specific asset.",
+            "properties": {
+                "owners_today": {
+                    "type": "number",
+                    "description": "Total unique users holding this asset today."
+                },
+                "owners_yesterday": {
+                    "type": "number",
+                    "description": "Total unique users holding this asset yesterday."
+                },
+                "owner_delta": {
+                    "type": "number",
+                    "description": "The net change in unique owners (today - yesterday)."
+                },
+                "owner_delta_percent": {
+                    "type": ["number", "null"],
+                    "description": "Percentage change in unique owners. Null if yesterday had 0 owners."
+                }
+            },
+            "required": ["owners_today", "owners_yesterday", "owner_delta", "owner_delta_percent"]
+        };
 
-        if (!todayInsights || !todayInsights.insights || !yesterdayInsights || !yesterdayInsights.insights) {
-            console.warn('[DailyOwnershipDelta] Missing insights data for today or yesterday.');
-            return;
+        return {
+            "type": "object",
+            "description": "Calculates the daily change in the total number of unique owners for each asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Matches any string key (ticker)
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assetOwnership.has(instrumentId)) {
+            this.assetOwnership.set(instrumentId, {
+                owners_yesterday: new Set(),
+                owners_today: new Set()
+            });
         }
+    }
 
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
+    _getInstrumentIds(portfolio) {
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Set();
         }
+        return new Set(positions.map(p => p.InstrumentID).filter(Boolean));
+    }
 
-        const yesterdayTotals = new Map(yesterdayInsights.insights.map(i => [i.instrumentId, i.total]));
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
 
-        for (const instrument of todayInsights.insights) {
-            const instrumentId = instrument.instrumentId;
-            const todayTotal = instrument.total || 0;
-            const yesterdayTotal = yesterdayTotals.get(instrumentId) || 0; // Default to 0 if not found yesterday
+        const yIds = this._getInstrumentIds(yesterdayPortfolio);
+        const tIds = this._getInstrumentIds(todayPortfolio);
 
-            const delta = todayTotal - yesterdayTotal;
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+        // Add user to yesterday's owner sets
+        for (const yId of yIds) {
+            this._initAsset(yId);
+            this.assetOwnership.get(yId).owners_yesterday.add(userId);
+        }
 
-            this.deltaByTicker[ticker] = delta;
+        // Add user to today's owner sets
+        for (const tId of tIds) {
+            this._initAsset(tId);
+            this.assetOwnership.get(tId).owners_today.add(userId);
         }
     }
 
-    getResult() {
-        // --- ADD THIS CHECK ---
-        if (!this.processedDay) {
-            console.warn('[DailyOwnershipDelta] getResult called but process never ran (missing insights). Returning null for backfill.');
-            return null;
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
-        // --- END ADD ---
 
-        return this.deltaByTicker;
+        const result = {};
+        for (const [instrumentId, data] of this.assetOwnership.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const yOwners = data.owners_yesterday.size;
+            const tOwners = data.owners_today.size;
+            
+            if (yOwners > 0 || tOwners > 0) {
+                result[ticker] = {
+                    owners_today: tOwners,
+                    owners_yesterday: yOwners,
+                    owner_delta: tOwners - yOwners,
+                    owner_delta_percent: (yOwners > 0) ? ((tOwners - yOwners) / yOwners) * 100 : null
+                };
+            }
+        }
+        return result;
     }
 
     reset() {
-        this.deltaByTicker = {};
-        this.processedDay = false; // Reset the flag for the next day
+        this.assetOwnership.clear();
         this.mappings = null;
     }
 }

package/calculations/meta/capital_deployment_strategy.js

@@ -1,140 +1,108 @@
 /**
- * @fileoverview Meta-calculation (Pass 2) that analyzes "what" the crowd does
- * following a net deposit signal.
+ * @fileoverview Calculation (Pass 3) for capital deployment strategy.
  *
- * --- META REFACTOR (v2) ---
- * This calc fetches *today's* dependencies from the runner, but still
- * performs its own historical lookback for the *signal*.
+ * This metric answers: "Following a net deposit event, does the crowd
+ * tend to deploy new capital into new assets or add to existing ones?"
+ *
+ * It *depends* on 'crowd-cash-flow-proxy', 'new_allocation_percentage',
+ * and 'reallocation_increase_percentage'.
  */
-
-const { FieldValue } = require('@google-cloud/firestore');
-
 class CapitalDeploymentStrategy {
+    constructor() {
+        // This class only aggregates results from other calculations.
+        // No per-user processing is needed.
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Analyzes if the crowd deploys new capital into new or existing assets, triggered by a net deposit event.",
+            "properties": {
+                "is_net_deposit_day": {
+                    "type": "boolean",
+                    "description": "True if today was a net deposit day for the crowd."
+                },
+                "net_cash_flow_proxy": {
+                    "type": "number",
+                    "description": "The estimated net cash flow (from 'crowd-cash-flow-proxy')."
+                },
+                "total_deployed_to_new_positions_pct": {
+                    "type": "number",
+                    "description": "The total % portfolio allocation deployed to new positions (from 'new_allocation_percentage')."
+                },
+                "total_deployed_to_existing_positions_pct": {
+                    "type": "number",
+                    "description": "The total % portfolio allocation added to existing positions (from 'reallocation_increase_percentage')."
+                },
+                "deployment_ratio_new_vs_existing": {
+                    "type": ["number", "null"],
+                    "description": "Ratio of (New / Existing) deployment. Null if no deployment to existing positions."
+                }
+            },
+            "required": ["is_net_deposit_day", "net_cash_flow_proxy", "total_deployed_to_new_positions_pct", "total_deployed_to_existing_positions_pct", "deployment_ratio_new_vs_existing"]
+        };
+    }
 
     /**
-     * (NEW) Statically declare dependencies.
+     * Statically declare dependencies.
      */
     static getDependencies() {
         return [
-            'crowd-cash-flow-proxy', 
-            'new-allocation-percentage', 
-            'reallocation-increase-percentage'
+            'crowd-cash-flow-proxy',
+            'new_allocation_percentage',
+            'reallocation_increase_percentage'
         ];
     }
-    
-    constructor() {
-        this.lookbackDays = 7;
-        this.correlationWindow = 3; // How many days after a signal to link behavior
-        this.depositSignalThreshold = -0.005; 
-    }
 
-    _getDateStr(baseDate, daysAgo) {
-        const date = new Date(baseDate + 'T00:00:00Z');
-        date.setUTCDate(date.getUTCDate() - daysAgo);
-        return date.toISOString().slice(0, 10);
+    /**
+     * process() is a no-op. All logic is in getResult().
+     */
+    process() {
+        // No-op
     }
 
     /**
-     * REFACTORED PROCESS METHOD
-     * @param {string} dateStr The date to run the analysis for (e.g., "2025-10-31").
-     * @param {object} dependencies The shared dependencies (db, logger).
-     * @param {object} config The computation system configuration.
-     * @param {object} fetchedDependencies In-memory results from previous passes.
-     * @returns {Promise<object|null>} The analysis result or null.
+     * Aggregates results from dependencies.
      */
-    async process(dateStr, dependencies, config, fetchedDependencies) {
-        const { db, logger } = dependencies;
-        const collection = config.resultsCollection;
-        const resultsSub = config.resultsSubcollection || 'results';
-        const compsSub = config.computationsSubcollection || 'computations';
-
-        // 1. Find the most recent deposit signal (Still requires historical lookback)
-        let depositSignal = null;
-        let depositSignalDay = null;
-        let refsToGet = [];
+    getResult(fetchedDependencies) {
+        const cashFlowData = fetchedDependencies['crowd-cash-flow-proxy'];
+        const newAllocData = fetchedDependencies['new_allocation_percentage'];
+        const reallocData = fetchedDependencies['reallocation_increase_percentage'];
 
-        for (let i = 1; i <= this.lookbackDays; i++) {
-            const checkDate = this._getDateStr(dateStr, i);
-            refsToGet.push({
-                date: checkDate,
-                key: `signal_${checkDate}`,
-                ref: db.collection(collection).doc(checkDate).collection(resultsSub).doc('capital_flow').collection(compsSub).doc('crowd-cash-flow-proxy')
-            });
-        }
-
-        const signalSnapshots = await db.getAll(...refsToGet.map(r => r.ref));
-        const dataMap = new Map();
-        signalSnapshots.forEach((snap, idx) => {
-            if (snap.exists) dataMap.set(refsToGet[idx].key, snap.data());
-        });
-
-        for (let i = 1; i <= this.lookbackDays; i++) {
-            const checkDate = this._getDateStr(dateStr, i);
-            const flowData = dataMap.get(`signal_${checkDate}`);
-            if (flowData && flowData.cash_flow_effect_proxy < this.depositSignalThreshold) {
-                depositSignal = flowData;
-                depositSignalDay = checkDate;
-                break; // Found the most recent signal
-            }
-        }
-
-        if (!depositSignal) {
-            return {
-                status: 'no_deposit_signal_found',
-                lookback_days: this.lookbackDays
-            };
-        }
-
-        // 2. Check if today is within the correlation window
-        const daysSinceSignal = (new Date(dateStr) - new Date(depositSignalDay)) / (1000 * 60 * 60 * 24);
-
-        if (daysSinceSignal <= 0 || daysSinceSignal > this.correlationWindow) {
+        if (!cashFlowData || !newAllocData || !reallocData) {
+            // Return a default "non-event" state if dependencies are missing
             return {
-                status: 'outside_correlation_window',
-                signal_day: depositSignalDay,
-                days_since_signal: daysSinceSignal
+                is_net_deposit_day: false,
+                net_cash_flow_proxy: 0,
+                total_deployed_to_new_positions_pct: 0,
+                total_deployed_to_existing_positions_pct: 0,
+                deployment_ratio_new_vs_existing: null
             };
         }
 
-        // 3. Fetch deployment data for *today* FROM `fetchedDependencies`
-        const newAllocData = fetchedDependencies['new-allocation-percentage'];
-        const reAllocData = fetchedDependencies['reallocation-increase-percentage'];
-
-        // 4. Handle missing dependencies
-        if (!newAllocData || !reAllocData) {
-            logger.log('WARN', `[CapitalDeploymentStrategy] Missing in-memory deployment data for ${dateStr}. Skipping.`);
-            return null;
-        }
-
-        // 5. Calculate deployment bias
-        const newAlloc = newAllocData.average_new_allocation_percentage || 0;
-        const reAlloc = reAllocData.average_reallocation_increase_percentage || 0;
-
-        const totalDeployment = newAlloc + reAlloc;
-        let newAssetBias = 0;
-        let existingAssetBias = 0;
+        const netCashFlow = cashFlowData.net_cash_flow_proxy || 0;
+        const isNetDepositDay = netCashFlow > 0;
 
-        if (totalDeployment > 0) {
-            newAssetBias = (newAlloc / totalDeployment) * 100;
-            existingAssetBias = (reAlloc / totalDeployment) * 100;
-        }
+        // We only report deployment stats IF it was a deposit day.
+        const newAllocSum = isNetDepositDay ? newAllocData.total_new_allocation_pct_sum : 0;
+        const reallocSum = isNetDepositDay ? reallocData.total_reallocation_increase_pct_sum : 0;
 
         return {
-            status: 'analysis_complete',
-            analysis_date: dateStr,
-            signal_date: depositSignalDay,
-            days_since_signal: daysSinceSignal,
-            signal_deposit_proxy_pct: Math.abs(depositSignal.cash_flow_effect_proxy),
-            deployment_new_alloc_pct: newAlloc,
-            deployment_existing_alloc_pct: reAlloc,
-            total_deployment_pct: totalDeployment,
-            new_asset_bias: newAssetBias,
-            existing_asset_bias: existingAssetBias
+            is_net_deposit_day: isNetDepositDay,
+            net_cash_flow_proxy: netCashFlow,
+            total_deployed_to_new_positions_pct: newAllocSum,
+            total_deployed_to_existing_positions_pct: reallocSum,
+            deployment_ratio_new_vs_existing: (reallocSum > 0) ? (newAllocSum / reallocSum) : null
         };
     }
 
-    async getResult() { return null; }
-    reset() {}
+    reset() {
+        // No state to reset
+    }
 }
 
 module.exports = CapitalDeploymentStrategy;