bulltrackers-module 1.0.265 → 1.0.267

package/functions/computation-system/WorkflowOrchestrator.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Main Orchestrator. Coordinates the topological execution.
  * UPDATED: Implements Smart Audit logic to detect WHY a hash mismatch occurred.
+ * FIX: Added 'Audit Upgrade' check to force re-run if composition metadata is missing.
  */
 const { normalizeName, DEFINITIVE_EARLIEST_DATES }         = require('./utils/utils');
 const { checkRootDataAvailability, checkRootDependencies } = require('./data/AvailabilityChecker');
@@ -49,8 +50,9 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
 
         const markRunnable = (isReRun = false, reRunDetails = null) => {
             if (isReRun) report.reRuns.push(reRunDetails);
-            else report.runnable.push(calc);
-            simulationStatus[cName] = { hash: currentHash, category: calc.category };
+            else report.runnable.push({ name: cName, ...reRunDetails });
+            // Simulate success so dependents can pass their check
+            simulationStatus[cName] = { hash: currentHash, category: calc.category, composition: calc.composition };
         };
 
         let migrationOldCategory = null;
@@ -107,7 +109,7 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         
         // --- HASH CHECK LOGIC ---
         if (!storedHash) { 
-            markRunnable(false); // New Calculation
+            markRunnable(false, { reason: "New Calculation" }); 
         } 
         else if (storedHash !== currentHash) {
             // Smart Logic: Why did it change?
@@ -116,22 +118,17 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
             const newComp = calc.composition;
 
             if (oldComp && newComp) {
-                // 1. Check Code
                 if (oldComp.code !== newComp.code) {
                     changeReason = "Code Changed";
                 }
-                // 2. Check Layers
                 else if (JSON.stringify(oldComp.layers) !== JSON.stringify(newComp.layers)) {
-                    // Find specific layer
                     const changedLayers = [];
                     for(const lKey in newComp.layers) {
                         if (newComp.layers[lKey] !== oldComp.layers[lKey]) changedLayers.push(lKey);
                     }
                     changeReason = `Layer Update: [${changedLayers.join(', ')}]`;
                 }
-                // 3. Check Dependencies
                 else if (JSON.stringify(oldComp.deps) !== JSON.stringify(newComp.deps)) {
-                    // Find specific dep
                     const changedDeps = [];
                     for(const dKey in newComp.deps) {
                         if (newComp.deps[dKey] !== oldComp.deps[dKey]) changedDeps.push(dKey);
@@ -150,12 +147,21 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
                 oldHash: storedHash, 
                 newHash: currentHash, 
                 previousCategory: migrationOldCategory,
-                reason: changeReason // <--- Passed to Reporter
+                reason: changeReason 
             }); 
         } 
         else if (migrationOldCategory) {       
             markRunnable(true, { name: cName, reason: 'Category Migration', previousCategory: migrationOldCategory, newCategory: calc.category }); 
         } 
+        // [CRITICAL FIX] Audit Upgrade Check: Force re-run if hash matches but composition is missing (Legacy Record)
+        else if (!stored.composition) {
+            markRunnable(true, { 
+                name: cName, 
+                oldHash: storedHash, 
+                newHash: currentHash, 
+                reason: 'Audit Upgrade (Populating Composition Metadata)' 
+            });
+        }
         else { 
             report.skipped.push({ name: cName }); 
             simulationStatus[cName] = { hash: currentHash, category: calc.category, composition: calc.composition }; 

package/functions/computation-system/context/ManifestBuilder.js

@@ -85,7 +85,6 @@ function getDependencySet(endpoints, adjacencyList) {
 function buildManifest(productLinesToRun = [], calculations) {
     log.divider('Building Dynamic Manifest');
     
-    // [LOG VERIFICATION] Log the Input Request
     const requestedLog = (!productLinesToRun || productLinesToRun.length === 0) 
         ? "ALL (Wildcard/Empty)" 
         : productLinesToRun.join(', ');

package/functions/computation-system/executors/MetaExecutor.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Executor for "Meta" (global) calculations.
  * UPDATED: Uses CachedDataLoader for all data access.
+ * UPDATED: Tracks processed shard/item counts.
  */
 const { normalizeName }    = require('../utils/utils');
 const { CachedDataLoader } = require('../data/CachedDataLoader');
@@ -19,8 +20,6 @@ class MetaExecutor {
                 const inst = new mCalc.class(); 
                 inst.manifest = mCalc;
                 
-                // We do not pass 'rootData' (which has null refs) to execution. 
-                // The Executor fetches its own data via loader.
                 await MetaExecutor.executeOncePerDay(inst, mCalc, dStr, fetchedDeps, previousFetchedDeps, config, deps, cachedLoader);
                 state[normalizeName(mCalc.name)] = inst;
             } catch (e) { 
@@ -33,6 +32,7 @@ class MetaExecutor {
     static async executeOncePerDay(calcInstance, metadata, dateStr, computedDeps, prevDeps, config, deps, loader) {
         const mappings = await loader.loadMappings();
         const { logger } = deps;
+        const stats = { processedShards: 0, processedItems: 0 };
         
         // Lazy fetch insights/social using the loader
         const insights   = metadata.rootDataDependencies?.includes('insights') ? { today: await loader.loadInsights(dateStr) } : null;
@@ -55,9 +55,16 @@ class MetaExecutor {
                 await calcInstance.process(partialContext);
                 partialContext.prices = null; 
                 processedCount++;
+                
+                stats.processedShards++;
+                stats.processedItems += Object.keys(shardData).length;
+
                 if (processedCount % 10 === 0 && global.gc) { global.gc(); }
             }
             logger.log('INFO', `[Executor] Finished Batched Execution for ${metadata.name} (${processedCount} shards).`);
+            
+            // Attach stats
+            calcInstance._executionStats = stats;
             return calcInstance.getResult ? await calcInstance.getResult() : {};
         } else {
             const context = ContextFactory.buildMetaContext({ 
@@ -65,7 +72,12 @@ class MetaExecutor {
                 prices: {}, computedDependencies: computedDeps, 
                 previousComputedDependencies: prevDeps, config, deps 
             });
-            return await calcInstance.process(context);
+            const res = await calcInstance.process(context);
+            
+            stats.processedItems = 1; // "Global" item
+            calcInstance._executionStats = stats;
+            
+            return res;
         }
     }
 }

package/functions/computation-system/executors/StandardExecutor.js

@@ -2,6 +2,7 @@
  * @fileoverview Executor for "Standard" (per-user) calculations.
  * UPDATED: Handles lazy loading of data references.
  * UPDATED: Supports Multi-Date Fan-Out Aggregation (Time Machine Mode).
+ * UPDATED: Tracks processed vs skipped users for telemetry.
  */
 const { normalizeName }                                                = require('../utils/utils');
 const { streamPortfolioData, streamHistoryData, getPortfolioPartRefs } = require('../utils/data_loader');
@@ -41,10 +42,6 @@ class StandardExecutor {
         await StandardExecutor.streamAndProcess(dStr, state, passName, config, deps, fullRoot, rootData.portfolioRefs, rootData.historyRefs, fetchedDeps, previousFetchedDeps);
         
         // 4. Pre-Commit Transformation for Fan-Out
-        // If a calc produced multi-date output per user, we must transpose it:
-        // FROM: UserA -> { "2024-01-01": data, "2024-01-02": data }
-        // TO:   "2024-01-01" -> { UserA: data }, "2024-01-02" -> { UserA: data }
-        
         const transformedState = {};
         for (const [name, inst] of Object.entries(state)) {
             const result = await inst.getResult(); // { userId: { date: data } } or { userId: data }
@@ -69,7 +66,8 @@ class StandardExecutor {
                     // Mock a "getResult" for the committer that returns the Transposed Map
                     transformedState[name] = {
                         manifest: inst.manifest,
-                        getResult: async () => transposed
+                        getResult: async () => transposed,
+                        _executionStats: inst._executionStats // Preserve stats
                     };
                     continue;
                 }
@@ -91,6 +89,12 @@ class StandardExecutor {
         
         logger.log('INFO', `[${passName}] Streaming for ${streamingCalcs.length} computations...`);
         
+        // [NEW] Execution Metrics Container
+        const executionStats = {};
+        Object.keys(state).forEach(name => {
+            executionStats[name] = { processedUsers: 0, skippedUsers: 0 };
+        });
+
         const cachedLoader = new CachedDataLoader(config, deps);
         await cachedLoader.loadMappings();
         
@@ -113,7 +117,13 @@ class StandardExecutor {
                 if (tH_iter) tH_chunk = (await tH_iter.next()).value || {};
                 
                 // Execute chunk for all calcs
-                const promises = streamingCalcs.map(calc =>  StandardExecutor.executePerUser(calc, calc.manifest, dateStr, tP_chunk, yP_chunk, tH_chunk, fetchedDeps, previousFetchedDeps, config, deps, cachedLoader) );
+                const promises = streamingCalcs.map(calc =>  
+                    StandardExecutor.executePerUser(
+                        calc, calc.manifest, dateStr, tP_chunk, yP_chunk, tH_chunk, 
+                        fetchedDeps, previousFetchedDeps, config, deps, cachedLoader,
+                        executionStats[normalizeName(calc.manifest.name)]
+                    ) 
+                );
                 await Promise.all(promises);
             }
         } finally {
@@ -122,10 +132,15 @@ class StandardExecutor {
             if (tH_iter && tH_iter.return) await tH_iter.return();
         }
         
+        // Attach stats to the instances so ResultCommitter can find them
+        for(const name in state) {
+            if(state[name]) state[name]._executionStats = executionStats[name];
+        }
+        
         logger.log('INFO', `[${passName}] Streaming complete.`);
     }
 
-    static async executePerUser(calcInstance, metadata, dateStr, portfolioData, yesterdayPortfolioData, historyData, computedDeps, prevDeps, config, deps, loader) {
+    static async executePerUser(calcInstance, metadata, dateStr, portfolioData, yesterdayPortfolioData, historyData, computedDeps, prevDeps, config, deps, loader, stats) {
         const { logger } = deps;
         const targetUserType = metadata.userType; 
         const mappings = await loader.loadMappings();
@@ -139,7 +154,10 @@ class StandardExecutor {
             
             if (targetUserType !== 'all') {
                  const mappedTarget = (targetUserType === 'speculator') ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
-                 if (mappedTarget !== actualUserType) continue;
+                 if (mappedTarget !== actualUserType) {
+                     if (stats) stats.skippedUsers++;
+                     continue;
+                 }
             }
             
             const context = ContextFactory.buildPerUserContext({ 
@@ -149,7 +167,10 @@ class StandardExecutor {
                 config, deps 
             });
             
-            try { await calcInstance.process(context); } 
+            try { 
+                await calcInstance.process(context); 
+                if (stats) stats.processedUsers++;
+            } 
             catch (e) { logger.log('WARN', `Calc ${metadata.name} failed for user ${userId}: ${e.message}`); }
         }
     }

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

@@ -4,6 +4,7 @@
  * UPDATED: Implements Audit Ledger creation with Transactions to prevent Race Conditions.
  * UPDATED: Added Preemptive Hash Check.
  * UPDATED: Added Parallel Status Fetching.
+ * UPDATED: Include triggerReason in Pub/Sub payload.
  */
 
 const { getExpectedDateStrings, normalizeName, DEFINITIVE_EARLIEST_DATES } = require('../utils/utils.js');
@@ -35,14 +36,9 @@ async function dispatchComputationPass(config, dependencies, computationManifest
     if (!calcsInThisPass.length) { return logger.log('WARN', `[Dispatcher] No calcs for Pass ${passToRun}. Exiting.`); }
 
     // --- [NEW] OPTIMIZATION 1: PREEMPTIVE HASH CHECK ---
-    // If the combined hash of all calculations hasn't changed, we might not need to do anything.
-    // Note: This optimization assumes external data (root data) hasn't changed. 
-    // To be safe, we only use this to skip code-change re-runs, but root data might have arrived.
-    // For now, we calculate it but rely on the deep check.
     const currentManifestHash = generateCodeHash(
         computationManifest.map(c => c.hash).sort().join('|')
     );
-    // TODO: Implement metadata storage for this hash to skip "Analysis" phase if needed.
     // ---------------------------------------------------
 
     const calcNames = calcsInThisPass.map(c => c.name);
@@ -122,6 +118,7 @@ async function dispatchComputationPass(config, dependencies, computationManifest
                     computation: normalizeName(item.name),
                     hash: item.hash || item.newHash, 
                     previousCategory: item.previousCategory || null,
+                    triggerReason: item.reason || "Unknown", // <--- THE KEY ADDITION
                     timestamp: Date.now()
                 });
             });
@@ -157,6 +154,7 @@ async function dispatchComputationPass(config, dependencies, computationManifest
                         expectedHash: task.hash || 'unknown',
                         createdAt: new Date(),
                         dispatcherHash: currentManifestHash, // Tracking source
+                        triggerReason: task.triggerReason, // Track trigger in ledger too
                         retries: 0
                     }, { merge: true });
                     return true;

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

@@ -3,6 +3,7 @@
  * 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.
  */
 
 const { executeDispatchTask } = require('../WorkflowOrchestrator.js');
@@ -35,17 +36,21 @@ async function handleComputationTask(message, config, dependencies) {
 
     // ----------------------------------- Validate & Execute -----------------------------------
     if (!data || data.action !== 'RUN_COMPUTATION_DATE') { return; }
-    const { date, pass, computation, previousCategory } = data;
+    
+    // Extract Trigger Reason
+    const { date, pass, computation, previousCategory, triggerReason } = data;
+    
     if (!date || !pass || !computation) { logger.log('ERROR', `[Worker] Invalid payload: Missing date, pass, or computation.`, data); return; }
     let computationManifest;
     try { computationManifest = getManifest(config.activeProductLines || [], calculations, runDependencies);
     } 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' });
+        // FIX: Passing { durationMs: 0 } instead of {} to satisfy type requirements
+        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}`);
+        logger.log('INFO', `[Worker] 📥 Received: ${computation} for ${date} [Reason: ${triggerReason || 'Unknown'}]`);
         
         const startTime = Date.now();
         const result    = await executeDispatchTask(
@@ -67,19 +72,21 @@ async function handleComputationTask(message, config, dependencies) {
             logger.log('ERROR', `[Worker] ❌ Failed logic/storage for ${computation}`, failReason.error);
             const metrics      = failReason.metrics || {};
             metrics.durationMs = duration;
-            await recordRunAttempt(db, { date, computation, pass }, 'FAILURE', failReason.error, metrics);
+            await recordRunAttempt(db, { date, computation, pass }, 'FAILURE', failReason.error, metrics, triggerReason);
             throw new Error(failReason.error.message || 'Computation Logic Failed');
         } 
         else if (Object.keys(successUpdates).length > 0) {
             const successData  = successUpdates[computation]; 
             const metrics      = successData.metrics || {};
             metrics.durationMs = duration;
-            logger.log('INFO', `[Worker] ✅ Stored: ${computation} for ${date} (${metrics.storage?.sizeBytes} bytes)`);
-            await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', null, metrics);
+            
+            logger.log('INFO', `[Worker] ✅ Stored: ${computation}. Processed: ${metrics.execution?.processedUsers || metrics.execution?.processedItems || '?'} items.`);
+            
+            await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', null, metrics, triggerReason);
         } 
         else {
             logger.log('WARN', `[Worker] ⚠️ No results produced for ${computation} (Empty?)`);
-            await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', { message: 'Empty Result' }, { durationMs: duration });
+            await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', { message: 'Empty Result' }, { durationMs: duration }, triggerReason);
         }
     } catch (err) { 
         const retryCount = message.deliveryAttempt || 0;
@@ -96,7 +103,7 @@ async function handleComputationTask(message, config, dependencies) {
              } catch (dlqErr) { logger.log('FATAL', `[Worker] Failed to write to DLQ`, dlqErr); }
         }
         logger.log('ERROR', `[Worker] ❌ Crash: ${computation} for ${date}: ${err.message}`); 
-        await recordRunAttempt(db, { date, computation, pass }, 'CRASH', {  message: err.message, stack: err.stack, stage: 'SYSTEM_CRASH' });
+        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/persistence/ResultCommitter.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Handles saving computation results with observability and Smart Cleanup.
  * UPDATED: Stores Hash Composition in status for audit trail.
+ * UPDATED: Captures execution metrics.
  */
 const { commitBatchInChunks }              = require('./FirestoreUtils');
 const { updateComputationStatus }          = require('./StatusRepository');
@@ -27,9 +28,13 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     for (const name in stateObj) {
         const calc = stateObj[name];
         
+        // [NEW] Check for execution stats attached by Executor
+        const execStats = calc._executionStats || { processedUsers: 0, skippedUsers: 0 };
+
         const runMetrics = {
             storage: { sizeBytes: 0, isSharded: false, shardCount: 1, keys: 0 },
-            validation: { isValid: true, anomalies: [] }
+            validation: { isValid: true, anomalies: [] },
+            execution: execStats // <--- Pass this to RunRecorder
         };
 
         try {
@@ -47,9 +52,9 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             if (isEmpty) { 
                 if (calc.manifest.hash) { 
                     successUpdates[name] = { 
-                        hash: calc.manifest.hash, 
-                        category: calc.manifest.category, 
-                        composition: calc.manifest.composition, // <--- Added Composition
+                        hash:        calc.manifest.hash, 
+                        category:    calc.manifest.category, 
+                        composition: calc.manifest.composition,
                         metrics: runMetrics 
                     }; 
                 } 
@@ -83,9 +88,9 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
-                        hash: calc.manifest.hash, 
-                        category: calc.manifest.category, 
-                        composition: calc.manifest.composition, // <--- Added Composition
+                        hash:        calc.manifest.hash, 
+                        category:    calc.manifest.category, 
+                        composition: calc.manifest.composition,
                         metrics: runMetrics 
                     }; 
                 }
@@ -101,15 +106,15 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
 
                 const writeStats = await writeSingleResult(result, mainDocRef, name, dStr, logger, config, deps);
                 
-                runMetrics.storage.sizeBytes = writeStats.totalSize;
-                runMetrics.storage.isSharded = writeStats.isSharded;
+                runMetrics.storage.sizeBytes  = writeStats.totalSize;
+                runMetrics.storage.isSharded  = writeStats.isSharded;
                 runMetrics.storage.shardCount = writeStats.shardCount;
 
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
-                        hash: calc.manifest.hash, 
-                        category: calc.manifest.category,
-                        composition: calc.manifest.composition, // <--- Added Composition
+                        hash:        calc.manifest.hash, 
+                        category:    calc.manifest.category,
+                        composition: calc.manifest.composition, 
                         metrics: runMetrics 
                     }; 
                 }
@@ -145,6 +150,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     return { successUpdates, failureReport };
 }
 
+// ... (Helper functions remain unchanged from context) ...
 async function writeSingleResult(result, docRef, name, dateContext, logger, config, deps) {
     const strategies = [ { bytes: 900 * 1024, keys: null }, { bytes: 450 * 1024, keys: 10000 }, { bytes: 200 * 1024, keys: 2000 } ];
     let committed = false; let lastError = null; let finalStats = { totalSize: 0, isSharded: false, shardCount: 1 };

package/functions/computation-system/persistence/ResultsValidator.js

@@ -59,11 +59,7 @@ class HeuristicValidator {
                 // Vector/Profile Empty Check (Specific to your System)
                 // If result contains 'profile', 'history', 'sparkline', or 'buckets' arrays
                 const arrayProps = ['profile', 'history', 'sparkline', 'buckets', 'prices'];
-                for (const prop of arrayProps) {
-                    if (Array.isArray(val[prop]) && val[prop].length === 0) {
-                        emptyVectorCount++;
-                    }
-                }
+                for (const prop of arrayProps) { if (Array.isArray(val[prop]) && val[prop].length === 0) { emptyVectorCount++; } }
 
                 // Extract primary numeric score for Flatline check (heuristically guessing the 'main' metric)
                 const numericProp = subValues.find(v => typeof v === 'number' && v !== 0);
@@ -71,8 +67,8 @@ class HeuristicValidator {
             } 
             // --- TYPE B: Scalar / Primitive Result ---
             if (typeof val === 'number') {
-                if (isNaN(val) || !isFinite(val)) {
-                    nanCount++;
+                if (isNaN(val) || !isFinite(val)) 
+                    { nanCount++;
                 } else {
                     numericValues.push(val); // Include zeros
                     if (val === 0) zeroCount++;

package/functions/computation-system/persistence/RunRecorder.js

@@ -1,142 +1,101 @@
 /**
  * @fileoverview Utility for recording computation run attempts (The Audit Logger).
- * REFACTORED: Organizes logs by Computation Name -> History.
- * Implements aggregated error stats and advanced performance metrics.
+ * UPDATED: Stores 'trigger' reason and 'execution' stats.
  */
 
 const { FieldValue } = require('../utils/utils'); 
 const os = require('os');
 
-// Root collection for the new audit system
 const AUDIT_COLLECTION = 'computation_audit_logs';
 
-/**
- * Sanitizes error messages to be used as Firestore Map keys.
- * Replaces invalid characters (. / [ ] *) with underscores.
- */
 function sanitizeErrorKey(message) {
     if (!message) return 'Unknown_Error';
-    // Take first 100 chars to avoid key limit issues
     const shortMsg = message.toString().substring(0, 100); 
     return shortMsg.replace(/[./\[\]*`]/g, '_').trim();
 }
 
 /**
  * Records a run attempt with detailed metrics and aggregated stats.
- * @param {Firestore} db - Firestore instance
- * @param {Object} context - Context object
- * @param {string} context.date - The "Target Date" of the computation
- * @param {string} context.computation - The name of the calculation
- * @param {string} context.pass - The topology pass number
- * @param {string} status - 'SUCCESS', 'FAILURE', 'CRASH', or 'SKIPPED'
- * @param {Object|null} error - Error object if failed
- * @param {Object} detailedMetrics - Expanded metrics object (Optional, defaults provided)
- * @param {number} [detailedMetrics.durationMs] - Execution time
- * @param {Object} [detailedMetrics.storage] - { sizeBytes, isSharded, shardCount }
- * @param {Object} [detailedMetrics.validation] - { isValid, anomalies: [] }
+ * ADDED: 'triggerReason' param.
  */
-async function recordRunAttempt(db, context, status, error = null, detailedMetrics = { durationMs: 0 }) {
+async function recordRunAttempt(db, context, status, error = null, detailedMetrics = { durationMs: 0 }, triggerReason = 'Unknown') {
     if (!db || !context) return;
 
     const { date: targetDate, computation, pass } = context;
     const now = new Date();
     const triggerTimestamp = now.getTime();
     
-    // 1. Construct Paths
-    // Parent Doc: Stores global aggregates for this computation
     const computationDocRef = db.collection(AUDIT_COLLECTION).doc(computation);
-    
-    // History Doc: Stores this specific run
-    // ID Format: targetDate_triggerTimestamp (Sortable by data date, then execution time)
     const runId     = `${targetDate}_${triggerTimestamp}`;
     const runDocRef = computationDocRef.collection('history').doc(runId);
 
-    // 2. Prepare Metrics & Environment Info
     const workerId = process.env.FUNCTION_TARGET || process.env.K_REVISION || os.hostname();
     
-    // Calculate size in MB
     let sizeMB = 0;
     if (detailedMetrics.storage && detailedMetrics.storage.sizeBytes) { sizeMB = Number((detailedMetrics.storage.sizeBytes / (1024 * 1024)).toFixed(4)); }
 
-    // Extract Validation Anomalies (Unusual Keys/Values)
     const anomalies = detailedMetrics.validation?.anomalies || [];
     if (error && error.message && error.message.includes('Data Integrity')) { anomalies.push(error.message); }
 
-    // 3. Construct the Run Log Entry
     const runEntry = {
-        // Identity
         runId: runId,
         computationName: computation,
         pass: String(pass),
         workerId: workerId,
-        
-        // Timing
-        targetDate: targetDate,        // The date the data belongs to
-        triggerTime: now.toISOString(), // The date the code ran
+        targetDate: targetDate,
+        triggerTime: now.toISOString(),
         durationMs: detailedMetrics.durationMs || 0,
-
-        // Status
         status: status,
         
-        // Data Metrics
+        // [NEW] Trigger Context
+        trigger: {
+            reason: triggerReason || 'Unknown', 
+            type: (triggerReason && triggerReason.includes('Layer')) ? 'CASCADE' : ((triggerReason && triggerReason.includes('New')) ? 'INIT' : 'UPDATE')
+        },
+
+        // [NEW] Execution Stats (Internal Loop Data)
+        executionStats: detailedMetrics.execution || {},
+
         outputStats: {
             sizeMB: sizeMB,
             isSharded: !!detailedMetrics.storage?.isSharded,
             shardCount: detailedMetrics.storage?.shardCount || 1,
-            keysWritten: detailedMetrics.storage?.keys || 0 // If available
+            keysWritten: detailedMetrics.storage?.keys || 0 
         },
 
-        // Health & Diagnostics
-        anomalies: anomalies, // Logs "Consistent 0s", "N/As" etc.
-        
-        // Metadata
-        _schemaVersion: '2.0'
+        anomalies: anomalies,
+        _schemaVersion: '2.1'
     };
 
-    // Attach Error Details if present
     if (error) {
         runEntry.error = {
             message: error.message || 'Unknown Error',
             stage: error.stage || 'UNKNOWN',
-            stack: error.stack ? error.stack.substring(0, 1000) : null, // Truncate stack
+            stack: error.stack ? error.stack.substring(0, 1000) : null,
             code: error.code || null
         };
     }
 
-    // 4. Prepare Aggregation Update (Atomic Increments)
     const statsUpdate = {
         lastRunAt: now,
         lastRunStatus: status,
         totalRuns: FieldValue.increment(1)
     };
 
-    if (status === 'SUCCESS') {
-        statsUpdate.successCount = FieldValue.increment(1);
-    } else {
-        statsUpdate.failureCount = FieldValue.increment(1);
-        // Increment specific error type counter
+    if (status === 'SUCCESS') { statsUpdate.successCount = FieldValue.increment(1);
+    } else {                    statsUpdate.failureCount = FieldValue.increment(1);
         if (error) {
             const safeKey = sanitizeErrorKey(error.message);
             statsUpdate[`errorCounts.${safeKey}`] = FieldValue.increment(1);
         }
     }
 
-    // 5. Execute as Batch
     try {
         const batch = db.batch();
-        
-        // Set the specific run log
         batch.set(runDocRef, runEntry);
-        
-        // Merge updates into the parent computation document
-        // We use { merge: true } implicitly with set or explicit update. 
-        // Using set({ merge: true }) ensures doc creation if it doesn't exist.
         batch.set(computationDocRef, statsUpdate, { merge: true });
-
         await batch.commit();
-
     } catch (e) {
-        // Fallback logging if Firestore fails (prevents infinite loop crashing)
         console.error(`[RunRecorder] ❌ CRITICAL: Failed to write audit log for ${computation}`, e);
     }
 }

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

@@ -2,6 +2,7 @@
  * @fileoverview Build Reporter & Auto-Runner.
  * Generates a "Pre-Flight" report of what the computation system WILL do.
  * UPDATED: Fixed 'latest' document overwrite bug.
+ * UPDATED: Now reports specific reasons for Re-Runs.
  */
 
 const { analyzeDateExecution }                                             = require('../WorkflowOrchestrator');

package/package.json

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