bulltrackers-module 1.0.731 → 1.0.733

package/functions/computation-system/helpers/computation_dispatcher.js

@@ -1,750 +0,0 @@
-/**
- * V2 TO REPLACE THE OLD.
- * FILENAME: computation-system/helpers/computation_dispatcher.js
- * PURPOSE: Sequential Cursor-Based Dispatcher (Refactored & Condensed).
- * UPDATED: Added SNAPSHOT handling.
- */
-
-const { getExpectedDateStrings, getEarliestDataDates, normalizeName, DEFINITIVE_EARLIEST_DATES } = require('../utils/utils.js');
-const { groupByPass, analyzeDateExecution } = require('../WorkflowOrchestrator.js');
-const { PubSubUtils } = require('../../core/utils/pubsub_utils');
-const { fetchComputationStatus } = require('../persistence/StatusRepository');
-const { checkRootDataAvailability } = require('../data/AvailabilityChecker');
-const { runFinalSweepCheck } = require('../tools/FinalSweepReporter');
-const { resolveDependencyChain } = require('./on_demand_helpers'); 
-const { checkRootDependencies } = require('../data/AvailabilityChecker');
-// 1. IMPORT SNAPSHOT SERVICE
-const { generateDailySnapshots } = require('../services/SnapshotService');
-const crypto = require('crypto');
-// Import Google Auth Library for OAuth 2.0 authentication
-let GoogleAuth = null;
-try {
-    GoogleAuth = require('google-auth-library').GoogleAuth;
-} catch (e) {
-    // google-auth-library might not be installed, will handle gracefully
-}
-
-const BASE_SECONDS_PER_WEIGHT_UNIT = 3;
-const SESSION_CACHE_DURATION_MS = 1000 * 60 * 30; // 30 Minutes
-const STALE_LOCK_THRESHOLD_MS = 1000 * 60 * 15;
-
-/**
- * Helper function to send an authenticated callback to Cloud Workflows
- * Uses OAuth 2.0 access token from the default service account
- */
-async function sendAuthenticatedCallback(callbackUrl, payload, logger, directFetch) {
-    if (!GoogleAuth) {
-        throw new Error('google-auth-library is required for authenticated callbacks. Please install: npm install google-auth-library');
-    }
-    
-    try {
-        // Get OAuth 2.0 access token using default service account credentials
-        const auth = new GoogleAuth({
-            scopes: ['https://www.googleapis.com/auth/cloud-platform']
-        });
-        const accessToken = await auth.getAccessToken();
-        
-        if (!accessToken) {
-            throw new Error('Failed to obtain OAuth 2.0 access token');
-        }
-        
-        logger.log('INFO', '[Dispatcher] ✅ Obtained OAuth 2.0 access token for callback');
-        
-        // Add timeout to prevent hanging (30 seconds should be plenty for a callback)
-        const timeoutPromise = new Promise((_, reject) => 
-            setTimeout(() => reject(new Error('Callback timeout after 30s')), 30000)
-        );
-        
-        const fetchPromise = directFetch(callbackUrl, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${accessToken}`
-            },
-            body: JSON.stringify(payload)
-        });
-        
-        const response = await Promise.race([fetchPromise, timeoutPromise]);
-        
-        if (!response.ok) {
-            const errorText = await response.text().catch(() => 'Unable to read response');
-            throw new Error(`Callback returned non-OK status: ${response.status} ${response.statusText}. Response: ${errorText.substring(0, 200)}`);
-        }
-        
-        logger.log('INFO', `[Dispatcher] ✅ Callback sent successfully (status: ${response.status})`);
-        return response;
-    } catch (err) {
-        logger.log('ERROR', `[Dispatcher] Authenticated callback failed: ${err.message}. Stack: ${err.stack?.substring(0, 300)}`);
-        throw err;
-    }
-}
-
-
-function getMillis(field) {
-    if (!field) return 0;
-    if (field.toDate && typeof field.toDate === 'function') return field.toDate().getTime();
-    const date = new Date(field);
-    return isNaN(date.getTime()) ? 0 : date.getTime();
-}
-
-function isComputationScheduled(dateStr, scheduleConfig) {
-    if (!scheduleConfig || !scheduleConfig.type || scheduleConfig.type === 'DAILY') return true;
-    const date = new Date(dateStr + 'T00:00:00Z');
-    
-    if (scheduleConfig.type === 'WEEKLY') {
-        const days = Array.isArray(scheduleConfig.days) ? scheduleConfig.days : [scheduleConfig.day];
-        return days.includes(date.getUTCDay());
-    }
-    if (scheduleConfig.type === 'MONTHLY') {
-        const days = Array.isArray(scheduleConfig.days) ? scheduleConfig.days : [scheduleConfig.day];
-        return days.includes(date.getUTCDate());
-    }
-    return true;
-}
-
-function createTaskPayload(task, date, pass, dispatchId, resources, triggerReason) {
-    return {
-        action: 'RUN_COMPUTATION_DATE',
-        computation: task.name || task.computation,
-        date: date,
-        pass: pass,
-        dispatchId: dispatchId,
-        triggerReason: triggerReason || task.reason || 'DISPATCH',
-        resources: resources || task.resources || 'standard',
-        hash: task.hash,
-        traceContext: {
-            traceId: crypto.randomBytes(16).toString('hex'),
-            spanId: crypto.randomBytes(8).toString('hex'),
-            sampled: true
-        }
-    };
-}
-
-async function assessDateRunnability(date, computations, config, dependencies, manifestMap) {
-    const { status: rootStatus } = await checkRootDataAvailability(date, config, dependencies, DEFINITIVE_EARLIEST_DATES) || {};
-    if (!rootStatus) return null;
-
-    const dailyStatus = await fetchComputationStatus(date, config, dependencies);
-    
-    let prevDailyStatus = null;
-    if (computations.some(c => c.isHistorical)) {
-        const prevD = new Date(date + 'T00:00:00Z');
-        prevD.setUTCDate(prevD.getUTCDate() - 1);
-        const earliest = (await getEarliestDataDates(config, dependencies)).absoluteEarliest;
-        if (prevD >= earliest) {
-            prevDailyStatus = await fetchComputationStatus(prevD.toISOString().slice(0, 10), config, dependencies);
-        }
-    }
-
-    const report = analyzeDateExecution(date, computations, rootStatus, dailyStatus, manifestMap, prevDailyStatus);
-    return { report, dailyStatus };
-}
-
-async function publishTaskBatch(dependencies, config, tasks, pass, topicOverride = null) {
-    if (tasks.length === 0) return 0;
-    
-    const { logger } = dependencies;
-    const pubsubUtils = new PubSubUtils(dependencies);
-    const isHighMem = topicOverride ? topicOverride.includes('highmem') : tasks[0].resources === 'high-mem';
-    const topic = topicOverride || (isHighMem ? config.computationTopicHighMem : config.computationTopicStandard) 
-                  || (isHighMem ? 'computation-tasks-highmem' : 'computation-tasks');
-
-    const names = tasks.map(t => t.computation).join(', ');
-    logger.log('INFO', `[Dispatcher] 📤 Dispatching ${tasks.length} tasks to ${topic}: ${names.slice(0, 100)}...`);
-
-    const CHUNK_SIZE = 250;
-    const chunks = [];
-    for (let i = 0; i < tasks.length; i += CHUNK_SIZE) chunks.push(tasks.slice(i, i + CHUNK_SIZE));
-
-    for (const chunk of chunks) {
-        await pubsubUtils.batchPublishTasks(dependencies, {
-            topicName: topic,
-            tasks: chunk,
-            taskType: `pass-${pass}-${isHighMem ? 'high' : 'std'}`
-        });
-    }
-    return tasks.length;
-}
-
-async function getStableDateSession(config, dependencies, pass, dateLimitStr, forceRebuild) {
-    const { db, logger } = dependencies;
-    const sessionId = `pass_${pass}_${dateLimitStr.replace(/-/g, '')}`;
-    const sessionRef = db.collection('dispatcher_sessions').doc(sessionId);
-
-    if (!forceRebuild) {
-        const snap = await sessionRef.get();
-        if (snap.exists && (Date.now() - new Date(snap.data().createdAt).getTime()) < SESSION_CACHE_DURATION_MS) {
-            return snap.data().dates;
-        }
-    }
-
-    logger.log('INFO', `[Session] 🔄 Rebuilding dispatch session for Pass ${pass}...`);
-    const earliest = await getEarliestDataDates(config, dependencies);
-    const dates = getExpectedDateStrings(earliest.absoluteEarliest, new Date(dateLimitStr + 'T00:00:00Z'));
-    await sessionRef.set({ dates, createdAt: new Date().toISOString(), configHash: dateLimitStr });
-    return dates;
-}
-
-// =============================================================================
-// HANDLERS
-// =============================================================================
-
-// 2. NEW SNAPSHOT HANDLER (Asynchronous with Callback)
-async function handleSnapshot(config, dependencies, reqBody) {
-    const { logger } = dependencies;
-    const targetDate = reqBody.date; // Optional: if provided, only process up to this date
-    const callbackUrl = reqBody.callback_url; // Callback URL from workflow
-    
-    logger.log('INFO', `[Dispatcher] 📸 Snapshot request received. Date: ${targetDate || 'all'}, Callback URL: ${callbackUrl || 'NOT PROVIDED'}`);
-    
-    // Use native fetch if available (Node 18+), otherwise fall back to node-fetch
-    const directFetch = typeof fetch !== 'undefined' ? fetch : require('node-fetch');
-    
-    try {
-        // Get earliest available root data date
-        const earliestDates = await getEarliestDataDates(config, dependencies);
-        const earliestDate = earliestDates.absoluteEarliest;
-        
-        if (!earliestDate) {
-            throw new Error('Could not determine earliest available root data date');
-        }
-        
-        // Determine end date: use targetDate if provided, otherwise use today
-        const endDate = targetDate ? new Date(targetDate + 'T00:00:00Z') : new Date();
-        endDate.setUTCHours(0, 0, 0, 0);
-        
-        // Generate all dates from earliest to end date
-        const startDate = new Date(earliestDate);
-        startDate.setUTCHours(0, 0, 0, 0);
-        
-        const dateStrings = getExpectedDateStrings(startDate, endDate);
-        
-        if (dateStrings.length === 0) {
-            logger.log('WARN', '[Dispatcher] No dates to process for snapshot');
-            const finalResult = { status: 'OK', processed: 0, skipped: 0 };
-            
-            // Send callback if provided
-            if (callbackUrl) {
-                logger.log('INFO', `[Dispatcher] 📞 Calling back Workflow at: ${callbackUrl}`);
-                try {
-                    await sendAuthenticatedCallback(callbackUrl, finalResult, logger, directFetch);
-                } catch (err) {
-                    logger.log('ERROR', `[Dispatcher] Callback failed: ${err.message}`);
-                }
-            } else {
-                logger.log('WARN', '[Dispatcher] No callback URL provided, workflow will not be notified');
-            }
-            
-            return finalResult;
-        }
-        
-        logger.log('INFO', `[Dispatcher] 📸 Processing snapshots for ${dateStrings.length} dates from ${dateStrings[0]} to ${dateStrings[dateStrings.length - 1]}`);
-        
-        // Process each date (snapshot service will skip if already exists)
-        const results = [];
-        const BATCH_SIZE = 5; // Process 5 dates in parallel to avoid overwhelming the system
-        
-        for (let i = 0; i < dateStrings.length; i += BATCH_SIZE) {
-            const batch = dateStrings.slice(i, i + BATCH_SIZE);
-            const batchResults = await Promise.allSettled(
-                batch.map(dateStr => generateDailySnapshots(dateStr, config, dependencies))
-            );
-            
-            batchResults.forEach((result, idx) => {
-                const dateStr = batch[idx];
-                if (result.status === 'fulfilled') {
-                    const value = result.value;
-                    results.push({ date: dateStr, status: value.status || 'OK' });
-                } else {
-                    logger.log('ERROR', `[Dispatcher] Snapshot failed for ${dateStr}: ${result.reason?.message || result.reason}`);
-                    results.push({ date: dateStr, status: 'ERROR', error: result.reason?.message || String(result.reason) });
-                }
-            });
-        }
-        
-        const successful = results.filter(r => r.status === 'OK').length;
-        const skipped    = results.filter(r => r.status === 'SKIPPED').length;
-        const failed     = results.filter(r => r.status === 'ERROR').length;
-        
-        logger.log('INFO', `[Dispatcher] 📸 Snapshot batch complete: ${successful} processed, ${skipped} skipped, ${failed} failed out of ${results.length} total`);
-        
-        const finalResult = { 
-            status: failed === 0 ? 'OK' : 'PARTIAL', 
-            processed: successful,
-            skipped: skipped,
-            failed: failed,
-            total: results.length,
-            results: results
-        };
-        
-        // Send callback to workflow if provided
-        if (callbackUrl) {
-            logger.log('INFO', `[Dispatcher] 📞 Calling back Workflow at: ${callbackUrl}`);
-            try {
-                await sendAuthenticatedCallback(callbackUrl, finalResult, logger, directFetch);
-            } catch (err) {
-                logger.log('ERROR', `[Dispatcher] Callback failed: ${err.message}`);
-            }
-        } else {
-            logger.log('WARN', '[Dispatcher] No callback URL provided, workflow will not be notified');
-        }
-        
-        return finalResult;
-    } catch (e) {
-        logger.log('ERROR', `[Dispatcher] Snapshot failed: ${e.message}`);
-        const errorResult = { status: 'ERROR', error: e.message };
-        
-        // Notify workflow of failure too, otherwise it hangs!
-        if (callbackUrl) {
-            logger.log('INFO', `[Dispatcher] 📞 Calling back Workflow with error at: ${callbackUrl}`);
-            try {
-                await sendAuthenticatedCallback(callbackUrl, errorResult, logger, directFetch);
-            } catch (err) {
-                logger.log('ERROR', `[Dispatcher] Error callback failed: ${err.message}`);
-            }
-        } else {
-            logger.log('WARN', '[Dispatcher] No callback URL provided, workflow will not be notified of error');
-        }
-        
-        return errorResult;
-    }
-}
-
-async function handleForceRun(config, dependencies, computationManifest, reqBody) {
-    const { logger } = dependencies;
-    const computationName = reqBody.computation;
-    const dateInput = reqBody.date; 
-    
-    if (!computationName) throw new Error('Force Run requires "computation" name.');
-
-    const manifestItem = computationManifest.find(c => normalizeName(c.name) === normalizeName(computationName));
-    if (!manifestItem) throw new Error(`Computation '${computationName}' not found.`);
-
-    // --- STEP 1: RESOLVE FULL ANCESTRY ---
-    // We get the full chain of dependencies (ancestors) for the target.
-    // This includes the target itself and all upstream computations.
-    const chainPasses = resolveDependencyChain(computationName, computationManifest);
-    const allAncestors = chainPasses.flatMap(p => p.computations); // Flat list of all required names
-    
-    // Create a map for quick lookup of ancestor manifests
-    const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-
-    // --- STEP 2: DETERMINE CANDIDATE DATES ---
-    let candidateDates = [];
-    if (dateInput) {
-        candidateDates = [dateInput];
-    } else {
-        logger.log('INFO', `[ForceRun] No date provided. Calculating date range for ${computationName}...`);
-        const earliest = await getEarliestDataDates(config, dependencies);
-        candidateDates = getExpectedDateStrings(earliest.absoluteEarliest, new Date());
-    }
-    
-    logger.log('INFO', `[ForceRun] Checking ${candidateDates.length} candidate dates for runnability (Deep Check)...`);
-
-    const runnableDates = [];
-    const skippedDates = [];
-    const targetComputationNormalized = normalizeName(computationName);
-    // Remove schedule constraints for the force run assessment
-    const targetComp = { ...manifestItem, schedule: null }; 
-
-    for (const date of candidateDates) {
-        // --- STEP 3: DEEP ROOT CHECK ---
-        // Before even asking if the *target* is runnable, we ask:
-        // "Are the raw ingredients available for the ENTIRE chain?"
-        
-        // Fetch Root Data Status for this date once
-        const availability = await checkRootDataAvailability(date, config, dependencies, DEFINITIVE_EARLIEST_DATES);
-        const rootStatus = availability ? availability.status : null;
-
-        if (!rootStatus) {
-            skippedDates.push({ date, reason: 'Availability Index Missing' });
-            continue;
-        }
-
-        let deepImpossibleReason = null;
-        
-        // Check EVERY ancestor's root requirements
-        for (const ancName of allAncestors) {
-            const ancManifest = manifestMap.get(normalizeName(ancName));
-            if (!ancManifest) continue;
-            
-            // Re-use the standard checker for each ancestor
-            const ancCheck = checkRootDependencies(ancManifest, rootStatus);
-            
-            if (!ancCheck.canRun) {
-                // If an ancestor cannot exist, the target cannot exist.
-                deepImpossibleReason = `Ancestor '${ancName}' is missing roots: ${ancCheck.missing.join(', ')}`;
-                break;
-            }
-        }
-
-        if (deepImpossibleReason) {
-            // Skip this date entirely - it is strictly impossible.
-            skippedDates.push({ date, reason: deepImpossibleReason });
-            continue;
-        }
-
-        // --- STEP 4: STANDARD RUNNABILITY ---
-        // If deep roots are fine, we proceed to the standard check.
-        // This handles logic like "Waiting for yesterday" or "Already Complete"
-        const result = await assessDateRunnability(date, [targetComp], config, dependencies, manifestMap);
-        
-        if (!result) { 
-             skippedDates.push({ date, reason: 'Assessment Failed' }); 
-             continue; 
-        }
-
-        const { report } = result;
-        const isRunnable = report.runnable.some(t => normalizeName(t.name) === targetComputationNormalized);
-        const needsReRun = report.reRuns.some(t => normalizeName(t.name) === targetComputationNormalized);
-        const hasFailedDep = report.failedDependency.some(t => normalizeName(t.name) === targetComputationNormalized);
-        const isSkipped = report.skipped.some(t => normalizeName(t.name) === targetComputationNormalized);
-        
-        // NOTE: hasFailedDep is ALLOWED here because we are "Forcing" it.
-        // We know the roots exist (checked above), so the missing dependency is likely just 
-        // "Not Computed Yet", which is exactly what the user wants to fix manually.
-        if (isRunnable || needsReRun || hasFailedDep || isSkipped) {
-            runnableDates.push(date);
-        } else if (report.blocked.length > 0) {
-            // Blocked usually means "Waiting for yesterday"
-            // For force runs, we often want to override this, but if it's strictly blocked 
-            // by logic, we might still count it. Usually, we treat it as runnable.
-            runnableDates.push(date);
-        } else {
-             const imp = report.impossible.find(t => normalizeName(t.name) === targetComputationNormalized);
-             skippedDates.push({ date, reason: imp ? imp.reason : 'Unknown State' });
-        }
-    }
-    
-    // ... (Remainder of the function remains the same: dispatching tasks) ...
-    
-    logger.log('INFO', `[ForceRun] ✅ Found ${runnableDates.length} runnable dates out of ${candidateDates.length} candidates`);
-
-    if (runnableDates.length === 0) {
-        return {
-            status: 'NO_RUNNABLE_DATES',
-            computation: computationName,
-            mode: dateInput ? 'SINGLE_DATE' : 'ALL_DATES',
-            datesChecked: candidateDates.length,
-            datesRunnable: 0,
-            skippedReasons: skippedDates.slice(0, 10)
-        };
-    }
-    
-    // Dispatch Logic
-    const topic = (reqBody.resources === 'high-mem') 
-        ? (config.computationTopicHighMem || 'computation-tasks-highmem')
-        : (config.computationTopicStandard || 'computation-tasks');
-
-    const dispatchId = require('crypto').randomUUID();
-    const tasks = runnableDates.map(date => 
-        createTaskPayload(manifestItem, date, manifestItem.pass || "1", dispatchId, reqBody.resources, 'MANUAL_FORCE_API')
-    );
-    
-    const dispatchedCount = await publishTaskBatch(dependencies, config, tasks, manifestItem.pass || "1", topic);
-
-    return { 
-        status: 'FORCED', 
-        computation: computationName,
-        mode: dateInput ? 'SINGLE_DATE' : 'ALL_DATES',
-        datesChecked: candidateDates.length,
-        datesRunnable: runnableDates.length,
-        datesTriggered: dispatchedCount,
-        skippedCount: skippedDates.length,
-        targetTopic: topic
-    };
-}
-
-async function handlePassVerification(config, dependencies, computationManifest, reqBody) {
-    const { logger } = dependencies;
-    const pass = String(reqBody.pass || "1");
-    const dateLimit = reqBody.date || "2025-01-01";
-    
-    logger.log('INFO', `[Verify] 🧹 Sweeping Pass ${pass} for unfinished work...`);
-    
-    const sessionDates = await getStableDateSession(config, dependencies, pass, dateLimit, false);
-    const passComputations = groupByPass(computationManifest)[pass] || [];
-    const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-    const weightMap = new Map(computationManifest.map(c => [normalizeName(c.name), c.weight || 1.0]));
-
-    const missingTasks = [];
-
-    for (const date of sessionDates) {
-        const scheduled = passComputations.filter(c => isComputationScheduled(date, c.schedule));
-        if (scheduled.length === 0) continue;
-
-        const result = await assessDateRunnability(date, scheduled, config, dependencies, manifestMap);
-        if (!result) continue;
-
-        const pending = [...result.report.runnable, ...result.report.reRuns];
-        
-        if (pending.length > 0) {
-            const totalWeight = pending.reduce((sum, t) => sum + (weightMap.get(normalizeName(t.name)) || 1.0), 0);
-            const eta = Math.max(30, Math.ceil(totalWeight * BASE_SECONDS_PER_WEIGHT_UNIT));
-            
-            missingTasks.push({ date, taskCount: pending.length, eta });
-        }
-    }
-
-    logger.log('INFO', `[Verify] Found ${missingTasks.length} dates with pending work.`);
-    return { missingTasks };
-}
-
-async function handleSweepDispatch(config, dependencies, computationManifest, reqBody) {
-    const { logger, db } = dependencies;
-    const pass = String(reqBody.pass || "1");
-    const date = reqBody.date;
-    if (!date) throw new Error('Sweep dispatch requires date');
-
-    const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-    const calculations = groupByPass(computationManifest)[pass] || [];
-    const scheduled = calculations.filter(c => isComputationScheduled(date, c.schedule));
-
-    if (!scheduled.length) return { dispatched: 0 };
-
-    const result = await assessDateRunnability(date, scheduled, config, dependencies, manifestMap);
-    if (!result) return { dispatched: 0 };
-    
-    const pending = [...result.report.runnable, ...result.report.reRuns];
-    const validTasks = [];
-
-    for (const task of pending) {
-        const ledgerPath = `computation_audit_ledger/${date}/passes/${pass}/tasks/${normalizeName(task.name)}`;
-        const doc = await db.doc(ledgerPath).get();
-        
-        if (doc.exists) {
-            const data = doc.data();
-            const isActive = ['PENDING', 'IN_PROGRESS'].includes(data.status);
-            
-            if (isActive) {
-                const lastActivity = getMillis(data.telemetry?.lastHeartbeat) || getMillis(data.startedAt);
-                if ((Date.now() - lastActivity) < STALE_LOCK_THRESHOLD_MS) continue; 
-                logger.log('WARN', `[Sweep] 🧟 Breaking ZOMBIE lock for ${task.name}`);
-            }
-            if (['QUALITY_CIRCUIT_BREAKER', 'SEMANTIC_GATE'].includes(data.error?.stage) && data.hash === task.hash) {
-                continue;
-            }
-        }
-        validTasks.push(task);
-    }
-
-    const dispatchId = crypto.randomUUID();
-    const tasksPayload = validTasks.map(t => 
-        createTaskPayload(t, date, pass, dispatchId, 'high-mem', 'SWEEP_RECOVERY')
-    );
-
-    return { dispatched: await publishTaskBatch(dependencies, config, tasksPayload, pass, config.computationTopicHighMem) };
-}
-
-async function handleStandardDispatch(config, dependencies, computationManifest, reqBody) {
-    const { logger, db } = dependencies;
-    const pass = String(reqBody.pass || "1");
-    const dateLimit = reqBody.date || "2025-01-01";
-    const targetCursorN = parseInt(reqBody.cursorIndex || 1);
-
-    const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-    const passComputations = groupByPass(computationManifest)[pass] || [];
-    const manifestWeightMap = new Map(computationManifest.map(c => [normalizeName(c.name), c.weight || 1.0]));
-    const sessionDates = await getStableDateSession(config, dependencies, pass, dateLimit, reqBody.forceRebuild);
-
-    if (!passComputations.length || !sessionDates || targetCursorN > sessionDates.length) {
-        return { status: 'MOVE_TO_NEXT_PASS', dispatched: 0 };
-    }
-
-    const MAX_SCAN = 50;
-    const TIME_LIMIT = 40000;
-    const startT = Date.now();
-    
-    let currentCursor = targetCursorN;
-    let tasksToDispatch = [];
-    let processedDate = null;
-    let scanned = 0;
-
-    while (currentCursor <= sessionDates.length) {
-        scanned++;
-        processedDate = sessionDates[currentCursor - 1];
-
-        if ((Date.now() - startT) > TIME_LIMIT || scanned > MAX_SCAN) {
-            logger.log('INFO', `[Dispatcher] ⏩ Fast-forward paused at ${processedDate} after scanning ${scanned} dates.`);
-            break;
-        }
-
-        const scheduled = passComputations.filter(c => isComputationScheduled(processedDate, c.schedule));
-        if (scheduled.length === 0) {
-            currentCursor++; 
-            continue;
-        }
-
-        const result = await assessDateRunnability(processedDate, scheduled, config, dependencies, manifestMap);
-        if (result && (result.report.runnable.length > 0 || result.report.reRuns.length > 0)) {
-            let candidates = await attemptSimHashResolution(dependencies, processedDate, [...result.report.runnable, ...result.report.reRuns], result.dailyStatus, manifestMap);
-            const { standard, highMem } = await resolveRoutes(db, processedDate, pass, candidates, logger);
-            tasksToDispatch = [...standard, ...highMem];
-
-            if (tasksToDispatch.length > 0) break; 
-        }
-        currentCursor++;
-    }
-
-    if (currentCursor > sessionDates.length && tasksToDispatch.length === 0) {
-        return {
-            status: 'CONTINUE_PASS',
-            dateProcessed: processedDate,
-            dispatched: 0,
-            n_cursor_ignored: false,
-            remainingDates: 0,
-            nextCursor: currentCursor 
-        };
-    }
-
-    if (tasksToDispatch.length === 0) {
-        return {
-            status: 'CONTINUE_PASS',
-            dateProcessed: processedDate,
-            dispatched: 0,
-            n_cursor_ignored: false,
-            remainingDates: sessionDates.length - currentCursor + 1,
-            nextCursor: currentCursor 
-        };
-    }
-
-    const totalWeight = tasksToDispatch.reduce((sum, t) => sum + (manifestWeightMap.get(normalizeName(t.name)) || 1.0), 0);
-    const etaSeconds = Math.max(20, Math.ceil(totalWeight * BASE_SECONDS_PER_WEIGHT_UNIT));
-
-    if (scanned > 1) {
-        logger.log('INFO', `[Dispatcher] ⏩ Fast-forwarded ${scanned - 1} empty dates. Dispatching ${tasksToDispatch.length} tasks for ${processedDate}.`);
-    } else {
-        logger.log('INFO', `[Dispatcher] ✅ Dispatching ${tasksToDispatch.length} tasks for ${processedDate}.`);
-    }
-
-    const dispatchId = crypto.randomUUID();
-    const standardPayload = tasksToDispatch.filter(t => t.resources !== 'high-mem').map(t => createTaskPayload(t, processedDate, pass, dispatchId, 'standard', t.reason));
-    const highMemPayload  = tasksToDispatch.filter(t => t.resources === 'high-mem').map(t => createTaskPayload(t, processedDate, pass, dispatchId, 'high-mem', t.reason));
-
-    await Promise.all([
-        publishTaskBatch(dependencies, config, standardPayload, pass),
-        publishTaskBatch(dependencies, config, highMemPayload, pass)
-    ]);
-
-    return {
-        status: 'CONTINUE_PASS',
-        dateProcessed: processedDate,
-        dispatched: tasksToDispatch.length,
-        n_cursor_ignored: false,
-        etaSeconds: etaSeconds,
-        remainingDates: sessionDates.length - targetCursorN,
-        nextCursor: currentCursor + 1 
-    };
-}
-
-// =============================================================================
-// LOGIC: Resolution & Routing
-// =============================================================================
-
-async function attemptSimHashResolution(dependencies, date, tasks, dailyStatus, manifestMap) {
-    const { db, logger } = dependencies;
-    const resolved = [], remaining = [];
-    const hashCache = new Map();
-
-    for (const task of tasks) {
-        const status = dailyStatus ? dailyStatus[task.name] : null;
-        const manifest = manifestMap.get(normalizeName(task.name));
-        
-        if (status?.simHash && manifest) {
-            let knownSimHash = hashCache.get(manifest.hash);
-            if (!knownSimHash) {
-                const doc = await db.collection('system_simhash_registry').doc(manifest.hash).get();
-                if (doc.exists) {
-                    knownSimHash = doc.data().simHash;
-                    hashCache.set(manifest.hash, knownSimHash);
-                }
-            }
-            if (knownSimHash === status.simHash) {
-                resolved.push({ name: task.name, hash: manifest.hash, simHash: knownSimHash, prevStatus: status });
-                continue;
-            }
-        }
-        remaining.push(task);
-    }
-    
-    if (resolved.length) {
-        const updates = {};
-        resolved.forEach(t => updates[t.name] = { ...t.prevStatus, hash: t.hash, simHash: t.simHash, reason: 'SimHash Auto-Resolve', lastUpdated: new Date().toISOString() });
-        await db.collection('computation_status').doc(date).set(updates, { merge: true });
-        logger.log('INFO', `[SimHash] ⏩ Resolved ${resolved.length} tasks for ${date}.`);
-    }
-    return remaining;
-}
-
-async function resolveRoutes(db, date, pass, tasks, logger) {
-    const standard = [];
-    const highMem = [];
-
-    const checks = tasks.map(async (task) => {
-        const name = normalizeName(task.name);
-        const doc = await db.doc(`computation_audit_ledger/${date}/passes/${pass}/tasks/${name}`).get();
-        
-        if (!doc.exists) return { task, type: 'std' }; 
-
-        const data = doc.data();
-        
-        if (['PENDING', 'IN_PROGRESS'].includes(data.status)) {
-            const lastActive = getMillis(data.telemetry?.lastHeartbeat) || getMillis(data.startedAt);
-            if ((Date.now() - lastActive) < STALE_LOCK_THRESHOLD_MS) return null; 
-            logger.log('WARN', `[Dispatcher] 🧟 Breaking stale lock for ${name}`);
-        }
-
-        if (data.status === 'FAILED') {
-            const stage = data.error?.stage;
-            const isCodeChanged = data.hash !== task.hash;
-
-            if (['QUALITY_CIRCUIT_BREAKER', 'SEMANTIC_GATE'].includes(stage)) {
-                if (!isCodeChanged) return null; 
-                return { task: { ...task, reason: 'Retry: Code Version Changed' }, type: 'std' };
-            }
-
-            if (data.resourceTier === 'high-mem') {
-                if (!isCodeChanged) return null; 
-                return { task: { ...task, reason: 'Retry: Code Changed (HighMem Reset)' }, type: 'std' };
-            }
-
-            return { task: { ...task, reason: `Retry: ${data.error?.message}`, resources: 'high-mem' }, type: 'high' };
-        }
-
-        return { task, type: 'std' };
-    });
-
-    const results = (await Promise.all(checks)).filter(r => r !== null);
-    results.forEach(r => r.type === 'high' ? highMem.push(r.task) : standard.push(r.task));
-    
-    return { standard, highMem };
-}
-
-// =============================================================================
-// MAIN ENTRY
-// =============================================================================
-
-async function dispatchComputationPass(config, dependencies, computationManifest, reqBody = {}) {
-    switch (reqBody.action) {
-        case 'VERIFY':    return handlePassVerification(config, dependencies, computationManifest, reqBody);
-        case 'SWEEP':     return handleSweepDispatch(config, dependencies, computationManifest, reqBody);
-        case 'REPORT':    return handleFinalSweepReporting(config, dependencies, computationManifest, reqBody);
-        case 'FORCE_RUN': return handleForceRun(config, dependencies, computationManifest, reqBody);
-        case 'SNAPSHOT':  return handleSnapshot(config, dependencies, reqBody);
-        default:          return handleStandardDispatch(config, dependencies, computationManifest, reqBody);
-    }
-}
-
-async function handleFinalSweepReporting(config, dependencies, computationManifest, reqBody) {
-    const { logger } = dependencies;
-    const date = reqBody.date || new Date().toISOString().slice(0, 10);
-    try {
-        const res = await runFinalSweepCheck(config, dependencies, date, String(reqBody.pass || "1"), computationManifest);
-        return { status: 'COMPLETED', date, issues: res.issuesCount };
-    } catch (e) {
-        logger.log('ERROR', `[Dispatcher] Report failed: ${e.message}`);
-        return { status: 'ERROR', error: e.message };
-    }
-}
-
-module.exports = { dispatchComputationPass };