bulltrackers-module 1.0.211 → 1.0.213

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

@@ -1,284 +1,328 @@
-/**
- * @fileoverview
- * Dynamic Manifest Builder (v3 - Refactored)
- *
- * This script builds the computation manifest dynamically by introspecting all
- * calculation classes from the new product-line structure (core, gem, gauss, etc.).
- * It validates metadata, resolves dependencies, and performs a topological sort
- * to determine execution passes.
- *
- * UPDATED LOGIC:
- * - Core Computations: Metadata 'category' determines the output path/grouping.
- * - Product Lines: Folder name STRICTLY determines the category (metadata ignored).
- */
-
-/* --------------------------------------------------
- * Pretty Console Helpers
- * -------------------------------------------------- */
-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`); },
-};
-
-/* --------------------------------------------------
- * Helper Utilities
- * -------------------------------------------------- */
-
-const normalizeName = (name) => { if (typeof name !== 'string') return name; return name.trim().replace(/,$/, '').replace(/_/g, '-').toLowerCase(); };
-
-/**
- * Finds the closest string matches for a typo.
- */
-function suggestClosest(name, candidates, n = 3) {
-    const levenshtein = (a = '', b = '') => {
-        const m = a.length, n = b.length;
-        if (!m) return n; if (!n) return m;
-        const dp = Array.from({ length: m + 1 }, (_, i) => Array(n + 1).fill(i));
-        for (let j = 0; j <= n; j++) dp[0][j] = j;
-        for (let i = 1; i <= m; i++)
-        for (let j = 1; j <= n; j++)
-        dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : Math.min(dp[i - 1][j - 1], dp[i][j - 1], dp[i - 1][j]) + 1;
-        return dp[m][n];
-    };
-    const scores = candidates.map(c => [c, levenshtein(name, c)]);
-    scores.sort((a, b)              => a[1] - b[1]);
-    return scores.slice(0, n).map(s => s[0]);
-}
-
-/**
- * Checks for a cycle using Depth First Search.
- */
-function findCycles(manifestMap, adjacencyList) {
-    const visited = new Set(), stack = new Set(), cycles = [];
-    const dfs = (node, path) => {
-        if (stack.has(node)) { const idx = path.indexOf(node); cycles.push([...path.slice(idx), node]); return; }
-        if (visited.has(node)) return;
-        visited.add(node); stack.add(node);
-        for (const nb of adjacencyList.get(node) || []) dfs(nb, [...path, nb]);
-        stack.delete(node); };
-    for (const name of manifestMap.keys()) dfs(name, [name]);
-    return cycles;
-}
-
-/**
- * Recursively traces all dependencies for a given set of "endpoint" calcs.
- */
-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;
-}
-
-/* --------------------------------------------------
- * Core Manifest Builder
- * -------------------------------------------------- */
-
-/**
- * Builds the full computation manifest.
- * @param {string[]} productLinesToRun - Array of product line categories (folder names) to build for.
- * @param {object} calculations - The injected calculations object from the main application.
- * @returns {object[]} The final sorted manifest array.
- */
-function buildManifest(productLinesToRun = [], calculations) {
-    log.divider('Building Dynamic Manifest');
-    log.info(`Target Product Lines: [${productLinesToRun.join(', ')}]`);
-    const manifestMap      = new Map();
-    const adjacency        = new Map(); 
-    const reverseAdjacency = new Map(); 
-    const inDegree         = new Map();
-    let hasFatalError      = false;
-    
-    /* ---------------- 1. Load All Calculations ---------------- */
-    log.step('Loading and validating all calculation classes…');
-    const allCalculationClasses = new Map();
-
-    /**
-     * Processes a single calculation class, validates it, and adds to maps.
-     * @param {Class} Class - The calculation class structure.
-     * @param {string} name - The filename/key.
-     * @param {string} folderName - The folder this file came from (e.g. 'core', 'gem').
-     */
-    function processCalc(Class, name, folderName) {
-        if (!Class || typeof Class !== 'function') return;
-        const normalizedName = normalizeName(name);
-        allCalculationClasses.set(normalizedName, Class);
-        
-        // --- RULE 1: Check for static getMetadata() ---
-        if (typeof Class.getMetadata !== 'function') { log.fatal(`Calculation "${normalizedName}" is missing the static getMetadata() method. Build FAILED.`); hasFatalError = true; return; }
-        // --- RULE 2: Check for static getDependencies() ---
-        if (typeof Class.getDependencies !== 'function') { log.fatal(`Calculation "${normalizedName}" is missing the static getDependencies() method. Build FAILED.`); hasFatalError = true;return; }
-        // --- RULE 3: Check for static getSchema() ---
-        if (typeof Class.getSchema !== 'function') {log.warn(`Calculation "${normalizedName}" is missing the static getSchema() method. (Recommended)`); }
-        
-        const metadata     = Class.getMetadata();
-        const dependencies = Class.getDependencies().map(normalizeName);
-        
-        // --- RULE 4: Check for isHistorical mismatch ---
-        if (metadata.isHistorical === true && !Class.toString().includes('yesterday')) { 
-            log.warn(`Calculation "${normalizedName}" is marked 'isHistorical: true' but does not seem to reference 'yesterday' data.`); 
-        }
-
-        // --- RULE 5: Category Enforcement Logic ---
-        let finalCategory = folderName; // Default to folder name
-
-        if (folderName === 'core') {
-            // For CORE: We respect metadata.category if it exists. 
-            // This allows core computations to write to specific output paths (e.g. 'market_stats').
-            if (metadata.category) {
-                finalCategory = metadata.category;
-            }
-        } else {
-            // For PRODUCT LINES: We IGNORE metadata.category and enforce the folder name.
-            // This ensures product lines always group correctly regardless of typos in metadata.
-            finalCategory = folderName;
-        }
-
-        const manifestEntry = {
-            name: normalizedName,
-            class: Class,
-            category: finalCategory,     // The logic category / output path
-            sourcePackage: folderName,   // The physical source folder (used for "Core Always Run" checks)
-            type: metadata.type,
-            isHistorical: metadata.isHistorical, 
-            rootDataDependencies: metadata.rootDataDependencies || [],
-            userType: metadata.userType,
-            dependencies: dependencies,
-            pass: 0,
-        };
-        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); }); 
-    }
-    
-    if (!calculations || typeof calculations !== 'object') {
-        log.fatal('Calculations object was not provided or is invalid.');
-        throw new Error('Manifest build failed: Invalid calculations object.');
-    }
-
-    // Iterate over folders (folderName becomes the default category)
-    for (const folderName in calculations) {
-        if (folderName === 'legacy') { log.info('Skipping "legacy" calculations package.'); 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 in calculations.'); }
-    log.success(`Loaded and validated ${manifestMap.size} total calculations.`);
-
-    /* ---------------- 2. Validate Dependency Links ---------------- */
-    log.divider('Validating Dependency Links');
-    const allNames = new Set(manifestMap.keys());
-    let invalidLinks = false;
-    for (const [name, entry] of manifestMap) {
-        for (const dep of entry.dependencies) {
-            if (!allNames.has(dep)) {
-                invalidLinks = true;
-                const guesses = suggestClosest(dep, Array.from(allNames));
-                log.error(`${name} depends on unknown calculation "${dep}"`);
-                if (guesses.length) log.info(`Did you mean: ${guesses.join(', ')} ?`);
-            }
-            if (dep === name) {
-                invalidLinks = true;
-                log.error(`${name} has a circular dependency on *itself*!`);
-            }
-        }
-    }
-    if (invalidLinks) { throw new Error('Manifest validation failed. Fix missing or self-referencing dependencies.'); }
-    log.success('All dependency links are valid.');
-
-    /* ---------------- 3. Filter for Product Lines ---------------- */
-    log.divider('Filtering by Product Line');
-    
-    // 1. Find all "endpoint" calculations in the target product lines.
-    // This checks the assigned category (which now matches the folder for all non-core lines).
-    const productLineEndpoints = [];
-    for (const [name, entry] of manifestMap.entries()) { 
-        if (productLinesToRun.includes(entry.category)) { 
-            productLineEndpoints.push(name); 
-        } 
-    }
-
-    // 2. Add 'core' calculations as they are always included.
-    // We check 'sourcePackage' here so that even if a core calculation has a custom category
-    // (like 'market_stats'), it is still recognized as Core and included.
-    for (const [name, entry] of manifestMap.entries()) { 
-        if (entry.sourcePackage === 'core') { 
-            productLineEndpoints.push(name); 
-        } 
-    }
-
-    // 3. Trace all dependencies upwards from these endpoints.
-    const requiredCalcs = getDependencySet(productLineEndpoints, adjacency);
-    log.info(`Identified ${productLineEndpoints.length} endpoint/core calculations.`);
-    log.info(`Traced dependencies: ${requiredCalcs.size} total calculations are required.`);
-
-    // 4. Create the final, filtered maps for sorting.
-    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); }
-    log.success(`Filtered manifest to ${filteredManifestMap.size} calculations.`);
-
-    /* ---------------- 4. Topological Sort (Kahn's Algorithm) ---------------- */
-    log.divider('Topological Sorting (Kahn\'s Algorithm)');
-    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) {
-        log.divider('Circular Dependency Detected');
-        const cycles = findCycles(filteredManifestMap, adjacency);
-        for (const c of cycles) log.error('Cycle: ' + c.join(' → '));
-        throw new Error('Circular dependency detected. Manifest build failed.'); }
-
-    /* ---------------- 5. Summary ---------------- */
-    log.divider('Manifest Summary');
-    log.success(`Total calculations in build: ${sortedManifest.length}`);
-    log.success(`Total passes required: ${maxPass}\n`);
-    const grouped = [...sortedManifest.reduce((m, e) => { if (!m.has(e.pass)) m.set(e.pass, []); m.get(e.pass).push(e); return m; }, new Map())].sort((a, b) => a[0] - b[0]);
-    for (const [pass, list] of grouped) { console.log(`Pass ${pass} (${list.length} calcs):`); console.log('  ' + list.map(l => l.name).join(', ')); }
-    log.divider('Build Complete');
-    return sortedManifest;
-}
-
-/**
- * Main entry point for building and exporting the manifest.
- * @param {string[]} productLinesToRun - Array of product line categories (folder names) to build for.
- * @param {object} calculations - The injected calculations object.
- */
-function build(productLinesToRun, calculations) {
-    try {
-        const manifest = buildManifest(productLinesToRun, calculations);
-        return manifest; // Returns the array
-    } catch (error) { 
-        log.error(error.message); 
-        return null; 
-    }
-}
-
+/**
+ * @fileoverview
+ * Dynamic Manifest Builder (v5.1 - Smart Hashing with Safe Mode)
+ *
+ * This script builds the computation manifest and generates a "Smart Hash"
+ * for each calculation.
+ *
+ * KEY FEATURE:
+ * It performs static analysis on the calculation code to detect which
+ * specific math layers it utilizes. It then combines the calculation's own
+ * code hash with the current hashes of those specific layers.
+ * * SAFE MODE:
+ * If a calculation uses no detectable layer keywords, it defaults to
+ * depending on ALL layers to prevent staleness.
+ * * FIXED:
+ * - Broadened LAYER_TRIGGERS to detect context usage (e.g. 'math.signals')
+ * - Updated isHistorical check to look for 'previousComputed'
+ */
+
+const { generateCodeHash } = require('../utils/utils');
+
+// 1. Import Layers directly to generate their "State Hashes"
+// We import them individually to hash them as distinct domains.
+const MathematicsLayer = require('../layers/mathematics');
+const ExtractorsLayer  = require('../layers/extractors');
+const ProfilingLayer   = require('../layers/profiling');
+const ValidatorsLayer  = require('../layers/validators');
+
+/* --------------------------------------------------
+ * 1. Layer Hash Generation
+ * -------------------------------------------------- */
+
+/**
+ * Generates a single hash representing the entire state of a layer module.
+ * Combines all exported classes/functions/objects into one deterministic string.
+ */
+function generateLayerHash(layerExports, layerName) {
+    const keys = Object.keys(layerExports).sort(); // Sort for determinism
+    let combinedSource = `LAYER:${layerName}`;
+
+    for (const key of keys) {
+        const item = layerExports[key];
+        if (typeof item === 'function') {
+            combinedSource += item.toString();
+        } else if (typeof item === 'object' && item !== null) {
+            combinedSource += JSON.stringify(item);
+        } else {
+            combinedSource += String(item);
+        }
+    }
+    return generateCodeHash(combinedSource);
+}
+
+// Pre-compute layer hashes at startup
+const LAYER_HASHES = {
+    'mathematics': generateLayerHash(MathematicsLayer, 'mathematics'),
+    'extractors':  generateLayerHash(ExtractorsLayer, 'extractors'),
+    'profiling':   generateLayerHash(ProfilingLayer, 'profiling'),
+    'validators':  generateLayerHash(ValidatorsLayer, 'validators')
+};
+
+// Map code patterns to Layer dependencies
+// If a calculation's code contains these strings, it depends on that layer.
+const LAYER_TRIGGERS = {
+    'mathematics': [
+        'math.compute', 'MathPrimitives',
+        'math.signals', 'SignalPrimitives', 'signals.',
+        'math.aggregate', 'Aggregators',
+        'math.timeseries', 'TimeSeries', 'timeSeries.',
+        'math.distribution', 'DistributionAnalytics', 'distribution.',
+        'math.financial', 'FinancialEngineering'
+    ],
+    'extractors': [
+        'math.extract', 'DataExtractor',
+        'math.history', 'HistoryExtractor',
+        'math.prices', 'priceExtractor',
+        'math.insights', 'InsightsExtractor', 'insights.',
+        'math.tradeSeries', 'TradeSeriesBuilder'
+    ],
+    'profiling': [
+        'math.profiling', 'SCHEMAS',
+        'math.classifier', 'UserClassifier',
+        'math.psychometrics', 'Psychometrics',
+        'math.bias', 'CognitiveBiases',
+        'math.skill', 'SkillAttribution'
+    ],
+    'validators': [
+        'math.validate', 'Validators'
+    ]
+};
+
+/* --------------------------------------------------
+ * Pretty Console Helpers
+ * -------------------------------------------------- */
+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`); },
+};
+
+/* --------------------------------------------------
+ * Helper Utilities
+ * -------------------------------------------------- */
+
+const normalizeName = (name) => { if (typeof name !== 'string') return name; return name.trim().replace(/,$/, '').replace(/_/g, '-').toLowerCase(); };
+
+function suggestClosest(name, candidates, n = 3) {
+    const levenshtein = (a = '', b = '') => {
+        const m = a.length, n = b.length;
+        if (!m) return n; if (!n) return m;
+        const dp = Array.from({ length: m + 1 }, (_, i) => Array(n + 1).fill(i));
+        for (let j = 0; j <= n; j++) dp[0][j] = j;
+        for (let i = 1; i <= m; i++)
+        for (let j = 1; j <= n; j++)
+        dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : Math.min(dp[i - 1][j - 1], dp[i][j - 1], dp[i - 1][j]) + 1;
+        return dp[m][n];
+    };
+    const scores = candidates.map(c => [c, levenshtein(name, c)]);
+    scores.sort((a, b)              => a[1] - b[1]);
+    return scores.slice(0, n).map(s => s[0]);
+}
+
+function findCycles(manifestMap, adjacencyList) {
+    const visited = new Set(), stack = new Set(), cycles = [];
+    const dfs = (node, path) => {
+        if (stack.has(node)) { const idx = path.indexOf(node); cycles.push([...path.slice(idx), node]); return; }
+        if (visited.has(node)) return;
+        visited.add(node); stack.add(node);
+        for (const nb of adjacencyList.get(node) || []) dfs(nb, [...path, nb]);
+        stack.delete(node); };
+    for (const name of manifestMap.keys()) dfs(name, [name]);
+    return cycles;
+}
+
+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;
+}
+
+/* --------------------------------------------------
+ * Core Manifest Builder
+ * -------------------------------------------------- */
+
+function buildManifest(productLinesToRun = [], calculations) {
+    log.divider('Building Dynamic Manifest (Smart Hashing)');
+    log.info(`Target Product Lines: [${productLinesToRun.join(', ')}]`);
+    log.info(`Layer Hashes Initialized: ${Object.keys(LAYER_HASHES).join(', ')}`);
+
+    const manifestMap      = new Map();
+    const adjacency        = new Map(); 
+    const reverseAdjacency = new Map(); 
+    const inDegree         = new Map();
+    let hasFatalError      = false;
+    
+    /* ---------------- 1. Load All Calculations ---------------- */
+    log.step('Loading and validating all calculation classes…');
+    const allCalculationClasses = new Map();
+
+    function processCalc(Class, name, folderName) {
+        if (!Class || typeof Class !== 'function') return;
+        const normalizedName = normalizeName(name);
+        allCalculationClasses.set(normalizedName, Class);
+        
+        if (typeof Class.getMetadata !== 'function') { log.fatal(`Calculation "${normalizedName}" is missing static getMetadata().`); hasFatalError = true; return; }
+        if (typeof Class.getDependencies !== 'function') { log.fatal(`Calculation "${normalizedName}" is missing static getDependencies().`); hasFatalError = true;return; }
+        
+        const metadata     = Class.getMetadata();
+        const dependencies = Class.getDependencies().map(normalizeName);
+        
+        // FIX: Updated check to include 'previousComputed'
+        const codeStr = Class.toString();
+        if (metadata.isHistorical === true && !codeStr.includes('yesterday') && !codeStr.includes('previousComputed')) { 
+            log.warn(`Calculation "${normalizedName}" marked 'isHistorical' but no 'previousComputed' or 'yesterday' reference found.`); 
+        }
+
+        let finalCategory = folderName;
+        if (folderName === 'core') {
+            if (metadata.category) finalCategory = metadata.category;
+        } else {
+            finalCategory = folderName;
+        }
+
+        // --- SMART HASH GENERATION ---
+        let compositeHashString = generateCodeHash(codeStr); // Start with own code
+        const usedLayers = [];
+
+        // 1. Check for specific layer usage
+        for (const [layerName, triggers] of Object.entries(LAYER_TRIGGERS)) {
+            // If code contains any trigger for this layer
+            if (triggers.some(trigger => codeStr.includes(trigger))) {
+                compositeHashString += LAYER_HASHES[layerName]; // Append Layer Hash
+                usedLayers.push(layerName);
+            }
+        }
+
+        // 2. SAFE MODE FALLBACK
+        // If we found NO specific triggers (e.g. legacy code or unique structure), 
+        // assume it might use anything. Depend on ALL layers to be safe.
+        let isSafeMode = false;
+        if (usedLayers.length === 0) {
+            isSafeMode = true;
+            Object.values(LAYER_HASHES).forEach(h => compositeHashString += h);
+        }
+
+        // Generate final composite hash
+        const finalHash = generateCodeHash(compositeHashString);
+
+        if (isSafeMode) {
+            log.warn(`[Hash] ${normalizedName}: No specific dependencies detected. Enforcing SAFE MODE (Linked to ALL Layers).`);
+        } 
+
+        const manifestEntry = {
+            name: normalizedName,
+            class: Class,
+            category: finalCategory,     
+            sourcePackage: folderName,   
+            type: metadata.type,
+            isHistorical: metadata.isHistorical, 
+            rootDataDependencies: metadata.rootDataDependencies || [],
+            userType: metadata.userType,
+            dependencies: dependencies,
+            pass: 0,
+            hash: finalHash, // The Smart Hash
+            debugUsedLayers: isSafeMode ? ['ALL (Safe Mode)'] : usedLayers
+        };
+        
+        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); }); 
+    }
+    
+    if (!calculations || typeof calculations !== 'object') {
+        throw new Error('Manifest build failed: Invalid calculations object.');
+    }
+
+    // Iterate over folders (folderName becomes the default category)
+    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.`);
+
+    /* ---------------- 2. Validate Dependency Links ---------------- */
+    const allNames = new Set(manifestMap.keys());
+    let invalidLinks = false;
+    for (const [name, entry] of manifestMap) {
+        for (const dep of entry.dependencies) {
+            if (!allNames.has(dep)) {
+                invalidLinks = true;
+                const guesses = suggestClosest(dep, Array.from(allNames));
+                log.error(`${name} depends on unknown calculation "${dep}". Did you mean: ${guesses.join(', ')}?`);
+            }
+            if (dep === name) {
+                invalidLinks = true;
+                log.error(`${name} has a circular dependency on *itself*!`);
+            }
+        }
+    }
+    if (invalidLinks) { throw new Error('Manifest validation failed.'); }
+
+    /* ---------------- 3. Filter for Product Lines ---------------- */
+    const productLineEndpoints = [];
+    for (const [name, entry] of manifestMap.entries()) { 
+        if (productLinesToRun.includes(entry.category)) { productLineEndpoints.push(name); } 
+    }
+    // Always include core
+    for (const [name, entry] of manifestMap.entries()) { 
+        if (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); }
+
+    /* ---------------- 4. Topological Sort ---------------- */
+    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. Manifest build failed.'); }
+
+    log.success(`Total passes required: ${maxPass}`);
+    return sortedManifest;
+}
+
+function build(productLinesToRun, calculations) {
+    try {
+        return buildManifest(productLinesToRun, calculations);
+    } catch (error) { 
+        log.error(error.message); 
+        return null; 
+    }
+}
+
 module.exports = { build };