bulltrackers-module 1.0.295 → 1.0.297

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);