bulltrackers-module 1.0.219 → 1.0.221

package/functions/computation-system/WorkflowOrchestrator.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Main Orchestrator. Coordinates the topological execution of calculations.
+ */
+const { normalizeName, getExpectedDateStrings }            = require('./utils/utils');
+const { checkRootDependencies, checkRootDataAvailability } = require('./data/AvailabilityChecker');
+const { fetchExistingResults }                             = require('./data/DependencyFetcher');
+const { fetchComputationStatus, updateComputationStatus }  = require('./persistence/StatusRepository');
+const { runBatchPriceComputation }                         = require('./executors/PriceBatchExecutor');
+const { StandardExecutor }                                 = require('./executors/StandardExecutor');
+const { MetaExecutor }                                     = require('./executors/MetaExecutor');
+
+const PARALLEL_BATCH_SIZE = 7;
+
+function groupByPass(manifest) { 
+    return manifest.reduce((acc, calc) => { 
+        (acc[calc.pass] = acc[calc.pass] || []).push(calc); 
+        return acc; 
+    }, {}); 
+}
+
+async function runComputationPass(config, dependencies, computationManifest) {
+    const { logger } = dependencies;
+    const passToRun = String(config.COMPUTATION_PASS_TO_RUN);
+    if (!passToRun) return logger.log('ERROR', '[PassRunner] No pass defined. Aborting.');
+
+    logger.log('INFO', `🚀 Starting PASS ${passToRun}...`);
+
+    const earliestDates = {
+        portfolio: new Date('2025-09-25T00:00:00Z'),
+        history:   new Date('2025-11-05T00:00:00Z'),
+        social:    new Date('2025-10-30T00:00:00Z'),
+        insights:  new Date('2025-08-26T00:00:00Z'),
+        price:     new Date('2025-08-01T00:00:00Z')
+    };
+    earliestDates.absoluteEarliest = Object.values(earliestDates).reduce((a, b) => a < b ? a : b);
+    const passes                   = groupByPass(computationManifest);
+    const calcsInThisPass          = passes[passToRun] || [];
+
+    if (!calcsInThisPass.length) return logger.log('WARN', `[PassRunner] No calcs for Pass ${passToRun}. Exiting.`);
+
+    const passEarliestDate = earliestDates.absoluteEarliest;
+    const endDateUTC       = new Date(Date.UTC(new Date().getUTCFullYear(), new Date().getUTCMonth(), new Date().getUTCDate() - 1));
+    const allExpectedDates = getExpectedDateStrings(passEarliestDate, endDateUTC);
+    
+    // Separate specialized batch calcs
+    const priceBatchCalcs           = calcsInThisPass.filter(c => c.type === 'meta' && c.rootDataDependencies?.includes('price'));
+    const standardAndOtherMetaCalcs = calcsInThisPass.filter(c => !priceBatchCalcs.includes(c));
+
+    if (priceBatchCalcs.length > 0) {
+        try { 
+            await runBatchPriceComputation(config, dependencies, allExpectedDates, priceBatchCalcs); 
+        } catch (e) { 
+            logger.log('ERROR', 'Batch Price failed', e); 
+        }
+    }
+
+    if (standardAndOtherMetaCalcs.length === 0) return;
+
+    for (let i = 0; i < allExpectedDates.length; i += PARALLEL_BATCH_SIZE) {
+        const batch = allExpectedDates.slice(i, i + PARALLEL_BATCH_SIZE);
+        await Promise.all(batch.map(dateStr => 
+            runDateComputation(dateStr, passToRun, standardAndOtherMetaCalcs, config, dependencies, computationManifest)
+        ));
+    }
+}
+
+async function runDateComputation(dateStr, passToRun, calcsInThisPass, config, dependencies, computationManifest) {
+    const { logger } = dependencies;
+    const dateToProcess = new Date(dateStr + 'T00:00:00Z');
+    
+    // 1. Version Check
+    const dailyStatus    = await fetchComputationStatus(dateStr, config, dependencies);
+    const calcsToAttempt = [];
+    
+    for (const calc of calcsInThisPass) {
+        const cName = normalizeName(calc.name);
+        const storedStatus = dailyStatus[cName];
+        const currentHash = calc.hash;
+
+        if (calc.dependencies && calc.dependencies.length > 0) { 
+            const missing = calc.dependencies.filter(depName => !dailyStatus[normalizeName(depName)]); 
+            if (missing.length > 0) { 
+                logger.log('TRACE', `[Skip] ${cName} missing deps: ${missing.join(', ')}`);  
+                continue; 
+            } 
+        }
+        if (!storedStatus) { 
+            logger.log('INFO', `[Versioning] ${cName}: New run needed.`); 
+            calcsToAttempt.push(calc); continue; 
+        }
+        if (typeof storedStatus === 'string' && currentHash && storedStatus !== currentHash) { 
+            logger.log('INFO', `[Versioning] ${cName}: Code Changed.`); 
+            calcsToAttempt.push(calc); continue; 
+        }
+        if (storedStatus === true && currentHash) { 
+            logger.log('INFO', `[Versioning] ${cName}: Upgrading legacy status.`); 
+            calcsToAttempt.push(calc); continue; 
+        }
+    }
+
+    if (!calcsToAttempt.length) return null;
+
+    // 2. Data Check
+    const earliestDates = {
+        portfolio: new Date('2025-09-25T00:00:00Z'),
+        history:   new Date('2025-11-05T00:00:00Z'),
+        social:    new Date('2025-10-30T00:00:00Z'),
+        insights:  new Date('2025-08-26T00:00:00Z'),
+        price:     new Date('2025-08-01T00:00:00Z')
+    };
+
+    const rootData = await checkRootDataAvailability(dateStr, config, dependencies, earliestDates);
+    if (!rootData) { logger.log('INFO', `[DateRunner] Root data missing for ${dateStr}. Skipping.`); return null; }
+    
+    const runnableCalcs = calcsToAttempt.filter(c => checkRootDependencies(c, rootData.status).canRun);
+    if (!runnableCalcs.length) return null;
+
+    const standardToRun = runnableCalcs.filter(c => c.type === 'standard');
+    const metaToRun = runnableCalcs.filter(c => c.type === 'meta');
+    logger.log('INFO', `[DateRunner] Running ${dateStr}: ${standardToRun.length} std, ${metaToRun.length} meta`);
+    
+    const dateUpdates = {};
+
+    try {
+        const calcsRunning    = [...standardToRun, ...metaToRun];
+        const existingResults = await fetchExistingResults(dateStr, calcsRunning, computationManifest, config, dependencies, false);
+        const prevDate        = new Date(dateToProcess); prevDate.setUTCDate(prevDate.getUTCDate() - 1);
+        const prevDateStr     = prevDate.toISOString().slice(0, 10);
+        const previousResults = await fetchExistingResults(prevDateStr, calcsRunning, computationManifest, config, dependencies, true);
+
+        if (standardToRun.length) { 
+            const updates = await StandardExecutor.run(dateToProcess, standardToRun, `Pass ${passToRun} (Std)`, config, dependencies, rootData, existingResults, previousResults, false); 
+            Object.assign(dateUpdates, updates); 
+        }
+        if (metaToRun.length) { 
+            const updates = await MetaExecutor.run(dateToProcess, metaToRun, `Pass ${passToRun} (Meta)`, config, dependencies, existingResults, previousResults, rootData, false); 
+            Object.assign(dateUpdates, updates); 
+        }
+
+    } catch (err) {
+        logger.log('ERROR', `[DateRunner] FAILED Pass ${passToRun} for ${dateStr}`, { errorMessage: err.message });
+        [...standardToRun, ...metaToRun].forEach(c => dateUpdates[normalizeName(c.name)] = false);
+        throw err; 
+    }
+
+    if (Object.keys(dateUpdates).length > 0) { 
+        await updateComputationStatus(dateStr, dateUpdates, config, dependencies); 
+    }
+
+    return { date: dateStr, updates: dateUpdates };
+}
+
+module.exports = { runComputationPass, runDateComputation, groupByPass };

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

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Factory for creating the Computation Context.
+ */
+const mathLayer          = require('../layers/index');
+const { LEGACY_MAPPING } = require('../topology/HashManager');
+
+class ContextFactory { 
+    static buildMathContext() {
+        const mathContext = {};
+        for (const [key, value] of Object.entries(mathLayer)) { 
+            mathContext[key] = value; 
+            const legacyKey = LEGACY_MAPPING[key]; 
+            if (legacyKey) { mathContext[legacyKey] = value; } 
+        }
+        return mathContext;
+    }
+
+    static buildPerUserContext(options) {
+        const { 
+            todayPortfolio, yesterdayPortfolio, todayHistory, yesterdayHistory, 
+            userId, userType, dateStr, metadata, mappings, insights, socialData, 
+            computedDependencies, previousComputedDependencies, config, deps 
+        } = options;
+        
+        return {
+            user: { 
+                id: userId, 
+                type: userType, 
+                portfolio: { today: todayPortfolio, yesterday: yesterdayPortfolio }, 
+                history: { today: todayHistory, yesterday: yesterdayHistory } 
+            },
+            date: { today: dateStr },
+            insights: { today: insights?.today, yesterday: insights?.yesterday },
+            social: { today: socialData?.today, yesterday: socialData?.yesterday },
+            mappings: mappings || {},
+            math: ContextFactory.buildMathContext(), 
+            computed: computedDependencies || {},
+            previousComputed: previousComputedDependencies || {},
+            meta: metadata, config, deps
+        };
+    }
+
+    static buildMetaContext(options) {
+        const { 
+            dateStr, metadata, mappings, insights, socialData, prices, 
+            computedDependencies, previousComputedDependencies, config, deps 
+        } = options;
+        
+        return {
+            date: { today: dateStr },
+            insights: { today: insights?.today, yesterday: insights?.yesterday },
+            social: { today: socialData?.today, yesterday: socialData?.yesterday },
+            prices: prices || {},
+            mappings: mappings || {},
+            math: ContextFactory.buildMathContext(), 
+            computed: computedDependencies || {},
+            previousComputed: previousComputedDependencies || {},
+            meta: metadata, config, deps
+        };
+    }
+}
+
+module.exports = { ContextFactory };

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

@@ -0,0 +1,240 @@
+/**
+ * @fileoverview Dynamic Manifest Builder - Handles Topological Sort and Auto-Discovery.
+ */
+const { generateCodeHash, LEGACY_MAPPING } = require('../topology/HashManager.js');
+const { normalizeName }                    = require('../utils/utils');
+
+// Import Layers
+const MathematicsLayer = require('../layers/mathematics');
+const ExtractorsLayer  = require('../layers/extractors');
+const ProfilingLayer   = require('../layers/profiling');
+const ValidatorsLayer  = require('../layers/validators');
+
+const LAYER_GROUPS = {
+    'mathematics': MathematicsLayer,
+    'extractors':  ExtractorsLayer,
+    'profiling':   ProfilingLayer,
+    'validators':  ValidatorsLayer
+};
+
+function generateLayerHashes(layerExports, layerName) {
+    const hashes = {};
+    const keys = Object.keys(layerExports).sort(); 
+    for (const key of keys) {
+        const item = layerExports[key];
+        let source = `LAYER:${layerName}:EXPORT:${key}`;
+        if (typeof item === 'function') source += item.toString();
+        else if (typeof item === 'object' && item !== null) source += JSON.stringify(item);
+        else source += String(item);
+        hashes[key] = generateCodeHash(source);
+    }
+    return hashes;
+}
+
+function buildDynamicTriggers() {
+    const triggers = {};
+    for (const [layerName, layerExports] of Object.entries(LAYER_GROUPS)) {
+        triggers[layerName] = {};
+        for (const exportName of Object.keys(layerExports)) {
+            const patterns = [];
+            patterns.push(exportName);
+            const alias = LEGACY_MAPPING[exportName];
+            if (alias) {
+                patterns.push(`math.${alias}`);
+                patterns.push(`${alias}.`);
+            }
+            triggers[layerName][exportName] = patterns;
+        }
+    }
+    return triggers;
+}
+
+const LAYER_HASHES = {};
+for (const [name, exports] of Object.entries(LAYER_GROUPS)) {
+    LAYER_HASHES[name] = generateLayerHashes(exports, name);
+}
+const LAYER_TRIGGERS = buildDynamicTriggers();
+
+const log = {
+    info: (msg) => console.log('ℹ︎ ' + msg),
+    step: (msg) => console.log('› ' + msg),
+    warn: (msg) => console.warn('⚠︎ ' + msg),
+    success: (msg) => console.log('✔︎ ' + msg),
+    error: (msg) => console.error('✖ ' + msg),
+    fatal: (msg) => { console.error('✖ FATAL ✖ ' + msg); console.error('✖ FATAL ✖ Manifest build FAILED.'); },
+    divider: (label) => { const line = ''.padEnd(60, '─'); console.log(`\n${line}\n${label}\n${line}\n`); },
+};
+
+function getDependencySet(endpoints, adjacencyList) {
+    const required = new Set(endpoints);
+    const queue = [...endpoints];
+    while (queue.length > 0) { 
+        const calcName = queue.shift(); 
+        const dependencies = adjacencyList.get(calcName);
+        if (dependencies) { 
+            for (const dep of dependencies) { 
+                if (!required.has(dep)) { required.add(dep); queue.push(dep); } 
+            } 
+        } 
+    }
+    return required;
+}
+
+function buildManifest(productLinesToRun = [], calculations) {
+    log.divider('Building Dynamic Manifest');
+    
+    const manifestMap = new Map();
+    const adjacency = new Map(); 
+    const reverseAdjacency = new Map(); 
+    const inDegree = new Map();
+    let hasFatalError = false;
+    
+    function processCalc(Class, name, folderName) {
+        if (!Class || typeof Class !== 'function') return;
+        const normalizedName = normalizeName(name);
+        
+        if (typeof Class.getMetadata     !== 'function') { log.fatal(`Calculation "${normalizedName}" missing static getMetadata().`);     hasFatalError = true; return; }
+        if (typeof Class.getDependencies !== 'function') { log.fatal(`Calculation "${normalizedName}" missing static getDependencies().`); hasFatalError = true; return; }
+        
+        const metadata     = Class.getMetadata();
+        const dependencies = Class.getDependencies().map(normalizeName);
+        const codeStr      = Class.toString();
+        
+        let compositeHashString = generateCodeHash(codeStr); 
+        const usedDeps = [];
+
+        for (const [layerName, exportsMap] of Object.entries(LAYER_TRIGGERS)) {
+            const layerHashes = LAYER_HASHES[layerName];
+            for (const [exportName, triggers] of Object.entries(exportsMap)) {
+                if (triggers.some(trigger => codeStr.includes(trigger))) {
+                    const exportHash = layerHashes[exportName];
+                    if (exportHash) {
+                        compositeHashString += exportHash;
+                        usedDeps.push(`${layerName}.${exportName}`);
+                    }
+                }
+            }
+        }
+        
+        // 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); }); 
+        }
+
+        const baseHash = generateCodeHash(compositeHashString);
+
+        const manifestEntry = {
+            name: normalizedName,
+            class: Class,
+            category: folderName === 'core' && metadata.category ? metadata.category : folderName,     
+            sourcePackage: folderName,   
+            type: metadata.type,
+            isHistorical: metadata.isHistorical, 
+            rootDataDependencies: metadata.rootDataDependencies || [],
+            userType: metadata.userType,
+            dependencies: dependencies,
+            pass: 0,
+            hash: baseHash,
+            debugUsedLayers: isSafeMode ? ['ALL (Safe Mode)'] : usedDeps
+        };
+        
+        manifestMap.set(normalizedName, manifestEntry);
+        adjacency.set(normalizedName, dependencies);
+        inDegree.set(normalizedName, dependencies.length);
+        dependencies.forEach(dep => { if (!reverseAdjacency.has(dep)) reverseAdjacency.set(dep, []); reverseAdjacency.get(dep).push(normalizedName); }); 
+    }
+    
+    for (const folderName in calculations) {
+        if (folderName === 'legacy') continue;
+        const group = calculations[folderName];
+        for (const key in group) {
+            const entry = group[key];
+            if (typeof entry === 'function') { processCalc(entry, key, folderName); } 
+        } 
+    }
+
+    if (hasFatalError) throw new Error('Manifest build failed due to missing static methods.');
+    log.success(`Loaded ${manifestMap.size} calculations.`);
+
+    // --- Topological Sort & Product Line Filtering ---
+    const allNames = new Set(manifestMap.keys());
+    for (const [name, entry] of manifestMap) {
+        for (const dep of entry.dependencies) {
+            if (!allNames.has(dep)) log.error(`${name} depends on unknown calculation "${dep}"`);
+        }
+    }
+
+    const productLineEndpoints = [];
+    for (const [name, entry] of manifestMap.entries()) {  
+        if (productLinesToRun.includes(entry.category) || entry.sourcePackage === 'core') { 
+            productLineEndpoints.push(name); 
+        }  
+    }
+
+    const requiredCalcs = getDependencySet(productLineEndpoints, adjacency);
+    log.info(`Filtered down to ${requiredCalcs.size} active calculations.`);
+
+    const filteredManifestMap = new Map();
+    const filteredInDegree = new Map();
+    const filteredReverseAdjacency = new Map();
+
+    for (const name of requiredCalcs) { 
+        filteredManifestMap.set(name, manifestMap.get(name)); 
+        filteredInDegree.set(name, inDegree.get(name));
+        const consumers = (reverseAdjacency.get(name) || []).filter(consumer => requiredCalcs.has(consumer)); 
+        filteredReverseAdjacency.set(name, consumers); 
+    }
+
+    const sortedManifest = [];
+    const queue = [];
+    let maxPass = 0;
+
+    for (const [name, degree] of filteredInDegree) { 
+        if (degree === 0) { queue.push(name); filteredManifestMap.get(name).pass = 1; maxPass = 1; } 
+    }
+    queue.sort();
+    
+    while (queue.length) {
+        const currentName = queue.shift();
+        const currentEntry = filteredManifestMap.get(currentName);
+        sortedManifest.push(currentEntry);
+        
+        for (const neighborName of (filteredReverseAdjacency.get(currentName) || [])) { 
+            const newDegree = filteredInDegree.get(neighborName) - 1; 
+            filteredInDegree.set(neighborName, newDegree);
+            const neighborEntry = filteredManifestMap.get(neighborName);
+            if (neighborEntry.pass <= currentEntry.pass) { 
+                neighborEntry.pass = currentEntry.pass + 1; 
+                if (neighborEntry.pass > maxPass) maxPass = neighborEntry.pass; 
+            }
+            if (newDegree === 0) queue.push(neighborName); 
+        }
+        queue.sort(); 
+    }
+
+    if (sortedManifest.length !== filteredManifestMap.size) throw new Error('Circular dependency detected.');
+
+    // --- Cascading Hash (Phase 2) ---
+    for (const entry of sortedManifest) {
+        let dependencySignature = entry.hash;
+        if (entry.dependencies && entry.dependencies.length > 0) {
+            const depHashes = entry.dependencies.map(depName => { 
+                const depEntry = filteredManifestMap.get(depName); 
+                return depEntry ? depEntry.hash : ''; 
+            }).join('|'); 
+            dependencySignature += `|DEPS:${depHashes}`;
+        }
+        entry.hash = generateCodeHash(dependencySignature);
+    }
+
+    return sortedManifest;
+}
+
+function build(productLinesToRun, calculations) {
+    try { return buildManifest(productLinesToRun, calculations); } 
+    catch (error) { log.error(error.message); return null; }
+}
+
+module.exports = { build };

package/functions/computation-system/controllers/computation_controller.js

@@ -1,6 +1,6 @@
 /**
  * FIXED: computation_controller.js
- * V5.0: Dynamic Layer Loading via Barrel File
+ * V5.1: Exports LEGACY_MAPPING for Manifest Builder
  */
 
 // Load all layers dynamically from the index
@@ -21,7 +21,13 @@ const LEGACY_MAPPING = {
     TimeSeries: 'TimeSeries',
     priceExtractor: 'priceExtractor',
     InsightsExtractor: 'insights',
-    UserClassifier: 'classifier'
+    UserClassifier: 'classifier',
+    // Added based on your profiling.js file:
+    Psychometrics: 'psychometrics',
+    CognitiveBiases: 'bias',
+    SkillAttribution: 'skill',
+    ExecutionAnalytics: 'execution',
+    AdaptiveAnalytics: 'adaptive'
 };
 
 class DataLoader {
@@ -41,7 +47,7 @@ class ContextBuilder {
         for (const [key, value] of Object.entries(mathLayer)) { mathContext[key] = value; const legacyKey = LEGACY_MAPPING[key]; if (legacyKey) { mathContext[legacyKey] = value; } }
         return mathContext;
     }
-
+    // ... (rest of class remains identical)
     static buildPerUserContext(options) {
         const { todayPortfolio, yesterdayPortfolio, todayHistory, yesterdayHistory, userId, userType, dateStr, metadata, mappings, insights, socialData, computedDependencies, previousComputedDependencies, config, deps } = options;
         return {
@@ -74,6 +80,7 @@ class ContextBuilder {
 }
 
 class ComputationExecutor {
+    // ... (remains identical to previous version)
     constructor(config, dependencies, dataLoader) {
         this.config = config;
         this.deps   = dependencies;
@@ -139,4 +146,5 @@ class ComputationController {
     }
 }
 
-module.exports = { ComputationController };
+// EXPORT LEGACY_MAPPING SO BUILDER CAN USE IT
+module.exports = { ComputationController, LEGACY_MAPPING };

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

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Checks availability of root data (Portfolios, Prices, etc).
+ */
+const { 
+    getPortfolioPartRefs, 
+    loadDailyInsights, 
+    loadDailySocialPostInsights, 
+    getHistoryPartRefs 
+} = require('../utils/data_loader');
+
+function checkRootDependencies(calcManifest, rootDataStatus) {
+    const missing = [];
+    if (!calcManifest.rootDataDependencies) return { canRun: true, missing };
+    for (const dep of calcManifest.rootDataDependencies) {
+        if (dep === 'portfolio'     && !rootDataStatus.hasPortfolio) missing.push('portfolio');
+        else if (dep === 'insights' && !rootDataStatus.hasInsights)  missing.push('insights');
+        else if (dep === 'social'   && !rootDataStatus.hasSocial)    missing.push('social');
+        else if (dep === 'history'  && !rootDataStatus.hasHistory)   missing.push('history');
+        else if (dep === 'price'    && !rootDataStatus.hasPrices)    missing.push('price');
+    }
+    return { canRun: missing.length === 0, missing };
+}
+
+async function checkRootDataAvailability(dateStr, config, dependencies, earliestDates) {
+    const { logger } = dependencies;
+    const dateToProcess = new Date(dateStr + 'T00:00:00Z');
+    let portfolioRefs = [], historyRefs = [];
+    let hasPortfolio = false, hasInsights = false, hasSocial = false, hasHistory = false, hasPrices = false;
+    let insightsData = null, socialData = null;
+
+    try {
+        const tasks = [];
+        if (dateToProcess >= earliestDates.portfolio) {
+            tasks.push(getPortfolioPartRefs(config, dependencies, dateStr).then(r => { portfolioRefs = r; hasPortfolio = !!r.length; }));
+        }
+        if (dateToProcess >= earliestDates.insights) {
+            tasks.push(loadDailyInsights(config, dependencies, dateStr).then(r => { insightsData = r; hasInsights = !!r; }));
+        }
+        if (dateToProcess >= earliestDates.social) {
+            tasks.push(loadDailySocialPostInsights(config, dependencies, dateStr).then(r => { socialData = r; hasSocial = !!r; }));
+        }
+        if (dateToProcess >= earliestDates.history) {
+            tasks.push(getHistoryPartRefs(config, dependencies, dateStr).then(r => { historyRefs = r; hasHistory = !!r.length; }));
+        }
+        if (dateToProcess >= earliestDates.price) {   
+            tasks.push(checkPriceDataAvailability(config, dependencies).then(r => { hasPrices = r; })); 
+        }
+
+        await Promise.all(tasks);
+
+        if (!(hasPortfolio || hasInsights || hasSocial || hasHistory || hasPrices)) return null;
+
+        return { 
+            portfolioRefs, 
+            historyRefs, 
+            todayInsights: insightsData, 
+            todaySocialPostInsights: socialData, 
+            status: { hasPortfolio, hasInsights, hasSocial, hasHistory, hasPrices }, 
+            yesterdayPortfolioRefs: null // Filled later if needed
+        };
+    } catch (err) { 
+        logger.log('ERROR', `Error checking data: ${err.message}`); 
+        return null; 
+    }
+}
+
+async function checkPriceDataAvailability(config, { db }) { 
+    try { 
+        const collection = config.priceCollection || 'asset_prices';
+        const snapshot = await db.collection(collection).limit(1).get(); 
+        return !snapshot.empty; 
+    } catch (e) { return false; } 
+}
+
+module.exports = { checkRootDependencies, checkRootDataAvailability };

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

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Execution-scoped data loader with caching.
+ */
+const { 
+    loadDailyInsights, 
+    loadDailySocialPostInsights, 
+    getRelevantShardRefs, 
+    getPriceShardRefs 
+} = require('../utils/data_loader');
+
+class CachedDataLoader {
+    constructor(config, dependencies) { 
+        this.config = config; 
+        this.deps = dependencies; 
+        this.cache = { 
+            mappings: null, 
+            insights: new Map(), 
+            social:   new Map()
+        }; 
+    }
+
+    async loadMappings() { 
+        if (this.cache.mappings) return this.cache.mappings; 
+        const { calculationUtils } = this.deps; 
+        this.cache.mappings = await calculationUtils.loadInstrumentMappings(); 
+        return this.cache.mappings; 
+    }
+
+    async loadInsights(dateStr) { 
+        if (this.cache.insights.has(dateStr)) return this.cache.insights.get(dateStr); 
+        const insights = await loadDailyInsights(this.config, this.deps, dateStr); 
+        this.cache.insights.set(dateStr, insights); 
+        return insights; 
+    }
+
+    async loadSocial(dateStr) { 
+        if (this.cache.social.has(dateStr)) return this.cache.social.get(dateStr); 
+        const social = await loadDailySocialPostInsights(this.config, this.deps, dateStr); 
+        this.cache.social.set(dateStr, social); 
+        return social; 
+    }
+
+    async getPriceShardReferences() { 
+        return getPriceShardRefs(this.config, this.deps); 
+    }
+
+    async getSpecificPriceShardReferences(targetInstrumentIds) { 
+        return getRelevantShardRefs(this.config, this.deps, targetInstrumentIds); 
+    }
+
+    async loadPriceShard(docRef) { 
+        try { 
+            const snap = await docRef.get(); 
+            if (!snap.exists) return {}; 
+            return snap.data(); 
+        } catch (e) { 
+            console.error(`Error loading shard ${docRef.path}:`, e); 
+            return {}; 
+        } 
+    }
+}
+
+module.exports = { CachedDataLoader };