bulltrackers-module 1.0.264 → 1.0.265

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}`;
@@ -58,7 +56,6 @@ function analyzeDateExecution(dateStr, calcsInPass, rootDataStatus, dailyStatus,
         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); // 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');
@@ -106,9 +107,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 +123,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 +159,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 +199,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 +210,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 +262,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/persistence/ResultCommitter.js

@@ -1,8 +1,6 @@
 /**
  * @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.
  */
 const { commitBatchInChunks }              = require('./FirestoreUtils');
 const { updateComputationStatus }          = require('./StatusRepository');
@@ -10,13 +8,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,13 +22,11 @@ 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
         const runMetrics = {
             storage: { sizeBytes: 0, isSharded: false, shardCount: 1, keys: 0 },
             validation: { isValid: true, anomalies: [] }
@@ -41,7 +34,6 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
 
         try {
             const result = await calc.getResult();
-
             const overrides   = validationOverrides[calc.manifest.name] || {};
             const healthCheck = HeuristicValidator.analyze(calc.manifest.name, result, overrides);
 
@@ -54,52 +46,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, // <--- Added 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
+                        composition: calc.manifest.composition, // <--- Added Composition
+                        metrics: runMetrics 
                     }; 
                 }
 
             } else {
-                // --- STANDARD MODE (Single Date) ---
+                // --- STANDARD MODE ---
                 const mainDocRef = db.collection(config.resultsCollection)
                     .doc(dStr)
                     .collection(config.resultsSubcollection)
@@ -107,30 +99,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.shardCount = writeStats.shardCount;
 
-                // Mark Success & Pass Metrics
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
                         hash: calc.manifest.hash, 
                         category: calc.manifest.category,
+                        composition: calc.manifest.composition, // <--- Added 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 +133,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 +145,79 @@ 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.
- */
 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/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

@@ -111,8 +111,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.265",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [