bulltrackers-module 1.0.657 → 1.0.659

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

@@ -1,10 +1,8 @@
 /**
+ * V2 TO REPLACE THE OLD.
  * FILENAME: computation-system/helpers/computation_dispatcher.js
- * PURPOSE: Sequential Cursor-Based Dispatcher.
- * UPDATED: Implemented "Fast-Forward" Scanning Loop to skip empty dates efficiently.
- * UPDATED: Enforces Strict One-Shot Policy (Standard -> HighMem -> Dead Letter).
- * UPDATED: Generates Google Cloud Trace Context (traceId/spanId) for end-to-end monitoring.
- * UPDATED: Added Schedule Awareness (Daily, Weekly, Monthly) to filter tasks by date.
+ * PURPOSE: Sequential Cursor-Based Dispatcher (Refactored & Condensed).
+ * UPDATED: Added SNAPSHOT handling.
  */
 
 const { getExpectedDateStrings, getEarliestDataDates, normalizeName, DEFINITIVE_EARLIEST_DATES } = require('../utils/utils.js');
@@ -12,272 +10,181 @@ const { groupByPass, analyzeDateExecution } = require('../WorkflowOrchestrator.j
 const { PubSubUtils } = require('../../core/utils/pubsub_utils');
 const { fetchComputationStatus } = require('../persistence/StatusRepository');
 const { checkRootDataAvailability } = require('../data/AvailabilityChecker');
-const { runFinalSweepCheck } = require('../tools/FinalSweepReporter'); // [NEW]
+const { runFinalSweepCheck } = require('../tools/FinalSweepReporter');
+// 1. IMPORT SNAPSHOT SERVICE
+const { generateDailySnapshots } = require('../services/SnapshotService');
 const crypto = require('crypto');
 
-const OOM_THRESHOLD_MB = 1500; // Unused
 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: Firestore Timestamp Conversion
-// =============================================================================
-/**
- * Converts a Firestore Timestamp or Date to milliseconds.
- * Firestore stores Date objects as Timestamp objects, which have a .toDate() method.
- * This function handles both cases correctly.
- * @param {any} field - Firestore Timestamp, Date object, or string
- * @returns {number} Milliseconds since epoch, or 0 if invalid
- */
+// ... [SHARED UTILS and SHARED ASYNC HELPERS remain exactly the same] ...
+
 function getMillis(field) {
     if (!field) return 0;
-    // Handle Firestore Timestamp (has .toDate() method)
-    if (field.toDate && typeof field.toDate === 'function') {
-        return field.toDate().getTime();
-    }
-    // Handle standard Date object or string
+    if (field.toDate && typeof field.toDate === 'function') return field.toDate().getTime();
     const date = new Date(field);
     return isNaN(date.getTime()) ? 0 : date.getTime();
-} 
+}
 
-// =============================================================================
-// HELPER: Schedule Logic
-// =============================================================================
-/**
- * Checks if a computation is scheduled to run on a specific date.
- * Defaults to DAILY if no schedule is present.
- * * @param {string} dateStr - YYYY-MM-DD string
- * @param {Object} scheduleConfig - { type: 'DAILY'|'WEEKLY'|'MONTHLY', days: [] }
- * @returns {boolean} True if the computation should run
- */
 function isComputationScheduled(dateStr, scheduleConfig) {
-    // Default: Run every day if no schedule is provided or explicitly DAILY
-    if (!scheduleConfig || !scheduleConfig.type || scheduleConfig.type === 'DAILY') {
-        return true;
-    }
-
-    const date = new Date(dateStr + 'T00:00:00Z'); // Ensure UTC parsing
+    if (!scheduleConfig || !scheduleConfig.type || scheduleConfig.type === 'DAILY') return true;
+    const date = new Date(dateStr + 'T00:00:00Z');
     
-    // Weekly Schedule: Check Day of Week (0=Sun, 1=Mon, ..., 6=Sat)
     if (scheduleConfig.type === 'WEEKLY') {
-        const dayOfWeek = date.getUTCDay();
-        const validDays = Array.isArray(scheduleConfig.days) ? scheduleConfig.days : [scheduleConfig.day];
-        return validDays.includes(dayOfWeek);
+        const days = Array.isArray(scheduleConfig.days) ? scheduleConfig.days : [scheduleConfig.day];
+        return days.includes(date.getUTCDay());
     }
-
-    // Monthly Schedule: Check Day of Month (1-31)
     if (scheduleConfig.type === 'MONTHLY') {
-        const dayOfMonth = date.getUTCDate();
-        const validDates = Array.isArray(scheduleConfig.days) ? scheduleConfig.days : [scheduleConfig.day];
-        return validDates.includes(dayOfMonth);
+        const days = Array.isArray(scheduleConfig.days) ? scheduleConfig.days : [scheduleConfig.day];
+        return days.includes(date.getUTCDate());
     }
-
-    // Fallback default
     return true;
 }
 
-// =============================================================================
-// HELPER: Ledger Awareness
-// =============================================================================
-async function filterActiveTasks(db, date, pass, tasks, logger, forceRun = false) {
-    if (!tasks || tasks.length === 0) return [];
-    if (forceRun) return tasks; 
-    
-    const checkPromises = tasks.map(async (t) => {
-        const taskName = normalizeName(t.name);
-        const ledgerPath = `computation_audit_ledger/${date}/passes/${pass}/tasks/${taskName}`;
-        const snap = await db.doc(ledgerPath).get();
-        
-        if (snap.exists) {
-            const data = snap.data();
-            const isActive = ['PENDING', 'IN_PROGRESS'].includes(data.status);
-
-            if (isActive) {
-                const lastActivityTime = getMillis(data.telemetry?.lastHeartbeat) || getMillis(data.startedAt);
-                
-                if ((Date.now() - lastActivityTime) > STALE_LOCK_THRESHOLD_MS) {
-                    if (logger) logger.log('WARN', `[Dispatcher] 🧟 Breaking stale lock for ${taskName}.`);
-                    return t; 
-                }
-                return null; 
-            }
-            // Note: We do NOT filter COMPLETED here anymore for Sweep. 
-            // If the Orchestrator says it needs to run, we run it.
+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
         }
-        return t;
-    });
-    const results = await Promise.all(checkPromises);
-    return results.filter(t => t !== null);
+    };
 }
 
-// =============================================================================
-// HELPER: SimHash Stability
-// =============================================================================
-async function attemptSimHashResolution(dependencies, date, tasks, dailyStatus, manifestMap) {
-    const { db, logger } = dependencies;
-    const resolvedTasks = [];
-    const remainingTasks = [];
-    const simHashCache = new Map();
-
-    for (const task of tasks) {
-        const currentStatus = dailyStatus ? dailyStatus[task.name] : null;
-        const manifestItem = manifestMap.get(normalizeName(task.name));
-
-        if (currentStatus && currentStatus.simHash && manifestItem) {
-            let newSimHash = simHashCache.get(manifestItem.hash);
-            if (!newSimHash) {
-                const simDoc = await db.collection('system_simhash_registry').doc(manifestItem.hash).get();
-                if (simDoc.exists) {
-                    newSimHash = simDoc.data().simHash;
-                    simHashCache.set(manifestItem.hash, newSimHash);
-                }
-            }
+async function assessDateRunnability(date, computations, config, dependencies, manifestMap) {
+    const { status: rootStatus } = await checkRootDataAvailability(date, config, dependencies, DEFINITIVE_EARLIEST_DATES) || {};
+    if (!rootStatus) return null;
 
-            if (newSimHash && newSimHash === currentStatus.simHash) {
-                resolvedTasks.push({
-                    name: task.name,
-                    hash: manifestItem.hash,
-                    simHash: newSimHash,
-                    prevStatus: currentStatus
-                });
-                continue; 
-            }
+    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);
         }
-        remainingTasks.push(task);
     }
 
-    if (resolvedTasks.length > 0) {
-        const updatePayload = {};
-        resolvedTasks.forEach(t => {
-            updatePayload[t.name] = {
-                ...(t.prevStatus || {}),
-                hash: t.hash,
-                simHash: t.simHash,
-                reason: 'SimHash Stable (Auto-Resolved)',
-                lastUpdated: new Date().toISOString()
-            };
+    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'}`
         });
-        await db.collection('computation_status').doc(date).set(updatePayload, { merge: true });
-        logger.log('INFO', `[SimHash] ⏩ Fast-forwarded ${resolvedTasks.length} tasks for ${date}.`);
     }
-
-    return remainingTasks;
+    return tasks.length;
 }
 
-async function getStableDateSession(config, dependencies, passToRun, dateLimitStr, forceRebuild) {
+async function getStableDateSession(config, dependencies, pass, dateLimitStr, forceRebuild) {
     const { db, logger } = dependencies;
-    const sessionId = `pass_${passToRun}_${dateLimitStr.replace(/-/g, '')}`;
+    const sessionId = `pass_${pass}_${dateLimitStr.replace(/-/g, '')}`;
     const sessionRef = db.collection('dispatcher_sessions').doc(sessionId);
 
     if (!forceRebuild) {
-        const sessionSnap = await sessionRef.get();
-        if (sessionSnap.exists) {
-            const data = sessionSnap.data();
-            if ((Date.now() - new Date(data.createdAt).getTime()) < SESSION_CACHE_DURATION_MS) {
-                return data.dates;
-            }
+        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 ${passToRun}...`);
-    const earliestDates = await getEarliestDataDates(config, dependencies);
-    const allDates = getExpectedDateStrings(earliestDates.absoluteEarliest, new Date(dateLimitStr + 'T00:00:00Z'));
-    
-    await sessionRef.set({ dates: allDates, createdAt: new Date().toISOString(), configHash: dateLimitStr });
-    return allDates;
+    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;
 }
 
-// MAIN ENTRY POINT
 // =============================================================================
-async function dispatchComputationPass(config, dependencies, computationManifest, reqBody = {}) {
-    const action = reqBody.action || 'DISPATCH'; 
+// HANDLERS
+// =============================================================================
+
+// 2. NEW SNAPSHOT HANDLER
+async function handleSnapshot(config, dependencies, reqBody) {
+    const { logger } = dependencies;
+    const date = reqBody.date;
     
-    if (action === 'VERIFY') {
-        return handlePassVerification(config, dependencies, computationManifest, reqBody);
-    } 
-    else if (action === 'SWEEP') {
-        return handleSweepDispatch(config, dependencies, computationManifest, reqBody);
-    }
-    else if (action === 'REPORT') {
-        return handleFinalSweepReporting(config, dependencies, computationManifest, reqBody);
-    }
-    // [NEW] FORCE RUN HANDLER
-    else if (action === 'FORCE_RUN') {
-        return handleForceRun(config, dependencies, computationManifest, reqBody);
+    if (!date) throw new Error('Snapshot action requires a "date"');
+
+    try {
+        logger.log('INFO', `[Dispatcher] 📸 Triggering Snapshot Service for ${date}`);
+        // Calls the service we created earlier
+        const result = await generateDailySnapshots(date, config, dependencies);
+        return result; 
+    } catch (e) {
+        logger.log('ERROR', `[Dispatcher] Snapshot failed: ${e.message}`);
+        // Return error object so workflow can see failure
+        return { status: 'ERROR', error: e.message };
     }
-    
-    return handleStandardDispatch(config, dependencies, computationManifest, reqBody);
 }
 
-// =============================================================================
-// NEW: Force Run Handler (Bypasses Checks)
-// =============================================================================
 async function handleForceRun(config, dependencies, computationManifest, reqBody) {
     const { logger } = dependencies;
-    const pubsubUtils = new PubSubUtils(dependencies);
-    const computationName = reqBody.computation; // Required
-    const dateInput = reqBody.date;              // Optional (YYYY-MM-DD)
+    const computationName = reqBody.computation;
+    const dateInput = reqBody.date; 
     
-    if (!computationName) {
-        throw new Error('Force Run requires "computation" name.');
-    }
+    if (!computationName) throw new Error('Force Run requires "computation" name.');
 
-    // 1. Verify Computation Exists
     const manifestItem = computationManifest.find(c => normalizeName(c.name) === normalizeName(computationName));
-    if (!manifestItem) {
-        throw new Error(`Computation '${computationName}' not found in manifest.`);
-    }
+    if (!manifestItem) throw new Error(`Computation '${computationName}' not found.`);
 
-    // 2. Determine Target Dates
     let candidateDates = [];
     if (dateInput) {
-        // Single Date Mode
         candidateDates = [dateInput];
     } else {
-        // All Dates Mode (Backfill)
         logger.log('INFO', `[ForceRun] No date provided. Calculating date range for ${computationName}...`);
-        const earliestDates = await getEarliestDataDates(config, dependencies);
-        // Calculate from system start until today
-        candidateDates = getExpectedDateStrings(earliestDates.absoluteEarliest, new Date());
+        const earliest = await getEarliestDataDates(config, dependencies);
+        candidateDates = getExpectedDateStrings(earliest.absoluteEarliest, new Date());
     }
     
     logger.log('INFO', `[ForceRun] Checking ${candidateDates.length} candidate dates for runnability...`);
 
-    // 3. Filter to only runnable dates using analyzeDateExecution
-    const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-    const calcsInPass = groupByPass(computationManifest, manifestItem.pass || "1");
-    const targetComputationNormalized = normalizeName(computationName);
-    
-    // Filter to only the target computation
-    const targetCalcs = calcsInPass.filter(c => normalizeName(c.name) === targetComputationNormalized);
-    
-    if (targetCalcs.length === 0) {
-        throw new Error(`Computation '${computationName}' not found in pass ${manifestItem.pass || "1"}`);
-    }
-    
     const runnableDates = [];
     const skippedDates = [];
+    const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
     
-    for (const dateStr of candidateDates) {
-        // Check root data availability
-        const rootDataStatus = await checkRootDataAvailability(dateStr, config, dependencies, DEFINITIVE_EARLIEST_DATES);
-        
-        // Get computation status for this date
-        const dailyStatus = await fetchComputationStatus(dateStr, config, dependencies);
-        
-        // Check previous day status if needed
-        let prevDailyStatus = null;
-        if (targetCalcs.some(c => c.isHistorical)) {
-            const prevDate = new Date(dateStr + 'T00:00:00Z');
-            prevDate.setUTCDate(prevDate.getUTCDate() - 1);
-            prevDailyStatus = await fetchComputationStatus(prevDate.toISOString().slice(0, 10), config, dependencies);
+    const targetComp = { ...manifestItem, schedule: null }; 
+    const targetComputationNormalized = normalizeName(computationName);
+
+    for (const date of candidateDates) {
+        const result = await assessDateRunnability(date, [targetComp], config, dependencies, manifestMap);
+        if (!result) {
+            skippedDates.push({ date, reason: 'Root data unavailable' });
+            continue; 
         }
-        
-        // Analyze if this computation can run on this date
-        const report = analyzeDateExecution(dateStr, targetCalcs, rootDataStatus, dailyStatus, manifestMap, prevDailyStatus);
-        
-        // Check if the target computation is runnable, needs re-run, or has failed dependencies
+
+        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);
@@ -285,21 +192,18 @@ async function handleForceRun(config, dependencies, computationManifest, reqBody
         const isBlocked = report.blocked.some(t => normalizeName(t.name) === targetComputationNormalized);
         
         if (isRunnable || needsReRun || hasFailedDep) {
-            runnableDates.push(dateStr);
+            runnableDates.push(date);
         } else if (isImpossible) {
-            skippedDates.push({ date: dateStr, reason: report.impossible.find(t => normalizeName(t.name) === targetComputationNormalized)?.reason || 'Impossible' });
+            skippedDates.push({ date, reason: report.impossible.find(t => normalizeName(t.name) === targetComputationNormalized)?.reason || 'Impossible' });
         } else if (isBlocked) {
-            skippedDates.push({ date: dateStr, reason: report.blocked.find(t => normalizeName(t.name) === targetComputationNormalized)?.reason || 'Blocked' });
+            skippedDates.push({ date, reason: report.blocked.find(t => normalizeName(t.name) === targetComputationNormalized)?.reason || 'Blocked' });
         } else {
-            skippedDates.push({ date: dateStr, reason: 'Not runnable (unknown reason)' });
+            skippedDates.push({ date, reason: 'Not runnable (unknown reason)' });
         }
     }
     
     logger.log('INFO', `[ForceRun] ✅ Found ${runnableDates.length} runnable dates out of ${candidateDates.length} candidates`);
-    if (skippedDates.length > 0) {
-        logger.log('INFO', `[ForceRun] ⏭️ Skipped ${skippedDates.length} dates: ${skippedDates.slice(0, 5).map(s => `${s.date} (${s.reason})`).join(', ')}${skippedDates.length > 5 ? '...' : ''}`);
-    }
-    
+
     if (runnableDates.length === 0) {
         return {
             status: 'NO_RUNNABLE_DATES',
@@ -313,48 +217,19 @@ async function handleForceRun(config, dependencies, computationManifest, reqBody
     
     logger.log('WARN', `[ForceRun] 🚨 MANUALLY Triggering ${computationName} for ${runnableDates.length} runnable dates. Pass: ${manifestItem.pass}`);
 
-    // 4. Construct Tasks (only for runnable dates)
-    const dispatchId = crypto.randomUUID();
-    const tasks = runnableDates.map(date => {
-        const traceId = crypto.randomBytes(16).toString('hex');
-        const spanId = crypto.randomBytes(8).toString('hex');
-        return {
-            action: 'RUN_COMPUTATION_DATE',
-            computation: manifestItem.name,
-            date: date,
-            pass: manifestItem.pass || "1",
-            dispatchId: dispatchId,
-            triggerReason: 'MANUAL_FORCE_API',
-            resources: reqBody.resources || 'standard',
-            // Trace context allows you to find these specific runs in Cloud Trace
-            traceContext: { traceId, spanId, sampled: true }
-        };
-    });
-
-    // 4. Batch Publish (Chunked to stay under Pub/Sub limits)
-    const CHUNK_SIZE = 250; // Safe batch size
     const topic = (reqBody.resources === 'high-mem') 
         ? (config.computationTopicHighMem || 'computation-tasks-highmem')
         : (config.computationTopicStandard || 'computation-tasks');
-        
-    let dispatchedCount = 0;
-    const chunks = [];
-    for (let i = 0; i < tasks.length; i += CHUNK_SIZE) {
-        chunks.push(tasks.slice(i, i + CHUNK_SIZE));
-    }
 
-    // Publish chunks sequentially to avoid memory spikes
-    for (const chunk of chunks) {
-        await pubsubUtils.batchPublishTasks(dependencies, {
-            topicName: topic,
-            tasks: chunk,
-            taskType: 'manual-force-run'
-        });
-        dispatchedCount += chunk.length;
-    }
+    const dispatchId = 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',
+        status: 'FORCED', 
         computation: computationName,
         mode: dateInput ? 'SINGLE_DATE' : 'ALL_DATES',
         datesChecked: candidateDates.length,
@@ -365,89 +240,34 @@ async function handleForceRun(config, dependencies, computationManifest, reqBody
     };
 }
 
-// =============================================================================
-// NEW: Final Sweep Reporting Handler
-// =============================================================================
-async function handleFinalSweepReporting(config, dependencies, computationManifest, reqBody) {
-    const { logger } = dependencies;
-    const passToRun = String(reqBody.pass || "1");
-    // Target date is required for detailed forensics
-    const date = reqBody.date || new Date().toISOString().slice(0, 10); 
-    
-    logger.log('INFO', `[Dispatcher] 📝 Triggering Final Sweep Forensics for Pass ${passToRun} on ${date}...`);
-
-    try {
-        const result = await runFinalSweepCheck(config, dependencies, date, passToRun, computationManifest);
-        return { 
-            status: 'COMPLETED',
-            date: date,
-            pass: passToRun,
-            issuesFound: result.issuesCount 
-        };
-    } catch (e) {
-        logger.log('ERROR', `[Dispatcher] Forensics failed: ${e.message}`);
-        return { status: 'ERROR', error: e.message };
-    }
-}
-
-// =============================================================================
-// LOGIC: Verify Pass Completion
-// =============================================================================
 async function handlePassVerification(config, dependencies, computationManifest, reqBody) {
     const { logger } = dependencies;
-    const passToRun = String(reqBody.pass || "1");
-    const dateLimitStr = reqBody.date || "2025-01-01";
+    const pass = String(reqBody.pass || "1");
+    const dateLimit = reqBody.date || "2025-01-01";
     
-    logger.log('INFO', `[Verify] 🧹 Sweeping Pass ${passToRun} for unfinished work...`);
+    logger.log('INFO', `[Verify] 🧹 Sweeping Pass ${pass} for unfinished work...`);
     
-    const sessionDates = await getStableDateSession(config, dependencies, passToRun, dateLimitStr, false);
-    const passes = groupByPass(computationManifest);
-    const calcsInPass = passes[passToRun] || [];
+    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) {
-        // [SCHEDULE CHECK] Filter tasks that are not scheduled for this date
-        const scheduledComputations = calcsInPass.filter(c => 
-            isComputationScheduled(date, c.schedule)
-        );
-
-        if (scheduledComputations.length === 0) continue;
-
-        const [dailyStatus, availability] = await Promise.all([
-            fetchComputationStatus(date, config, dependencies),
-            checkRootDataAvailability(date, config, dependencies, DEFINITIVE_EARLIEST_DATES)
-        ]);
-
-        let prevDailyStatus = null;
-        if (scheduledComputations.some(c => c.isHistorical)) {
-             const prevD = new Date(date + 'T00:00:00Z');
-             prevD.setUTCDate(prevD.getUTCDate() - 1);
-             prevDailyStatus = await fetchComputationStatus(prevD.toISOString().slice(0, 10), config, dependencies);
-        }
+        const scheduled = passComputations.filter(c => isComputationScheduled(date, c.schedule));
+        if (scheduled.length === 0) continue;
 
-        const report = analyzeDateExecution(
-            date, 
-            scheduledComputations, // Use filtered list 
-            availability ? availability.status : {}, 
-            dailyStatus, 
-            manifestMap, 
-            prevDailyStatus
-        );
-        
-        const pending = [...report.runnable, ...report.reRuns];
+        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: date,
-                taskCount: pending.length,
-                eta: eta
-            });
+            missingTasks.push({ date, taskCount: pending.length, eta });
         }
     }
 
@@ -455,487 +275,262 @@ async function handlePassVerification(config, dependencies, computationManifest,
     return { missingTasks };
 }
 
-// =============================================================================
-// LOGIC: Sweep Dispatch (Forced High-Mem)
-// =============================================================================
 async function handleSweepDispatch(config, dependencies, computationManifest, reqBody) {
     const { logger, db } = dependencies;
-    const pubsubUtils = new PubSubUtils(dependencies);
-    const passToRun = String(reqBody.pass || "1");
+    const pass = String(reqBody.pass || "1");
     const date = reqBody.date;
-
     if (!date) throw new Error('Sweep dispatch requires date');
 
-    const passes = groupByPass(computationManifest);
-    const calcsInPass = passes[passToRun] || [];
-    
-    // [SCHEDULE CHECK] Filter tasks that are not scheduled for this date
-    const scheduledComputations = calcsInPass.filter(c => 
-        isComputationScheduled(date, c.schedule)
-    );
-
-    if (scheduledComputations.length === 0) {
-        logger.log('INFO', `[Sweep] ${date} has no scheduled tasks for Pass ${passToRun}. Ignoring.`);
-        return { dispatched: 0 };
-    }
-
-    // 1. Analyze specific date
-    const [dailyStatus, availability] = await Promise.all([
-        fetchComputationStatus(date, config, dependencies),
-        checkRootDataAvailability(date, config, dependencies, DEFINITIVE_EARLIEST_DATES)
-    ]);
-    
-    let prevDailyStatus = null;
-    if (scheduledComputations.some(c => c.isHistorical)) {
-         const prevD = new Date(date + 'T00:00:00Z');
-         prevD.setUTCDate(prevD.getUTCDate() - 1);
-         prevDailyStatus = await fetchComputationStatus(prevD.toISOString().slice(0, 10), config, dependencies);
-    }
-
     const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-    const report = analyzeDateExecution(
-        date, 
-        scheduledComputations, // Use filtered list
-        availability ? availability.status : {}, 
-        dailyStatus, 
-        manifestMap, 
-        prevDailyStatus
-    );
-    const pending = [...report.runnable, ...report.reRuns];
+    const calculations = groupByPass(computationManifest)[pass] || [];
+    const scheduled = calculations.filter(c => isComputationScheduled(date, c.schedule));
 
-    if (pending.length === 0) {
-        logger.log('INFO', `[Sweep] ${date} is clean. No dispatch.`);
-        return { dispatched: 0 };
-    }
+    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 name = normalizeName(task.name);
-        const ledgerPath = `computation_audit_ledger/${date}/passes/${passToRun}/tasks/${name}`;
+        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);
             
-           // 1. ACTIVE CHECK: Don't double-dispatch if already running... UNLESS IT'S A ZOMBIE
-            if (['PENDING', 'IN_PROGRESS'].includes(data.status)) {
+            if (isActive) {
                 const lastActivity = getMillis(data.telemetry?.lastHeartbeat) || getMillis(data.startedAt);
-
-                // If it's been silent for > 15 mins, it's a Zombie. Kill it and Re-run.
-                if ((Date.now() - lastActivity) > STALE_LOCK_THRESHOLD_MS) {
-                    logger.log('WARN', `[Sweep] 🧟 Found ZOMBIE lock for ${name}. Breaking lock and re-running.`);
-                    // Don't continue; let it fall through to dispatch
-                } else {
-                    logger.log('INFO', `[Sweep] ⏳ Skipping ${name} - Valid IN_PROGRESS.`);
-                    continue;
-                }
+                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;
             }
-
-            // 2. COMPLETION CHECK (GHOST STATE FIX)
-            // We REMOVED the check that skips if (status === 'COMPLETED' && hash === task.hash).
-            // If we are here, 'analyzeDateExecution' (The Brain) decided this task is NOT done
-            // (likely due to a missing or outdated entry in computation_status).
-            // Even if the Ledger (The Log) says it finished, the system state is inconsistent.
-            // We MUST re-run to repair the Status Index.
-            
-            const stage = data.error?.stage;
-            
-            // 3. DETERMINISTIC FAILURE CHECK
-            if (['QUALITY_CIRCUIT_BREAKER', 'SEMANTIC_GATE', 'SHARDING_LIMIT_EXCEEDED'].includes(stage)) {
-                 // If hash matches, it's the exact same code that failed before. Don't retry in loop.
-                 if (data.hash === task.hash) {
-                     logger.log('WARN', `[Sweep] 🛑 Skipping deterministic failure for ${name} (${stage}).`);
-                     continue;
-                 }
-                 logger.log('INFO', `[Sweep] 🔄 Code Updated for ${name}. Retrying sweep despite previous ${stage}.`);
-             }
-             
-             // 4. DEAD END CHECK (High Mem)
-             if (data.resourceTier === 'high-mem' && data.status === 'FAILED') {
-                 // If code hasn't changed, don't hammer it.
-                 if (data.hash === task.hash) {
-                     logger.log('WARN', `[Sweep] 🛑 Skipping ${name} - Already failed on High-Mem.`);
-                     continue;
-                 }
-             }
         }
         validTasks.push(task);
     }
 
-    if (validTasks.length === 0) {
-        logger.log('INFO', `[Sweep] ${date} has no retryable tasks. Ignoring.`);
-        return { dispatched: 0 };
-    }
-
-    // 2. FORCE High Mem & INJECT TRACE
-    const currentDispatchId = crypto.randomUUID();
-    
-    const tasksPayload = validTasks.map(t => {
-        const traceId = crypto.randomBytes(16).toString('hex');
-        const spanId = crypto.randomBytes(8).toString('hex');
-
-        return {
-            ...t,
-            action: 'RUN_COMPUTATION_DATE',
-            computation: t.name,
-            date: date,
-            pass: passToRun,
-            dispatchId: currentDispatchId,
-            triggerReason: 'SWEEP_RECOVERY',
-            resources: 'high-mem', // FORCE
-            traceContext: { traceId, spanId, sampled: true }
-        };
-    });
-
-    const taskNames = tasksPayload.map(t => t.computation || t.name).join(', ');
-    logger.log('WARN', `[Sweep] 🧹 Forcing ${tasksPayload.length} tasks to HIGH-MEM for ${date}.`, {
-        date: date,
-        pass: passToRun,
-        tasks: tasksPayload.map(t => ({ name: t.computation || t.name, reason: 'sweep' })),
-        topic: config.computationTopicHighMem || 'computation-tasks-highmem'
-    });
-
-    await pubsubUtils.batchPublishTasks(dependencies, {
-        topicName: config.computationTopicHighMem || 'computation-tasks-highmem',
-        tasks: tasksPayload,
-        taskType: `pass-${passToRun}-sweep`
-    });
+    const dispatchId = crypto.randomUUID();
+    const tasksPayload = validTasks.map(t => 
+        createTaskPayload(t, date, pass, dispatchId, 'high-mem', 'SWEEP_RECOVERY')
+    );
 
-    return { dispatched: tasksPayload.length };
+    return { dispatched: await publishTaskBatch(dependencies, config, tasksPayload, pass, config.computationTopicHighMem) };
 }
 
-// =============================================================================
-// LOGIC: Standard Dispatch (Fast-Forward Enabled)
-// =============================================================================
 async function handleStandardDispatch(config, dependencies, computationManifest, reqBody) {
     const { logger, db } = dependencies;
-    const pubsubUtils = new PubSubUtils(dependencies);
-    
-    const passToRun = String(reqBody.pass || "1");
+    const pass = String(reqBody.pass || "1");
+    const dateLimit = reqBody.date || "2025-01-01";
     const targetCursorN = parseInt(reqBody.cursorIndex || 1);
-    const dateLimitStr = reqBody.date || "2025-01-01";
-    const forceRebuild = reqBody.forceRebuild === true;
 
     const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
-    const passes = groupByPass(computationManifest);
-    const calcsInThisPass = passes[passToRun] || [];
+    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 (!calcsInThisPass.length) return { status: 'MOVE_TO_NEXT_PASS', dispatched: 0 };
-
-    const sessionDates = await getStableDateSession(config, dependencies, passToRun, dateLimitStr, forceRebuild);
-    if (!sessionDates || sessionDates.length === 0) return { status: 'MOVE_TO_NEXT_PASS', dispatched: 0 };
-
-    // --- Fast-Forward Loop Configuration ---
-    // Scans up to 50 dates or 40 seconds to find work, avoiding empty "wait loops"
-    const MAX_SCAN_DEPTH = 50; // This is actually 50 + Today, so 51.
-    const TIME_LIMIT_MS = 40000; 
-    const startTime = Date.now();
+    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 selectedTasks = [];
-    let selectedDate = null;
-    let datesScanned = 0;
+    let tasksToDispatch = [];
+    let processedDate = null;
+    let scanned = 0;
 
-    // Loop until work is found, end is reached, or safety limits hit
     while (currentCursor <= sessionDates.length) {
-        datesScanned++;
-        selectedDate = sessionDates[currentCursor - 1]; // 0-indexed array
+        scanned++;
+        processedDate = sessionDates[currentCursor - 1];
 
-        // 1. Safety Break (Prevent Timeout)
-        if ((Date.now() - startTime) > TIME_LIMIT_MS || datesScanned > MAX_SCAN_DEPTH) {
-            logger.log('INFO', `[Dispatcher] ⏩ Fast-forward paused at ${selectedDate} after scanning ${datesScanned} dates.`);
+        if ((Date.now() - startT) > TIME_LIMIT || scanned > MAX_SCAN) {
+            logger.log('INFO', `[Dispatcher] ⏩ Fast-forward paused at ${processedDate} after scanning ${scanned} dates.`);
             break;
         }
 
-        // 2. [SCHEDULE CHECK] Filter computations scheduled for this specific date
-        const scheduledComputations = calcsInThisPass.filter(c => 
-            isComputationScheduled(selectedDate, c.schedule)
-        );
-
-        // Optimization: If nothing is scheduled for today, skip expensive DB checks
-        if (scheduledComputations.length === 0) {
-            // DEBUG: Log when schedule filtering removes all tasks
-            if (calcsInThisPass.length > 0) {
-                logger.log('TRACE', `[Dispatcher] Date ${selectedDate}: ${calcsInThisPass.length} pass computations, but 0 scheduled for this date. Skipping.`);
-            }
-            currentCursor++;
+        const scheduled = passComputations.filter(c => isComputationScheduled(processedDate, c.schedule));
+        if (scheduled.length === 0) {
+            currentCursor++; 
             continue;
         }
 
-        // 3. Analyze Date
-        const earliestDates = await getEarliestDataDates(config, dependencies);
-        let prevDailyStatusPromise = Promise.resolve(null);
-        if (scheduledComputations.some(c => c.isHistorical)) {
-            const prevD = new Date(selectedDate + 'T00:00:00Z');
-            prevD.setUTCDate(prevD.getUTCDate() - 1);
-            if (prevD >= earliestDates.absoluteEarliest) {
-                prevDailyStatusPromise = fetchComputationStatus(prevD.toISOString().slice(0, 10), config, dependencies);
-            }
-        }
+        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];
 
-        const [dailyStatus, prevDailyStatus, availability] = await Promise.all([
-            fetchComputationStatus(selectedDate, config, dependencies),
-            prevDailyStatusPromise,
-            checkRootDataAvailability(selectedDate, config, dependencies, DEFINITIVE_EARLIEST_DATES)
-        ]);
-
-        // DEBUG: Log availability check
-        if (!availability || !availability.status) {
-            logger.log('WARN', `[Dispatcher] ⚠️ Date ${selectedDate}: Availability check failed or returned null. Skipping analysis.`);
+            if (tasksToDispatch.length > 0) break; 
         }
-
-        if (availability && availability.status) {
-            const report = analyzeDateExecution(
-                selectedDate, 
-                scheduledComputations, // Use filtered list
-                availability.status, 
-                dailyStatus, 
-                manifestMap, 
-                prevDailyStatus
-            );
-            let rawTasks = [...report.runnable, ...report.reRuns];
-            
-            // DEBUG: Log analysis results
-            if (rawTasks.length === 0 && (report.runnable.length > 0 || report.reRuns.length > 0)) {
-                logger.log('WARN', `[Dispatcher] ⚠️ Date ${selectedDate}: analyzeDateExecution found ${report.runnable.length} runnable + ${report.reRuns.length} reRuns, but rawTasks is empty!`);
-            }
-            if (rawTasks.length > 0) {
-                logger.log('TRACE', `[Dispatcher] Date ${selectedDate}: analyzeDateExecution found ${report.runnable.length} runnable, ${report.reRuns.length} reRuns. Total: ${rawTasks.length}`);
-            }
-
-            if (rawTasks.length > 0) {
-                rawTasks = await attemptSimHashResolution(dependencies, selectedDate, rawTasks, dailyStatus, manifestMap);
-                const activeTasks = await filterActiveTasks(db, selectedDate, passToRun, rawTasks, logger);
-                
-                if (activeTasks.length > 0) {
-                    // DEBUG: Log what we're about to route
-                    logger.log('INFO', `[Dispatcher] 🔍 Date ${selectedDate}: ${rawTasks.length} raw tasks → ${activeTasks.length} after filtering. Routing...`);
-                    const { standard, highMem } = await splitRoutes(db, selectedDate, passToRun, activeTasks, logger);
-                    selectedTasks = [...standard, ...highMem];
-                    
-                    // DEBUG: Log routing results
-                    if (selectedTasks.length === 0 && activeTasks.length > 0) {
-                        logger.log('WARN', `[Dispatcher] ⚠️ Date ${selectedDate}: ${activeTasks.length} tasks filtered out by splitRoutes! Tasks: ${activeTasks.map(t => t.name).join(', ')}`);
-                    }
-                    
-                    if (selectedTasks.length > 0) {
-                        // Found work! Break loop to dispatch.
-                        break; 
-                    }
-                } else if (rawTasks.length > 0) {
-                    // DEBUG: Log if filterActiveTasks removed all tasks
-                    logger.log('WARN', `[Dispatcher] ⚠️ Date ${selectedDate}: ${rawTasks.length} raw tasks all filtered out by filterActiveTasks! Tasks: ${rawTasks.map(t => t.name).join(', ')}`);
-                }
-            }
-        }
-
-        // No work found for this date. Fast-forward to next.
         currentCursor++;
     }
 
-    // --- Result Handling ---
-
-    // Case 1: Satiated (Scanned to end of session with no work)
-    if (currentCursor > sessionDates.length && selectedTasks.length === 0) {
+    if (currentCursor > sessionDates.length && tasksToDispatch.length === 0) {
         return {
             status: 'CONTINUE_PASS',
-            dateProcessed: selectedDate,
+            dateProcessed: processedDate,
             dispatched: 0,
             n_cursor_ignored: false,
             remainingDates: 0,
-            nextCursor: currentCursor // Matches length + 1
+            nextCursor: currentCursor 
         };
     }
 
-    // Case 2: Paused by Limit (No work found yet, but more dates remain)
-    if (selectedTasks.length === 0) {
+    if (tasksToDispatch.length === 0) {
         return {
             status: 'CONTINUE_PASS',
-            dateProcessed: selectedDate,
+            dateProcessed: processedDate,
             dispatched: 0,
             n_cursor_ignored: false,
             remainingDates: sessionDates.length - currentCursor + 1,
-            nextCursor: currentCursor // Resume from here
+            nextCursor: currentCursor 
         };
     }
 
-    // Case 3: Work Found (Dispatching)
-    const totalweight = selectedTasks.reduce((sum, t) => sum + (manifestWeightMap.get(normalizeName(t.name)) || 1.0), 0);
-    const currentDispatchId = crypto.randomUUID();
-    const etaSeconds = Math.max(20, Math.ceil(totalweight * BASE_SECONDS_PER_WEIGHT_UNIT));
+    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 (datesScanned > 1) {
-        logger.log('INFO', `[Dispatcher] ⏩ Fast-forwarded ${datesScanned - 1} empty dates. Dispatching ${selectedTasks.length} tasks for ${selectedDate}.`);
+    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 ${selectedTasks.length} tasks for ${selectedDate}.`);
+        logger.log('INFO', `[Dispatcher] ✅ Dispatching ${tasksToDispatch.length} tasks for ${processedDate}.`);
     }
 
-    const mapToTaskPayload = (t) => {
-        const traceId = crypto.randomBytes(16).toString('hex');
-        const spanId = crypto.randomBytes(8).toString('hex');
-        return {
-            ...t, 
-            action: 'RUN_COMPUTATION_DATE', 
-            computation: t.name, 
-            date: selectedDate, 
-            pass: passToRun,
-            dispatchId: currentDispatchId, 
-            triggerReason: t.reason, 
-            resources: t.resources || 'standard',
-            traceContext: {
-                traceId: traceId,
-                spanId: spanId,
-                sampled: true
-            }
-        };
-    };
+    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));
 
-    const standardTasks = selectedTasks.filter(t => t.resources !== 'high-mem').map(mapToTaskPayload);
-    const highMemTasks  = selectedTasks.filter(t => t.resources === 'high-mem').map(mapToTaskPayload);
-
-    const pubPromises = [];
-    if (standardTasks.length > 0) {
-        const taskNames = standardTasks.map(t => t.computation || t.name).join(', ');
-        logger.log('INFO', `[Dispatcher] 📤 Dispatching ${standardTasks.length} standard tasks: ${taskNames}`, {
-            date: selectedDate,
-            pass: passToRun,
-            tasks: standardTasks.map(t => ({ name: t.computation || t.name, reason: t.triggerReason || 'new' })),
-            topic: config.computationTopicStandard || 'computation-tasks'
-        });
-        pubPromises.push(pubsubUtils.batchPublishTasks(dependencies, {
-            topicName: config.computationTopicStandard || 'computation-tasks',
-            tasks: standardTasks,
-            taskType: `pass-${passToRun}-std`
-        }));
-    }
-    if (highMemTasks.length > 0) {
-        const taskNames = highMemTasks.map(t => t.computation || t.name).join(', ');
-        logger.log('INFO', `[Dispatcher] 📤 Dispatching ${highMemTasks.length} high-memory tasks: ${taskNames}`, {
-            date: selectedDate,
-            pass: passToRun,
-            tasks: highMemTasks.map(t => ({ name: t.computation || t.name, reason: t.triggerReason || 'retry' })),
-            topic: config.computationTopicHighMem || 'computation-tasks-highmem'
-        });
-        pubPromises.push(pubsubUtils.batchPublishTasks(dependencies, {
-            topicName: config.computationTopicHighMem || 'computation-tasks-highmem',
-            tasks: highMemTasks,
-            taskType: `pass-${passToRun}-high`
-        }));
-    }
-    await Promise.all(pubPromises);
+    await Promise.all([
+        publishTaskBatch(dependencies, config, standardPayload, pass),
+        publishTaskBatch(dependencies, config, highMemPayload, pass)
+    ]);
 
     return {
         status: 'CONTINUE_PASS',
-        dateProcessed: selectedDate,
-        dispatched: selectedTasks.length,
+        dateProcessed: processedDate,
+        dispatched: tasksToDispatch.length,
         n_cursor_ignored: false,
         etaSeconds: etaSeconds,
         remainingDates: sessionDates.length - targetCursorN,
-        nextCursor: currentCursor + 1 // Start next scan AFTER this date
+        nextCursor: currentCursor + 1 
     };
 }
 
 // =============================================================================
-// HELPER: Route Splitting (One-Shot Enforcement)
+// LOGIC: Resolution & Routing
 // =============================================================================
-// [UPDATED] Route Splitting with Version-Aware Dead Lettering
-async function splitRoutes(db, date, pass, tasks, logger) {
+
+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 = [];
 
-    for (const task of tasks) {
+    const checks = tasks.map(async (task) => {
         const name = normalizeName(task.name);
-        const ledgerPath = `computation_audit_ledger/${date}/passes/${pass}/tasks/${name}`;
-        const doc = await db.doc(ledgerPath).get();
+        const doc = await db.doc(`computation_audit_ledger/${date}/passes/${pass}/tasks/${name}`).get();
         
-        if (!doc.exists) {
-            // No ledger entry - trust analyzeDateExecution, dispatch as standard
-            standard.push(task);
-            continue;
-        }
+        if (!doc.exists) return { task, type: 'std' }; 
 
         const data = doc.data();
         
-        // CRITICAL FIX: If analyzeDateExecution says this task should run, we MUST trust it.
-        // The ledger might say COMPLETED, but if computation_status is missing/outdated,
-        // we need to re-run to repair the state. Only skip if actively running.
-        // Note: filterActiveTasks already filtered out non-stale PENDING/IN_PROGRESS,
-        // but we double-check here in case of race conditions.
         if (['PENDING', 'IN_PROGRESS'].includes(data.status)) {
-            // Check if it's stale (should have been caught by filterActiveTasks, but double-check)
-            const lastActivityTime = getMillis(data.telemetry?.lastHeartbeat) || getMillis(data.startedAt);
-            
-            if ((Date.now() - lastActivityTime) > STALE_LOCK_THRESHOLD_MS) {
-                // Stale lock - break it and continue
-                logger.log('WARN', `[Dispatcher] 🧟 splitRoutes: Breaking stale lock for ${name}.`);
-                // Fall through to handle as if no active lock
-            } else {
-                // Valid active lock - skip (shouldn't happen if filterActiveTasks worked correctly)
-                logger.log('TRACE', `[Dispatcher] splitRoutes: Skipping ${name} - Valid IN_PROGRESS (should have been filtered earlier).`);
-                continue;
-            }
+            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;
 
-            // 1. DETERMINISTIC FAILURES (Never Retry UNLESS Code Updated)
-            if (['QUALITY_CIRCUIT_BREAKER', 'SEMANTIC_GATE', 'SHARDING_LIMIT_EXCEEDED'].includes(stage)) {
-                 // [FIX] Check if the hash matches. If code changed, we MUST retry.
-                 if (data.hash === task.hash) {
-                     logger.log('WARN', `[Dispatcher] 🛑 Dropping ${name} - Deterministic Failure (${stage}).`);
-                     continue; 
-                 }
-                 
-                 // If hashes differ, we reset to Standard execution to give the new code a chance
-                 logger.log('INFO', `[Dispatcher] 🔄 Code Updated for ${name}. Retrying despite previous ${stage}.`);
-                 standard.push({ ...task, reason: 'Retry: Code Version Changed' });
-                 continue;
+            if (['QUALITY_CIRCUIT_BREAKER', 'SEMANTIC_GATE'].includes(stage)) {
+                if (!isCodeChanged) return null; 
+                return { task: { ...task, reason: 'Retry: Code Version Changed' }, type: 'std' };
             }
 
-            // 2. HIGH MEMORY FAILURE HANDLING (The New Logic)
             if (data.resourceTier === 'high-mem') {
-                const failedHash = data.hash || data.composition?.code; // Support legacy or new structure
-                const currentHash = task.hash;
-
-                // A. EXACT CODE MATCH: It failed High-Mem with THIS code.
-                if (failedHash === currentHash) {
-                    logger.log('WARN', `[Dispatcher] 💀 Dead End: ${name} failed High-Mem on this version (${currentHash.slice(0,6)}). Waiting for code fix.`);
-                    continue; // STOP. Do not retry.
-                } 
-                
-                // B. CODE MISMATCH: The code has changed since the High-Mem failure.
-                // We reset it to 'standard' to see if the fix optimized memory usage.
-                else {
-                    logger.log('INFO', `[Dispatcher] 🔄 Code Updated for ${name}. Resetting High-Mem failure to Standard retry.`);
-                    standard.push({
-                        ...task,
-                        reason: 'Retry: Code Version Changed'
-                    });
-                    continue;
-                }
+                if (!isCodeChanged) return null; 
+                return { task: { ...task, reason: 'Retry: Code Changed (HighMem Reset)' }, type: 'std' };
             }
 
-            // 3. STANDARD FAILURE -> PROMOTE TO HIGH MEM
-            highMem.push({ 
-                ...task, 
-                resources: 'high-mem', 
-                reason: `Retry: ${data.error?.message || 'Standard Failure'}` 
-            });
-
-        } else {
-            // Status is likely COMPLETED or some other state.
-            // CRITICAL: If analyzeDateExecution says this should run, we MUST trust it.
-            // The ledger might show COMPLETED, but if computation_status is missing/outdated,
-            // we need to re-run to repair the state. This is the "ghost state fix" logic.
-            // Trust the Brain (analyzeDateExecution) over the Log (ledger).
-            logger.log('INFO', `[Dispatcher] 🔄 splitRoutes: ${name} has ledger status '${data.status}', but analyzeDateExecution says it should run. Trusting analysis and dispatching.`);
-            standard.push(task);
+            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);
+        // 3. REGISTER SNAPSHOT ACTION
+        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 };