bulltrackers-module 1.0.220 → 1.0.222

package/functions/computation-system/WorkflowOrchestrator.js

@@ -2,7 +2,7 @@
  * @fileoverview Main Orchestrator. Coordinates the topological execution of calculations.
  */
 const { normalizeName, getExpectedDateStrings }            = require('./utils/utils');
-const { checkRootDependencies, checkRootDataAvailability } = require('./data/AvailabilityChecker');
+const { checkRootDataAvailability, getViableCalculations } = require('./data/AvailabilityChecker');
 const { fetchExistingResults }                             = require('./data/DependencyFetcher');
 const { fetchComputationStatus, updateComputationStatus }  = require('./persistence/StatusRepository');
 const { runBatchPriceComputation }                         = require('./executors/PriceBatchExecutor');
@@ -68,7 +68,7 @@ async function runDateComputation(dateStr, passToRun, calcsInThisPass, config, d
     const { logger } = dependencies;
     const dateToProcess = new Date(dateStr + 'T00:00:00Z');
     
-    // 1. Version Check
+    // 1. Version Check: Determine which calculations are *stale*
     const dailyStatus    = await fetchComputationStatus(dateStr, config, dependencies);
     const calcsToAttempt = [];
     
@@ -77,22 +77,17 @@ async function runDateComputation(dateStr, passToRun, calcsInThisPass, config, d
         const storedStatus = dailyStatus[cName];
         const currentHash = calc.hash;
 
-        if (calc.dependencies && calc.dependencies.length > 0) { 
-            const missing = calc.dependencies.filter(depName => !dailyStatus[normalizeName(depName)]); 
-            if (missing.length > 0) { 
-                logger.log('TRACE', `[Skip] ${cName} missing deps: ${missing.join(', ')}`);  
-                continue; 
-            } 
-        }
         if (!storedStatus) { 
-            logger.log('INFO', `[Versioning] ${cName}: New run needed.`); 
+            // New calculation
             calcsToAttempt.push(calc); continue; 
         }
         if (typeof storedStatus === 'string' && currentHash && storedStatus !== currentHash) { 
+            // Code changed, must re-run
             logger.log('INFO', `[Versioning] ${cName}: Code Changed.`); 
             calcsToAttempt.push(calc); continue; 
         }
         if (storedStatus === true && currentHash) { 
+            // Migrating legacy status
             logger.log('INFO', `[Versioning] ${cName}: Upgrading legacy status.`); 
             calcsToAttempt.push(calc); continue; 
         }
@@ -100,7 +95,7 @@ async function runDateComputation(dateStr, passToRun, calcsInThisPass, config, d
 
     if (!calcsToAttempt.length) return null;
 
-    // 2. Data Check
+    // 2. Data Availability Check
     const earliestDates = {
         portfolio: new Date('2025-09-25T00:00:00Z'),
         history:   new Date('2025-11-05T00:00:00Z'),
@@ -112,8 +107,15 @@ async function runDateComputation(dateStr, passToRun, calcsInThisPass, config, d
     const rootData = await checkRootDataAvailability(dateStr, config, dependencies, earliestDates);
     if (!rootData) { logger.log('INFO', `[DateRunner] Root data missing for ${dateStr}. Skipping.`); return null; }
     
-    const runnableCalcs = calcsToAttempt.filter(c => checkRootDependencies(c, rootData.status).canRun);
-    if (!runnableCalcs.length) return null;
+    // 3. Viability Check (Smart Execution Map)
+    // Filter candidates: Remove any calculation that misses Root Data OR Dependencies
+    const runnableCalcs = getViableCalculations(calcsToAttempt, rootData.status, dailyStatus);
+
+    if (!runnableCalcs.length) {
+        // If we had candidates but they were pruned, it means they are blocked.
+        // logger.log('INFO', `[DateRunner] ${dateStr}: Candidates pruned due to missing deps/data.`);
+        return null;
+    }
 
     const standardToRun = runnableCalcs.filter(c => c.type === 'standard');
     const metaToRun = runnableCalcs.filter(c => c.type === 'meta');
@@ -123,6 +125,7 @@ async function runDateComputation(dateStr, passToRun, calcsInThisPass, config, d
 
     try {
         const calcsRunning    = [...standardToRun, ...metaToRun];
+        // Fetch dependencies for the *runnable* calculations
         const existingResults = await fetchExistingResults(dateStr, calcsRunning, computationManifest, config, dependencies, false);
         const prevDate        = new Date(dateToProcess); prevDate.setUTCDate(prevDate.getUTCDate() - 1);
         const prevDateStr     = prevDate.toISOString().slice(0, 10);

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

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Factory for creating the Computation Context.
  */
-const mathLayer = require('../layers/index');
+const mathLayer          = require('../layers/index');
 const { LEGACY_MAPPING } = require('../topology/HashManager');
 
 class ContextFactory { 

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

@@ -2,7 +2,7 @@
  * @fileoverview Dynamic Manifest Builder - Handles Topological Sort and Auto-Discovery.
  */
 const { generateCodeHash, LEGACY_MAPPING } = require('../topology/HashManager.js');
-const { normalizeName } = require('../utils/utils');
+const { normalizeName }                    = require('../utils/utils');
 
 // Import Layers
 const MathematicsLayer = require('../layers/mathematics');
@@ -93,12 +93,12 @@ function buildManifest(productLinesToRun = [], calculations) {
         if (!Class || typeof Class !== 'function') return;
         const normalizedName = normalizeName(name);
         
-        if (typeof Class.getMetadata !== 'function') { log.fatal(`Calculation "${normalizedName}" missing static getMetadata().`); hasFatalError = true; return; }
+        if (typeof Class.getMetadata     !== 'function') { log.fatal(`Calculation "${normalizedName}" missing static getMetadata().`);     hasFatalError = true; return; }
         if (typeof Class.getDependencies !== 'function') { log.fatal(`Calculation "${normalizedName}" missing static getDependencies().`); hasFatalError = true; return; }
         
-        const metadata = Class.getMetadata();
+        const metadata     = Class.getMetadata();
         const dependencies = Class.getDependencies().map(normalizeName);
-        const codeStr = Class.toString();
+        const codeStr      = Class.toString();
         
         let compositeHashString = generateCodeHash(codeStr); 
         const usedDeps = [];

package/functions/computation-system/data/AvailabilityChecker.js

@@ -5,8 +5,9 @@ const {
     getPortfolioPartRefs, 
     loadDailyInsights, 
     loadDailySocialPostInsights, 
-    getHistoryPartRefs 
+    getHistoryPartRefs
 } = require('../utils/data_loader');
+const { normalizeName } = require('../utils/utils');
 
 function checkRootDependencies(calcManifest, rootDataStatus) {
     const missing = [];
@@ -21,15 +22,60 @@ function checkRootDependencies(calcManifest, rootDataStatus) {
     return { canRun: missing.length === 0, missing };
 }
 
+/**
+ * Filters candidates to only those that are strictly "viable" to run.
+ * A calculation is Viable if:
+ * 1. All required Root Data is present.
+ * 2. All required Dependencies (from previous passes) are present in dailyStatus.
+ * * @param {Array} candidates - Calculations attempting to run in this pass.
+ * @param {Object} rootDataStatus - { hasPortfolio: bool, hasPrices: bool... }
+ * @param {Object} dailyStatus - Map of { "calc-name": "hash" } for completed items.
+ */
+function getViableCalculations(candidates, rootDataStatus, dailyStatus) {
+    const viable = [];
+    
+    for (const calc of candidates) {
+        // 1. Check Root Data
+        const rootCheck = checkRootDependencies(calc, rootDataStatus);
+        if (!rootCheck.canRun) {
+            // Root data missing -> Impossible to run.
+            continue;
+        }
+
+        // 2. Check Dependencies
+        let dependenciesMet = true;
+        if (calc.dependencies && calc.dependencies.length > 0) {
+            for (const depName of calc.dependencies) {
+                const normDep = normalizeName(depName);
+                
+                // If a dependency is missing from dailyStatus, it failed in a previous pass.
+                // Therefore, the current calculation is impossible.
+                if (!dailyStatus[normDep]) {
+                    dependenciesMet = false;
+                    break;
+                }
+            }
+        }
+
+        if (dependenciesMet) {
+            viable.push(calc);
+        }
+    }
+
+    return viable;
+}
+
 async function checkRootDataAvailability(dateStr, config, dependencies, earliestDates) {
-    const { logger } = dependencies;
+    const { logger, db } = dependencies;
     const dateToProcess = new Date(dateStr + 'T00:00:00Z');
+    
     let portfolioRefs = [], historyRefs = [];
     let hasPortfolio = false, hasInsights = false, hasSocial = false, hasHistory = false, hasPrices = false;
     let insightsData = null, socialData = null;
 
     try {
         const tasks = [];
+        // Only check data sources if the date is after the earliest known data point
         if (dateToProcess >= earliestDates.portfolio) {
             tasks.push(getPortfolioPartRefs(config, dependencies, dateStr).then(r => { portfolioRefs = r; hasPortfolio = !!r.length; }));
         }
@@ -43,11 +89,12 @@ async function checkRootDataAvailability(dateStr, config, dependencies, earliest
             tasks.push(getHistoryPartRefs(config, dependencies, dateStr).then(r => { historyRefs = r; hasHistory = !!r.length; }));
         }
         if (dateToProcess >= earliestDates.price) {   
-            tasks.push(checkPriceDataAvailability(config, dependencies).then(r => { hasPrices = r; })); 
+            tasks.push(checkPriceAvailability(config, db).then(r => { hasPrices = r; })); 
         }
 
         await Promise.all(tasks);
 
+        // If ABSOLUTELY NO data exists, we can return null early
         if (!(hasPortfolio || hasInsights || hasSocial || hasHistory || hasPrices)) return null;
 
         return { 
@@ -56,7 +103,7 @@ async function checkRootDataAvailability(dateStr, config, dependencies, earliest
             todayInsights: insightsData, 
             todaySocialPostInsights: socialData, 
             status: { hasPortfolio, hasInsights, hasSocial, hasHistory, hasPrices }, 
-            yesterdayPortfolioRefs: null // Filled later if needed
+            yesterdayPortfolioRefs: null // Filled later by StandardExecutor if needed
         };
     } catch (err) { 
         logger.log('ERROR', `Error checking data: ${err.message}`); 
@@ -64,7 +111,11 @@ async function checkRootDataAvailability(dateStr, config, dependencies, earliest
     }
 }
 
-async function checkPriceDataAvailability(config, { db }) { 
+/**
+ * Checks if any price data exists in the collection.
+ * Note: Uses a lightweight limit(1) query.
+ */
+async function checkPriceAvailability(config, db) { 
     try { 
         const collection = config.priceCollection || 'asset_prices';
         const snapshot = await db.collection(collection).limit(1).get(); 
@@ -72,4 +123,4 @@ async function checkPriceDataAvailability(config, { db }) {
     } catch (e) { return false; } 
 }
 
-module.exports = { checkRootDependencies, checkRootDataAvailability };
+module.exports = { checkRootDependencies, checkRootDataAvailability, getViableCalculations };

package/functions/computation-system/data/CachedDataLoader.js

@@ -15,7 +15,7 @@ class CachedDataLoader {
         this.cache = { 
             mappings: null, 
             insights: new Map(), 
-            social: new Map() 
+            social:   new Map()
         }; 
     }
 

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

@@ -1,10 +1,10 @@
 /**
  * @fileoverview Executor for "Meta" (global) calculations.
  */
-const { normalizeName } = require('../utils/utils');
+const { normalizeName }    = require('../utils/utils');
 const { CachedDataLoader } = require('../data/CachedDataLoader');
-const { ContextFactory } = require('../context/ContextFactory');
-const { commitResults } = require('../persistence/ResultCommitter');
+const { ContextFactory }   = require('../context/ContextFactory');
+const { commitResults }    = require('../persistence/ResultCommitter');
 
 class MetaExecutor {
     static async run(date, calcs, passName, config, deps, fetchedDeps, previousFetchedDeps, rootData, skipStatusWrite = false) {
@@ -30,8 +30,8 @@ class MetaExecutor {
     static async executeOncePerDay(calcInstance, metadata, dateStr, computedDeps, prevDeps, config, deps, loader) {
         const mappings = await loader.loadMappings();
         const { logger } = deps;
-        const insights = metadata.rootDataDependencies?.includes('insights') ? { today: await loader.loadInsights(dateStr) } : null;
-        const social = metadata.rootDataDependencies?.includes('social') ? { today: await loader.loadSocial(dateStr) } : null;
+        const insights   = metadata.rootDataDependencies?.includes('insights') ? { today: await loader.loadInsights(dateStr) } : null;
+        const social     = metadata.rootDataDependencies?.includes('social')   ? { today: await loader.loadSocial(dateStr)   } : null;
         
         if (metadata.rootDataDependencies?.includes('price')) {
             logger.log('INFO', `[Executor] Running Batched/Sharded Execution for ${metadata.name}`);

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

@@ -1,21 +1,21 @@
 /**
  * @fileoverview Specialized Executor for Price-Dependent Batch computations.
  */
-const pLimit = require('p-limit');
-const { normalizeName } = require('../utils/utils');
+const pLimit                                   = require('p-limit');
+const { normalizeName }                        = require('../utils/utils');
 const { getRelevantShardRefs, loadDataByRefs } = require('../utils/data_loader');
-const { CachedDataLoader } = require('../data/CachedDataLoader');
-const mathLayer = require('../layers/index');
-const { LEGACY_MAPPING } = require('../topology/HashManager');
+const { CachedDataLoader }                     = require('../data/CachedDataLoader');
+const mathLayer                                = require('../layers/index');
+const { LEGACY_MAPPING }                       = require('../topology/HashManager');
 
 async function runBatchPriceComputation(config, deps, dateStrings, calcs, targetTickers = []) {
     const { logger, db, calculationUtils } = deps;
     const cachedLoader = new CachedDataLoader(config, deps);
-    const mappings = await cachedLoader.loadMappings();
+    const mappings     = await cachedLoader.loadMappings();
     
     let targetInstrumentIds = [];
     if (targetTickers && targetTickers.length > 0) {
-        const tickerToInst = mappings.tickerToInstrument || {};
+        const tickerToInst  = mappings.tickerToInstrument || {};
         targetInstrumentIds = targetTickers.map(t => tickerToInst[t]).filter(id => id);
         if (targetInstrumentIds.length === 0) { logger.log('WARN', '[BatchPrice] Target tickers provided but no IDs found. Aborting.'); return; } 
     }

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

@@ -1,23 +1,23 @@
 /**
  * @fileoverview Executor for "Standard" (per-user) calculations.
  */
-const { normalizeName } = require('../utils/utils');
+const { normalizeName }                                                = require('../utils/utils');
 const { streamPortfolioData, streamHistoryData, getPortfolioPartRefs } = require('../utils/data_loader');
-const { CachedDataLoader } = require('../data/CachedDataLoader');
-const { ContextFactory } = require('../context/ContextFactory');
-const { commitResults } = require('../persistence/ResultCommitter');
-const mathLayer = require('../layers/index');
+const { CachedDataLoader }                                             = require('../data/CachedDataLoader');
+const { ContextFactory }                                               = require('../context/ContextFactory');
+const { commitResults }                                                = require('../persistence/ResultCommitter');
+const mathLayer                                                        = require('../layers/index');
 
 class StandardExecutor {
     static async run(date, calcs, passName, config, deps, rootData, fetchedDeps, previousFetchedDeps, skipStatusWrite = false) {
-        const dStr = date.toISOString().slice(0, 10);
+        const dStr   = date.toISOString().slice(0, 10);
         const logger = deps.logger;
         
         // 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);
+            const prev                      = new Date(date); prev.setUTCDate(prev.getUTCDate() - 1);
+            const prevStr                   = prev.toISOString().slice(0, 10);
             fullRoot.yesterdayPortfolioRefs = await getPortfolioPartRefs(config, deps, prevStr);
         }
 
@@ -53,19 +53,15 @@ class StandardExecutor {
         const cachedLoader = new CachedDataLoader(config, deps);
         await cachedLoader.loadMappings();
         
-        const prevDate = new Date(dateStr + 'T00:00:00Z'); prevDate.setUTCDate(prevDate.getUTCDate() - 1);
+        const prevDate    = new Date(dateStr + 'T00:00:00Z'); prevDate.setUTCDate(prevDate.getUTCDate() - 1);
         const prevDateStr = prevDate.toISOString().slice(0, 10);
         
-        const tP_iter = streamPortfolioData(config, deps, dateStr, portfolioRefs);
+        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 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 && historyRefs) 
-            ? streamHistoryData(config, deps, dateStr, historyRefs) 
-            : null;
+        const tH_iter = (needsTradingHistory && historyRefs) ? streamHistoryData(config, deps, dateStr, historyRefs) : null;
 
         let yP_chunk = {}, tH_chunk = {};
         
@@ -74,9 +70,7 @@ 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) );
             await Promise.all(promises);
         }
         logger.log('INFO', `[${passName}] Streaming complete.`);
@@ -87,12 +81,12 @@ class StandardExecutor {
         const targetUserType = metadata.userType; 
         const mappings = await loader.loadMappings();
         const insights = metadata.rootDataDependencies?.includes('insights') ? { today: await loader.loadInsights(dateStr) } : null;
-        const SCHEMAS = mathLayer.SCHEMAS;
+        const SCHEMAS  = mathLayer.SCHEMAS;
 
         for (const [userId, todayPortfolio] of Object.entries(portfolioData)) {
             const yesterdayPortfolio = yesterdayPortfolioData ? yesterdayPortfolioData[userId] : null;
-            const todayHistory = historyData ? historyData[userId] : null;
-            const actualUserType = todayPortfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
+            const todayHistory       = historyData ? historyData[userId] : null;
+            const actualUserType     = todayPortfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
             
             if (targetUserType !== 'all') {
                  const mappedTarget = (targetUserType === 'speculator') ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;

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

@@ -5,8 +5,8 @@
  */
 
 const { getExpectedDateStrings } = require('../utils/utils.js');
-const { groupByPass } = require('../WorkflowOrchestrator.js');
-const { PubSubUtils } = require('../../core/utils/pubsub_utils');
+const { groupByPass }            = require('../WorkflowOrchestrator.js');
+const { PubSubUtils }            = require('../../core/utils/pubsub_utils');
 
 const TOPIC_NAME = 'computation-tasks';
 
@@ -15,14 +15,14 @@ const TOPIC_NAME = 'computation-tasks';
  * Instead of running them, it queues them in Pub/Sub.
  */
 async function dispatchComputationPass(config, dependencies, computationManifest) {
-    const { logger } = dependencies;
+    const { logger }  = dependencies;
     const pubsubUtils = new PubSubUtils(dependencies);
-    const passToRun = String(config.COMPUTATION_PASS_TO_RUN);
+    const passToRun   = String(config.COMPUTATION_PASS_TO_RUN);
     
     if (!passToRun) { return logger.log('ERROR', '[Dispatcher] No pass defined (COMPUTATION_PASS_TO_RUN). Aborting.'); }
 
     // 1. Validate Pass Existence
-    const passes = groupByPass(computationManifest);
+    const passes          = groupByPass(computationManifest);
     const calcsInThisPass = passes[passToRun] || [];
 
     if (!calcsInThisPass.length) { return logger.log('WARN', `[Dispatcher] No calcs for Pass ${passToRun}. Exiting.`); }

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

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Low-level Firestore interactions.
  */
-const { withRetry } = require('../utils/utils.js'); // Assuming this exists or is passed in deps
+const { withRetry } = require('../utils/utils.js'); 
 
 async function commitBatchInChunks(config, deps, writes, operationName) {
     const { db, logger, calculationUtils } = deps;
@@ -12,13 +12,13 @@ async function commitBatchInChunks(config, deps, writes, operationName) {
         return;
     }
 
-    const MAX_BATCH_OPS = 300;
+    const MAX_BATCH_OPS   = 300;
     const MAX_BATCH_BYTES = 9 * 1024 * 1024; 
 
-    let currentBatch = db.batch();
+    let currentBatch    = db.batch();
     let currentOpsCount = 0;
     let currentBytesEst = 0;
-    let batchIndex = 1;
+    let batchIndex      = 1;
 
     const commitAndReset = async () => {
         if (currentOpsCount > 0) {
@@ -34,7 +34,7 @@ async function commitBatchInChunks(config, deps, writes, operationName) {
                 throw err;
             }
         }
-        currentBatch = db.batch();
+        currentBatch    = db.batch();
         currentOpsCount = 0;
         currentBytesEst = 0;
     };

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

@@ -1,13 +1,13 @@
 /**
  * @fileoverview Handles saving computation results with transparent auto-sharding.
  */
-const { commitBatchInChunks } = require('./FirestoreUtils');
+const { commitBatchInChunks }     = require('./FirestoreUtils');
 const { updateComputationStatus } = require('./StatusRepository');
-const { batchStoreSchemas } = require('../utils/schema_capture');
+const { batchStoreSchemas }       = require('../utils/schema_capture');
 
 async function commitResults(stateObj, dStr, passName, config, deps, skipStatusWrite = false) {
     const successUpdates = {};
-    const schemas = [];
+    const schemas        = [];
 
     for (const name in stateObj) {
         const calc = stateObj[name];
@@ -40,7 +40,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             if (updates.length > 0) {
                 await commitBatchInChunks(config, deps, updates, `${name} Results`);
                 successUpdates[name] = calc.manifest.hash || true;
-                const isSharded = updates.some(u => u.data._sharded === true);
+                const isSharded      = updates.some(u => u.data._sharded === true);
                 deps.logger.log('INFO', `${name} for ${dStr}: \u2714 Success (Written ${isSharded ? 'Sharded' : 'Standard'})`);
             } else {
                 deps.logger.log('INFO', `${name} for ${dStr}: - Empty Data`);
@@ -74,42 +74,43 @@ function calculateFirestoreBytes(value) {
 
 async function prepareAutoShardedWrites(result, docRef, logger) {
     const SAFETY_THRESHOLD_BYTES = 1000 * 1024; // 1MB Limit
-    const OVERHEAD_ALLOWANCE = 20 * 1024;
-    const CHUNK_LIMIT = SAFETY_THRESHOLD_BYTES - OVERHEAD_ALLOWANCE;
-    const totalSize = calculateFirestoreBytes(result);
-    const docPathSize = Buffer.byteLength(docRef.path, 'utf8') + 16;
-
-    if ((totalSize + docPathSize) < CHUNK_LIMIT) { 
-        const data = { ...result, _completed: true, _sharded: false }; 
-        return [{ ref: docRef, data, options: { merge: true } }]; 
-    }
+    const OVERHEAD_ALLOWANCE     = 20 * 1024;
+    const CHUNK_LIMIT            = SAFETY_THRESHOLD_BYTES - 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 shardIndex               = 0;
+
+    // If under limit, write directly
+    if ((totalSize + docPathSize) < CHUNK_LIMIT) {  const data = { ...result, _completed: true, _sharded: false };  return [{ ref: docRef, data, options: { merge: true } }];  }
 
     logger.log('INFO', `[AutoShard] Result size ~${Math.round(totalSize/1024)}KB exceeds limit. Sharding...`);
-    const writes = [];
-    const shardCollection = docRef.collection('_shards');
-    let currentChunk = {};
-    let currentChunkSize = 0;
-    let shardIndex = 0;
 
+    // iF over limit, shard the document
     for (const [key, value] of Object.entries(result)) { 
         if (key.startsWith('_')) continue;
-        const keySize = Buffer.byteLength(key, 'utf8') + 1;         
+        const keySize   = Buffer.byteLength(key, 'utf8') + 1;         
         const valueSize = calculateFirestoreBytes(value);
-        const itemSize = keySize + valueSize;
+        const itemSize  = keySize + valueSize;
 
+        // If adding this item exceeds the chunk limit, commit current chunk
         if (currentChunkSize + itemSize > CHUNK_LIMIT) { 
             writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } });
             shardIndex++;
-            currentChunk = {};
+            currentChunk     = {};
             currentChunkSize = 0;
         }
         currentChunk[key] = value;
         currentChunkSize += itemSize;
     }
-    if (Object.keys(currentChunk).length > 0) { 
-        writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } }); 
-    }
+
+    // Write the final chunk
+    if (Object.keys(currentChunk).length > 0) {  writes.push({ ref: shardCollection.doc(`shard_${shardIndex}`), data: currentChunk, options: { merge: false } });  }
     
+    // Finally, write the pointer document
     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/StatusRepository.js

@@ -3,19 +3,25 @@
  */
 
 async function fetchComputationStatus(dateStr, config, { db }) {
-    if (!key) throw new Error('fetchStatus requires a key'); 
+    // FIX: Check dateStr directly, or define 'key' before checking it.
+    if (!dateStr) throw new Error('fetchStatus requires a key'); 
+    
     const key = dateStr;
     const collection = config.computationStatusCollection || 'computation_status';
     const docRef = db.collection(collection).doc(key);
+    
     const snap = await docRef.get();
     return snap.exists ? snap.data() : {};
 }
 
 async function updateComputationStatus(dateStr, updates, config, { db }) {
     if (!dateStr) throw new Error('updateStatus requires a key');
+    
     if (!updates || Object.keys(updates).length === 0) return;
+    
     const collection = config.computationStatusCollection || 'computation_status';
     const docRef = db.collection(collection).doc(dateStr);
+    
     await docRef.set(updates, { merge: true });
     return true;
 }

package/functions/computation-system/utils/utils.js

@@ -3,7 +3,7 @@
  */
 
 const { FieldValue, FieldPath } = require('@google-cloud/firestore');
-const crypto = require('crypto');
+const crypto                    = require('crypto');
 
 /** Stage 1: Normalize a calculation name to kebab-case */
 function normalizeName(name) { return name.replace(/_/g, '-'); }

package/package.json

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