bulltrackers-module 1.0.105 → 1.0.106

package/functions/orchestrator/helpers/discovery_helpers.js

@@ -1,226 +1,226 @@
-/**
- * @fileoverview Orchestrator's discovery sub-pipes.
- * REFACTORED: All functions are now stateless and receive dependencies.
- */
-
-/**
- * Sub-pipe: pipe.orchestrator.checkDiscoveryNeed
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {object} config - The user type specific config (e.g., config.discoveryConfig.normal).
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
- * @returns {Promise<{needsDiscovery: boolean, blocksToFill: Array<object>}>}
- */
-async function checkDiscoveryNeed(userType, config, dependencies) {
-    const { logger, firestoreUtils } = dependencies;
-    logger.log('INFO', `[Orchestrator Helpers] Checking discovery need for ${userType}...`);
-    
-    const { 
-        targetUsersPerBlock,
-        speculatorBlockCountsDocPath, 
-        normalBlockCountsDocPath,
-        speculatorInstruments,
-        allHighValueBlocks
-    } = config;
-
-    const isSpeculator = userType === 'speculator';
-    
-    // Pass dependencies and config to core util
-    const blockCounts = await firestoreUtils.getBlockCapacities(
-        dependencies, 
-        { speculatorBlockCountsDocPath, normalBlockCountsDocPath }, 
-        userType
-    );
-
-    let underPopulatedBlocks = [];
-    if (isSpeculator) {
-        for (const instrument of speculatorInstruments) {
-            for (const block of allHighValueBlocks) {
-                const instrumentBlockKey = `${instrument}_${block.startId}`;
-                if ((blockCounts[instrumentBlockKey] || 0) < targetUsersPerBlock) {
-                    underPopulatedBlocks.push({ ...block, instrument });
-                }
-            }
-        }
-    } else {
-        underPopulatedBlocks = allHighValueBlocks.filter(
-            block => (blockCounts[block.startId] || 0) < targetUsersPerBlock
-        );
-    }
-
-    const needsDiscovery = underPopulatedBlocks.length > 0;
-    if (!needsDiscovery) {
-        logger.log('SUCCESS', `✅ All blocks are at target capacity for ${userType} users.`);
-    } else {
-        logger.log('INFO', `Found ${underPopulatedBlocks.length} underpopulated blocks/instruments for ${userType}.`);
-    }
-    return { needsDiscovery, blocksToFill: underPopulatedBlocks };
-}
-
-/**
- * Sub-pipe: pipe.orchestrator.getDiscoveryCandidates
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {Array<object>} blocksToFill - From checkDiscoveryNeed.
- * @param {object} config - The user type specific config.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
- * @returns {Promise<Set<string>>} Set of candidate CIDs.
- */
-async function getDiscoveryCandidates(userType, blocksToFill, config, dependencies) {
-    const { logger, firestoreUtils } = dependencies;
-    logger.log('INFO', `[Orchestrator Helpers] Getting discovery candidates for ${userType}...`);
-    
-    const {
-        maxTasksPerRun,
-        discoveryBatchSize,
-        maxRandomCidsToDiscover,
-        specBlocksCollection,
-        pendingSpecCollection,
-        normalUserCollection,
-        invalidSpecCollection,
-        speculatorInstrumentSet,
-        snapshotsSubCollectionName,
-        partsSubCollectionName
-    } = config;
-    
-    const isSpeculator = userType === 'speculator';
-    const dispatchedCids = new Set();
-
-    // Pass dependencies and config to core util
-    const latestNormalPortfolios = await firestoreUtils.getLatestNormalUserPortfolios(
-        dependencies,
-        { normalUserCollectionName: normalUserCollection, snapshotsSubCollectionName, partsSubCollectionName }
-    );
-    const existingNormalUserIds = new Set(Object.keys(latestNormalPortfolios));
-
-    // Pass dependencies and config to core util
-    const exclusionIds = await firestoreUtils.getExclusionIds(dependencies, {
-        specBlocksCollection, 
-        pendingSpecCollection, 
-        normalUserCollection,
-        invalidSpecCollection,
-        existingNormalUserIds
-    }, userType);
-
-    if (isSpeculator) {
-        // Pass dependencies to core util
-        const prioritizedCandidates = await firestoreUtils.getPrioritizedSpeculators(
-            dependencies,
-            exclusionIds, 
-            speculatorInstrumentSet,
-            latestNormalPortfolios
-        );
-        logger.log('INFO', `Found ${prioritizedCandidates.length} potential new speculators from existing user pool.`);
-
-        prioritizedCandidates.forEach(cidStr => {
-            if (dispatchedCids.size < maxTasksPerRun) {
-                dispatchedCids.add(cidStr);
-            }
-        });
-        logger.log('INFO', `Added ${dispatchedCids.size} prioritized speculators.`);
-    }
-
-    // --- Random Generation ---
-    let dispatchedRandomCidCount = 0;
-    const initialDispatchedCount = dispatchedCids.size;
-
-    while ((dispatchedRandomCidCount + initialDispatchedCount) < maxRandomCidsToDiscover &&
-        dispatchedCids.size < maxTasksPerRun && blocksToFill.length > 0)
-    {
-        const blockIndex = dispatchedCids.size % blocksToFill.length;
-        const block = blocksToFill[blockIndex];
-        if (!block) break; 
-
-        for (let j = 0; j < discoveryBatchSize; j++) {
-            if ((dispatchedRandomCidCount + initialDispatchedCount) >= maxRandomCidsToDiscover || dispatchedCids.size >= maxTasksPerRun) break;
-
-            let randomId;
-            let retryCount = 0;
-            const MAX_RETRIES = 50;
-            do {
-                if (++retryCount > MAX_RETRIES) break;
-                randomId = String(Math.floor(Math.random() * 1000000) + block.startId);
-            } while (
-                exclusionIds.has(randomId) ||
-                dispatchedCids.has(randomId)
-            );
-
-            if (retryCount <= MAX_RETRIES) {
-                dispatchedCids.add(randomId);
-                dispatchedRandomCidCount++;
-            }
-        }
-    }
-
-    logger.log('INFO', `Generated ${dispatchedRandomCidCount} random CIDs for ${userType} discovery.`);
-    logger.log('INFO', `Total candidates for dispatch: ${dispatchedCids.size}`);
-    return dispatchedCids; 
-}
-
-/**
- * Sub-pipe: pipe.orchestrator.dispatchDiscovery
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {Set<string>} candidates - Set of candidate CIDs.
- * @param {object} config - The user type specific config.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils, pubsubUtils.
- * @returns {Promise<void>}
- */
-async function dispatchDiscovery(userType, candidates, config, dependencies) {
-    const { logger, firestoreUtils, pubsubUtils } = dependencies;
-    const {
-        topicName,
-        dispatchBatchSize,
-        pubsubBatchSize,
-        pendingSpecCollection, 
-        pendingMaxFieldsPerDoc,
-        pendingMaxWritesPerBatch
-    } = config;
-
-    if (candidates.size === 0) {
-        logger.log('INFO', `[Orchestrator Helpers] No ${userType} candidates to dispatch.`);
-        return;
-    }
-    logger.log('INFO', `[Orchestrator Helpers] Dispatching ${candidates.size} discovery tasks for ${userType}...`);
-    
-    const isSpeculator = userType === 'speculator';
-    const cidsArray = Array.from(candidates);
-
-    if (isSpeculator) {
-        await firestoreUtils.clearCollection(dependencies, pendingSpecCollection); 
-        await firestoreUtils.batchWriteShardedIds(dependencies, {
-            collectionPath: pendingSpecCollection,
-            items: cidsArray, 
-            timestamp: new Date(),
-            maxFieldsPerDoc: pendingMaxFieldsPerDoc,
-            maxWritesPerBatch: pendingMaxWritesPerBatch
-        });
-    }
-
-    const tasks = [];
-    for (let i = 0; i < cidsArray.length; i += dispatchBatchSize) {
-        const batchCids = cidsArray.slice(i, i + dispatchBatchSize).map(cid => parseInt(cid)); 
-        if (batchCids.length > 0) {
-            const blockId = Math.floor(batchCids[0] / 1000000) * 1000000;
-            tasks.push({
-                type: 'discover',
-                cids: batchCids,
-                blockId, 
-                userType
-            });
-        }
-    }
-
-    // Pass dependencies and config to core util
-    await pubsubUtils.batchPublishTasks(dependencies, {
-        topicName, 
-        tasks, 
-        taskType: `${userType} discovery`,
-        maxPubsubBatchSize: pubsubBatchSize
-    });
-    logger.log('SUCCESS', `[Orchestrator Helpers] Dispatched ${tasks.length} task messages (${candidates.size} CIDs) for ${userType} discovery.`);
-}
-
-
-module.exports = {
-  checkDiscoveryNeed,
-  getDiscoveryCandidates,
-  dispatchDiscovery,
-};
+/**
+ * @fileoverview Orchestrator's discovery sub-pipes.
+ * REFACTORED: All functions are now stateless and receive dependencies.
+ */
+
+/**
+ * Sub-pipe: pipe.orchestrator.checkDiscoveryNeed
+ * @param {string} userType - 'normal' or 'speculator'.
+ * @param {object} config - The user type specific config (e.g., config.discoveryConfig.normal).
+ * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
+ * @returns {Promise<{needsDiscovery: boolean, blocksToFill: Array<object>}>}
+ */
+async function checkDiscoveryNeed(userType, config, dependencies) {
+    const { logger, firestoreUtils } = dependencies;
+    logger.log('INFO', `[Orchestrator Helpers] Checking discovery need for ${userType}...`);
+    
+    const { 
+        targetUsersPerBlock,
+        speculatorBlockCountsDocPath, 
+        normalBlockCountsDocPath,
+        speculatorInstruments,
+        allHighValueBlocks
+    } = config;
+
+    const isSpeculator = userType === 'speculator';
+    
+    // Pass dependencies and config to core util
+    const blockCounts = await firestoreUtils.getBlockCapacities(
+        dependencies, 
+        { speculatorBlockCountsDocPath, normalBlockCountsDocPath }, 
+        userType
+    );
+
+    let underPopulatedBlocks = [];
+    if (isSpeculator) {
+        for (const instrument of speculatorInstruments) {
+            for (const block of allHighValueBlocks) {
+                const instrumentBlockKey = `${instrument}_${block.startId}`;
+                if ((blockCounts[instrumentBlockKey] || 0) < targetUsersPerBlock) {
+                    underPopulatedBlocks.push({ ...block, instrument });
+                }
+            }
+        }
+    } else {
+        underPopulatedBlocks = allHighValueBlocks.filter(
+            block => (blockCounts[block.startId] || 0) < targetUsersPerBlock
+        );
+    }
+
+    const needsDiscovery = underPopulatedBlocks.length > 0;
+    if (!needsDiscovery) {
+        logger.log('SUCCESS', `✅ All blocks are at target capacity for ${userType} users.`);
+    } else {
+        logger.log('INFO', `Found ${underPopulatedBlocks.length} underpopulated blocks/instruments for ${userType}.`);
+    }
+    return { needsDiscovery, blocksToFill: underPopulatedBlocks };
+}
+
+/**
+ * Sub-pipe: pipe.orchestrator.getDiscoveryCandidates
+ * @param {string} userType - 'normal' or 'speculator'.
+ * @param {Array<object>} blocksToFill - From checkDiscoveryNeed.
+ * @param {object} config - The user type specific config.
+ * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
+ * @returns {Promise<Set<string>>} Set of candidate CIDs.
+ */
+async function getDiscoveryCandidates(userType, blocksToFill, config, dependencies) {
+    const { logger, firestoreUtils } = dependencies;
+    logger.log('INFO', `[Orchestrator Helpers] Getting discovery candidates for ${userType}...`);
+    
+    const {
+        maxTasksPerRun,
+        discoveryBatchSize,
+        maxRandomCidsToDiscover,
+        specBlocksCollection,
+        pendingSpecCollection,
+        normalUserCollection,
+        invalidSpecCollection,
+        speculatorInstrumentSet,
+        snapshotsSubCollectionName,
+        partsSubCollectionName
+    } = config;
+    
+    const isSpeculator = userType === 'speculator';
+    const dispatchedCids = new Set();
+
+    // Pass dependencies and config to core util
+    const latestNormalPortfolios = await firestoreUtils.getLatestNormalUserPortfolios(
+        dependencies,
+        { normalUserCollectionName: normalUserCollection, snapshotsSubCollectionName, partsSubCollectionName }
+    );
+    const existingNormalUserIds = new Set(Object.keys(latestNormalPortfolios));
+
+    // Pass dependencies and config to core util
+    const exclusionIds = await firestoreUtils.getExclusionIds(dependencies, {
+        specBlocksCollection, 
+        pendingSpecCollection, 
+        normalUserCollection,
+        invalidSpecCollection,
+        existingNormalUserIds
+    }, userType);
+
+    if (isSpeculator) {
+        // Pass dependencies to core util
+        const prioritizedCandidates = await firestoreUtils.getPrioritizedSpeculators(
+            dependencies,
+            exclusionIds, 
+            speculatorInstrumentSet,
+            latestNormalPortfolios
+        );
+        logger.log('INFO', `Found ${prioritizedCandidates.length} potential new speculators from existing user pool.`);
+
+        prioritizedCandidates.forEach(cidStr => {
+            if (dispatchedCids.size < maxTasksPerRun) {
+                dispatchedCids.add(cidStr);
+            }
+        });
+        logger.log('INFO', `Added ${dispatchedCids.size} prioritized speculators.`);
+    }
+
+    // --- Random Generation ---
+    let dispatchedRandomCidCount = 0;
+    const initialDispatchedCount = dispatchedCids.size;
+
+    while ((dispatchedRandomCidCount + initialDispatchedCount) < maxRandomCidsToDiscover &&
+        dispatchedCids.size < maxTasksPerRun && blocksToFill.length > 0)
+    {
+        const blockIndex = dispatchedCids.size % blocksToFill.length;
+        const block = blocksToFill[blockIndex];
+        if (!block) break; 
+
+        for (let j = 0; j < discoveryBatchSize; j++) {
+            if ((dispatchedRandomCidCount + initialDispatchedCount) >= maxRandomCidsToDiscover || dispatchedCids.size >= maxTasksPerRun) break;
+
+            let randomId;
+            let retryCount = 0;
+            const MAX_RETRIES = 50;
+            do {
+                if (++retryCount > MAX_RETRIES) break;
+                randomId = String(Math.floor(Math.random() * 1000000) + block.startId);
+            } while (
+                exclusionIds.has(randomId) ||
+                dispatchedCids.has(randomId)
+            );
+
+            if (retryCount <= MAX_RETRIES) {
+                dispatchedCids.add(randomId);
+                dispatchedRandomCidCount++;
+            }
+        }
+    }
+
+    logger.log('INFO', `Generated ${dispatchedRandomCidCount} random CIDs for ${userType} discovery.`);
+    logger.log('INFO', `Total candidates for dispatch: ${dispatchedCids.size}`);
+    return dispatchedCids; 
+}
+
+/**
+ * Sub-pipe: pipe.orchestrator.dispatchDiscovery
+ * @param {string} userType - 'normal' or 'speculator'.
+ * @param {Set<string>} candidates - Set of candidate CIDs.
+ * @param {object} config - The user type specific config.
+ * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils, pubsubUtils.
+ * @returns {Promise<void>}
+ */
+async function dispatchDiscovery(userType, candidates, config, dependencies) {
+    const { logger, firestoreUtils, pubsubUtils } = dependencies;
+    const {
+        topicName,
+        dispatchBatchSize,
+        pubsubBatchSize,
+        pendingSpecCollection, 
+        pendingMaxFieldsPerDoc,
+        pendingMaxWritesPerBatch
+    } = config;
+
+    if (candidates.size === 0) {
+        logger.log('INFO', `[Orchestrator Helpers] No ${userType} candidates to dispatch.`);
+        return;
+    }
+    logger.log('INFO', `[Orchestrator Helpers] Dispatching ${candidates.size} discovery tasks for ${userType}...`);
+    
+    const isSpeculator = userType === 'speculator';
+    const cidsArray = Array.from(candidates);
+
+    if (isSpeculator) {
+        await firestoreUtils.clearCollection(dependencies, pendingSpecCollection); 
+        await firestoreUtils.batchWriteShardedIds(dependencies, {
+            collectionPath: pendingSpecCollection,
+            items: cidsArray, 
+            timestamp: new Date(),
+            maxFieldsPerDoc: pendingMaxFieldsPerDoc,
+            maxWritesPerBatch: pendingMaxWritesPerBatch
+        });
+    }
+
+    const tasks = [];
+    for (let i = 0; i < cidsArray.length; i += dispatchBatchSize) {
+        const batchCids = cidsArray.slice(i, i + dispatchBatchSize).map(cid => parseInt(cid)); 
+        if (batchCids.length > 0) {
+            const blockId = Math.floor(batchCids[0] / 1000000) * 1000000;
+            tasks.push({
+                type: 'discover',
+                cids: batchCids,
+                blockId, 
+                userType
+            });
+        }
+    }
+
+    // Pass dependencies and config to core util
+    await pubsubUtils.batchPublishTasks(dependencies, {
+        topicName, 
+        tasks, 
+        taskType: `${userType} discovery`,
+        maxPubsubBatchSize: pubsubBatchSize
+    });
+    logger.log('SUCCESS', `[Orchestrator Helpers] Dispatched ${tasks.length} task messages (${candidates.size} CIDs) for ${userType} discovery.`);
+}
+
+
+module.exports = {
+  checkDiscoveryNeed,
+  getDiscoveryCandidates,
+  dispatchDiscovery,
+};

package/functions/orchestrator/helpers/update_helpers.js

@@ -1,92 +1,92 @@
-/**
- * @fileoverview Orchestrator's update sub-pipes.
- * REFACTORED: All functions are now stateless and receive dependencies.
- */
-
-/**
- * Sub-pipe: pipe.orchestrator.getUpdateTargets
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {object} thresholds - Contains date thresholds.
- * @param {object} config - The *global* updateConfig object.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
- * @returns {Promise<Array<any>>} Array of targets.
- */
-async function getUpdateTargets(userType, thresholds, config, dependencies) {
-    const { logger, firestoreUtils } = dependencies;
-    logger.log('INFO', `[Orchestrator Helpers] Getting update targets for ${userType}...`);
-    let targets = [];
-
-    try {
-        if (userType === 'normal') {
-            // Pass dependencies and config to core util
-            targets = await firestoreUtils.getNormalUsersToUpdate(dependencies, {
-                dateThreshold: thresholds.dateThreshold,
-                normalUserCollectionName: config.normalUserCollectionName,
-                normalUserTimestampsDocId: config.normalUserTimestampsDocId
-            });
-        } else if (userType === 'speculator') {
-            // Pass dependencies and config to core util
-            targets = await firestoreUtils.getSpeculatorsToUpdate(dependencies, {
-                dateThreshold: thresholds.dateThreshold, 
-                gracePeriodThreshold: thresholds.gracePeriodThreshold,
-                speculatorBlocksCollectionName: config.speculatorBlocksCollectionName
-            });
-        }
-        logger.log('SUCCESS', `[Orchestrator Helpers] Found ${targets.length} targets for ${userType} update.`);
-        return targets;
-    } catch (error) {
-         logger.log('ERROR', `[Orchestrator Helpers] Error getting update targets for ${userType}`, { errorMessage: error.message });
-         throw error;
-    }
-}
-
-/**
- * Sub-pipe: pipe.orchestrator.dispatchUpdates
- * @param {Array<any>} targets - Array of targets from getUpdateTargets.
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {object} config - The *global* updateConfig object.
- * @param {object} dependencies - Contains db, pubsub, logger, pubsubUtils.
- * @returns {Promise<void>}
- */
-async function dispatchUpdates(targets, userType, config, dependencies) {
-    const { logger, pubsubUtils } = dependencies;
-    const { dispatcherTopicName, taskBatchSize, pubsubBatchSize } = config;
-
-    if (targets.length === 0) {
-        logger.log('INFO', `[Orchestrator Helpers] No ${userType} update targets to dispatch.`);
-        return;
-    }
-    logger.log('INFO', `[Orchestrator Helpers] Dispatching ${targets.length} update tasks for ${userType} to ${dispatcherTopicName}...`);
-
-    const individualTasks = targets.map(target => ({
-        type: 'update',
-        userId: userType === 'normal' ? target : target.userId,
-        instrumentId: userType ==='speculator' ? target.instrumentId : undefined,
-        userType,
-    }));
-
-    const dispatcherMessages = [];
-    for (let i = 0; i < individualTasks.length; i += taskBatchSize) {
-        const batch = individualTasks.slice(i, i + taskBatchSize);
-        dispatcherMessages.push({ tasks: batch }); // Wrap the batch
-    }
-
-    try {
-        // Pass dependencies and config to core util
-        await pubsubUtils.batchPublishTasks(dependencies, {
-            topicName: dispatcherTopicName, 
-            tasks: dispatcherMessages, 
-            taskType: `${userType} update batch`,
-            maxPubsubBatchSize: pubsubBatchSize
-        });
-        logger.log('SUCCESS', `[Orchestrator Helpers] Published ${dispatcherMessages.length} messages (${individualTasks.length} tasks) for ${userType} updates to the dispatcher.`);
-    } catch (error) {
-        logger.log('ERROR', `[Orchestrator Helpers] Error dispatching update tasks for ${userType}`, { errorMessage: error.message });
-        throw error;
-    }
-}
-
-module.exports = {
-  getUpdateTargets,
-  dispatchUpdates,
-};
+/**
+ * @fileoverview Orchestrator's update sub-pipes.
+ * REFACTORED: All functions are now stateless and receive dependencies.
+ */
+
+/**
+ * Sub-pipe: pipe.orchestrator.getUpdateTargets
+ * @param {string} userType - 'normal' or 'speculator'.
+ * @param {object} thresholds - Contains date thresholds.
+ * @param {object} config - The *global* updateConfig object.
+ * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
+ * @returns {Promise<Array<any>>} Array of targets.
+ */
+async function getUpdateTargets(userType, thresholds, config, dependencies) {
+    const { logger, firestoreUtils } = dependencies;
+    logger.log('INFO', `[Orchestrator Helpers] Getting update targets for ${userType}...`);
+    let targets = [];
+
+    try {
+        if (userType === 'normal') {
+            // Pass dependencies and config to core util
+            targets = await firestoreUtils.getNormalUsersToUpdate(dependencies, {
+                dateThreshold: thresholds.dateThreshold,
+                normalUserCollectionName: config.normalUserCollectionName,
+                normalUserTimestampsDocId: config.normalUserTimestampsDocId
+            });
+        } else if (userType === 'speculator') {
+            // Pass dependencies and config to core util
+            targets = await firestoreUtils.getSpeculatorsToUpdate(dependencies, {
+                dateThreshold: thresholds.dateThreshold, 
+                gracePeriodThreshold: thresholds.gracePeriodThreshold,
+                speculatorBlocksCollectionName: config.speculatorBlocksCollectionName
+            });
+        }
+        logger.log('SUCCESS', `[Orchestrator Helpers] Found ${targets.length} targets for ${userType} update.`);
+        return targets;
+    } catch (error) {
+         logger.log('ERROR', `[Orchestrator Helpers] Error getting update targets for ${userType}`, { errorMessage: error.message });
+         throw error;
+    }
+}
+
+/**
+ * Sub-pipe: pipe.orchestrator.dispatchUpdates
+ * @param {Array<any>} targets - Array of targets from getUpdateTargets.
+ * @param {string} userType - 'normal' or 'speculator'.
+ * @param {object} config - The *global* updateConfig object.
+ * @param {object} dependencies - Contains db, pubsub, logger, pubsubUtils.
+ * @returns {Promise<void>}
+ */
+async function dispatchUpdates(targets, userType, config, dependencies) {
+    const { logger, pubsubUtils } = dependencies;
+    const { dispatcherTopicName, taskBatchSize, pubsubBatchSize } = config;
+
+    if (targets.length === 0) {
+        logger.log('INFO', `[Orchestrator Helpers] No ${userType} update targets to dispatch.`);
+        return;
+    }
+    logger.log('INFO', `[Orchestrator Helpers] Dispatching ${targets.length} update tasks for ${userType} to ${dispatcherTopicName}...`);
+
+    const individualTasks = targets.map(target => ({
+        type: 'update',
+        userId: userType === 'normal' ? target : target.userId,
+        instrumentId: userType ==='speculator' ? target.instrumentId : undefined,
+        userType,
+    }));
+
+    const dispatcherMessages = [];
+    for (let i = 0; i < individualTasks.length; i += taskBatchSize) {
+        const batch = individualTasks.slice(i, i + taskBatchSize);
+        dispatcherMessages.push({ tasks: batch }); // Wrap the batch
+    }
+
+    try {
+        // Pass dependencies and config to core util
+        await pubsubUtils.batchPublishTasks(dependencies, {
+            topicName: dispatcherTopicName, 
+            tasks: dispatcherMessages, 
+            taskType: `${userType} update batch`,
+            maxPubsubBatchSize: pubsubBatchSize
+        });
+        logger.log('SUCCESS', `[Orchestrator Helpers] Published ${dispatcherMessages.length} messages (${individualTasks.length} tasks) for ${userType} updates to the dispatcher.`);
+    } catch (error) {
+        logger.log('ERROR', `[Orchestrator Helpers] Error dispatching update tasks for ${userType}`, { errorMessage: error.message });
+        throw error;
+    }
+}
+
+module.exports = {
+  getUpdateTargets,
+  dispatchUpdates,
+};