bulltrackers-module 1.0.296 → 1.0.297

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

@@ -1,10 +1,6 @@
 /**
  * @fileoverview Executor for "Standard" (per-user) calculations.
- * UPDATED: Implements Batch Flushing to prevent OOM on large datasets.
- * UPDATED: Implements "Circuit Breaker" to fail fast on high error rates.
- * UPDATED: Implements "Adaptive Flushing" based on V8 Heap usage.
- * UPDATED: Manages incremental sharding states.
- * UPDATED: Implements 'isInitialWrite' flag for robust cleanup.
+ * UPDATED: Tracks IO Operations (Reads/Writes) for Cost Analysis.
  */
 const { normalizeName }                                                = require('../utils/utils');
 const { streamPortfolioData, streamHistoryData, getPortfolioPartRefs } = require('../utils/data_loader');
@@ -20,7 +16,7 @@ class StandardExecutor {
         const dStr   = date.toISOString().slice(0, 10);
         const logger = deps.logger;
         
-        // 1. Prepare Yesterdays Data if needed
+        // 1. Prepare Yesterdays Data (Counts as Read Ops)
         const fullRoot = { ...rootData };
         if (calcs.some(c => c.isHistorical)) {
             const prev = new Date(date); prev.setUTCDate(prev.getUTCDate() - 1);
@@ -28,22 +24,17 @@ class StandardExecutor {
             fullRoot.yesterdayPortfolioRefs = await getPortfolioPartRefs(config, deps, prevStr);
         }
 
-        // 2. Initialize Instances
         const state = {};
         for (const c of calcs) { 
             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) { 
-                logger.log('WARN', `Failed to init ${c.name}`); 
-            } 
+            } catch (e) { logger.log('WARN', `Failed to init ${c.name}`); } 
         }
 
-        // 3. Stream, Process & Batch Flush
         return await StandardExecutor.streamAndProcess(dStr, state, passName, config, deps, fullRoot, rootData.portfolioRefs, rootData.historyRefs, fetchedDeps, previousFetchedDeps, skipStatusWrite);
     }
 
@@ -54,33 +45,34 @@ class StandardExecutor {
         
         if (streamingCalcs.length === 0) return { successUpdates: {}, failureReport: [] };
         
-        logger.log('INFO', `[${passName}] Streaming for ${streamingCalcs.length} computations...`);
-        
+        // [NEW] Calculate Total Read Ops for this execution context
+        // Each reference in the arrays corresponds to a document fetch
+        let totalReadOps = (portfolioRefs?.length || 0) + (historyRefs?.length || 0);
+        if (rootData.yesterdayPortfolioRefs) totalReadOps += rootData.yesterdayPortfolioRefs.length;
+        // Add +2 for Insights & Social (1 doc each)
+        totalReadOps += 2; 
+
+        // Distribute read costs evenly among calculations (approximation)
+        const readOpsPerCalc = Math.ceil(totalReadOps / streamingCalcs.length);
+
         const executionStats = {};
         const shardIndexMap  = {}; 
         const aggregatedSuccess = {};
         const aggregatedFailures = [];
-
-        // [NEW] Global Error Tracking for Circuit Breaker
         const errorStats = { count: 0, total: 0 };
 
         Object.keys(state).forEach(name => {
             executionStats[name] = { 
-                processedUsers: 0, 
-                skippedUsers: 0,
-                timings: { setup: 0, stream: 0, processing: 0 }
+                processedUsers: 0, skippedUsers: 0, timings: { setup: 0, stream: 0, processing: 0 }
             };
-            shardIndexMap[name]  = 0;
+            shardIndexMap[name] = 0;
         });
 
-        // Track if we have performed a flush yet (for cleanup logic)
         let hasFlushed = false;
-
-        const startSetup = performance.now();
         const cachedLoader = new CachedDataLoader(config, deps);
+        const startSetup = performance.now();
         await cachedLoader.loadMappings();
         const setupDuration = performance.now() - startSetup;
-        
         Object.keys(executionStats).forEach(name => executionStats[name].timings.setup += setupDuration);
 
         const prevDate    = new Date(dateStr + 'T00:00:00Z'); prevDate.setUTCDate(prevDate.getUTCDate() - 1);
@@ -93,8 +85,6 @@ class StandardExecutor {
         const tH_iter = (needsTradingHistory) ? streamHistoryData(config, deps, dateStr, historyRefs) : null;
 
         let yP_chunk = {}, tH_chunk = {};
-        
-        const MIN_BATCH_SIZE = 1000; // Minimum to process before checking stats
         let usersSinceLastFlush = 0;
 
         try {
@@ -106,52 +96,26 @@ class StandardExecutor {
                 Object.keys(executionStats).forEach(name => executionStats[name].timings.stream += streamDuration);
 
                 const chunkSize = Object.keys(tP_chunk).length;
-
                 const startProcessing = performance.now();
                 
-                // [UPDATED] Collect execution results (success/failure counts)
-                const promises = streamingCalcs.map(calc =>  
+                const batchResults = await Promise.all(streamingCalcs.map(calc =>  
                     StandardExecutor.executePerUser(
                         calc, calc.manifest, dateStr, tP_chunk, yP_chunk, tH_chunk, 
                         fetchedDeps, previousFetchedDeps, config, deps, cachedLoader,
                         executionStats[normalizeName(calc.manifest.name)]
                     ) 
-                );
+                ));
                 
-                const batchResults = await Promise.all(promises);
                 const procDuration = performance.now() - startProcessing;
-                
                 Object.keys(executionStats).forEach(name => executionStats[name].timings.processing += procDuration);
 
-                // [NEW] Update Error Stats
-                batchResults.forEach(r => {
-                    errorStats.total += (r.success + r.failures);
-                    errorStats.count += r.failures;
-                });
-
-                // [NEW] Circuit Breaker: Fail fast if error rate > 10% after processing 100+ items
-                // We check total > 100 to avoid failing on the very first user if they happen to be bad.
-                if (errorStats.total > 100 && (errorStats.count / errorStats.total) > 0.10) {
-                    const failRate = (errorStats.count / errorStats.total * 100).toFixed(1);
-                    throw new Error(`[Circuit Breaker] High failure rate detected (${failRate}%). Aborting batch to prevent silent data loss.`);
-                }
+                batchResults.forEach(r => { errorStats.total += (r.success + r.failures); errorStats.count += r.failures; });
+                if (errorStats.total > 100 && (errorStats.count / errorStats.total) > 0.10) { throw new Error(`[Circuit Breaker] High failure rate detected.`); }
 
                 usersSinceLastFlush += chunkSize;
-
-                // [NEW] Adaptive Flushing (Memory Pressure Check)
                 const heapStats = v8.getHeapStatistics();
-                const heapUsedRatio = heapStats.used_heap_size / heapStats.heap_size_limit;
-                const MEMORY_THRESHOLD = 0.70; // 70% of available RAM
-                const COUNT_THRESHOLD = 5000;
-
-                if (usersSinceLastFlush >= COUNT_THRESHOLD || heapUsedRatio > MEMORY_THRESHOLD) {
-                    const reason = heapUsedRatio > MEMORY_THRESHOLD ? `MEMORY_PRESSURE (${(heapUsedRatio*100).toFixed(0)}%)` : 'BATCH_LIMIT';
-                    
-                    logger.log('INFO', `[${passName}] 🛁 Flushing buffer after ${usersSinceLastFlush} users. Reason: ${reason}`);
-                    
-                    // [UPDATED] Pass isInitialWrite: true only on the first flush
+                if (usersSinceLastFlush >= 5000 || (heapStats.used_heap_size / heapStats.heap_size_limit) > 0.70) {
                     const flushResult = await StandardExecutor.flushBuffer(state, dateStr, passName, config, deps, shardIndexMap, executionStats, 'INTERMEDIATE', true, !hasFlushed);
-                    
                     hasFlushed = true;
                     StandardExecutor.mergeReports(aggregatedSuccess, aggregatedFailures, flushResult);
                     usersSinceLastFlush = 0;
@@ -161,22 +125,23 @@ class StandardExecutor {
             if (yP_iter && yP_iter.return) await yP_iter.return();
             if (tH_iter && tH_iter.return) await tH_iter.return();
         }
-        
-        logger.log('INFO', `[${passName}] Streaming complete. Performing final commit.`);
-        // [UPDATED] If we never flushed in the loop, this is the initial write
+
         const finalResult = await StandardExecutor.flushBuffer(state, dateStr, passName, config, deps, shardIndexMap, executionStats, 'FINAL', skipStatusWrite, !hasFlushed);
-        
         StandardExecutor.mergeReports(aggregatedSuccess, aggregatedFailures, finalResult);
 
+        // [NEW] Inject Read Ops into the final report
+        Object.values(aggregatedSuccess).forEach(update => {
+            if (!update.metrics.io) update.metrics.io = { reads: 0, writes: 0, deletes: 0 };
+            update.metrics.io.reads = readOpsPerCalc;
+        });
+
         return { successUpdates: aggregatedSuccess, failureReport: aggregatedFailures };
     }
 
     static async flushBuffer(state, dateStr, passName, config, deps, shardIndexMap, executionStats, mode, skipStatusWrite, isInitialWrite = false) {
         const transformedState = {};
-        
         for (const [name, inst] of Object.entries(state)) {
             const rawResult = inst.results || {};
-            
             const firstUser = Object.keys(rawResult)[0];
             let dataToCommit = rawResult;
 
@@ -199,43 +164,40 @@ class StandardExecutor {
                 getResult: async () => dataToCommit,
                 _executionStats: executionStats[name]
             };
-
-            // Clear the memory immediately after preparing the commit
             inst.results = {};
         }
 
-        // [UPDATED] Pass isInitialWrite to ResultCommitter
         const result = await commitResults(transformedState, dateStr, passName, config, deps, skipStatusWrite, {
-            flushMode: mode,      
-            shardIndexes: shardIndexMap,
-            isInitialWrite: isInitialWrite 
+            flushMode: mode, shardIndexes: shardIndexMap, isInitialWrite: isInitialWrite 
         });
 
-        if (result.shardIndexes) {
-            Object.assign(shardIndexMap, result.shardIndexes);
-        }
-
+        if (result.shardIndexes) Object.assign(shardIndexMap, result.shardIndexes);
         return result;
     }
 
     static mergeReports(successAcc, failureAcc, newResult) {
         if (!newResult) return;
-        
         for (const [name, update] of Object.entries(newResult.successUpdates)) {
             if (!successAcc[name]) {
                 successAcc[name] = update;
             } else {
-                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);
-                }
+                // Merge Storage metrics
+                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);
                 
+                // [NEW] Merge IO Metrics
+                if (update.metrics.io) {
+                    if (!successAcc[name].metrics.io) successAcc[name].metrics.io = { writes: 0, deletes: 0, reads: 0 };
+                    successAcc[name].metrics.io.writes += (update.metrics.io.writes || 0);
+                    successAcc[name].metrics.io.deletes += (update.metrics.io.deletes || 0);
+                }
+
+                // Merge timings
                 if (update.metrics?.execution?.timings) {
                      if (!successAcc[name].metrics.execution) successAcc[name].metrics.execution = { timings: { setup:0, stream:0, processing:0 }};
                      const tDest = successAcc[name].metrics.execution.timings;
                      const tSrc  = update.metrics.execution.timings;
-                     
                      tDest.setup += (tSrc.setup || 0);
                      tDest.stream += (tSrc.stream || 0);
                      tDest.processing += (tSrc.processing || 0);
@@ -243,12 +205,9 @@ class StandardExecutor {
                 successAcc[name].hash = update.hash;
             }
         }
-
-        if (newResult.failureReport) {
-            failureAcc.push(...newResult.failureReport);
-        }
+        if (newResult.failureReport) failureAcc.push(...newResult.failureReport);
     }
-
+    
     static async executePerUser(calcInstance, metadata, dateStr, portfolioData, yesterdayPortfolioData, historyData, computedDeps, prevDeps, config, deps, loader, stats) {
         const { logger } = deps;
         const targetUserType = metadata.userType; 
@@ -256,7 +215,6 @@ class StandardExecutor {
         const insights = metadata.rootDataDependencies?.includes('insights') ? { today: await loader.loadInsights(dateStr) } : null;
         const SCHEMAS  = mathLayer.SCHEMAS;
 
-        // [NEW] Track local batch success/failure
         let chunkSuccess = 0;
         let chunkFailures = 0;
 

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

@@ -2,7 +2,7 @@
  * FILENAME: computation-system/helpers/computation_worker.js
  * PURPOSE: Consumes tasks, executes logic, and signals Workflow upon Batch Completion.
  * UPDATED: Implements IAM Auth for Workflow Callbacks.
- * UPDATED: Implements Memory Heartbeat (Flight Recorder) for OOM detection.
+ * UPDATED: Implements Peak Memory Heartbeat and Resource Tier tracking.
  */
 
 const { executeDispatchTask } = require('../WorkflowOrchestrator.js');
@@ -11,6 +11,7 @@ const { StructuredLogger }    = require('../logger/logger');
 const { recordRunAttempt }    = require('../persistence/RunRecorder'); 
 const https                   = require('https'); 
 const { GoogleAuth }          = require('google-auth-library'); 
+const { normalizeName }       = require('../utils/utils');
 
 let calculationPackage;
 try { calculationPackage = require('aiden-shared-calculations-unified');
@@ -20,15 +21,19 @@ const calculations = calculationPackage.calculations;
 const MAX_RETRIES = 3;
 
 /**
- * [NEW] Helper: Starts a background heartbeat to track memory usage.
- * This acts as a "Black Box Recorder". If the worker crashes (OOM),
- * the last written value will remain in Firestore for the Dispatcher to analyze.
+ * [UPDATED] Heartbeat now returns a closure to get the PEAK memory.
+ * This acts as a "Black Box Recorder".
  */
 function startMemoryHeartbeat(db, ledgerPath, intervalMs = 2000) {
+    let peakRss = 0;
+    
     const getMemStats = () => {
         const mem = process.memoryUsage();
+        const rssMB = Math.round(mem.rss / 1024 / 1024);
+        if (rssMB > peakRss) peakRss = rssMB;
+        
         return {
-            rssMB: Math.round(mem.rss / 1024 / 1024),       // Resident Set Size (OOM Killer Metric)
+            rssMB: rssMB,
             heapUsedMB: Math.round(mem.heapUsed / 1024 / 1024),
             timestamp: new Date()
         };
@@ -50,7 +55,10 @@ function startMemoryHeartbeat(db, ledgerPath, intervalMs = 2000) {
     // Unref so this timer doesn't prevent the process from exiting naturally
     timer.unref();
 
-    return timer;
+    return {
+        timer,
+        getPeak: () => peakRss
+    };
 }
 
 /**
@@ -127,7 +135,9 @@ async function handleComputationTask(message, config, dependencies) {
 
     if (!data || data.action !== 'RUN_COMPUTATION_DATE') { return; }
     
-    const { date, pass, computation, previousCategory, triggerReason, dispatchId, dependencyResultHashes, metaStatePath } = data;
+    // [UPDATED] Extract 'resources' from payload (set by Dispatcher)
+    const { date, pass, computation, previousCategory, triggerReason, dispatchId, dependencyResultHashes, metaStatePath, resources } = data;
+    const resourceTier = resources || 'standard'; // Default to standard
     
     if (!date || !pass || !computation) { logger.log('ERROR', `[Worker] Invalid payload.`, data); return; }
 
@@ -158,7 +168,7 @@ async function handleComputationTask(message, config, dependencies) {
             } catch (dlqErr) { logger.log('FATAL', `[Worker] Failed to write to DLQ`, dlqErr); }
     }
 
-    logger.log('INFO', `[Worker] 📥 Received Task: ${computation} (${date}) [Attempt ${retryCount}/${MAX_RETRIES}]`);
+    logger.log('INFO', `[Worker] 📥 Received Task: ${computation} (${date}) [Attempt ${retryCount}/${MAX_RETRIES}] [Tier: ${resourceTier}]`);
 
     // 1. Update Status to IN_PROGRESS & Initialize Telemetry
     try {
@@ -172,12 +182,13 @@ async function handleComputationTask(message, config, dependencies) {
     } catch (leaseErr) {}
 
     // 2. START HEARTBEAT (The Flight Recorder)
-    const heartbeatTimer = startMemoryHeartbeat(db, ledgerPath, 2000);
+    // [UPDATED] Using new logic to track peak
+    const heartbeatControl = startMemoryHeartbeat(db, ledgerPath, 2000);
 
     let computationManifest;
     try { computationManifest = getManifest(config.activeProductLines || [], calculations, runDependencies);
     } catch (manifestError) { 
-        clearInterval(heartbeatTimer); // Stop if we fail early
+        clearInterval(heartbeatControl.timer); // Stop if we fail early
         logger.log('FATAL', `[Worker] Failed to load Manifest: ${manifestError.message}`);
         return; 
     }
@@ -191,7 +202,7 @@ async function handleComputationTask(message, config, dependencies) {
         const duration = Date.now() - startTime;
 
         // STOP HEARTBEAT ON SUCCESS
-        clearInterval(heartbeatTimer);
+        clearInterval(heartbeatControl.timer);
 
         const failureReport  = result?.updates?.failureReport  || [];
         const successUpdates = result?.updates?.successUpdates || {};
@@ -203,20 +214,33 @@ async function handleComputationTask(message, config, dependencies) {
         else {
             if (Object.keys(successUpdates).length > 0) { logger.log('INFO', `[Worker] ✅ Stored: ${computation}`); } 
             else { logger.log('WARN', `[Worker] ⚠️ Empty Result: ${computation}`); }
+            
+            // Extract the metrics from the success update for the recorder
+            const calcUpdate = successUpdates[normalizeName(computation)] || {};
+            const finalMetrics = {
+                durationMs: duration,
+                peakMemoryMB: heartbeatControl.getPeak(),
+                io: calcUpdate.metrics?.io,
+                storage: calcUpdate.metrics?.storage,
+                execution: calcUpdate.metrics?.execution,
+                validation: calcUpdate.metrics?.validation,
+                composition: calcUpdate.composition
+            };
 
             await db.doc(ledgerPath).update({
                 status: 'COMPLETED',
                 completedAt: new Date()
             }).catch(() => {});
 
-            await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', null, { durationMs: duration }, triggerReason);
+            // [UPDATED] Pass resourceTier and metrics to recordRunAttempt
+            await recordRunAttempt(db, { date, computation, pass }, 'SUCCESS', null, finalMetrics, triggerReason, resourceTier);
 
             const callbackUrl = await decrementAndCheck(db, metaStatePath, logger);
             if (callbackUrl) { await triggerWorkflowCallback(callbackUrl, 'SUCCESS', logger); }
         }
     } catch (err) { 
         // STOP HEARTBEAT ON ERROR
-        clearInterval(heartbeatTimer);
+        clearInterval(heartbeatControl.timer);
 
         // --- ERROR HANDLING ---
         const isDeterministicError = err.stage === 'SHARDING_LIMIT_EXCEEDED' || 
@@ -241,7 +265,7 @@ async function handleComputationTask(message, config, dependencies) {
                     failedAt: new Date()
                 }, { merge: true });
 
-                 await recordRunAttempt(db, { date, computation, pass }, 'FAILURE', { message: err.message, stage: err.stage || 'PERMANENT_FAIL' }, { durationMs: 0 }, triggerReason);
+                 await recordRunAttempt(db, { date, computation, pass }, 'FAILURE', { message: err.message, stage: err.stage || 'PERMANENT_FAIL' }, { durationMs: 0, peakMemoryMB: heartbeatControl.getPeak() }, triggerReason, resourceTier);
                  
                  const callbackUrl = await decrementAndCheck(db, metaStatePath, logger);
                  if (callbackUrl) { await triggerWorkflowCallback(callbackUrl, 'SUCCESS', logger); }
@@ -252,9 +276,9 @@ async function handleComputationTask(message, config, dependencies) {
         if (retryCount >= MAX_RETRIES) { throw err; }
 
         logger.log('ERROR', `[Worker] ❌ Crash: ${computation}: ${err.message}`); 
-        await recordRunAttempt(db, { date, computation, pass }, 'CRASH', {  message: err.message, stack: err.stack, stage: 'SYSTEM_CRASH' }, { durationMs: 0 }, triggerReason);
+        await recordRunAttempt(db, { date, computation, pass }, 'CRASH', {  message: err.message, stack: err.stack, stage: 'SYSTEM_CRASH' }, { durationMs: 0, peakMemoryMB: heartbeatControl.getPeak() }, triggerReason, resourceTier);
         throw err; 
     }
 }
 
-module.exports = { handleComputationTask };
+module.exports = { handleComputationTask };

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

@@ -1,32 +1,21 @@
 /**
  * @fileoverview Handles saving computation results with observability and Smart Cleanup.
- * UPDATED: Implements GZIP Compression for efficient storage.
- * UPDATED: Implements Content-Based Hashing (ResultHash) for dependency short-circuiting.
- * UPDATED: Auto-enforces Weekend Mode validation.
- * UPDATED: Implements "Initial Write" logic to wipe stale data/shards on a fresh run.
- * UPDATED: Implements "Contract Validation" (Semantic Gates) to block logical violations.
- * OPTIMIZED: Fetches pre-calculated 'simHash' from Registry (removes expensive simulation step).
+ * UPDATED: Tracks specific Firestore Ops (Writes/Deletes) for cost analysis.
  */
 const { commitBatchInChunks, generateDataHash } = require('../utils/utils');
 const { updateComputationStatus }          = require('./StatusRepository');
 const { batchStoreSchemas }                = require('../utils/schema_capture');
 const { generateProcessId, PROCESS_TYPES } = require('../logger/logger');
 const { HeuristicValidator }               = require('./ResultsValidator');
-const ContractValidator                    = require('./ContractValidator'); // [NEW]
+const ContractValidator                    = require('./ContractValidator');
 const validationOverrides                  = require('../config/validation_overrides'); 
 const pLimit                               = require('p-limit'); 
 const zlib                                 = require('zlib'); 
 
-const NON_RETRYABLE_ERRORS = [
-    'PERMISSION_DENIED',     'DATA_LOSS',             'FAILED_PRECONDITION'
-];
-
+const NON_RETRYABLE_ERRORS = [ 'PERMISSION_DENIED', 'DATA_LOSS', 'FAILED_PRECONDITION' ];
 const SIMHASH_REGISTRY_COLLECTION = 'system_simhash_registry';
-const CONTRACTS_COLLECTION        = 'system_contracts'; // [NEW]
+const CONTRACTS_COLLECTION        = 'system_contracts';
 
-/**
- * Commits results to Firestore.
- */
 async function commitResults(stateObj, dStr, passName, config, deps, skipStatusWrite = false, options = {}) {
     const successUpdates = {};
     const failureReport  = [];
@@ -35,17 +24,12 @@ 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 isInitialWrite   = options.isInitialWrite === true; 
     const shardIndexes     = options.shardIndexes || {};
     const nextShardIndexes = {};
-
-    const fanOutLimit = pLimit(10); 
-
-    // [NEW] Bulk fetch contracts for all calcs in this batch to minimize latency
-    // This prevents N+1 reads during the loop
-    const contractMap = await fetchContracts(db, Object.keys(stateObj));
+    const fanOutLimit      = pLimit(10); 
+    const contractMap      = await fetchContracts(db, Object.keys(stateObj));
 
     for (const name in stateObj) {
         const calc      = stateObj[name];
@@ -55,43 +39,34 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
         const runMetrics = {
             storage:    { sizeBytes: 0, isSharded: false, shardCount: 1, keys: 0 },
             validation: { isValid: true, anomalies: [] },
-            execution: execStats
+            execution: execStats,
+            // [NEW] Track Ops
+            io: { writes: 0, deletes: 0 }
         };
 
         try {
             const result = await calc.getResult();
-            const configOverrides = validationOverrides[calc.manifest.name] || {};
             
+            const configOverrides = validationOverrides[calc.manifest.name] || {};
             const dataDeps = calc.manifest.rootDataDependencies || [];
             const isPriceOnly = (dataDeps.length === 1 && dataDeps[0] === 'price');
-            
             let effectiveOverrides = { ...configOverrides };
-            
             if (isPriceOnly && !effectiveOverrides.weekend) {
-                effectiveOverrides.weekend = {
-                    maxZeroPct: 100,
-                    maxFlatlinePct: 100,
-                    maxNullPct: 100 
-                };
+                effectiveOverrides.weekend = { maxZeroPct: 100, maxFlatlinePct: 100, maxNullPct: 100 };
             }
 
-            // 1. SEMANTIC GATE (CONTRACT VALIDATION) [NEW]
-            // We run this BEFORE Heuristics because it catches "Logic Bugs" vs "Data Noise"
             const contract = contractMap[name];
             if (contract) {
                 const contractCheck = ContractValidator.validate(result, contract);
                 if (!contractCheck.valid) {
-                    // STOP THE CASCADE: Fail this specific calculation
                     runMetrics.validation.isValid = false;
                     runMetrics.validation.anomalies.push(contractCheck.reason);
-                    
                     const semanticError = new Error(contractCheck.reason);
                     semanticError.stage = 'SEMANTIC_GATE';
                     throw semanticError;
                 }
             }
 
-            // 2. HEURISTIC VALIDATION (Data Integrity)
             if (result && Object.keys(result).length > 0) {
                 const healthCheck = HeuristicValidator.analyze(calc.manifest.name, result, dStr, effectiveOverrides);
                 if (!healthCheck.valid) {
@@ -102,38 +77,25 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                     throw validationError;
                 }
             }
-            
+
             const isEmpty = !result || (typeof result === 'object' && Object.keys(result).length === 0);
             const resultHash = isEmpty ? 'empty' : generateDataHash(result);
-
-            // [OPTIMIZATION] FETCH SimHash from Registry (Do NOT Calculate)
+            
             let simHash = null;
             if (calc.manifest.hash && flushMode !== 'INTERMEDIATE') {
-                try {
+                 try {
                     const regDoc = await db.collection(SIMHASH_REGISTRY_COLLECTION).doc(calc.manifest.hash).get();
-                    if (regDoc.exists) {
-                        simHash = regDoc.data().simHash;
-                    } else {
-                        logger.log('WARN', `[ResultCommitter] SimHash not found in registry for ${name}.`);
-                    }
-                } catch (regErr) {
-                    logger.log('WARN', `[ResultCommitter] Failed to read SimHash registry: ${regErr.message}`);
-                }
+                    if (regDoc.exists) simHash = regDoc.data().simHash;
+                } catch (e) {}
             }
 
             if (isEmpty) { 
-                if (flushMode === 'INTERMEDIATE') {
-                    nextShardIndexes[name] = currentShardIndex; 
-                    continue; 
-                }
+                if (flushMode === 'INTERMEDIATE') { nextShardIndexes[name] = currentShardIndex; continue; }
                 if (calc.manifest.hash) { 
                     successUpdates[name] = { 
-                        hash:        calc.manifest.hash,
-                        simHash:     simHash, 
-                        resultHash:  resultHash, 
+                        hash: calc.manifest.hash, simHash: simHash, resultHash: resultHash, 
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
-                        category:    calc.manifest.category, 
-                        composition: calc.manifest.composition,
+                        category: calc.manifest.category, composition: calc.manifest.composition,
                         metrics: runMetrics 
                     }; 
                 } 
@@ -141,7 +103,6 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             }
             
             if (typeof result === 'object') runMetrics.storage.keys = Object.keys(result).length;
-
             const resultKeys = Object.keys(result || {});
             const isMultiDate = resultKeys.length > 0 && resultKeys.every(k => /^\d{4}-\d{2}-\d{2}$/.test(k));
 
@@ -149,73 +110,42 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 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)
-                        .collection(config.resultsSubcollection)
-                        .doc(calc.manifest.category)
-                        .collection(config.computationsSubcollection)
-                        .doc(name);
-
-                    await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps, 0, 'STANDARD', false);
+                    const historicalDocRef = db.collection(config.resultsCollection).doc(historicalDate).collection(config.resultsSubcollection).doc(calc.manifest.category).collection(config.computationsSubcollection).doc(name);
+                    const stats = await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps, 0, 'STANDARD', false);
+                    
+                    // Aggregate IO Ops
+                    runMetrics.io.writes += stats.opCounts.writes;
+                    runMetrics.io.deletes += stats.opCounts.deletes;
                 }));
                 await Promise.all(datePromises);
                 
-                if (calc.manifest.hash) { 
-                    successUpdates[name] = {  
-                        hash:        calc.manifest.hash, 
-                        simHash:     simHash,
-                        resultHash:  resultHash, 
-                        dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
-                        category:    calc.manifest.category, 
-                        composition: calc.manifest.composition,
-                        metrics: runMetrics 
-                    }; 
-                }
-
+                if (calc.manifest.hash) { successUpdates[name] = { hash: calc.manifest.hash, simHash, resultHash, dependencyResultHashes: calc.manifest.dependencyResultHashes || {}, category: calc.manifest.category, composition: calc.manifest.composition, metrics: runMetrics }; }
             } else {
-                const mainDocRef = db.collection(config.resultsCollection)
-                    .doc(dStr)
-                    .collection(config.resultsSubcollection)
-                    .doc(calc.manifest.category)
-                    .collection(config.computationsSubcollection)
-                    .doc(name);
-
+                const mainDocRef = db.collection(config.resultsCollection).doc(dStr).collection(config.resultsSubcollection).doc(calc.manifest.category).collection(config.computationsSubcollection).doc(name);
                 const writeStats = await writeSingleResult(result, mainDocRef, name, dStr, logger, config, deps, currentShardIndex, flushMode, isInitialWrite);
                 
                 runMetrics.storage.sizeBytes  = writeStats.totalSize;
                 runMetrics.storage.isSharded  = writeStats.isSharded;
                 runMetrics.storage.shardCount = writeStats.shardCount;
+                runMetrics.io.writes += writeStats.opCounts.writes;
+                runMetrics.io.deletes += writeStats.opCounts.deletes;
                 
                 nextShardIndexes[name] = writeStats.nextShardIndex;
-
-                if (calc.manifest.hash) { 
-                    successUpdates[name] = {  
-                        hash:        calc.manifest.hash, 
-                        simHash:     simHash,
-                        resultHash:  resultHash,
-                        dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
-                        category:    calc.manifest.category,
-                        composition: calc.manifest.composition, 
-                        metrics: runMetrics 
-                    }; 
-                }
+                if (calc.manifest.hash) { successUpdates[name] = { hash: calc.manifest.hash, simHash, resultHash, dependencyResultHashes: calc.manifest.dependencyResultHashes || {}, category: calc.manifest.category, composition: calc.manifest.composition, metrics: runMetrics }; }
             }
 
             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 && 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: e }); }
-            failureReport.push({ name, error: { message: msg, stack: e.stack, stage }, metrics: runMetrics });
+            failureReport.push({ name, error: { message: e.message, stack: e.stack, stage }, metrics: runMetrics });
         }
     }
 
@@ -228,48 +158,34 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     return { successUpdates, failureReport, shardIndexes: nextShardIndexes };
 }
 
-/**
- * [NEW] Helper to fetch contracts for a list of calculations
- */
 async function fetchContracts(db, calcNames) {
     if (!calcNames || calcNames.length === 0) return {};
     const map = {};
-    
-    // In a high-throughput system, we might cache these in memory (LRU)
-    // For now, we fetch from Firestore efficiently.
     const refs = calcNames.map(name => db.collection(CONTRACTS_COLLECTION).doc(name));
-    
     try {
         const snaps = await db.getAll(...refs);
-        snaps.forEach(snap => {
-            if (snap.exists) {
-                map[snap.id] = snap.data();
-            }
-        });
-    } catch (e) {
-        console.warn(`[ResultCommitter] Failed to fetch contracts batch: ${e.message}`);
-    }
+        snaps.forEach(snap => { if (snap.exists) map[snap.id] = snap.data(); });
+    } catch (e) {}
     return map;
 }
 
 async function writeSingleResult(result, docRef, name, dateContext, logger, config, deps, startShardIndex = 0, flushMode = 'STANDARD', isInitialWrite = false) {
-    
-    // Transition & Cleanup Logic
+    const opCounts = { writes: 0, deletes: 0 };
     let wasSharded = false;
     let shouldWipeShards = false;
-
-    // Default: Merge updates. But if Initial Write, overwrite (merge: false) to clear stale fields.
     let rootMergeOption = !isInitialWrite; 
 
     if (isInitialWrite) {
         try {
             const currentSnap = await docRef.get();
+            // Note: Reads tracked implicitly by calling code or approximated here if needed.
+            // We focus on writes/deletes here.
             if (currentSnap.exists) {
                 const d = currentSnap.data();
                 wasSharded = (d._sharded === true);
                 if (wasSharded) shouldWipeShards = true;
             }
-        } catch (e) { /* ignore read error */ }
+        } catch (e) {}
     }
 
     // --- COMPRESSION STRATEGY ---
@@ -279,54 +195,32 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
 
         if (rawBuffer.length > 50 * 1024) { 
             const compressedBuffer = zlib.gzipSync(rawBuffer);
-            
             if (compressedBuffer.length < 900 * 1024) {
-                logger.log('INFO', `[Compression] ${name}: Compressed ${(rawBuffer.length/1024).toFixed(0)}KB -> ${(compressedBuffer.length/1024).toFixed(0)}KB. Saved as Blob.`);
+                logger.log('INFO', `[Compression] ${name}: Compressed ${(rawBuffer.length/1024).toFixed(0)}KB -> ${(compressedBuffer.length/1024).toFixed(0)}KB.`);
+                const compressedPayload = { _compressed: true, _completed: true, _lastUpdated: new Date().toISOString(), payload: compressedBuffer };
                 
-                const compressedPayload = {
-                    _compressed: true,
-                    _completed: true,
-                    _lastUpdated: new Date().toISOString(),
-                    payload: compressedBuffer
-                };
-                
-                // Cleanup: If it was sharded, or if we are wiping shards on initial write
                 if (shouldWipeShards) {
-                    logger.log('INFO', `[Cleanup] ${name}: Wiping old shards before Compressed Write.`);
                     const updates = [];
                     const shardCol = docRef.collection('_shards');
                     const shardDocs = await shardCol.listDocuments();
                     shardDocs.forEach(d => updates.push({ type: 'DELETE', ref: d }));
-                    
-                    // Root update with merge: false (overwrites everything)
                     updates.push({ ref: docRef, data: compressedPayload, options: { merge: false } });
                     
+                    opCounts.deletes += shardDocs.length;
+                    opCounts.writes += 1;
+
                     await commitBatchInChunks(config, deps, updates, `${name}::Cleanup+Compress`);
                 } else {
-                    // Standard update (respecting calculated rootMergeOption)
                     await docRef.set(compressedPayload, { merge: rootMergeOption });
+                    opCounts.writes += 1;
                 }
                 
-                return { 
-                    totalSize: compressedBuffer.length, 
-                    isSharded: false, 
-                    shardCount: 1, 
-                    nextShardIndex: startShardIndex 
-                };
+                return { totalSize: compressedBuffer.length, isSharded: false, shardCount: 1, nextShardIndex: startShardIndex, opCounts };
             }
         }
-    } catch (compErr) {
-        logger.log('WARN', `[Compression] Failed to compress ${name}. Falling back to standard sharding.`, compErr);
-    }
-    // --- END COMPRESSION STRATEGY ---
-
-    const strategies = [ 
-        { bytes: 900 * 1024, keys: null }, 
-        { bytes: 450 * 1024, keys: 10000 }, 
-        { bytes: 200 * 1024, keys: 2000 },
-        { bytes: 100 * 1024, keys: 50 } 
-    ];
+    } catch (compErr) {}
 
+    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 };
 
@@ -335,26 +229,27 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
         const constraints = strategies[attempt];
         try {
             const updates = await prepareAutoShardedWrites(result, docRef, logger, constraints.bytes, constraints.keys, startShardIndex, flushMode);
-            
-            // Inject Cleanup Ops
             if (shouldWipeShards) {
-                 logger.log('INFO', `[Cleanup] ${name}: Wiping old shards before Write (Initial).`);
                  const shardCol = docRef.collection('_shards');
                  const shardDocs = await shardCol.listDocuments();
-                 // Prepend DELETEs
                  shardDocs.forEach(d => updates.unshift({ type: 'DELETE', ref: d }));
-                 shouldWipeShards = false; // Done for this loop
+                 shouldWipeShards = false;
             }
-
-            // Ensure the root document write respects our merge option
             const rootUpdate = updates.find(u => u.ref.path === docRef.path && u.type !== 'DELETE');
-            if (rootUpdate) {
-                rootUpdate.options = { merge: rootMergeOption };
-            }
+            if (rootUpdate) { rootUpdate.options = { merge: rootMergeOption }; }
 
-            const pointer = updates.find(u => u.data && (u.data._completed !== undefined || u.data._sharded !== undefined));
+            // Calculate Ops
+            const writes = updates.filter(u => u.type !== 'DELETE').length;
+            const deletes = updates.filter(u => u.type === 'DELETE').length;
+
+            await commitBatchInChunks(config, deps, updates, `${name}::${dateContext}`);
+            
+            opCounts.writes += writes;
+            opCounts.deletes += deletes;
+            
             finalStats.totalSize = updates.reduce((acc, u) => acc + (u.data ? JSON.stringify(u.data).length : 0), 0);
             
+            const pointer = updates.find(u => u.data && (u.data._completed !== undefined || u.data._sharded !== undefined));
             let maxIndex = startShardIndex;
             updates.forEach(u => {
                 if (u.type === 'DELETE') return;
@@ -374,28 +269,26 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
                 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 || '';
-            const code = commitErr.code || '';
-            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 }); 
-                continue;
-            }
+             lastError = commitErr;
+             const msg = commitErr.message || '';
+             const code = commitErr.code || '';
+             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 }); 
+                 continue;
+             }
         }
     }
     if (!committed) { 
@@ -404,6 +297,7 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
         if (lastError && lastError.stack) { shardingError.stack = lastError.stack; }
         throw shardingError; 
     }
+    finalStats.opCounts = opCounts;
     return finalStats;
 }
 

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

@@ -1,7 +1,6 @@
 /**
  * @fileoverview Utility for recording computation run attempts (The Audit Logger).
- * UPDATED: Stores 'trigger' reason and 'execution' stats.
- * UPDATED (IDEA 2): Stores granular timing profiles.
+ * UPDATED: Stores 'trigger', 'execution' stats, 'cost' metrics, and 'forensics'.
  */
 
 const { FieldValue } = require('../utils/utils'); 
@@ -17,9 +16,8 @@ function sanitizeErrorKey(message) {
 
 /**
  * Records a run attempt with detailed metrics and aggregated stats.
- * ADDED: 'triggerReason' param.
  */
-async function recordRunAttempt(db, context, status, error = null, detailedMetrics = { durationMs: 0 }, triggerReason = 'Unknown') {
+async function recordRunAttempt(db, context, status, error = null, detailedMetrics = { durationMs: 0 }, triggerReason = 'Unknown', resourceTier = 'standard') {
     if (!db || !context) return;
 
     const { date: targetDate, computation, pass } = context;
@@ -38,7 +36,6 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
     const anomalies = detailedMetrics.validation?.anomalies || [];
     if (error && error.message && error.message.includes('Data Integrity')) { anomalies.push(error.message); }
 
-    // [IDEA 2] Prepare Execution Stats & Timings
     const rawExecStats = detailedMetrics.execution || {};
     const timings = rawExecStats.timings || {};
 
@@ -52,17 +49,28 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
         durationMs:      detailedMetrics.durationMs || 0,
         status:          status,
         
-        // [NEW] Trigger Context
+        // [NEW] Cost & Resource Analysis
+        resourceTier:    resourceTier, // 'standard' or 'high-mem'
+        peakMemoryMB:    detailedMetrics.peakMemoryMB || 0,
+        
+        // [NEW] IO Operations (for Cost Calc)
+        firestoreOps: {
+            reads:   detailedMetrics.io?.reads   || 0,
+            writes:  detailedMetrics.io?.writes  || 0,
+            deletes: detailedMetrics.io?.deletes || 0
+        },
+
+        // [NEW] Code Linkage (Forensics)
+        composition: detailedMetrics.composition || null,
+
         trigger: {
             reason: triggerReason || 'Unknown', 
             type: (triggerReason && triggerReason.includes('Layer')) ? 'CASCADE' : ((triggerReason && triggerReason.includes('New')) ? 'INIT' : 'UPDATE')
         },
 
-        // [IDEA 2] Enhanced Execution Stats
         executionStats: {
             processedUsers: rawExecStats.processedUsers     || 0,
             skippedUsers:   rawExecStats.skippedUsers       || 0,
-            // Explicitly break out timings for BigQuery/Analysis
             timings: {
                 setupMs:      Math.round(timings.setup      || 0),
                 streamMs:     Math.round(timings.stream     || 0),
@@ -78,7 +86,7 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
         },
 
         anomalies: anomalies,
-        _schemaVersion: '2.2' // Bumped for profiler
+        _schemaVersion: '2.3' // Version Bump for Monitoring
     };
 
     if (error) {
@@ -90,10 +98,12 @@ async function recordRunAttempt(db, context, status, error = null, detailedMetri
         };
     }
 
+    // Aggregated Stats for Quick Dashboarding
     const statsUpdate = {
         lastRunAt: now,
         lastRunStatus: status,
-        totalRuns: FieldValue.increment(1)
+        totalRuns: FieldValue.increment(1),
+        totalCostAccumulated: FieldValue.increment(0) // Placeholder for future cost adder
     };
 
     if (status === 'SUCCESS') { statsUpdate.successCount = FieldValue.increment(1);

package/functions/generic-api/admin-api/index.js

@@ -2,6 +2,7 @@
  * @fileoverview Admin API Router
  * Sub-module for system observability, debugging, and visualization.
  * Mounted at /admin within the Generic API.
+ * UPDATED: Added advanced cost, performance, and live monitoring endpoints.
  */
 
 const express = require('express');
@@ -84,8 +85,6 @@ const createAdminRouter = (config, dependencies, unifiedCalculations) => {
     });
 
     // --- 2. STATUS MATRIX (Calendar / State UI) ---
-    // Returns status of ALL computations across a date range.
-    // ENHANCED: Cross-references Manifest to detect "PENDING" (Not run yet) vs "MISSING".
     router.get('/matrix', async (req, res) => {
         const { start, end } = req.query;
         if (!start || !end) return res.status(400).json({ error: "Start and End dates required." });
@@ -153,7 +152,6 @@ const createAdminRouter = (config, dependencies, unifiedCalculations) => {
     });
 
     // --- 3. PIPELINE STATE (Progress Bar) ---
-    // Shows realtime status of the 5-pass system for a specific date
     router.get('/pipeline/state', async (req, res) => {
         const { date } = req.query;
         if (!date) return res.status(400).json({ error: "Date required" });
@@ -352,7 +350,6 @@ const createAdminRouter = (config, dependencies, unifiedCalculations) => {
     });
 
     // --- 7. FLIGHT RECORDER (Inspection) ---
-    // Existing inspection endpoint kept for drill-down
     router.get('/inspect/:date/:calcName', async (req, res) => {
         const { date, calcName } = req.params;
         try {
@@ -379,6 +376,156 @@ const createAdminRouter = (config, dependencies, unifiedCalculations) => {
         }
     });
 
+    // --- 8. COST & RESOURCE ANALYSIS ---
+    router.get('/analytics/costs', async (req, res) => {
+        const { date, days } = req.query;
+        // Default to today if no date, or range if days provided
+        const targetDate = date || new Date().toISOString().slice(0, 10);
+        
+        // Simple Cost Model (Estimates)
+        const COSTS = {
+            write: 0.18 / 100000,
+            read:  0.06 / 100000,
+            delete: 0.02 / 100000,
+            compute_std_sec:  0.000023, // 1vCPU 2GB (approx)
+            compute_high_sec: 0.000092  // 2vCPU 8GB (approx)
+        };
+
+        try {
+            const auditRef = db.collection('computation_audit_logs');
+            // We scan the 'history' subcollectionGroup for the given date(s)
+            // Note: This can be expensive. In prod, you'd want aggregate counters.
+            const query = db.collectionGroup('history').where('targetDate', '==', targetDate);
+            const snap = await query.get();
+
+            let totalCost = 0;
+            const byPass = {};
+            const byCalc = {};
+
+            snap.forEach(doc => {
+                const data = doc.data();
+                const ops = data.firestoreOps || { reads: 0, writes: 0, deletes: 0 };
+                const durationSec = (data.durationMs || 0) / 1000;
+                const tier = data.resourceTier || 'standard';
+
+                const ioCost = (ops.writes * COSTS.write) + (ops.reads * COSTS.read) + (ops.deletes * COSTS.delete);
+                const computeCost = durationSec * (tier === 'high-mem' ? COSTS.compute_high_sec : COSTS.compute_std_sec);
+                const itemCost = ioCost + computeCost;
+
+                totalCost += itemCost;
+
+                // Aggregations
+                const pass = data.pass || 'unknown';
+                if (!byPass[pass]) byPass[pass] = { cost: 0, runs: 0, duration: 0 };
+                byPass[pass].cost += itemCost;
+                byPass[pass].runs++;
+                byPass[pass].duration += durationSec;
+
+                const calc = data.computationName;
+                if (!byCalc[calc]) byCalc[calc] = { cost: 0, runs: 0, ops: { r:0, w:0 } };
+                byCalc[calc].cost += itemCost;
+                byCalc[calc].runs++;
+                byCalc[calc].ops.r += ops.reads;
+                byCalc[calc].ops.w += ops.writes;
+            });
+
+            // Top 10 Expensive Calcs
+            const topCalcs = Object.entries(byCalc)
+                .sort((a, b) => b[1].cost - a[1].cost)
+                .slice(0, 10)
+                .map(([name, stats]) => ({ name, ...stats }));
+
+            res.json({
+                date: targetDate,
+                totalCostUSD: totalCost,
+                breakdown: {
+                    byPass,
+                    topCalculations: topCalcs
+                },
+                meta: { model: COSTS }
+            });
+
+        } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // --- 9. REROUTE (OOM) ANALYSIS ---
+    router.get('/analytics/reroutes', async (req, res) => {
+        const { date } = req.query;
+        if (!date) return res.status(400).json({ error: "Date required" });
+
+        try {
+            // Find all runs that used high-mem
+            const query = db.collectionGroup('history')
+                .where('targetDate', '==', date)
+                .where('resourceTier', '==', 'high-mem');
+            
+            const snap = await query.get();
+            const reroutes = [];
+
+            snap.forEach(doc => {
+                const data = doc.data();
+                reroutes.push({
+                    computation: data.computationName,
+                    pass: data.pass,
+                    trigger: data.trigger?.reason,
+                    peakMemoryMB: data.peakMemoryMB,
+                    durationMs: data.durationMs,
+                    runId: data.runId
+                });
+            });
+
+            res.json({ count: reroutes.length, reroutes });
+        } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // --- 10. LIVE DASHBOARD (Snapshot) ---
+    // Poll this endpoint to simulate a WebSocket feed
+    router.get('/live/dashboard', async (req, res) => {
+        const today = new Date().toISOString().slice(0, 10);
+        try {
+            // Query the Ledger for Active Tasks
+            // We look at all passes for today
+            const passes = ['1', '2', '3', '4', '5'];
+            const activeTasks = [];
+            const recentFailures = [];
+
+            await Promise.all(passes.map(async (pass) => {
+                const colRef = db.collection(`computation_audit_ledger/${today}/passes/${pass}/tasks`);
+                
+                // Get Running
+                const runningSnap = await colRef.where('status', 'in', ['PENDING', 'IN_PROGRESS']).get();
+                runningSnap.forEach(doc => {
+                    activeTasks.push({ pass, ...doc.data() });
+                });
+
+                // Get Recent Failures (last 10 mins?? hard to query without index, just grab failures)
+                const failSnap = await colRef.where('status', '==', 'FAILED').get();
+                failSnap.forEach(doc => {
+                    recentFailures.push({ pass, ...doc.data() });
+                });
+            }));
+
+            // Get Pipeline Stage (which pass is active?)
+            // We infer this by seeing which pass has pending tasks
+            let currentStage = 'IDLE';
+            for (const p of passes) {
+                const hasActive = activeTasks.some(t => t.pass === p);
+                if (hasActive) { currentStage = `PASS_${p}`; break; }
+            }
+
+            res.json({
+                status: 'success',
+                timestamp: new Date(),
+                pipelineState: currentStage,
+                activeCount: activeTasks.length,
+                failureCount: recentFailures.length,
+                tasks: activeTasks,
+                failures: recentFailures
+            });
+
+        } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
     return router;
 };
 

package/package.json

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