bulltrackers-module 1.0.273 → 1.0.275

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

@@ -1,7 +1,7 @@
 /**
  * FILENAME: computation-system/helpers/computation_dispatcher.js
  * PURPOSE: "Smart Dispatcher" - Analyzes state and only dispatches valid, runnable tasks.
- * UPDATED: Fixed "undefined" reason crash for failed dependencies.
+ * UPDATED: Adds 'dispatchId' to payloads for precise tracing.
  */
 
 const { getExpectedDateStrings, normalizeName, DEFINITIVE_EARLIEST_DATES } = require('../utils/utils.js');
@@ -11,13 +11,13 @@ const { fetchComputationStatus, updateComputationStatus } = require('../persiste
 const { checkRootDataAvailability }             = require('../data/AvailabilityChecker');
 const { generateCodeHash }                      = require('../topology/HashManager');
 const pLimit                                    = require('p-limit');
+const crypto                                    = require('crypto'); // REQUIRED for UUID
 
 const TOPIC_NAME = 'computation-tasks';
 const STATUS_IMPOSSIBLE = 'IMPOSSIBLE';
 
 /**
  * Dispatches computation tasks for a specific pass.
- * Performs full pre-flight checks (Root Data, Dependencies, History) before emitting.
  */
 async function dispatchComputationPass(config, dependencies, computationManifest) {
     const { logger, db } = dependencies;
@@ -26,43 +26,36 @@ async function dispatchComputationPass(config, dependencies, computationManifest
     
     if (!passToRun) { return logger.log('ERROR', '[Dispatcher] No pass defined (COMPUTATION_PASS_TO_RUN). Aborting.'); }
 
-    // 1. Get Calculations for this Pass
+    const currentManifestHash = generateCodeHash(
+        computationManifest.map(c => c.hash).sort().join('|')
+    );
+
     const passes          = groupByPass(computationManifest);
     const calcsInThisPass = passes[passToRun] || [];
 
     if (!calcsInThisPass.length) { return logger.log('WARN', `[Dispatcher] No calcs for Pass ${passToRun}. Exiting.`); }
 
-    // --- [NEW] OPTIMIZATION 1: PREEMPTIVE HASH CHECK ---
-    const currentManifestHash = generateCodeHash(
-        computationManifest.map(c => c.hash).sort().join('|')
-    );
-    // ---------------------------------------------------
-
     const calcNames = calcsInThisPass.map(c => c.name);
     logger.log('INFO', `🚀 [Dispatcher] Smart-Dispatching PASS ${passToRun}`);
     logger.log('INFO', `[Dispatcher] Target Calculations: [${calcNames.join(', ')}]`);
 
-    // 2. Determine Date Range
     const passEarliestDate = Object.values(DEFINITIVE_EARLIEST_DATES).reduce((a, b) => a < b ? a : b);
     const endDateUTC       = new Date(Date.UTC(new Date().getUTCFullYear(), new Date().getUTCMonth(), new Date().getUTCDate() - 1));
     const allExpectedDates = getExpectedDateStrings(passEarliestDate, endDateUTC);
 
     const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
     const tasksToDispatch = [];
-    const limit = pLimit(20); // Process 20 days in parallel
+    const limit = pLimit(20);
 
     logger.log('INFO', `[Dispatcher] Analyzing ${allExpectedDates.length} dates for viability...`);
 
-    // 3. Analyze Each Date (Concurrent)
     const analysisPromises = allExpectedDates.map(dateStr => limit(async () => {
         try {
-            // [NEW] OPTIMIZATION 3: PARALLEL STATUS FETCH
             const fetchPromises = [
-                fetchComputationStatus(dateStr, config, dependencies), // A. Current Status
-                checkRootDataAvailability(dateStr, config, dependencies, DEFINITIVE_EARLIEST_DATES) // C. Root Data
+                fetchComputationStatus(dateStr, config, dependencies),
+                checkRootDataAvailability(dateStr, config, dependencies, DEFINITIVE_EARLIEST_DATES)
             ];
 
-            // B. Fetch Status (Yesterday) - Only if historical continuity is needed
             let prevDateStr = null;
             if (calcsInThisPass.some(c => c.isHistorical)) {
                 const prevDate = new Date(dateStr + 'T00:00:00Z');
@@ -83,25 +76,20 @@ async function dispatchComputationPass(config, dependencies, computationManifest
                 hasPortfolio: false, hasHistory: false, hasSocial: false, hasInsights: false, hasPrices: false
             };
 
-            // D. Run Core Analysis Logic
             const report = analyzeDateExecution(dateStr, calcsInThisPass, rootDataStatus, dailyStatus, manifestMap, prevDailyStatus);
 
-            // E. Handle Non-Runnable States (Write directly to DB, don't dispatch)
             const statusUpdates = {};
             
-            // Mark Impossible (Permanent Failure)
             report.impossible.forEach(item => {
                 if (dailyStatus[item.name]?.hash !== STATUS_IMPOSSIBLE) {
                     statusUpdates[item.name] = { hash: STATUS_IMPOSSIBLE, category: 'unknown', reason: item.reason };
                 }
             });
 
-            // Mark Blocked (Explicit Block)
             report.blocked.forEach(item => {
                  statusUpdates[item.name] = { hash: false, category: 'unknown', reason: item.reason };
             });
 
-            // [FIX] Mark Failed Dependencies (Implicit Block) - Safely generate reason string
             report.failedDependency.forEach(item => {
                  const missingStr = item.missing ? item.missing.join(', ') : 'unknown';
                  statusUpdates[item.name] = { 
@@ -115,11 +103,14 @@ async function dispatchComputationPass(config, dependencies, computationManifest
                 await updateComputationStatus(dateStr, statusUpdates, config, dependencies);
             }
 
-            // F. Queue Runnables
             const validToRun = [...report.runnable, ...report.reRuns];
             validToRun.forEach(item => {
+                // [NEW] Generate Unique ID
+                const uniqueDispatchId = crypto.randomUUID(); 
+                
                 tasksToDispatch.push({
                     action: 'RUN_COMPUTATION_DATE',
+                    dispatchId: uniqueDispatchId, // <--- TRACKING ID
                     date: dateStr,
                     pass: passToRun,
                     computation: normalizeName(item.name),
@@ -137,13 +128,11 @@ async function dispatchComputationPass(config, dependencies, computationManifest
 
     await Promise.all(analysisPromises);
 
-    // 4. Dispatch Valid Tasks with Atomic Ledger Check
     if (tasksToDispatch.length > 0) {
         logger.log('INFO', `[Dispatcher] 📝 Creating Audit Ledger entries (Transactional) for ${tasksToDispatch.length} tasks...`);
         
-        // --- [NEW] OPTIMIZATION 2: ATOMIC TRANSACTION FOR LEDGER ---
         const finalDispatched = [];
-        const txnLimit = pLimit(20); // Limit concurrent transactions
+        const txnLimit = pLimit(20);
         
         const txnPromises = tasksToDispatch.map(task => txnLimit(async () => {
             const ledgerRef = db.collection(`computation_audit_ledger/${task.date}/passes/${task.pass}/tasks`).doc(task.computation);
@@ -151,23 +140,27 @@ async function dispatchComputationPass(config, dependencies, computationManifest
             try {
                 await db.runTransaction(async (t) => {
                     const doc = await t.get(ledgerRef);
+                    
+                    // If task is PENDING, we assume it's running.
+                    // However, we now OVERWRITE if it's been pending for > 1 hour (stuck state)
+                    // For safety on your budget, we stick to strict "PENDING" check.
                     if (doc.exists && doc.data().status === 'PENDING') {
-                        // Task is already pending from another dispatcher, Skip.
                         return false; 
                     }
+                    
                     t.set(ledgerRef, {
                         status: 'PENDING',
+                        dispatchId: task.dispatchId, // <--- Store ID in Ledger
                         computation: task.computation,
                         expectedHash: task.hash || 'unknown',
                         createdAt: new Date(),
-                        dispatcherHash: currentManifestHash, // Tracking source
-                        triggerReason: task.triggerReason, // Track trigger in ledger too
+                        dispatcherHash: currentManifestHash,
+                        triggerReason: task.triggerReason,
                         retries: 0
                     }, { merge: true });
                     return true;
                 });
                 
-                // Only dispatch if we successfully reserved the PENDING state
                 finalDispatched.push(task);
 
             } catch (txnErr) {
@@ -176,7 +169,6 @@ async function dispatchComputationPass(config, dependencies, computationManifest
         }));
 
         await Promise.all(txnPromises);
-        // ---------------------------------------------------
 
         if (finalDispatched.length > 0) {
             logger.log('INFO', `[Dispatcher] ✅ Publishing ${finalDispatched.length} unique tasks to Pub/Sub...`);

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

@@ -1,9 +1,8 @@
 /**
  * FILENAME: computation-system/helpers/computation_worker.js
- * PURPOSE: Consumes computation tasks from Pub/Sub and executes them.
- * UPDATED: Integrated Run Ledger for per-run/per-date success/failure tracking.
- * UPDATED: Added Dead Letter Queue logic for Poison Pills.
- * UPDATED: Now logs the trigger reason.
+ * PURPOSE: Consumes computation tasks from Pub/Sub.
+ * UPDATED: Logs 'dispatchId' for tracing.
+ * UPDATED: Includes Deterministic Error Short-Circuit (Poison Pill Protection).
  */
 
 const { executeDispatchTask } = require('../WorkflowOrchestrator.js');
@@ -15,18 +14,14 @@ let calculationPackage;
 try { calculationPackage = require('aiden-shared-calculations-unified');
 } catch (e) {console.error("FATAL: Could not load 'aiden-shared-calculations-unified'."); throw e; }
 const calculations = calculationPackage.calculations;
-const MAX_RETRIES = 3; 
+const MAX_RETRIES = 0; // <--- CHANGED TO 0 (Application level check, though Pub/Sub config is better)
 
-/**
- * Handles a single Pub/Sub message.
- */
 async function handleComputationTask(message, config, dependencies) {
     const systemLogger = new StructuredLogger({ minLevel: config.minLevel || 'INFO', enableStructured: true, ...config });
     const runDependencies = { ...dependencies, logger: systemLogger };
     const { logger, db }  = runDependencies;
     let data;
 
-    // ----------------------------------- Parse message -----------------------------------
     try {
         if (message.data && message.data.message && message.data.message.data) { data = JSON.parse(Buffer.from(message.data.message.data, 'base64').toString()); 
         } else if (message.data && typeof message.data === 'string')           { data = JSON.parse(Buffer.from(message.data, 'base64').toString()); 
@@ -34,24 +29,28 @@ async function handleComputationTask(message, config, dependencies) {
         } else { data = message; }
     } catch (parseError) { logger.log('ERROR', `[Worker] Failed to parse Pub/Sub payload.`, { error: parseError.message }); return; }
 
-    // ----------------------------------- Validate & Execute -----------------------------------
     if (!data || data.action !== 'RUN_COMPUTATION_DATE') { return; }
     
-    // Extract Trigger Reason
-    const { date, pass, computation, previousCategory, triggerReason } = data;
+    // Extract Trigger Reason and Dispatch ID
+    const { date, pass, computation, previousCategory, triggerReason, dispatchId } = data;
     
-    if (!date || !pass || !computation) { logger.log('ERROR', `[Worker] Invalid payload: Missing date, pass, or computation.`, data); return; }
+    if (!date || !pass || !computation) { logger.log('ERROR', `[Worker] Invalid payload.`, data); return; }
+
+    // LOG THE ID FOR TRACING
+    logger.log('INFO', `[Worker] 📥 Received Task: ${computation} (${date})`, { 
+        dispatchId: dispatchId || 'legacy', 
+        reason: triggerReason 
+    });
+
     let computationManifest;
     try { computationManifest = getManifest(config.activeProductLines || [], calculations, runDependencies);
-    } catch (manifestError) { logger.log('FATAL', `[Worker] Failed to load Manifest: ${manifestError.message}`);
-        // FIX: Passing { durationMs: 0 } instead of {} to satisfy type requirements
+    } catch (manifestError) { 
+        logger.log('FATAL', `[Worker] Failed to load Manifest: ${manifestError.message}`);
         await recordRunAttempt(db, { date, computation, pass }, 'CRASH', { message: manifestError.message, stage: 'MANIFEST_LOAD' }, { durationMs: 0 }, triggerReason);
         return; 
     }
 
     try {
-        logger.log('INFO', `[Worker] 📥 Received: ${computation} for ${date} [Reason: ${triggerReason || 'Unknown'}]`);
-        
         const startTime = Date.now();
         const result    = await executeDispatchTask(
             date, 
@@ -70,7 +69,7 @@ async function handleComputationTask(message, config, dependencies) {
         if (failureReport.length > 0) {
             const failReason = failureReport[0]; 
             logger.log('ERROR', `[Worker] ❌ Failed logic/storage for ${computation}`, failReason.error);
-            const metrics      = failReason.metrics || {};
+            const metrics = failReason.metrics || {};
             metrics.durationMs = duration;
             await recordRunAttempt(db, { date, computation, pass }, 'FAILURE', failReason.error, metrics, triggerReason);
             throw new Error(failReason.error.message || 'Computation Logic Failed');
@@ -79,9 +78,7 @@ async function handleComputationTask(message, config, dependencies) {
             const successData  = successUpdates[computation]; 
             const metrics      = successData.metrics || {};
             metrics.durationMs = duration;
-            
-            logger.log('INFO', `[Worker] ✅ Stored: ${computation}. Processed: ${metrics.execution?.processedUsers || metrics.execution?.processedItems || '?'} items.`);
-            
+            logger.log('INFO', `[Worker] ✅ Stored: ${computation}. ID: ${dispatchId}`);
             await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', null, metrics, triggerReason);
         } 
         else {
@@ -89,12 +86,36 @@ async function handleComputationTask(message, config, dependencies) {
             await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', { message: 'Empty Result' }, { durationMs: duration }, triggerReason);
         }
     } catch (err) { 
+        // --- DETERMINISTIC ERROR SHORT-CIRCUIT ---
+        const isDeterministicError = err.stage === 'SHARDING_LIMIT_EXCEEDED' || 
+                                     err.stage === 'QUALITY_CIRCUIT_BREAKER' ||
+                                     (err.message && (err.message.includes('INVALID_ARGUMENT') || err.message.includes('Transaction too big')));
+
+        if (isDeterministicError) {
+             logger.log('ERROR', `[Worker] 🛑 Permanent Failure (Limit Issue). Sending to DLQ immediately: ${dispatchId}`);
+             try {
+                 await db.collection('computation_dead_letter_queue').add({
+                     originalData: data,
+                     dispatchId: dispatchId,
+                     error: { message: err.message, stack: err.stack, stage: err.stage || 'UNKNOWN' },
+                     finalAttemptAt: new Date(),
+                     failureReason: 'PERMANENT_DETERMINISTIC_ERROR'
+                 });
+                 // Return success to Pub/Sub to STOP retries
+                 await recordRunAttempt(db, { date, computation, pass }, 'FAILURE', { message: err.message, stage: err.stage || 'PERMANENT_FAIL' }, { durationMs: 0 }, triggerReason);
+                 return; 
+             } catch (dlqErr) { logger.log('FATAL', `[Worker] Failed to write to DLQ`, dlqErr); }
+        }
+
+        // --- STANDARD RETRY ---
         const retryCount = message.deliveryAttempt || 0;
+        // NOTE: If you configure Pub/Sub Max Attempts = 1, this logic is redundant but safe.
         if (retryCount >= MAX_RETRIES) {
-             logger.log('ERROR', `[Worker] ☠️ Task POISONED. Moved to DLQ: ${computation} ${date} (Attempt ${retryCount})`);
+             logger.log('ERROR', `[Worker] ☠️ Task POISONED. Moved to DLQ: ${computation}`);
              try {
                  await db.collection('computation_dead_letter_queue').add({
                      originalData: data,
+                     dispatchId: dispatchId,
                      error: { message: err.message, stack: err.stack },
                      finalAttemptAt: new Date(),
                      failureReason: 'MAX_RETRIES_EXCEEDED'
@@ -102,7 +123,8 @@ async function handleComputationTask(message, config, dependencies) {
                  return;
              } catch (dlqErr) { logger.log('FATAL', `[Worker] Failed to write to DLQ`, dlqErr); }
         }
-        logger.log('ERROR', `[Worker] ❌ Crash: ${computation} for ${date}: ${err.message}`); 
+
+        logger.log('ERROR', `[Worker] ❌ Crash: ${computation}: ${err.message}`); 
         await recordRunAttempt(db, { date, computation, pass }, 'CRASH', {  message: err.message, stack: err.stack, stage: 'SYSTEM_CRASH' }, { durationMs: 0 }, triggerReason);
         throw err; 
     }

package/functions/computation-system/tools/BuildReporter.js

@@ -3,6 +3,7 @@
  * Generates a "Pre-Flight" report of what the computation system WILL do.
  * REFACTORED: Strict 5-category reporting with date-based exclusion logic.
  * UPDATED: Added transactional locking to prevent duplicate reports on concurrent cold starts.
+ * UPDATED: Adds 'pass' number to detail records for better waterfall visibility.
  */
 
 const { analyzeDateExecution }                                             = require('../WorkflowOrchestrator');
@@ -164,12 +165,18 @@ async function generateBuildReport(config, dependencies, manifest, daysBack = 90
             dateSummary.meta.totalExpected = expectedCount;
 
             // Helper to push only if date is valid for this specific calc
+            // [UPDATED] Adds 'pass' number to the record
             const pushIfValid = (targetArray, item, extraReason = null) => {
                 const calcManifest = manifestMap.get(item.name);
                 if (calcManifest && isDateBeforeAvailability(dateStr, calcManifest)) {
                     return; // EXCLUDED: Date is before data exists
                 }
-                targetArray.push({ name: item.name, reason: item.reason || extraReason });
+                
+                targetArray.push({ 
+                    name:   item.name, 
+                    reason: item.reason || extraReason,
+                    pass:   calcManifest ? calcManifest.pass : '?'
+                });
             };
 
             // 1. RUN (New)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.273",
+  "version": "1.0.275",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [