bulltrackers-module 1.0.270 → 1.0.272

package/functions/computation-system/WorkflowOrchestrator.js

@@ -2,6 +2,7 @@
  * @fileoverview Main Orchestrator. Coordinates the topological execution.
  * UPDATED: Removed 'Permanently Impossible' optimization to ensure full visibility/recovery.
  * UPDATED: Includes 'Audit Upgrade' check.
+ * UPDATED: Detailed Dependency Reporting for Impossible Chains.
  */
 const { normalizeName, DEFINITIVE_EARLIEST_DATES }         = require('./utils/utils');
 const { checkRootDataAvailability, checkRootDependencies } = require('./data/AvailabilityChecker');
@@ -76,6 +77,7 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
 
         // 2. Check Dependencies
         let dependencyIsImpossible = false;
+        let impossibleDepCause = null;
         const missingDeps = [];
         if (calc.dependencies) {
             for (const dep of calc.dependencies) {
@@ -83,6 +85,7 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
                 const depStored = simulationStatus[normDep];
                 if (depStored && typeof depStored.hash === 'string' && depStored.hash.startsWith(STATUS_IMPOSSIBLE_PREFIX)) { 
                     dependencyIsImpossible = true; 
+                    impossibleDepCause = dep; // Capture the culprit
                     break; 
                 }
                 if (!isDepSatisfied(dep, simulationStatus, manifestMap)) { missingDeps.push(dep); }
@@ -90,7 +93,8 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         }
 
         if (dependencyIsImpossible) { 
-            markImpossible('Dependency is Impossible', 'UPSTREAM'); 
+            // [UPDATED] Include the name of the failing dependency in the reason string
+            markImpossible(`Dependency is Impossible (${impossibleDepCause})`, 'UPSTREAM'); 
             continue; 
         }
         if (missingDeps.length > 0) { report.failedDependency.push({ name: cName, missing: missingDeps }); continue; }

package/functions/computation-system/config/validation_overrides.js

@@ -3,4 +3,7 @@ module.exports = {
     // EXAMPLES :
     // "bankruptcy-detector": { maxZeroPct: 100 }, // It's rare, so 100% 0s is fine
     // "sparse-signal-generator": { maxNullPct: 99 }
+
+    "instrument-price-change-1d":        { maxZeroPct: 100 }, // Because weekeends/holidays return 0 change, technically crypto means this can't hit 100% but it's usually quite close, so we override
+    "instrument-price-momentum-20d ":    { maxZeroPct: 100 }, // Some assets can be very stagnant over a month, especially bonds or stablecoins
 };

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

@@ -2,6 +2,7 @@
  * @fileoverview Executor for "Meta" (global) calculations.
  * UPDATED: Uses CachedDataLoader for all data access.
  * UPDATED: Tracks processed shard/item counts.
+ * UPDATED: Removed global.gc() calls.
  */
 const { normalizeName }    = require('../utils/utils');
 const { CachedDataLoader } = require('../data/CachedDataLoader');
@@ -59,7 +60,7 @@ class MetaExecutor {
                 stats.processedShards++;
                 stats.processedItems += Object.keys(shardData).length;
 
-                if (processedCount % 10 === 0 && global.gc) { global.gc(); }
+                // Removed global.gc()
             }
             logger.log('INFO', `[Executor] Finished Batched Execution for ${metadata.name} (${processedCount} shards).`);
             

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

@@ -1,8 +1,8 @@
 /**
  * @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.
+ * UPDATED: Implements Batch Flushing to prevent OOM on large datasets.
+ * UPDATED: Removes manual global.gc() calls.
+ * UPDATED: Manages incremental sharding states.
  */
 const { normalizeName }                                                = require('../utils/utils');
 const { streamPortfolioData, streamHistoryData, getPortfolioPartRefs } = require('../utils/data_loader');
@@ -19,9 +19,8 @@ class StandardExecutor {
         // 1. Prepare Yesterdays Data if needed
         const fullRoot = { ...rootData };
         if (calcs.some(c => c.isHistorical)) {
-            const prev                      = new Date(date); prev.setUTCDate(prev.getUTCDate() - 1);
-            const prevStr                   = prev.toISOString().slice(0, 10);
-            // Explicitly fetch yesterday's refs as they aren't provided by the daily indexer
+            const prev = new Date(date); prev.setUTCDate(prev.getUTCDate() - 1);
+            const prevStr = prev.toISOString().slice(0, 10);
             fullRoot.yesterdayPortfolioRefs = await getPortfolioPartRefs(config, deps, prevStr);
         }
 
@@ -31,6 +30,8 @@ class StandardExecutor {
             try { 
                 const inst = new c.class(); 
                 inst.manifest = c; 
+                // Ensure internal storage exists for flushing
+                inst.results = {}; 
                 state[normalizeName(c.name)] = inst; 
                 logger.log('INFO', `${c.name} calculation running for ${dStr}`); 
             } catch (e) { 
@@ -38,61 +39,29 @@ class StandardExecutor {
             } 
         }
 
-        // 3. Stream & Process
-        await StandardExecutor.streamAndProcess(dStr, state, passName, config, deps, fullRoot, rootData.portfolioRefs, rootData.historyRefs, fetchedDeps, previousFetchedDeps);
-        
-        // 4. Pre-Commit Transformation for Fan-Out
-        const transformedState = {};
-        for (const [name, inst] of Object.entries(state)) {
-            const result = await inst.getResult(); // { userId: { date: data } } or { userId: data }
-            const firstUser = Object.keys(result)[0];
-            
-            // Check if the inner value is a Date Map
-            // Only checks the first user as heuristic; implies uniform return type
-            if (firstUser && result[firstUser] && typeof result[firstUser] === 'object') {
-                const innerKeys = Object.keys(result[firstUser]);
-                // Check if keys look like YYYY-MM-DD
-                const isDateMap = innerKeys.length > 0 && innerKeys.every(k => /^\d{4}-\d{2}-\d{2}$/.test(k));
-                
-                if (isDateMap) {
-                    const transposed = {};
-                    for (const [userId, dateMap] of Object.entries(result)) {
-                        for (const [dateKey, dailyData] of Object.entries(dateMap)) {
-                            if (!transposed[dateKey]) transposed[dateKey] = {};
-                            transposed[dateKey][userId] = dailyData;
-                        }
-                    }
-                    
-                    // Mock a "getResult" for the committer that returns the Transposed Map
-                    transformedState[name] = {
-                        manifest: inst.manifest,
-                        getResult: async () => transposed,
-                        _executionStats: inst._executionStats // Preserve stats
-                    };
-                    continue;
-                }
-            }
-            // Normal behavior
-            transformedState[name] = inst;
-        }
-
-        // 5. Commit
-        return await commitResults(transformedState, dStr, passName, config, deps, skipStatusWrite);
+        // 3. Stream, Process & Batch Flush
+        // The return value contains the aggregated success/failure reports from all flushes
+        return await StandardExecutor.streamAndProcess(dStr, state, passName, config, deps, fullRoot, rootData.portfolioRefs, rootData.historyRefs, fetchedDeps, previousFetchedDeps, skipStatusWrite);
     }
 
-    static async streamAndProcess(dateStr, state, passName, config, deps, rootData, portfolioRefs, historyRefs, fetchedDeps, previousFetchedDeps) {
+    static async streamAndProcess(dateStr, state, passName, config, deps, rootData, portfolioRefs, historyRefs, fetchedDeps, previousFetchedDeps, skipStatusWrite) {
         const { logger } = deps;
         const calcs = Object.values(state).filter(c => c && c.manifest);
         const streamingCalcs = calcs.filter(c => c.manifest.rootDataDependencies.includes('portfolio') || c.manifest.rootDataDependencies.includes('history'));
         
-        if (streamingCalcs.length === 0) return;
+        if (streamingCalcs.length === 0) return { successUpdates: {}, failureReport: [] };
         
         logger.log('INFO', `[${passName}] Streaming for ${streamingCalcs.length} computations...`);
         
-        // [NEW] Execution Metrics Container
+        // Metrics & State Tracking
         const executionStats = {};
+        const shardIndexMap  = {}; // Tracks sharding offsets per calculation
+        const aggregatedSuccess = {};
+        const aggregatedFailures = [];
+
         Object.keys(state).forEach(name => {
             executionStats[name] = { processedUsers: 0, skippedUsers: 0 };
+            shardIndexMap[name]  = 0;
         });
 
         const cachedLoader = new CachedDataLoader(config, deps);
@@ -102,20 +71,24 @@ class StandardExecutor {
         const prevDateStr = prevDate.toISOString().slice(0, 10);
         
         const tP_iter = streamPortfolioData(config, deps, dateStr, portfolioRefs);
-        
         const needsYesterdayPortfolio = streamingCalcs.some(c => c.manifest.isHistorical);
         const yP_iter = (needsYesterdayPortfolio && rootData.yesterdayPortfolioRefs)  ? streamPortfolioData(config, deps, prevDateStr, rootData.yesterdayPortfolioRefs) : null;
-        
         const needsTradingHistory = streamingCalcs.some(c => c.manifest.rootDataDependencies.includes('history'));
         const tH_iter = (needsTradingHistory) ? streamHistoryData(config, deps, dateStr, historyRefs) : null;
 
         let yP_chunk = {}, tH_chunk = {};
         
+        // OOM Protection: Batch Flushing Configuration
+        const BATCH_SIZE = 5000; // Flush every 5000 users
+        let usersSinceLastFlush = 0;
+
         try {
             for await (const tP_chunk of tP_iter) {
                 if (yP_iter) yP_chunk = (await yP_iter.next()).value || {};
                 if (tH_iter) tH_chunk = (await tH_iter.next()).value || {};
                 
+                const chunkSize = Object.keys(tP_chunk).length;
+
                 // Execute chunk for all calcs
                 const promises = streamingCalcs.map(calc =>  
                     StandardExecutor.executePerUser(
@@ -125,19 +98,113 @@ class StandardExecutor {
                     ) 
                 );
                 await Promise.all(promises);
+
+                usersSinceLastFlush += chunkSize;
+
+                // --- BATCH FLUSH CHECK ---
+                if (usersSinceLastFlush >= BATCH_SIZE) {
+                    logger.log('INFO', `[${passName}] 🛁 Flushing buffer after ${usersSinceLastFlush} users...`);
+                    
+                    const flushResult = await StandardExecutor.flushBuffer(state, dateStr, passName, config, deps, shardIndexMap, executionStats, 'INTERMEDIATE', true);
+                    
+                    // Aggregate metrics
+                    StandardExecutor.mergeReports(aggregatedSuccess, aggregatedFailures, flushResult);
+                    
+                    usersSinceLastFlush = 0;
+                }
             }
         } finally {
-            // Close manual iterators to release resources
             if (yP_iter && yP_iter.return) await yP_iter.return();
             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];
+        // --- FINAL FLUSH ---
+        logger.log('INFO', `[${passName}] Streaming complete. Performing final commit.`);
+        const finalResult = await StandardExecutor.flushBuffer(state, dateStr, passName, config, deps, shardIndexMap, executionStats, 'FINAL', skipStatusWrite);
+        
+        StandardExecutor.mergeReports(aggregatedSuccess, aggregatedFailures, finalResult);
+
+        return { successUpdates: aggregatedSuccess, failureReport: aggregatedFailures };
+    }
+
+    static async flushBuffer(state, dateStr, passName, config, deps, shardIndexMap, executionStats, mode, skipStatusWrite) {
+        const transformedState = {};
+        const { logger } = deps;
+
+        // 1. Prepare and Clear Instances
+        for (const [name, inst] of Object.entries(state)) {
+            // Get data from the standard storage location
+            const rawResult = inst.results || {};
+            
+            // Handle Multi-Date Fan-Out (Transposition)
+            // Logic: Checks if result is { userId: { date: data } }
+            const firstUser = Object.keys(rawResult)[0];
+            let dataToCommit = rawResult;
+            let isMultiDate = false;
+
+            if (firstUser && rawResult[firstUser] && typeof rawResult[firstUser] === 'object') {
+                const innerKeys = Object.keys(rawResult[firstUser]);
+                if (innerKeys.length > 0 && innerKeys.every(k => /^\d{4}-\d{2}-\d{2}$/.test(k))) {
+                    isMultiDate = true;
+                    const transposed = {};
+                    for (const [userId, dateMap] of Object.entries(rawResult)) {
+                        for (const [dateKey, dailyData] of Object.entries(dateMap)) {
+                            if (!transposed[dateKey]) transposed[dateKey] = {};
+                            transposed[dateKey][userId] = dailyData;
+                        }
+                    }
+                    dataToCommit = transposed;
+                }
+            }
+
+            // Create a mock instance for the committer that returns just this batch
+            transformedState[name] = {
+                manifest: inst.manifest,
+                getResult: async () => dataToCommit,
+                _executionStats: executionStats[name] // Attach current stats
+            };
+
+            // ⚠️ CRITICAL: CLEAR MEMORY
+            inst.results = {};
         }
+
+        // 2. Commit Batch
+        const result = await commitResults(transformedState, dateStr, passName, config, deps, skipStatusWrite, {
+            flushMode: mode,      // 'INTERMEDIATE' or 'FINAL'
+            shardIndexes: shardIndexMap // Pass the tracking map
+        });
+
+        // 3. Update Shard Indexes from result
+        if (result.shardIndexes) {
+            Object.assign(shardIndexMap, result.shardIndexes);
+        }
+
+        return result;
+    }
+
+    static mergeReports(successAcc, failureAcc, newResult) {
+        if (!newResult) return;
         
-        logger.log('INFO', `[${passName}] Streaming complete.`);
+        // Merge Success Updates (Sums metrics)
+        for (const [name, update] of Object.entries(newResult.successUpdates)) {
+            if (!successAcc[name]) {
+                successAcc[name] = update;
+            } else {
+                // Sum storage metrics
+                if (update.metrics?.storage) {
+                    successAcc[name].metrics.storage.sizeBytes += (update.metrics.storage.sizeBytes || 0);
+                    successAcc[name].metrics.storage.keys      += (update.metrics.storage.keys || 0);
+                    successAcc[name].metrics.storage.shardCount = Math.max(successAcc[name].metrics.storage.shardCount, update.metrics.storage.shardCount || 1);
+                }
+                // Keep the latest hash/composition info
+                successAcc[name].hash = update.hash;
+            }
+        }
+
+        // Merge Failures
+        if (newResult.failureReport) {
+            failureAcc.push(...newResult.failureReport);
+        }
     }
 
     static async executePerUser(calcInstance, metadata, dateStr, portfolioData, yesterdayPortfolioData, historyData, computedDeps, prevDeps, config, deps, loader, stats) {

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

@@ -1,10 +1,7 @@
 /**
  * FILENAME: computation-system/helpers/computation_dispatcher.js
  * PURPOSE: "Smart Dispatcher" - Analyzes state and only dispatches valid, runnable tasks.
- * 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.
+ * UPDATED: Fixed "undefined" reason crash for failed dependencies.
  */
 
 const { getExpectedDateStrings, normalizeName, DEFINITIVE_EARLIEST_DATES } = require('../utils/utils.js');
@@ -99,9 +96,19 @@ async function dispatchComputationPass(config, dependencies, computationManifest
                 }
             });
 
-            // Mark Blocked/Failed Deps (Temporary Failure)
-            [...report.blocked, ...report.failedDependency].forEach(item => {
-                statusUpdates[item.name] = { hash: false, category: 'unknown', reason: item.reason };
+            // Mark Blocked (Explicit Block)
+            report.blocked.forEach(item => {
+                 statusUpdates[item.name] = { hash: false, category: 'unknown', reason: item.reason };
+            });
+
+            // [FIX] Mark Failed Dependencies (Implicit Block) - Safely generate reason string
+            report.failedDependency.forEach(item => {
+                 const missingStr = item.missing ? item.missing.join(', ') : 'unknown';
+                 statusUpdates[item.name] = { 
+                     hash: false, 
+                     category: 'unknown', 
+                     reason: `Dependency Missing: ${missingStr}` 
+                 };
             });
 
             if (Object.keys(statusUpdates).length > 0) {
@@ -118,7 +125,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
+                    triggerReason: item.reason || "Unknown", 
                     timestamp: Date.now()
                 });
             });

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

@@ -1,7 +1,8 @@
 /**
  * @fileoverview Handles saving computation results with observability and Smart Cleanup.
- * UPDATED: Stores Hash Composition in status for audit trail.
- * UPDATED: Captures execution metrics.
+ * UPDATED: Added "Strategy 4" (50 keys) to handle 'too many index entries' errors.
+ * UPDATED: Supports Incremental (Flush) Commits to prevent OOM.
+ * FIX: Throws proper Error objects.
  */
 const { commitBatchInChunks }              = require('./FirestoreUtils');
 const { updateComputationStatus }          = require('./StatusRepository');
@@ -12,10 +13,16 @@ const validationOverrides                  = require('../config/validation_overr
 const pLimit                               = require('p-limit'); 
 
 const NON_RETRYABLE_ERRORS = [
-    'INVALID_ARGUMENT',      'PERMISSION_DENIED',     'DATA_LOSS',             'FAILED_PRECONDITION'
+    'PERMISSION_DENIED',     'DATA_LOSS',             'FAILED_PRECONDITION'
+    // removed INVALID_ARGUMENT from here as it covers 'too many index entries' which IS retryable via sharding
 ];
 
-async function commitResults(stateObj, dStr, passName, config, deps, skipStatusWrite = false) {
+/**
+ * Commits results to Firestore.
+ * @param {Object} options.flushMode - 'STANDARD', 'INTERMEDIATE', 'FINAL'
+ * @param {Object} options.shardIndexes - Map of { calcName: currentShardIndex }
+ */
+async function commitResults(stateObj, dStr, passName, config, deps, skipStatusWrite = false, options = {}) {
     const successUpdates = {};
     const failureReport  = [];
     const schemas        = [];
@@ -23,33 +30,49 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     const { logger, db } = deps;
     const pid            = generateProcessId(PROCESS_TYPES.STORAGE, passName, dStr);
     
+    // Options defaults
+    const flushMode    = options.flushMode || 'STANDARD';
+    const shardIndexes = options.shardIndexes || {};
+    const nextShardIndexes = {};
+
     const fanOutLimit = pLimit(10); 
 
     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 currentShardIndex = shardIndexes[name] || 0;
 
         const runMetrics = {
             storage: { sizeBytes: 0, isSharded: false, shardCount: 1, keys: 0 },
             validation: { isValid: true, anomalies: [] },
-            execution: execStats // <--- Pass this to RunRecorder
+            execution: execStats
         };
 
         try {
             const result = await calc.getResult();
             const overrides   = validationOverrides[calc.manifest.name] || {};
-            const healthCheck = HeuristicValidator.analyze(calc.manifest.name, result, overrides);
-
-            if (!healthCheck.valid) {
-                runMetrics.validation.isValid = false;
-                runMetrics.validation.anomalies.push(healthCheck.reason);
-                throw { message: healthCheck.reason, stage: 'QUALITY_CIRCUIT_BREAKER' };
+            
+            // Only validate if we have data or if it's the final flush
+            if (result && Object.keys(result).length > 0) {
+                const healthCheck = HeuristicValidator.analyze(calc.manifest.name, result, overrides);
+                if (!healthCheck.valid) {
+                    runMetrics.validation.isValid = false;
+                    runMetrics.validation.anomalies.push(healthCheck.reason);
+                    const validationError = new Error(healthCheck.reason);
+                    validationError.stage = 'QUALITY_CIRCUIT_BREAKER';
+                    throw validationError;
+                }
             }
             
-            const isEmpty = !result || (typeof result === 'object' && Object.keys(result).length === 0) || (typeof result === 'number' && result === 0);
+            const isEmpty = !result || (typeof result === 'object' && Object.keys(result).length === 0);
+            
+            // If empty and standard mode, record 0-byte success. 
+            // If empty and INTERMEDIATE flush, just skip this calc for this flush.
             if (isEmpty) { 
+                if (flushMode === 'INTERMEDIATE') {
+                    nextShardIndexes[name] = currentShardIndex; // No change
+                    continue; 
+                }
                 if (calc.manifest.hash) { 
                     successUpdates[name] = { 
                         hash:        calc.manifest.hash, 
@@ -63,13 +86,11 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             
             if (typeof result === 'object') runMetrics.storage.keys = Object.keys(result).length;
 
-            // ... (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...`);
-                
+                // Multi-Date Fan-Out Logic (Not optimized for incremental yet, falls back to standard per-date write)
                 const datePromises = resultKeys.map((historicalDate) => fanOutLimit(async () => {
                     const dailyData = result[historicalDate];
                     if (!dailyData || Object.keys(dailyData).length === 0) return;
@@ -81,9 +102,9 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                         .collection(config.computationsSubcollection)
                         .doc(name);
 
-                    await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps);
+                    // For historical Fan-Out, we assume standard flush mode (not incremental) for now
+                    await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps, 0, 'STANDARD');
                 }));
-                
                 await Promise.all(datePromises);
                 
                 if (calc.manifest.hash) { 
@@ -96,7 +117,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 }
 
             } else {
-                // --- STANDARD MODE ---
+                // --- STANDARD / INCREMENTAL MODE ---
                 const mainDocRef = db.collection(config.resultsCollection)
                     .doc(dStr)
                     .collection(config.resultsSubcollection)
@@ -104,11 +125,14 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                     .collection(config.computationsSubcollection)
                     .doc(name);
 
-                const writeStats = await writeSingleResult(result, mainDocRef, name, dStr, logger, config, deps);
+                const writeStats = await writeSingleResult(result, mainDocRef, name, dStr, logger, config, deps, currentShardIndex, flushMode);
                 
                 runMetrics.storage.sizeBytes  = writeStats.totalSize;
                 runMetrics.storage.isSharded  = writeStats.isSharded;
                 runMetrics.storage.shardCount = writeStats.shardCount;
+                
+                // Track next index for subsequent flushes
+                nextShardIndexes[name] = writeStats.nextShardIndex;
 
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
@@ -120,112 +144,182 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 }
             }
 
-            if (calc.manifest.class.getSchema) {
+            if (calc.manifest.class.getSchema && flushMode !== 'INTERMEDIATE') {
                 const { class: _cls, ...safeMetadata } = calc.manifest;
                 schemas.push({ name, category: calc.manifest.category, schema: calc.manifest.class.getSchema(), metadata: safeMetadata });
             }
 
-            if (calc.manifest.previousCategory && calc.manifest.previousCategory !== calc.manifest.category) {
+            if (calc.manifest.previousCategory && calc.manifest.previousCategory !== calc.manifest.category && flushMode !== 'INTERMEDIATE') {
                 cleanupTasks.push(deleteOldCalculationData(dStr, calc.manifest.previousCategory, name, config, deps));
             }
 
         } catch (e) {
             const stage = e.stage || 'EXECUTION';
             const msg   = e.message || 'Unknown error';
-            
-            if (logger && logger.log) { logger.log('ERROR', `Commit failed for ${name} [${stage}]`, { processId: pid, error: msg }); }
-            
-            failureReport.push({
-                name,
-                error: { message: msg, stack: e.stack, stage },
-                metrics: runMetrics 
-            });
+            if (logger && logger.log) { logger.log('ERROR', `Commit failed for ${name} [${stage}]`, { processId: pid, error: e }); }
+            failureReport.push({ name, error: { message: msg, stack: e.stack, stage }, metrics: runMetrics });
         }
     }
 
     if (schemas.length) batchStoreSchemas(deps, config, schemas).catch(() => {});
     if (cleanupTasks.length > 0) { await Promise.allSettled(cleanupTasks); }
-    if (!skipStatusWrite && Object.keys(successUpdates).length > 0) { await updateComputationStatus(dStr, successUpdates, config, deps); }
+    if (!skipStatusWrite && Object.keys(successUpdates).length > 0 && flushMode !== 'INTERMEDIATE') { 
+        await updateComputationStatus(dStr, successUpdates, config, deps); 
+    }
     
-    return { successUpdates, failureReport };
+    return { successUpdates, failureReport, shardIndexes: nextShardIndexes };
 }
 
-// ... (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 };
+async function writeSingleResult(result, docRef, name, dateContext, logger, config, deps, startShardIndex = 0, flushMode = 'STANDARD') {
+    // Strategy 1: Standard (900KB, no key limit)
+    // Strategy 2: Aggressive Bytes (450KB, 10k keys)
+    // Strategy 3: Very Aggressive (200KB, 2k keys)
+    // Strategy 4: [NEW] Index Explosion Protection (100KB, 50 keys) - Handles "too many index entries"
+    const strategies = [ 
+        { bytes: 900 * 1024, keys: null }, 
+        { bytes: 450 * 1024, keys: 10000 }, 
+        { bytes: 200 * 1024, keys: 2000 },
+        { bytes: 100 * 1024, keys: 50 } 
+    ];
+
+    let committed = false; let lastError = null; 
+    let finalStats = { totalSize: 0, isSharded: false, shardCount: 1, nextShardIndex: startShardIndex };
 
     for (let attempt = 0; attempt < strategies.length; attempt++) {
         if (committed) break;
         const constraints = strategies[attempt];
         try {
-            const updates = await prepareAutoShardedWrites(result, docRef, logger, constraints.bytes, constraints.keys);
-            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;
+            const updates = await prepareAutoShardedWrites(result, docRef, logger, constraints.bytes, constraints.keys, startShardIndex, flushMode);
+            
+            // Analyze the update batch
+            const pointer = updates.find(u => u.data._completed !== undefined || u.data._sharded !== undefined); // Pointer is on the main doc
+            
+            // Calculate stats
             finalStats.totalSize = updates.reduce((acc, u) => acc + (u.data ? JSON.stringify(u.data).length : 0), 0);
+            
+            // Logic to determine next shard index
+            let maxIndex = startShardIndex;
+            updates.forEach(u => {
+                const segs = u.ref.path.split('/');
+                const last = segs[segs.length - 1];
+                if (last.startsWith('shard_')) {
+                    const idx = parseInt(last.split('_')[1]);
+                    if (!isNaN(idx) && idx > maxIndex) maxIndex = idx;
+                }
+            });
+
+            if (pointer && pointer.data._shardCount) {
+                finalStats.shardCount = pointer.data._shardCount;
+                finalStats.isSharded = true;
+                finalStats.nextShardIndex = finalStats.shardCount; 
+            } else if (updates.length > 0) {
+                finalStats.nextShardIndex = maxIndex + 1;
+                finalStats.isSharded = true; 
+            }
+
             await commitBatchInChunks(config, deps, updates, `${name}::${dateContext} (Att ${attempt+1})`);
             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 || '';
-            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 }); }
+            const code = commitErr.code || '';
+
+            // Check for explicit "too many index entries" or transaction size issues
+            const isIndexError = msg.includes('too many index entries') || msg.includes('INVALID_ARGUMENT');
+            const isSizeError  = msg.includes('Transaction too big') || msg.includes('payload is too large');
+
+            if (NON_RETRYABLE_ERRORS.includes(code)) { 
+                logger.log('ERROR', `[SelfHealing] ${name} FATAL error: ${msg}.`); 
+                throw commitErr; 
+            }
+            
+            if (isIndexError || isSizeError) { 
+                logger.log('WARN', `[SelfHealing] ${name} on ${dateContext} failed attempt ${attempt+1}/${strategies.length}. Strategy: ${JSON.stringify(constraints)}. Error: ${msg}. Retrying with stricter limits...`); 
+                continue; 
+            }
+            else { 
+                logger.log('WARN', `[SelfHealing] ${name} on ${dateContext} unknown error. Retrying...`, { error: msg }); 
+                // We typically retry same strategy for unknown transient errors, but here we iterate to be safe.
+                continue;
+            }
         }
     }
-    if (!committed) { throw { message: `Exhausted sharding strategies for ${name}. Last error: ${lastError?.message}`, stack: lastError?.stack, stage: 'SHARDING_LIMIT_EXCEEDED' }; }
+    if (!committed) { 
+        const shardingError = new Error(`Exhausted sharding strategies for ${name}. Last error: ${lastError?.message}`);
+        shardingError.stage = 'SHARDING_LIMIT_EXCEEDED';
+        if (lastError && lastError.stack) { shardingError.stack = lastError.stack; }
+        throw shardingError; 
+    }
     return finalStats;
 }
 
-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 shardsSnap = await withRetry(() => shardsCol.listDocuments(), 'ListOldShards');
-        const batch = db.batch(); let ops = 0;
-        for (const shardDoc of shardsSnap) { batch.delete(shardDoc); ops++; }
-        batch.delete(oldDocRef); ops++;
-        await withRetry(() => batch.commit(), 'CleanupOldCategory');
-        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 (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;
-}
-
-async function prepareAutoShardedWrites(result, docRef, logger, maxBytes = 900 * 1024, maxKeys = null) {
+async function prepareAutoShardedWrites(result, docRef, logger, maxBytes = 900 * 1024, maxKeys = null, startShardIndex = 0, flushMode = 'STANDARD') {
     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;
+    let currentChunk = {}; let currentChunkSize = 0; let currentKeyCount = 0; 
+    let shardIndex = startShardIndex;
 
-    if (!maxKeys && (totalSize + docPathSize) < CHUNK_LIMIT) {  
+    // Small Data Optimization (Only valid if we are not in an incremental flow or if it's the first standard run)
+    if (!maxKeys && (totalSize + docPathSize) < CHUNK_LIMIT && flushMode === 'STANDARD' && startShardIndex === 0) {  
         const data = { ...result, _completed: true, _sharded: false, _lastUpdated: new Date().toISOString() };  
         return [{ ref: docRef, data, options: { merge: true } }];  
     }
 
+    // Sharding Logic
     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);
+        
         if (byteLimitReached || keyLimitReached) { 
-            writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } });
+            writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } }); // Overwrite shard doc
             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 } }); }
     
-    const pointerData = { _completed: true, _sharded: true, _shardCount: shardIndex + 1, _lastUpdated: new Date().toISOString() };
-    writes.push({ ref: docRef, data: pointerData, options: { merge: false } });
+    // Push remaining chunk
+    if (Object.keys(currentChunk).length > 0) { 
+        writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } });
+        shardIndex++; // Increment so count is correct (0-based index means count is index+1)
+    }
+    
+    // Pointer Logic
+    if (flushMode !== 'INTERMEDIATE') {
+        const pointerData = { 
+            _completed: true, 
+            _sharded: true, 
+            _shardCount: shardIndex, 
+            _lastUpdated: new Date().toISOString() 
+        };
+        writes.push({ ref: docRef, data: pointerData, options: { merge: true } }); // Merge pointer
+    }
+
     return writes;
 }
 
+// ... (Rest of file: deleteOldCalculationData, calculateFirestoreBytes remains unchanged) ...
+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 shardsSnap = await withRetry(() => shardsCol.listDocuments(), 'ListOldShards');
+        const batch = db.batch(); let ops = 0;
+        for (const shardDoc of shardsSnap) { batch.delete(shardDoc); ops++; }
+        batch.delete(oldDocRef); ops++;
+        await withRetry(() => batch.commit(), 'CleanupOldCategory');
+        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 (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;
+}
+
 module.exports = { commitResults };

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

@@ -1,23 +1,23 @@
 /**
  * @fileoverview HeuristicValidator.js
  * "Grey Box" validation that infers health using statistical analysis and structural sanity checks.
- * UPDATED: Added NaN detection, Flatline (Variance) checks, and Vector/Array depth checks.
+ * UPDATED: Added "Weekend Mode" to allow higher zero/null tolerance on Saturdays/Sundays.
  */
 
 class HeuristicValidator {
     /**
      * @param {string} calcName - Name for logging
      * @param {Object} data - The result data to inspect
+     * @param {string} dateStr - The computation date (YYYY-MM-DD)
      * @param {Object} [overrides] - Optional central config overrides
      */
-    static analyze(calcName, data, overrides = {}) {
+    static analyze(calcName, data, dateStr, overrides = {}) {
         // 1. Structure Check
-        if (!data || typeof data !== 'object') return { valid: true }; // Let scalar types pass
+        if (!data || typeof data !== 'object') return { valid: true }; 
         
         const keys = Object.keys(data);
         const totalItems = keys.length;
         
-        // Skip tiny datasets (statistically insignificant)
         if (totalItems < 5) return { valid: true };
 
         // 2. Sampling Configuration
@@ -26,17 +26,16 @@ class HeuristicValidator {
         
         let zeroCount = 0;
         let nullCount = 0;
-        let nanCount = 0; // NEW: Track NaNs
-        let emptyVectorCount = 0; // NEW: Track empty arrays in complex objects
+        let nanCount = 0; 
+        let emptyVectorCount = 0; 
         let analyzedCount = 0;
         
-        // For Variance/Flatline Check
         const numericValues = []; 
 
         for (let i = 0; i < totalItems; i += step) {
             const key = keys[i];
             const val = data[key];
-            if (!val) { // Catch null/undefined immediately
+            if (!val) { 
                 nullCount++;
                 analyzedCount++;
                 continue;
@@ -44,71 +43,79 @@ class HeuristicValidator {
             analyzedCount++;
 
             // --- TYPE A: Object / Complex Result ---
-            // Example: { "profile": [...], "current_price": 100 } or { "signal": "Buy", "score": 0.5 }
             if (typeof val === 'object') {
                 const subValues = Object.values(val);
                 
-                // Dead Object Check: All props are null/0/undefined
                 const isDeadObject = subValues.every(v => v === 0 || v === null || v === undefined);
                 if (isDeadObject) nullCount++;
 
-                // NaN Check in Properties
                 const hasNan = subValues.some(v => typeof v === 'number' && (isNaN(v) || !isFinite(v)));
                 if (hasNan) nanCount++;
 
-                // 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++; } }
 
-                // Extract primary numeric score for Flatline check (heuristically guessing the 'main' metric)
                 const numericProp = subValues.find(v => typeof v === 'number' && v !== 0);
                 if (numericProp !== undefined) numericValues.push(numericProp);
             } 
             // --- TYPE B: Scalar / Primitive Result ---
             if (typeof val === 'number') {
-                if (isNaN(val) || !isFinite(val)) 
-                    { nanCount++;
-                } else {
-                    numericValues.push(val); // Include zeros
+                if (isNaN(val) || !isFinite(val)) { nanCount++; } 
+                else {
+                    numericValues.push(val); 
                     if (val === 0) zeroCount++;
                 }
             }
         }
 
-        // 3. Thresholds
-        const thresholds = {
+        // 3. Weekend Detection & Threshold Resolution
+        let isWeekend = false;
+        if (dateStr) {
+            try {
+                // Force UTC interpretation to align with system dates
+                const safeDate = dateStr.includes('T') ? dateStr : `${dateStr}T00:00:00Z`;
+                const day = new Date(safeDate).getUTCDay();
+                // 0 = Sunday, 6 = Saturday
+                isWeekend = (day === 0 || day === 6);
+            } catch (e) { /* Fallback to standard validation if date is invalid */ }
+        }
+
+        // Default Thresholds
+        let thresholds = {
             maxZeroPct: overrides.maxZeroPct ?? 99, 
             maxNullPct: overrides.maxNullPct ?? 90,
-            maxNanPct:  overrides.maxNanPct  ?? 0,   // Strict: NaNs are usually bad bugs
-            maxFlatlinePct: 95 // If >95% of data is identical, it's suspicious
+            maxNanPct:  overrides.maxNanPct  ?? 0,   
+            maxFlatlinePct: overrides.maxFlatlinePct ?? 95 
         };
 
+        // Apply Weekend Overrides if applicable
+        if (isWeekend && overrides.weekend) {
+            thresholds = { ...thresholds, ...overrides.weekend };
+        }
+
         // 4. Calculate Stats
         const zeroPct = (zeroCount / analyzedCount) * 100;
         const nullPct = (nullCount / analyzedCount) * 100;
         const nanPct  = (nanCount  / analyzedCount) * 100;
         
         // 5. Variance / Flatline Analysis
-        // If we found numeric values, check if they are all the same
         let isFlatline = false;
         if (numericValues.length > 5) {
             const first          = numericValues[0];
             const identicalCount = numericValues.filter(v => Math.abs(v - first) < 0.000001).length;
             const flatlinePct    = (identicalCount / numericValues.length) * 100;
             
-            // Only flag flatline if the value isn't 0 (0 is handled by maxZeroPct)
             if (flatlinePct > thresholds.maxFlatlinePct && Math.abs(first) > 0.0001) { isFlatline = true; }
         }
 
         // 6. Evaluations
-        if (nanPct  > thresholds.maxNanPct)  { return { valid: false, reason: `Mathematical Error: ${nanPct.toFixed(1)}% of sampled results contain NaN or Infinity.` }; }
-        if (zeroPct > thresholds.maxZeroPct) { return { valid: false, reason: `Data Integrity:     ${zeroPct.toFixed(1)}% of sampled results are 0. (Suspected Logic Failure)` }; }
-        if (nullPct > thresholds.maxNullPct) { return { valid: false, reason: `Data Integrity:     ${nullPct.toFixed(1)}% of sampled results are Empty/Null.` }; }
+        // Note: We include the applied thresholds in the error message for clarity
+        if (nanPct  > thresholds.maxNanPct)  { return { valid: false, reason: `Mathematical Error: ${nanPct.toFixed(1)}% of sampled results contain NaN (Limit: ${thresholds.maxNanPct}%).` }; }
+        if (zeroPct > thresholds.maxZeroPct) { return { valid: false, reason: `Data Integrity:     ${zeroPct.toFixed(1)}% of results are 0 (Limit: ${thresholds.maxZeroPct}%${isWeekend ? ' [Weekend Mode]' : ''}).` }; }
+        if (nullPct > thresholds.maxNullPct) { return { valid: false, reason: `Data Integrity:     ${nullPct.toFixed(1)}% of results are Empty/Null (Limit: ${thresholds.maxNullPct}%${isWeekend ? ' [Weekend Mode]' : ''}).` }; }
 
         if (isFlatline) { return { valid: false, reason: `Anomaly: Detected Result Flatline. >${thresholds.maxFlatlinePct}% of outputs are identical (non-zero).` }; }
         
-        // Special check for Distribution/Profile calculations
         if (calcName.includes('profile') || calcName.includes('distribution')) {
             const vectorEmptyPct = (emptyVectorCount / analyzedCount) * 100;
             if (vectorEmptyPct > 90) {

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

@@ -2,7 +2,7 @@
  * @fileoverview Build Reporter & Auto-Runner.
  * Generates a "Pre-Flight" report of what the computation system WILL do.
  * REFACTORED: Strict 5-category reporting with date-based exclusion logic.
- * UPDATED: Added meta stats to compare Included vs Expected computation counts per date.
+ * UPDATED: Added transactional locking to prevent duplicate reports on concurrent cold starts.
  */
 
 const { analyzeDateExecution }                                             = require('../WorkflowOrchestrator');
@@ -29,40 +29,56 @@ function isDateBeforeAvailability(dateStr, calcManifest) {
     for (const dep of deps) {
         // Map dependency name to start date
         let startDate = null;
-        if (dep === 'portfolio') startDate = DEFINITIVE_EARLIEST_DATES.portfolio;
+        if (dep === 'portfolio')      startDate = DEFINITIVE_EARLIEST_DATES.portfolio;
         else if (dep === 'history')   startDate = DEFINITIVE_EARLIEST_DATES.history;
         else if (dep === 'social')    startDate = DEFINITIVE_EARLIEST_DATES.social;
         else if (dep === 'insights')  startDate = DEFINITIVE_EARLIEST_DATES.insights;
         else if (dep === 'price')     startDate = DEFINITIVE_EARLIEST_DATES.price;
 
         // If we have a start date and the target is BEFORE it, exclude this calc.
-        if (startDate && targetDate < startDate) {
-            return true;
-        }
+        if (startDate && targetDate < startDate) { return true; }
     }
     return false;
 }
 
 /**
  * AUTO-RUN ENTRY POINT
+ * UPDATED: Uses transactional locking to prevent race conditions.
+ * If we deploy multiple computation pass nodes simultaneously, only one should run the report.
  */
 async function ensureBuildReport(config, dependencies, manifest) {
     const { db, logger } = dependencies;
     const now = new Date();
     const buildId = `v${packageVersion}_${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,'0')}-${String(now.getDate()).padStart(2,'0')}_${String(now.getHours()).padStart(2,'0')}-${String(now.getMinutes()).padStart(2,'0')}-${String(now.getSeconds()).padStart(2,'0')}`;
-    const latestRef = db.collection('computation_build_records').doc('latest');
+    
+    // Lock document specific to this version
+    const lockRef = db.collection('computation_build_records').doc(`init_lock_v${packageVersion}`);
 
     try {
-        const latestDoc = await latestRef.get();
-        const priorVersion = latestDoc.exists ? latestDoc.data().packageVersion : null;
+        // Transaction: "Hey I am deploying" check
+        const shouldRun = await db.runTransaction(async (t) => {
+            const doc   = await t.get(lockRef);
+            
+            if (doc.exists) { return false; } // Someone else beat us to it
+
+            // Claim the lock
+            t.set(lockRef, { 
+                status: 'IN_PROGRESS', 
+                startedAt: new Date(),
+                workerId: process.env.K_REVISION || 'unknown',
+                buildId: buildId
+            });
+            return true;
+        });
 
-        if (priorVersion === packageVersion) {
-            logger.log('INFO', `[BuildReporter] ✅ Version ${packageVersion} already has a report. Skipping.`);
-            return;
-        }
+        if (!shouldRun) { logger.log('INFO', `[BuildReporter] 🔒 Report for v${packageVersion} is already being generated (Locked). Skipping.`); return; }
 
-        logger.log('INFO', `[BuildReporter] 🚀 New Version Detected (${packageVersion}). Auto-running Pre-flight Report...`);
+        logger.log('INFO', `[BuildReporter] 🚀 Lock Acquired. Running Pre-flight Report for v${packageVersion}...`);
+        
         await generateBuildReport(config, dependencies, manifest, 90, buildId);
+        
+        // Optional: Update lock to completed (fire-and-forget update)
+        lockRef.update({ status: 'COMPLETED', completedAt: new Date() }).catch(() => {});
 
     } catch (e) {
         logger.log('ERROR', `[BuildReporter] Auto-run check failed: ${e.message}`);
@@ -117,11 +133,11 @@ async function generateBuildReport(config, dependencies, manifest, daysBack = 90
                 }
             }
 
-            const results = await Promise.all(fetchPromises);
-            const dailyStatus = results[0];
-            const availability = results[1];
+            const results         = await Promise.all(fetchPromises);
+            const dailyStatus     = results[0];
+            const availability    = results[1];
             const prevDailyStatus = (prevDateStr && results[2]) ? results[2] : (prevDateStr ? {} : null);
-            const rootDataStatus = availability ? availability.status : { hasPortfolio: false, hasHistory: false, hasSocial: false, hasInsights: false, hasPrices: false };
+            const rootDataStatus  = availability ? availability.status : { hasPortfolio: false, hasHistory: false, hasSocial: false, hasInsights: false, hasPrices: false };
 
             const analysis = analyzeDateExecution(dateStr, manifest, rootDataStatus, dailyStatus, manifestMap, prevDailyStatus);
 
@@ -129,11 +145,11 @@ async function generateBuildReport(config, dependencies, manifest, daysBack = 90
             // STRICT 5-CATEGORY MAPPING
             // ---------------------------------------------------------
             const dateSummary = {
-                run: [],        // New / No Hash / "Runnable"
-                rerun: [],      // Hash Mismatch / Category Migration
-                blocked: [],    // Missing Data (Today) / Dependency Missing
+                run:        [], // New / No Hash / "Runnable"
+                rerun:      [], // Hash Mismatch / Category Migration
+                blocked:    [], // Missing Data (Today) / Dependency Missing
                 impossible: [], // Missing Data (Historical) / Impossible Dependency
-                uptodate: [],   // Hash Match (Previously "Skipped")
+                uptodate:   [], // Hash Match (Previously "Skipped")
                 
                 // [NEW] Metadata for Verification
                 meta: {
@@ -181,7 +197,7 @@ async function generateBuildReport(config, dependencies, manifest, daysBack = 90
                                   dateSummary.uptodate.length;
 
             dateSummary.meta.totalIncluded = includedCount;
-            dateSummary.meta.match = (includedCount === expectedCount);
+            dateSummary.meta.match         = (includedCount === expectedCount);
 
             if (!dateSummary.meta.match) {
                 logger.log('WARN', `[BuildReporter] ⚠️ Mismatch on ${dateStr}: Expected ${expectedCount} but got ${includedCount}.`);

package/package.json

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