bulltrackers-module 1.0.264 → 1.0.266

package/functions/computation-system/WorkflowOrchestrator.js

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Main Orchestrator. Coordinates the topological execution.
- * UPDATED: Uses centralized AvailabilityChecker for strict UserType validation.
+ * UPDATED: Implements Smart Audit logic to detect WHY a hash mismatch occurred.
  */
 const { normalizeName, DEFINITIVE_EARLIEST_DATES }         = require('./utils/utils');
 const { checkRootDataAvailability, checkRootDependencies } = require('./data/AvailabilityChecker');
@@ -10,13 +10,13 @@ const { StandardExecutor }                                 = require('./executor
 const { MetaExecutor }                                     = require('./executors/MetaExecutor');
 const { generateProcessId, PROCESS_TYPES }                 = require('./logger/logger');
 
-// [FIX] Split IMPOSSIBLE into semantic categories
 const STATUS_IMPOSSIBLE_PREFIX = 'IMPOSSIBLE';
 
 function groupByPass(manifest) {  return manifest.reduce((acc, calc) => { (acc[calc.pass] = acc[calc.pass] || []).push(calc);  return acc;  }, {}); }
 
 /**
  * Analyzes whether calculations should run, be skipped, or are blocked.
+ * Now performs Deep Hash Analysis to explain Re-Runs.
  */
 function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus, manifestMap, prevDailyStatus = null) {
     const report           = { runnable: [], blocked: [], impossible: [], failedDependency: [], reRuns: [], skipped: [] };
@@ -28,7 +28,6 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         const stored      = currentStatusMap[norm]; 
         const depManifest = manifestMap.get(norm);
         if (!stored)                           return false;
-        // [FIX] Check for any IMPOSSIBLE variant
         if (typeof stored.hash === 'string' && stored.hash.startsWith(STATUS_IMPOSSIBLE_PREFIX)) return false;
         if (!depManifest)                      return false;
         if (stored.hash !== depManifest.hash)  return false;
@@ -42,7 +41,6 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         const storedCategory = stored ? stored.category : null;
         const currentHash    = calc.hash;
 
-        // [FIX] Granular impossible marking
         const markImpossible = (reason, type = 'GENERIC') => { 
             report.impossible.push({ name: cName, reason }); 
             const statusHash = `${STATUS_IMPOSSIBLE_PREFIX}:${type}`;
@@ -51,14 +49,13 @@ 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 });
+            simulationStatus[cName] = { hash: currentHash, category: calc.category, composition: calc.composition };
         };
 
         let migrationOldCategory = null;
         if (storedCategory && storedCategory !== calc.category) { migrationOldCategory = storedCategory; }
         
-        // [FIX] Check for any IMPOSSIBLE variant in storage
         if (typeof storedHash === 'string' && storedHash.startsWith(STATUS_IMPOSSIBLE_PREFIX)) { 
             report.skipped.push({ name: cName, reason: `Permanently Impossible (${storedHash})` }); 
             continue; 
@@ -69,7 +66,6 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         if (!rootCheck.canRun) {
             const missingStr = rootCheck.missing.join(', ');
             if (!isTargetToday) {
-                // [FIX] Mark specifically as NO_DATA
                 markImpossible(`Missing Root Data: ${missingStr} (Historical)`, 'NO_DATA');
             } else {
                 report.blocked.push({ name: cName, reason: `Missing Root Data: ${missingStr} (Waiting)` });
@@ -83,7 +79,6 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
             for (const dep of calc.dependencies) {
                 const normDep   = normalizeName(dep);
                 const depStored = simulationStatus[normDep];
-                // [FIX] Check for any IMPOSSIBLE variant in dependencies
                 if (depStored && typeof depStored.hash === 'string' && depStored.hash.startsWith(STATUS_IMPOSSIBLE_PREFIX)) { 
                     dependencyIsImpossible = true; 
                     break; 
@@ -93,7 +88,6 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         }
 
         if (dependencyIsImpossible) { 
-            // [FIX] Mark specifically as UPSTREAM failure
             markImpossible('Dependency is Impossible', 'UPSTREAM'); 
             continue; 
         }
@@ -111,44 +105,88 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
             }
         }
         
-        if (!storedHash) { markRunnable(); } 
-        else if (storedHash !== currentHash) { markRunnable(true, { name: cName, oldHash: storedHash, newHash: currentHash, previousCategory: migrationOldCategory }); } 
-        else if (migrationOldCategory) {       markRunnable(true, { name: cName, reason: 'Category Migration', previousCategory: migrationOldCategory, newCategory: calc.category }); } 
-        else { report.skipped.push({ name: cName }); simulationStatus[cName] = { hash: currentHash, category: calc.category }; }
+        // --- HASH CHECK LOGIC ---
+        if (!storedHash) { 
+            markRunnable(false, { reason: "New Calculation" }); 
+        } 
+        else if (storedHash !== currentHash) {
+            // Smart Logic: Why did it change?
+            let changeReason = "Hash Mismatch (Unknown)";
+            const oldComp = stored.composition;
+            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);
+                    }
+                    changeReason = `Upstream Change: [${changedDeps.join(', ')}]`;
+                }
+                else {
+                    changeReason = "Logic/Epoch Change";
+                }
+            } else {
+                changeReason = "Hash Mismatch (No prior composition)";
+            }
+
+            markRunnable(true, { 
+                name: cName, 
+                oldHash: storedHash, 
+                newHash: currentHash, 
+                previousCategory: migrationOldCategory,
+                reason: changeReason // <--- Passed to Reporter
+            }); 
+        } 
+        else if (migrationOldCategory) {       
+            markRunnable(true, { name: cName, reason: 'Category Migration', previousCategory: migrationOldCategory, newCategory: calc.category }); 
+        } 
+        else { 
+            report.skipped.push({ name: cName }); 
+            simulationStatus[cName] = { hash: currentHash, category: calc.category, composition: calc.composition }; 
+        }
     }
     return report;
 }
 
 /**
  * DIRECT EXECUTION PIPELINE (For Workers)
- * Skips analysis. Assumes the calculation is valid and runnable.
- * [UPDATED] Accepted previousCategory argument to handle migrations.
  */
 async function executeDispatchTask(dateStr, pass, targetComputation, config, dependencies, computationManifest, previousCategory = null) {
     const { logger } = dependencies;
     const pid = generateProcessId(PROCESS_TYPES.EXECUTOR, targetComputation, dateStr);
     
-    // 1. Get Calculation Manifest
     const manifestMap = new Map(computationManifest.map(c => [normalizeName(c.name), c]));
     const calcManifest = manifestMap.get(normalizeName(targetComputation));
     
     if (!calcManifest) { throw new Error(`Calculation '${targetComputation}' not found in manifest.`); }
 
-    // [UPDATED] Attach migration context if present
     if (previousCategory) {
         calcManifest.previousCategory = previousCategory;
         logger.log('INFO', `[Executor] Migration detected for ${calcManifest.name}. Old data will be cleaned from: ${previousCategory}`);
     }
 
-    // 2. Fetch Root Data Availability
     const rootData = await checkRootDataAvailability(dateStr, config, dependencies, DEFINITIVE_EARLIEST_DATES);
-    
     if (!rootData) {
-        logger.log('ERROR', `[Executor] FATAL: Root data check failed for ${targetComputation} on ${dateStr}. Index might be missing.`);
+        logger.log('ERROR', `[Executor] FATAL: Root data check failed for ${targetComputation} on ${dateStr}.`);
         return;
     }
 
-    // 3. Fetch Dependencies
     const calcsToRun = [calcManifest];
     const existingResults = await fetchExistingResults(dateStr, calcsToRun, computationManifest, config, dependencies, false);
     
@@ -160,7 +198,6 @@ async function executeDispatchTask(dateStr, pass, targetComputation, config, dep
         previousResults = await fetchExistingResults(prevDateStr, calcsToRun, computationManifest, config, dependencies, true);
     }
 
-    // 4. Execute
     logger.log('INFO', `[Executor] Running ${calcManifest.name} for ${dateStr}`, { processId: pid });
     let resultUpdates = {};
 
@@ -176,5 +213,4 @@ async function executeDispatchTask(dateStr, pass, targetComputation, config, dep
     }
 }
 
-
 module.exports = { executeDispatchTask, groupByPass, analyzeDateExecution };

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

@@ -1,5 +1,6 @@
 /**
  * @fileoverview Dynamic Manifest Builder - Handles Topological Sort and Auto-Discovery.
+ * UPDATED: Generates Granular Hash Composition for Audit Trails.
  */
 const { generateCodeHash, LEGACY_MAPPING } = require('../topology/HashManager.js');
 const { normalizeName }                    = require('../utils/utils');
@@ -84,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(', ');
@@ -106,9 +106,13 @@ function buildManifest(productLinesToRun = [], calculations) {
         const metadata     = Class.getMetadata();
         const dependencies = Class.getDependencies().map(normalizeName);
         const codeStr      = Class.toString();
+        const selfCodeHash = generateCodeHash(codeStr);
+        
+        let compositeHashString = selfCodeHash + `|EPOCH:${SYSTEM_EPOCH}`; 
         
-        let compositeHashString = generateCodeHash(codeStr) + `|EPOCH:${SYSTEM_EPOCH}`; // Here we build the hash
         const usedDeps = [];
+        // Track layer hashes for composition analysis
+        const usedLayerHashes = {}; 
 
         for (const [layerName, exportsMap] of Object.entries(LAYER_TRIGGERS)) {
             const layerHashes = LAYER_HASHES[layerName];
@@ -118,19 +122,30 @@ function buildManifest(productLinesToRun = [], calculations) {
                     if (exportHash) {
                         compositeHashString += exportHash;
                         usedDeps.push(`${layerName}.${exportName}`);
+                        
+                        // Group hashes by layer for the composition report
+                        if (!usedLayerHashes[layerName]) usedLayerHashes[layerName] = '';
+                        usedLayerHashes[layerName] += exportHash;
                     }
                 }
             }
         }
         
+        // Simplify layer hashes to one hash per layer for the report
+        const layerComposition = {};
+        for(const [lName, lStr] of Object.entries(usedLayerHashes)) {
+            layerComposition[lName] = generateCodeHash(lStr);
+        }
+
         // Safe Mode Fallback
         let isSafeMode = false;
         if (usedDeps.length === 0) {
             isSafeMode = true;
             Object.values(LAYER_HASHES).forEach(layerObj => { Object.values(layerObj).forEach(h => compositeHashString += h); }); 
+            layerComposition['ALL_SAFE_MODE'] = 'ALL';
         }
 
-        const baseHash = generateCodeHash(compositeHashString);
+        const intrinsicHash = generateCodeHash(compositeHashString);
 
         const manifestEntry = {
             name: normalizedName,
@@ -143,7 +158,16 @@ function buildManifest(productLinesToRun = [], calculations) {
             userType: metadata.userType,
             dependencies: dependencies,
             pass: 0,
-            hash: baseHash,
+            hash: intrinsicHash, // Will be updated with deps
+            
+            // [NEW] Composition Object for Audit
+            composition: {
+                epoch: SYSTEM_EPOCH,
+                code: selfCodeHash,
+                layers: layerComposition,
+                deps: {} // Will be populated after topo sort
+            },
+            
             debugUsedLayers: isSafeMode ? ['ALL (Safe Mode)'] : usedDeps
         };
         
@@ -174,8 +198,6 @@ function buildManifest(productLinesToRun = [], calculations) {
     }
 
     const productLineEndpoints = [];
-    
-    // [UPDATE] Check if we should run ALL product lines (if empty or wildcard)
     const runAll = !productLinesToRun || productLinesToRun.length === 0 || productLinesToRun.includes('*');
 
     for (const [name, entry] of manifestMap.entries()) {  
@@ -187,7 +209,6 @@ function buildManifest(productLinesToRun = [], calculations) {
     const requiredCalcs = getDependencySet(productLineEndpoints, adjacency);
     log.info(`Filtered down to ${requiredCalcs.size} active calculations.`);
 
-    // [LOG VERIFICATION] Final Proof of Active Lines
     const activePackages = new Set();
     requiredCalcs.forEach(name => {
         const entry = manifestMap.get(name);
@@ -240,11 +261,17 @@ function buildManifest(productLinesToRun = [], calculations) {
 
     // --- Cascading Hash (Phase 2) ---
     for (const entry of sortedManifest) {
-        let dependencySignature = entry.hash;
+        let dependencySignature = entry.hash; // Start with intrinsic
+        
         if (entry.dependencies && entry.dependencies.length > 0) {
             const depHashes = entry.dependencies.map(depName => { 
-                const depEntry = filteredManifestMap.get(depName); 
-                return depEntry ? depEntry.hash : ''; 
+                const depEntry = filteredManifestMap.get(depName);
+                if (depEntry) {
+                    // Populate Composition
+                    entry.composition.deps[depName] = depEntry.hash;
+                    return depEntry.hash;
+                }
+                return ''; 
             }).join('|'); 
             dependencySignature += `|DEPS:${depHashes}`;
         }

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,8 +1,7 @@
 /**
  * @fileoverview Handles saving computation results with observability and Smart Cleanup.
- * UPDATED: Returns detailed failure reports AND metrics for the Audit Logger.
- * UPDATED: Stops retrying on non-transient errors.
- * UPDATED: Supports Multi-Date Fan-Out (Time Machine Mode) with CONCURRENCY THROTTLING.
+ * UPDATED: Stores Hash Composition in status for audit trail.
+ * UPDATED: Captures execution metrics.
  */
 const { commitBatchInChunks }              = require('./FirestoreUtils');
 const { updateComputationStatus }          = require('./StatusRepository');
@@ -10,13 +9,10 @@ const { batchStoreSchemas }                = require('../utils/schema_capture');
 const { generateProcessId, PROCESS_TYPES } = require('../logger/logger');
 const { HeuristicValidator }               = require('./ResultsValidator');
 const validationOverrides                  = require('../config/validation_overrides'); 
-const pLimit                               = require('p-limit'); // <--- CRITICAL IMPORT
+const pLimit                               = require('p-limit'); 
 
 const NON_RETRYABLE_ERRORS = [
-    'INVALID_ARGUMENT',      // Schema/Type mismatch
-    'PERMISSION_DENIED',     // Auth issue
-    'DATA_LOSS',             // Firestore corruption
-    'FAILED_PRECONDITION'    // Transaction requirements not met
+    'INVALID_ARGUMENT',      'PERMISSION_DENIED',     'DATA_LOSS',             'FAILED_PRECONDITION'
 ];
 
 async function commitResults(stateObj, dStr, passName, config, deps, skipStatusWrite = false) {
@@ -27,21 +23,22 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     const { logger, db } = deps;
     const pid            = generateProcessId(PROCESS_TYPES.STORAGE, passName, dStr);
     
-    // SAFETY LIMIT: Only allow 10 concurrent daily writes to prevent network saturation during Fan-Out
     const fanOutLimit = pLimit(10); 
 
     for (const name in stateObj) {
         const calc = stateObj[name];
         
-        // Prep metrics container
+        // [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 {
             const result = await calc.getResult();
-
             const overrides   = validationOverrides[calc.manifest.name] || {};
             const healthCheck = HeuristicValidator.analyze(calc.manifest.name, result, overrides);
 
@@ -54,52 +51,52 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             const isEmpty = !result || (typeof result === 'object' && Object.keys(result).length === 0) || (typeof result === 'number' && result === 0);
             if (isEmpty) { 
                 if (calc.manifest.hash) { 
-                    successUpdates[name] = { hash: false, category: calc.manifest.category, metrics: runMetrics }; 
+                    successUpdates[name] = { 
+                        hash:        calc.manifest.hash, 
+                        category:    calc.manifest.category, 
+                        composition: calc.manifest.composition,
+                        metrics: runMetrics 
+                    }; 
                 } 
                 continue; 
             }
             
             if (typeof result === 'object') runMetrics.storage.keys = Object.keys(result).length;
 
-            // --- MULTI-DATE FAN-OUT DETECTION ---
-            // If the result keys are ALL date strings (YYYY-MM-DD), we split the writes.
+            // ... (Fan-out logic remains same) ...
             const resultKeys = Object.keys(result || {});
             const isMultiDate = resultKeys.length > 0 && resultKeys.every(k => /^\d{4}-\d{2}-\d{2}$/.test(k));
 
             if (isMultiDate) {
                 logger.log('INFO', `[ResultCommitter] 🕰️ Multi-Date Output detected for ${name} (${resultKeys.length} days). Throttled Fan-Out...`);
                 
-                // Group updates by DATE. result is { "2024-01-01": { user1: ... }, "2024-01-02": { user1: ... } }
-                // We execute a fan-out commit for each date using p-limit.
-                
                 const datePromises = resultKeys.map((historicalDate) => fanOutLimit(async () => {
                     const dailyData = result[historicalDate];
                     if (!dailyData || Object.keys(dailyData).length === 0) return;
 
                     const historicalDocRef = db.collection(config.resultsCollection)
-                        .doc(historicalDate) // Use the HISTORICAL date, not dStr
+                        .doc(historicalDate)
                         .collection(config.resultsSubcollection)
                         .doc(calc.manifest.category)
                         .collection(config.computationsSubcollection)
                         .doc(name);
 
-                    // Re-use the existing sharding logic for this specific date payload
                     await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps);
                 }));
                 
                 await Promise.all(datePromises);
                 
-                // Mark success for the Target Date (dStr) so the workflow continues
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
-                        hash: calc.manifest.hash, 
-                        category: calc.manifest.category, 
-                        metrics: runMetrics // Pass metrics up
+                        hash:        calc.manifest.hash, 
+                        category:    calc.manifest.category, 
+                        composition: calc.manifest.composition,
+                        metrics: runMetrics 
                     }; 
                 }
 
             } else {
-                // --- STANDARD MODE (Single Date) ---
+                // --- STANDARD MODE ---
                 const mainDocRef = db.collection(config.resultsCollection)
                     .doc(dStr)
                     .collection(config.resultsSubcollection)
@@ -107,30 +104,27 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                     .collection(config.computationsSubcollection)
                     .doc(name);
 
-                // Use the encapsulated write function
                 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;
 
-                // Mark Success & Pass Metrics
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
-                        hash: calc.manifest.hash, 
-                        category: calc.manifest.category,
+                        hash:        calc.manifest.hash, 
+                        category:    calc.manifest.category,
+                        composition: calc.manifest.composition, 
                         metrics: runMetrics 
                     }; 
                 }
             }
 
-            // Capture Schema
             if (calc.manifest.class.getSchema) {
                 const { class: _cls, ...safeMetadata } = calc.manifest;
                 schemas.push({ name, category: calc.manifest.category, schema: calc.manifest.class.getSchema(), metadata: safeMetadata });
             }
 
-            // Cleanup Migration
             if (calc.manifest.previousCategory && calc.manifest.previousCategory !== calc.manifest.category) {
                 cleanupTasks.push(deleteOldCalculationData(dStr, calc.manifest.previousCategory, name, config, deps));
             }
@@ -144,7 +138,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             failureReport.push({
                 name,
                 error: { message: msg, stack: e.stack, stage },
-                metrics: runMetrics // Pass incomplete metrics for debugging
+                metrics: runMetrics 
             });
         }
     }
@@ -156,181 +150,80 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     return { successUpdates, failureReport };
 }
 
-/**
- * Encapsulated write logic for reuse in Fan-Out.
- * Handles sharding strategy and retries.
- */
+// ... (Helper functions remain unchanged from context) ...
 async function writeSingleResult(result, docRef, name, dateContext, logger, config, deps) {
-    // Strategy: 1=Normal, 2=Safe (Halved), 3=Aggressive (Quartered + Key Limit)
-    const strategies = [
-        { bytes: 900 * 1024, keys: null },      // Attempt 1: Standard
-        { bytes: 450 * 1024, keys: 10000 },     // Attempt 2: High Index usage
-        { bytes: 200 * 1024, keys: 2000 }       // Attempt 3: Extreme fragmentation
-    ];
-
-    let committed = false;
-    let lastError = null;
-    let finalStats = { totalSize: 0, isSharded: false, shardCount: 1 };
+    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 };
 
     for (let attempt = 0; attempt < strategies.length; attempt++) {
         if (committed) break;
-        
         const constraints = strategies[attempt];
-        
         try {
-            // 1. Prepare Shards with current constraints
             const updates = await prepareAutoShardedWrites(result, docRef, logger, constraints.bytes, constraints.keys);
-            
-            // Stats
             const pointer = updates.find(u => u.data._completed === true);
             finalStats.isSharded = pointer && pointer.data._sharded === true;
             finalStats.shardCount = finalStats.isSharded ? (pointer.data._shardCount || 1) : 1;
             finalStats.totalSize = updates.reduce((acc, u) => acc + (u.data ? JSON.stringify(u.data).length : 0), 0);
-
-            // 2. Attempt Commit
             await commitBatchInChunks(config, deps, updates, `${name}::${dateContext} (Att ${attempt+1})`);
-            
-            // Log Success
-            if (logger && logger.logStorage) { 
-                logger.logStorage(null, name, dateContext, docRef.path, finalStats.totalSize, finalStats.isSharded); 
-            }
-            
-            committed = true; // Exit loop
-
+            if (logger && logger.logStorage) { logger.logStorage(null, name, dateContext, docRef.path, finalStats.totalSize, finalStats.isSharded); }
+            committed = true;
         } catch (commitErr) {
             lastError = commitErr;
             const msg = commitErr.message || '';
-            
-            const isNonRetryable = NON_RETRYABLE_ERRORS.includes(commitErr.code);
-            if (isNonRetryable) {
-                logger.log('ERROR', `[SelfHealing] ${name} encountered FATAL error (Attempt ${attempt + 1}): ${msg}. Aborting.`);
-                throw commitErr; 
-            }
-
-            const isSizeError  = msg.includes('Transaction too big')    || msg.includes('payload is too large');
-            const isIndexError = msg.includes('too many index entries') || msg.includes('INVALID_ARGUMENT'); 
-
-            if (isSizeError || isIndexError) {
-                logger.log('WARN', `[SelfHealing] ${name} on ${dateContext} failed write attempt ${attempt + 1}. Retrying with tighter constraints...`, { error: msg });
-                continue; // Try next strategy
-            } else {
-                logger.log('WARN', `[SelfHealing] ${name} on ${dateContext} unknown error (Attempt ${attempt + 1}). Retrying...`, { error: msg });
-            }
+            if (NON_RETRYABLE_ERRORS.includes(commitErr.code)) { logger.log('ERROR', `[SelfHealing] ${name} FATAL error: ${msg}.`); throw commitErr; }
+            if (msg.includes('Transaction too big') || msg.includes('payload is too large') || msg.includes('too many index entries')) { logger.log('WARN', `[SelfHealing] ${name} on ${dateContext} failed attempt ${attempt+1}. Retrying...`, { error: msg }); continue; }
+            else { logger.log('WARN', `[SelfHealing] ${name} on ${dateContext} unknown error. Retrying...`, { error: msg }); }
         }
     }
-
-    if (!committed) {
-        throw { 
-            message: `Exhausted sharding strategies for ${name} on ${dateContext}. Last error: ${lastError?.message}`, 
-            stack: lastError?.stack, 
-            stage: 'SHARDING_LIMIT_EXCEEDED' 
-        };
-    }
-
+    if (!committed) { throw { message: `Exhausted sharding strategies for ${name}. Last error: ${lastError?.message}`, stack: lastError?.stack, stage: 'SHARDING_LIMIT_EXCEEDED' }; }
     return finalStats;
 }
 
-/**
- * Deletes result documents from a previous category location.
- */
 async function deleteOldCalculationData(dateStr, oldCategory, calcName, config, deps) {
     const { db, logger, calculationUtils } = deps;
     const { withRetry } = calculationUtils || { withRetry: (fn) => fn() };
-    
     try {
-        const oldDocRef = db.collection(config.resultsCollection)
-            .doc(dateStr)
-            .collection(config.resultsSubcollection)
-            .doc(oldCategory)
-            .collection(config.computationsSubcollection)
-            .doc(calcName);
-
-        const shardsCol  = oldDocRef.collection('_shards');
+        const oldDocRef = db.collection(config.resultsCollection).doc(dateStr).collection(config.resultsSubcollection).doc(oldCategory).collection(config.computationsSubcollection).doc(calcName);
+        const shardsCol = oldDocRef.collection('_shards');
         const shardsSnap = await withRetry(() => shardsCol.listDocuments(), 'ListOldShards');
-        const batch      = db.batch();
-        let ops          = 0;
-
+        const batch = db.batch(); let ops = 0;
         for (const shardDoc of shardsSnap) { batch.delete(shardDoc); ops++; }
-        batch.delete(oldDocRef);
-        ops++;
-
+        batch.delete(oldDocRef); ops++;
         await withRetry(() => batch.commit(), 'CleanupOldCategory');
-        logger.log('INFO', `[Migration] Cleaned up ${ops} docs for ${calcName} in old category '${oldCategory}'`);
-
-    } catch (e) {
-        logger.log('WARN', `[Migration] Failed to clean up old data for ${calcName}: ${e.message}`);
-    }
+        logger.log('INFO', `[Migration] Cleaned up ${ops} docs for ${calcName} in '${oldCategory}'`);
+    } catch (e) { logger.log('WARN', `[Migration] Failed to clean up ${calcName}: ${e.message}`); }
 }
 
 function calculateFirestoreBytes(value) {
-    if (value === null) return 1;
-    if (value === undefined) return 0;
-    if (typeof value === 'boolean') return 1;
-    if (typeof value === 'number') return 8;
-    if (typeof value === 'string') return Buffer.byteLength(value, 'utf8') + 1;
-    if (value instanceof Date) return 8;
-    if (value.constructor && value.constructor.name === 'DocumentReference') { return Buffer.byteLength(value.path, 'utf8') + 16; }
+    if (value === null) return 1; if (value === undefined) return 0; if (typeof value === 'boolean') return 1; if (typeof value === 'number') return 8; if (typeof value === 'string') return Buffer.byteLength(value, 'utf8') + 1; if (value instanceof Date) return 8; if (value.constructor && value.constructor.name === 'DocumentReference') { return Buffer.byteLength(value.path, 'utf8') + 16; }
     if (Array.isArray(value)) { let sum = 0; for (const item of value) sum += calculateFirestoreBytes(item); return sum; }
-    if (typeof value === 'object') { let sum = 0; for (const k in value) { if (Object.prototype.hasOwnProperty.call(value, k)) { sum += (Buffer.byteLength(k, 'utf8') + 1) + calculateFirestoreBytes(value[k]); } } return sum; }
-    return 0;
+    if (typeof value === 'object') { let sum = 0; for (const k in value) { if (Object.prototype.hasOwnProperty.call(value, k)) { sum += (Buffer.byteLength(k, 'utf8') + 1) + calculateFirestoreBytes(value[k]); } } return sum; } return 0;
 }
 
 async function prepareAutoShardedWrites(result, docRef, logger, maxBytes = 900 * 1024, maxKeys = null) {
-    const OVERHEAD_ALLOWANCE     = 20 * 1024;
-    const CHUNK_LIMIT            = maxBytes - OVERHEAD_ALLOWANCE;
-    
-    const totalSize              = calculateFirestoreBytes(result);
-    const docPathSize            = Buffer.byteLength(docRef.path, 'utf8') + 16;
-    
-    const writes                 = [];
-    const shardCollection        = docRef.collection('_shards');
-    let currentChunk             = {};
-    let currentChunkSize         = 0;
-    let currentKeyCount          = 0;
-    let shardIndex               = 0;
+    const OVERHEAD_ALLOWANCE = 20 * 1024; const CHUNK_LIMIT = maxBytes - OVERHEAD_ALLOWANCE;
+    const totalSize = calculateFirestoreBytes(result); const docPathSize = Buffer.byteLength(docRef.path, 'utf8') + 16;
+    const writes = []; const shardCollection = docRef.collection('_shards');
+    let currentChunk = {}; let currentChunkSize = 0; let currentKeyCount = 0; let shardIndex = 0;
 
-    // Fast path: If small enough AND keys are safe
     if (!maxKeys && (totalSize + docPathSize) < CHUNK_LIMIT) {  
-        const data = { 
-            ...result, 
-            _completed: true, 
-            _sharded: false,
-            _lastUpdated: new Date().toISOString() 
-        };  
+        const data = { ...result, _completed: true, _sharded: false, _lastUpdated: new Date().toISOString() };  
         return [{ ref: docRef, data, options: { merge: true } }];  
     }
 
     for (const [key, value] of Object.entries(result)) { 
         if (key.startsWith('_')) continue;
-        const keySize   = Buffer.byteLength(key, 'utf8') + 1;         
-        const valueSize = calculateFirestoreBytes(value);
-        const itemSize  = keySize + valueSize;
-
-        const byteLimitReached = (currentChunkSize + itemSize > CHUNK_LIMIT);
-        const keyLimitReached = (maxKeys && currentKeyCount + 1 >= maxKeys);
-
+        const keySize = Buffer.byteLength(key, 'utf8') + 1; const valueSize = calculateFirestoreBytes(value); const itemSize = keySize + valueSize;
+        const byteLimitReached = (currentChunkSize + itemSize > CHUNK_LIMIT); const keyLimitReached = (maxKeys && currentKeyCount + 1 >= maxKeys);
         if (byteLimitReached || keyLimitReached) { 
             writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } });
-            shardIndex++;
-            currentChunk     = {};
-            currentChunkSize = 0;
-            currentKeyCount  = 0;
+            shardIndex++; currentChunk = {}; currentChunkSize = 0; currentKeyCount = 0;
         }
-        currentChunk[key] = value;
-        currentChunkSize += itemSize;
-        currentKeyCount++;
-    }
-
-    if (Object.keys(currentChunk).length > 0) {  
-        writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } });  
+        currentChunk[key] = value; currentChunkSize += itemSize; currentKeyCount++;
     }
+    if (Object.keys(currentChunk).length > 0) { writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } }); }
     
-    const pointerData = { 
-        _completed: true, 
-        _sharded: true, 
-        _shardCount: shardIndex + 1, 
-        _lastUpdated: new Date().toISOString() 
-    };
+    const pointerData = { _completed: true, _sharded: true, _shardCount: shardIndex + 1, _lastUpdated: new Date().toISOString() };
     writes.push({ ref: docRef, data: pointerData, options: { merge: false } });
     return writes;
 }

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/persistence/StatusRepository.js

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Manages computation status tracking in Firestore.
- * UPDATED: Supports Schema V2 (Object with Category) for smart migrations.
+ * UPDATED: Supports Schema V2 (Object with Category & Composition) for deep auditing.
  */
 
 async function fetchComputationStatus(dateStr, config, { db }) {
@@ -14,8 +14,11 @@ async function fetchComputationStatus(dateStr, config, { db }) {
 
     // Normalize V1 (String) to V2 (Object)
     for (const [name, value] of Object.entries(rawData)) {
-        if (typeof value === 'string') { normalized[name] = { hash: value, category: null }; // Legacy entry
-        } else { normalized[name] = value; }
+        if (typeof value === 'string') { 
+            normalized[name] = { hash: value, category: null, composition: null }; // Legacy entry
+        } else { 
+            normalized[name] = value; 
+        }
     }
 
     return normalized;
@@ -30,8 +33,16 @@ async function updateComputationStatus(dateStr, updates, config, { db }) {
     
     const safeUpdates = {};
     for (const [key, val] of Object.entries(updates)) {
-        if (typeof val === 'string') { safeUpdates[key] = { hash: val, category: 'unknown', lastUpdated: new Date() };
-        } else { safeUpdates[key] = { ...val, lastUpdated: new Date() }; }
+        if (typeof val === 'string') { 
+            // Legacy Call Fallback
+            safeUpdates[key] = { hash: val, category: 'unknown', lastUpdated: new Date() };
+        } else { 
+            // V2 Call: val should contain { hash, category, composition }
+            safeUpdates[key] = { 
+                ...val, 
+                lastUpdated: new Date() 
+            }; 
+        }
     }
 
     await docRef.set(safeUpdates, { merge: true });

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');
@@ -111,8 +112,9 @@ async function generateBuildReport(config, dependencies, manifest, daysBack = 90
             // E. Format Findings
             const dateSummary = { willRun: [], willReRun: [], blocked: [], impossible: [] };
 
+            // Pass the generated "Reason" string through to the report
             analysis.runnable.forEach   (item => dateSummary.willRun.push    ({ name: item.name, reason: "New / No Previous Record" }));
-            analysis.reRuns.forEach     (item => dateSummary.willReRun.push  ({ name: item.name, reason: item.previousCategory ? "Migration" : "Hash Mismatch" }));
+            analysis.reRuns.forEach     (item => dateSummary.willReRun.push  ({ name: item.name, reason: item.reason || "Hash Mismatch" }));
             analysis.impossible.forEach (item => dateSummary.impossible.push ({ name: item.name, reason: item.reason }));
             [...analysis.blocked, ...analysis.failedDependency].forEach(item => dateSummary.blocked.push({ name: item.name, reason: item.reason || 'Dependency' }));
 

package/package.json

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