bulltrackers-module 1.0.127 → 1.0.128

package/functions/orchestrator/helpers/discovery_helpers.js

@@ -1,8 +1,3 @@
-/*
- * FILENAME: CloudFunctions/NpmWrappers/bulltrackers-module/functions/orchestrator/helpers/discovery_helpers.js
- * (FIXED: Publishes 'discover' tasks in the correct batch format { tasks: [...] })
- */
-
 /**
  * @fileoverview Orchestrator's discovery sub-pipes.
  * REFACTORED: All functions are now stateless and receive dependencies.
@@ -18,46 +13,17 @@
 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 { 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
-    );
-
+    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}.`);
-    }
+    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 };
 }
 
@@ -72,89 +38,29 @@ async function checkDiscoveryNeed(userType, config, dependencies) {
 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 {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 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
-        );
+    const exclusionIds = await firestoreUtils.getExclusionIds(dependencies, {specBlocksCollection, pendingSpecCollection, normalUserCollection,invalidSpecCollection,existingNormalUserIds}, userType);
+    if (isSpeculator) {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 ---
+        prioritizedCandidates.forEach(cidStr => {if (dispatchedCids.size < maxTasksPerRun) {dispatchedCids.add(cidStr);}});
+        logger.log('INFO', `Added ${dispatchedCids.size} prioritized speculators.`);}
     let dispatchedRandomCidCount = 0;
     const initialDispatchedCount = dispatchedCids.size;
-
-    while ((dispatchedRandomCidCount + initialDispatchedCount) < maxRandomCidsToDiscover &&
-        dispatchedCids.size < maxTasksPerRun && blocksToFill.length > 0)
-    {
+    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++;
-            }
-        }
-    }
-
+        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; 
@@ -169,90 +75,36 @@ async function getDiscoveryCandidates(userType, blocksToFill, config, dependenci
  * @returns {Promise<void>}
  */
 async function dispatchDiscovery(userType, candidates, config, dependencies) {
-    const { logger, firestoreUtils, pubsubUtils, pubsub } = dependencies; // <-- Add pubsub
-    const {
-        topicName,
-        dispatchBatchSize,
-        pubsubBatchSize, // This is no longer used by this function
-        pendingSpecCollection, 
-        pendingMaxFieldsPerDoc,
-        pendingMaxWritesPerBatch
-    } = config;
-
-    if (candidates.size === 0) {
-        logger.log('INFO', `[Orchestrator Helpers] No ${userType} candidates to dispatch.`);
-        return;
-    }
+    const { logger, firestoreUtils, pubsubUtils, pubsub } = 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
-        });
-    }
-
+    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
-            });
-        }
-    }
-
-    // --- START FIX: RE-IMPLEMENT BATCHING LOGIC ---
+    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});}}
     const topic = pubsub.topic(topicName);
     let totalCidsPublished = 0;
     let messagesPublished = 0;
-
-    // 'tasks' is an array of 'discover' task objects. We group them into
-    // batches and publish each batch as a single message.
-    // We use `dispatchBatchSize` here to determine how many 'discover' tasks go into one message.
-    // This value should probably be small, like 1-10.
-    
-    // Let's re-use `dispatchBatchSize` as the number of *tasks* per message.
-    // If `tasks.length` is 200 and `dispatchBatchSize` is 50, this will create 4 messages.
-    // This seems correct.
-
     for (let i = 0; i < tasks.length; i += dispatchBatchSize) {
-        // This batch contains multiple 'discover' tasks
         const batchOfTasks = tasks.slice(i, i + dispatchBatchSize);
-        
-        // Wrap this batch in the new payload format
         const messagePayload = { tasks: batchOfTasks };
-
-        try {
-            await topic.publishMessage({ json: messagePayload });
-            
-            // Log the number of CIDs in this message
-            const cidsInThisMessage = batchOfTasks.reduce((acc, task) => acc + task.cids.length, 0);
-            totalCidsPublished += cidsInThisMessage;
-            messagesPublished++;
-            
-            logger.log('INFO', `[Orchestrator Helpers] Dispatched batch ${messagesPublished} with ${batchOfTasks.length} discover tasks (${cidsInThisMessage} CIDs) as 1 Pub/Sub message.`);
-        } catch (publishError) {
-            logger.log('ERROR', `[Orchestrator Helpers] Failed to publish discover batch ${messagesPublished + 1}.`, { error: publishError.message });
-        }
-    }
-    
-    logger.log('SUCCESS', `[Orchestrator Helpers] Dispatched ${totalCidsPublished} CIDs in ${tasks.length} tasks, grouped into ${messagesPublished} Pub/Sub messages for ${userType} discovery.`);
-    // --- END FIX ---
+    try {await topic.publishMessage({ json: messagePayload });
+        const cidsInThisMessage = batchOfTasks.reduce((acc, task) => acc + task.cids.length, 0);
+        totalCidsPublished += cidsInThisMessage;
+        messagesPublished++;
+        logger.log('INFO', `[Orchestrator Helpers] Dispatched batch ${messagesPublished} with ${batchOfTasks.length} discover tasks (${cidsInThisMessage} CIDs) as 1 Pub/Sub message.`);} 
+    catch (publishError) {
+        logger.log('ERROR', `[Orchestrator Helpers] Failed to publish discover batch ${messagesPublished + 1}.`, { error: publishError.message });}}
+        logger.log('SUCCESS', `[Orchestrator Helpers] Dispatched ${totalCidsPublished} CIDs in ${tasks.length} tasks, grouped into ${messagesPublished} Pub/Sub messages for ${userType} discovery.`);
 }
 
-
 module.exports = {
   checkDiscoveryNeed,
   getDiscoveryCandidates,

package/functions/orchestrator/helpers/update_helpers.js

@@ -15,29 +15,19 @@ 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;
-    }
+        if (userType === 'normal') { targets = await firestoreUtils.getNormalUsersToUpdate(dependencies,{
+        dateThreshold: thresholds.dateThreshold,
+        normalUserCollectionName: config.normalUserCollectionName,
+        normalUserTimestampsDocId: config.normalUserTimestampsDocId
+    }); } 
+    else if (userType === 'speculator') { 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; }
 }
 
 /**
@@ -51,42 +41,12 @@ async function getUpdateTargets(userType, thresholds, config, dependencies) {
 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,
-};
+    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) { dispatcherMessages.push({ tasks: individualTasks.slice(i, i + taskBatchSize) }); }
+        try { 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 };

package/functions/orchestrator/index.js

@@ -4,145 +4,66 @@
  * that are called by the Cloud Function entry points.
  * They receive all dependencies.
  */
-
 const { checkDiscoveryNeed, getDiscoveryCandidates, dispatchDiscovery } = require('./helpers/discovery_helpers');
 const { getUpdateTargets, dispatchUpdates } = require('./helpers/update_helpers');
 
-
-/**
- * Main pipe for running the complete discovery orchestration process.
- * This is the function the Cloud Function entry point will call.
- * @param {object} config - The full orchestratorConfig object.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils.
- * @returns {Promise<void>}
- */
-async function runDiscoveryOrchestrator(config, dependencies) {
-    const { logger, firestoreUtils } = dependencies;
-    logger.log('INFO', '🚀 Discovery Orchestrator triggered via module...');
-
-    // Call sub-pipe from core
-    await firestoreUtils.resetProxyLocks(dependencies, config);
-
-    // Call sub-pipe for 'normal'
-    // Pass the directly required sub-pipe functions implicitly via runDiscovery call context
-    await runDiscovery('normal', config.discoveryConfig.normal, config, dependencies);
-
-    // Call sub-pipe for 'speculator'
-    await runDiscovery('speculator', config.discoveryConfig.speculator, config, dependencies);
+/** Stage 1: Main discovery orchestrator pipe */
+async function runDiscoveryOrchestrator(config, deps) {
+    const { logger, firestoreUtils } = deps;
+    logger.log('INFO', '🚀 Discovery Orchestrator triggered...');
+    await firestoreUtils.resetProxyLocks(deps, config);
+    await runDiscovery('normal', config.discoveryConfig.normal, config, deps);
+    await runDiscovery('speculator', config.discoveryConfig.speculator, config, deps);
 }
 
-/**
- * Main pipe for running the complete update orchestration process.
- * This is the function the Cloud Function entry point will call.
- * @param {object} config - The full orchestratorConfig object.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils, pubsubUtils.
- * @returns {Promise<void>}
- */
-async function runUpdateOrchestrator(config, dependencies) {
-    const { logger, firestoreUtils } = dependencies;
-    logger.log('INFO', '🚀 Update Orchestrator triggered via module...');
-
-    // Call sub-pipe from core
-    await firestoreUtils.resetProxyLocks(dependencies, config);
-
-    // Call sub-pipe for 'normal'
-    await runUpdates('normal', config.updateConfig, config, dependencies);
-
-    // Call sub-pipe for 'speculator'
-    await runUpdates('speculator', config.updateConfig, config, dependencies);
+/** Stage 2: Main update orchestrator pipe */
+async function runUpdateOrchestrator(config, deps) {
+    const { logger, firestoreUtils } = deps;
+    logger.log('INFO', '🚀 Update Orchestrator triggered...');
+    await firestoreUtils.resetProxyLocks(deps, config);
+    await runUpdates('normal', config.updateConfig, config, deps);
+    await runUpdates('speculator', config.updateConfig, config, deps);
 }
 
-// --- Internal Helpers (which are also exposed as sub-pipes) ---
-
-/**
- * Runs the discovery process for a *single* user type.
- * This is an internal helper, but also maps to pipe.orchestrator.runDiscovery
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {object} userTypeConfig - The specific config slice (e.g., config.discoveryConfig.normal).
- * @param {object} globalConfig - Global config.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils, pubsubUtils.
- */
-async function runDiscovery(userType, userTypeConfig, globalConfig, dependencies) {
-    const { logger } = dependencies;
-    logger.log('INFO', `[Module Orchestrator] Starting discovery for ${userType} users...`);
-
-    // --- 3. Use the directly required functions ---
-    // 1. pipe.orchestrator.checkDiscoveryNeed -> becomes checkDiscoveryNeed
-    const { needsDiscovery, blocksToFill } = await checkDiscoveryNeed(
-        userType,
-        userTypeConfig,
-        dependencies
-    );
+/** Stage 3: Run discovery for a single user type */
+async function runDiscovery(userType, userConfig, globalConfig, deps) {
+    const { logger } = deps;
+    logger.log('INFO', `[Orchestrator] Starting discovery for ${userType} users...`);
 
-    if (!needsDiscovery) {
-        logger.log('INFO', `[Module Orchestrator] No discovery needed for ${userType}.`);
-        return;
-    }
+    // Step 3.1: Check if discovery is needed
+    const { needsDiscovery, blocksToFill } = await checkDiscoveryNeed(userType, userConfig, deps);
+    if (!needsDiscovery) { logger.log('INFO', `[Orchestrator] No discovery needed for ${userType}.`); return; }
 
-    // 2. pipe.orchestrator.getDiscoveryCandidates -> becomes getDiscoveryCandidates
-    const candidates = await getDiscoveryCandidates(
-        userType,
-        blocksToFill,
-        userTypeConfig,
-        dependencies
-    );
+    // Step 3.2: Get discovery candidates
+    const candidates = await getDiscoveryCandidates(userType, blocksToFill, userConfig, deps);
 
-    // 3. pipe.orchestrator.dispatchDiscovery -> becomes dispatchDiscovery
-    await dispatchDiscovery(
-        userType,
-        candidates,
-        userTypeConfig,
-        dependencies
-    );
-
-    logger.log('SUCCESS', `[Module Orchestrator] Dispatched discovery tasks for ${userType}.`);
+    // Step 3.3: Dispatch discovery tasks
+    await dispatchDiscovery(userType, candidates, userConfig, deps);
+    logger.log('SUCCESS', `[Orchestrator] Dispatched discovery tasks for ${userType}.`);
 }
 
-/**
- * Runs the update process for a *single* user type.
- * This is an internal helper, but also maps to pipe.orchestrator.runUpdates
- * @param {string} userType - 'normal' or 'speculator'.
- * @param {object} updateConfig - The config.updateConfig object.
- * @param {object} globalConfig - Global config.
- * @param {object} dependencies - Contains db, pubsub, logger, firestoreUtils, pubsubUtils.
- */
-async function runUpdates(userType, updateConfig, globalConfig, dependencies) {
-    const { logger } = dependencies;
-    logger.log('INFO', `[Module Orchestrator] Collecting users for daily update (${userType})...`);
+/** Stage 4: Run updates for a single user type */
+async function runUpdates(userType, updateConfig, globalConfig, deps) {
+    const { logger } = deps;
+    logger.log('INFO', `[Orchestrator] Collecting users for daily update (${userType})...`);
 
+    // Step 4.1: Compute thresholds
     const now = new Date();
     const startOfTodayUTC = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
     const DaysAgoUTC = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    const thresholds = { dateThreshold: startOfTodayUTC, gracePeriodThreshold: DaysAgoUTC };
 
-    const thresholds = {
-        dateThreshold: startOfTodayUTC,
-        gracePeriodThreshold: DaysAgoUTC
-    };
-
-    // --- 4. Use the directly required functions ---
-    // 1. pipe.orchestrator.getUpdateTargets -> becomes getUpdateTargets
-    const targets = await getUpdateTargets(
-        userType,
-        thresholds,
-        updateConfig,
-        dependencies
-    );
-
-    // 2. pipe.orchestrator.dispatchUpdates -> becomes dispatchUpdates
-    await dispatchUpdates(
-        targets,
-        userType,
-        updateConfig,
-        dependencies
-    );
+    // Step 4.2: Get update targets
+    const targets = await getUpdateTargets(userType, thresholds, updateConfig, deps);
 
-    logger.log('SUCCESS', `[Module Orchestrator] Dispatched update tasks for ${userType}.`);
+    // Step 4.3: Dispatch update tasks
+    await dispatchUpdates(targets, userType, updateConfig, deps);
+    logger.log('SUCCESS', `[Orchestrator] Dispatched update tasks for ${userType}.`);
 }
 
 module.exports = {
-  runDiscoveryOrchestrator,
-  runUpdateOrchestrator,
-  // Exporting these internal helpers so the main index.js can map them
-  runDiscovery,
-  runUpdates
-};
+    runDiscoveryOrchestrator,
+    runUpdateOrchestrator,
+    runDiscovery,
+    runUpdates
+};