bulltrackers-module 1.0.732 → 1.0.733

package/functions/computation-system/tools/BuildReporter.js

@@ -1,531 +0,0 @@
-/**
- * FILENAME: computation-system/tools/BuildReporter.js
- * PURPOSE: Generates the "Build Report" - a comprehensive audit of the computation system's state.
- * UPDATED: Trigger logic now strictly depends on Package Version changes (Calculations OR Module).
- * UPDATED: Added Algorithmic "Dynamic Warnings" for impossibility analysis.
- */
-
-const { analyzeDateExecution } = require('../WorkflowOrchestrator');
-const { fetchComputationStatus, updateComputationStatus } = require('../persistence/StatusRepository');
-const { normalizeName, getExpectedDateStrings, DEFINITIVE_EARLIEST_DATES, getEarliestDataDates } = require('../utils/utils');
-const { checkRootDataAvailability } = require('../data/AvailabilityChecker');
-const SimRunner = require('../simulation/SimRunner');
-const SYSTEM_EPOCH = require('../system_epoch');
-const REPORTER_EPOCH = require('../reporter_epoch');
-const pLimit = require('p-limit');
-const path = require('path');
-const fs = require('fs');
-const crypto = require('crypto');
-
-const BUILD_RECORDS_COLLECTION = 'computation_build_records';
-const SIMHASH_REGISTRY_COLLECTION = 'system_simhash_registry';
-
-/**
- * Resolves version numbers for both the Infrastructure (Module) and the Logic (Calculations).
- */
-function getPackageVersions() {
-    let moduleVersion = 'unknown';
-    let calcVersion = 'unknown';
-
-    try {
-        const modulePkgPath = path.join(__dirname, '../../../../bulltrackers-module/package.json');
-        const modulepkg = JSON.parse(fs.readFileSync(modulePkgPath, 'utf8'));
-        moduleVersion = modulepkg.version;
-
-    } catch (e) {
-        moduleVersion = "1"
-        console.warn('[BuildReporter] Could not resolve Module version', e.message); 
-    }
-
-    try {
-        const calcPkgPath = path.join(__dirname, '../../../../calculations/package.json');
-        const calcpkg = JSON.parse(fs.readFileSync(calcPkgPath, 'utf8'));
-        calcVersion = calcpkg.version;
-        
-    } catch (e2) { 
-        calcVersion = "1"
-        console.warn('[BuildReporter] Could not resolve Calculations version', e2.message); 
-    }
-        
-
-    return { moduleVersion, calcVersion };
-}
-
-/**
- * Publishes a message to trigger the dedicated Build Reporter Cloud Function.
- * Fire-and-forget to avoid blocking initialization.
- */
-async function requestBuildReport(config, dependencies) {
-    const { pubsubUtils, logger } = dependencies;
-    
-    // Get versions (synchronous but fast, wrapped in try-catch)
-    let moduleVersion = 'unknown';
-    let calcVersion = 'unknown';
-    try {
-        const versions = getPackageVersions();
-        moduleVersion = versions.moduleVersion;
-        calcVersion = versions.calcVersion;
-    } catch (e) {
-        // If version resolution fails, use defaults
-        logger.log('WARN', `[BuildReporter] Version resolution failed, using defaults: ${e.message}`);
-    }
-    
-    // Fire-and-forget: don't await, just log errors
-    pubsubUtils.publish(config.buildReporterTopic, { 
-        requestedAt: new Date().toISOString(),
-        moduleVersion,
-        calcVersion
-    }).then(() => {
-        logger.log('INFO', `[BuildReporter] 🛰️ Trigger message sent to ${config.buildReporterTopic}`);
-    }).catch(e => {
-        logger.log('ERROR', `[BuildReporter] Failed to publish trigger: ${e.message}`);
-    });
-    
-    return { success: true, status: 'PENDING' };
-}
-
-/**
- * Cloud Function Entry Point for the Build Reporter.
- */
-async function handleBuildReportTrigger(message, context, config, dependencies, manifest) {
-    const { logger } = dependencies;
-    logger.log('INFO', `[BuildReporter] 📥 Trigger received. Starting build analysis...`);
-    try {
-        return await generateBuildReport(config, dependencies, manifest);
-    } catch (e) {
-        logger.log('ERROR', `[BuildReporter] Fatal error in execution: ${e.message}`);
-        throw e; 
-    }
-}
-
-function getSystemFingerprint(manifest) {
-    const sortedManifestHashes = manifest.map(c => c.hash).sort().join('|');
-    return crypto.createHash('sha256')
-        .update(sortedManifestHashes + SYSTEM_EPOCH + REPORTER_EPOCH) 
-        .digest('hex');
-}
-
-function isDateBeforeAvailability(dateStr, calcManifest) {
-    const targetDate = new Date(dateStr + 'T00:00:00Z');
-    const deps = calcManifest.rootDataDependencies || [];
-    if (deps.length === 0) return false;
-    for (const dep of deps) {
-        let startDate = null;
-        if (dep === 'portfolio')      startDate = DEFINITIVE_EARLIEST_DATES.portfolio;
-        else if (dep === 'history')   startDate = DEFINITIVE_EARLIEST_DATES.history;
-        else if (dep === 'social')    startDate = DEFINITIVE_EARLIEST_DATES.social;
-        else if (dep === 'insights')  startDate = DEFINITIVE_EARLIEST_DATES.insights;
-        else if (dep === 'price')     startDate = DEFINITIVE_EARLIEST_DATES.price;
-        if (startDate && targetDate < startDate) { return true; }
-    }
-    return false;
-}
-
-function calculateBlastRadius(targetCalcName, reverseGraph) {
-    const impactSet = new Set();
-    const queue = [targetCalcName];
-    while(queue.length > 0) {
-        const current = queue.shift();
-        const dependents = reverseGraph.get(current) || [];
-        dependents.forEach(child => {
-            if (!impactSet.has(child)) {
-                 impactSet.add(child);
-                 queue.push(child);
-            }
-        });
-    }
-    return {
-        directDependents: (reverseGraph.get(targetCalcName) || []).length,
-        totalCascadingDependents: impactSet.size,
-        affectedCalculations: Array.from(impactSet).slice(0, 50)
-    };
-}
-
-async function verifyBehavioralStability(candidates, manifestMap, dailyStatus, logger, simHashCache, db) {
-    const trueReRuns = [];
-    const stableUpdates = [];
-    const limit = pLimit(10);
-
-    const checks = candidates.map(item => limit(async () => {
-        try {
-            const manifest = manifestMap.get(item.name);
-            const stored = dailyStatus[item.name];
-
-            if (!stored || !stored.simHash || !manifest) {
-                trueReRuns.push(item);
-                return;
-            }
-
-            let newSimHash = simHashCache.get(manifest.hash);
-            if (!newSimHash) {
-                newSimHash = await SimRunner.run(manifest, manifestMap);
-                simHashCache.set(manifest.hash, newSimHash);
-                db.collection(SIMHASH_REGISTRY_COLLECTION).doc(manifest.hash).set({
-                    simHash: newSimHash,
-                    createdAt: new Date(),
-                    calcName: manifest.name
-                }).catch(err => logger.log('WARN', `Failed to write SimHash registry for ${manifest.name}: ${err.message}`));
-            }
-
-            if (newSimHash === stored.simHash) {
-                stableUpdates.push({
-                    ...item,
-                    reason: "Code Updated (Logic Stable)",
-                    simHash: newSimHash, 
-                    newHash: manifest.hash 
-                });
-            } else {
-                trueReRuns.push({
-                    ...item,
-                    reason: item.reason + ` [SimHash Mismatch]`,
-                    oldSimHash: stored.simHash,
-                    newSimHash: newSimHash
-                });
-            }
-        } catch (e) {
-            logger.log('WARN', `[BuildReporter] SimHash check failed for ${item.name}: ${e.message}`);
-            trueReRuns.push(item);
-        }
-    }));
-
-    await Promise.all(checks);
-    return { trueReRuns, stableUpdates };
-}
-
-/**
- * Algorithmic Analysis for Dynamic Warnings.
- * Detects patterns in "Impossible" states (e.g., Weekends, Category-Wide).
- */
-function generateDynamicWarnings(impossibleStats, categoryStats, totalDates) {
-    const warnings = [];
-
-    for (const [name, stats] of impossibleStats.entries()) {
-        const failureRate = stats.count / totalDates;
-        const categoryData = categoryStats.get(stats.category) || { total: 0, impossible: 0 };
-        const catTotal = Math.max(1, categoryData.total);
-        const catFailureRate = categoryData.impossible / catTotal;
-
-        // Skip negligible errors
-        if (failureRate < 0.05) continue; 
-
-        let type = 'INTERMITTENT_FAILURE';
-        let contextMsg = `Fails on ${stats.count}/${totalDates} dates.`;
-
-        // 1. Weekend Analysis
-        const isWeekendOnly = stats.dates.every(d => {
-            const day = new Date(d + 'T00:00:00Z').getUTCDay();
-            return day === 0 || day === 6; // Sunday or Saturday
-        });
-
-        if (isWeekendOnly && failureRate < 0.35) {
-            type = 'WEEKEND_GAP';
-            contextMsg = 'Computation consistently fails only on weekends (likely price/market data gaps).';
-        } else if (failureRate > 0.95) {
-            type = 'PERMANENT_FAILURE';
-            if (catFailureRate > 0.8) {
-                contextMsg = `Entire category '${stats.category}' is failing (${(catFailureRate*100).toFixed(0)}% fail rate). Systemic issue.`;
-            } else {
-                contextMsg = `Category '${stats.category}' is healthy, but this calculation is 100% impossible. Outlier.`;
-            }
-        }
-
-        warnings.push({
-            computation: name,
-            category: stats.category,
-            pass: stats.pass,
-            type: type,
-            failureRate: (failureRate * 100).toFixed(1) + '%',
-            message: contextMsg,
-            reasons: Array.from(stats.reasons).slice(0, 3) 
-        });
-    }
-
-    return warnings;
-}
-
-/**
- * The main reporter logic.
- */
-async function generateBuildReport(config, dependencies, manifest) {
-    const { db, logger } = dependencies;
-    const { moduleVersion, calcVersion } = getPackageVersions();
-    
-    // 1. Version-Based Trigger Check
-    // We create a composite ID for this exact code state
-    const buildId = `build_mod-${moduleVersion}_calc-${calcVersion}_${REPORTER_EPOCH}`;
-    
-    const existingDoc = await db.collection(BUILD_RECORDS_COLLECTION).doc(buildId).get();
-    if (existingDoc.exists) {
-        const data = existingDoc.data();
-        if (data.status === 'COMPLETED') {
-            logger.log('INFO', `[BuildReporter] ⚡ Report already exists for ${buildId}. Skipping execution.`);
-            return { success: true, status: 'SKIPPED_EXISTING', buildId };
-        }
-    }
-
-    logger.log('INFO', `[BuildReporter] 🚀 Generating new report for ${buildId}.`);
-
-    // 2. Initialize Data
-    await getEarliestDataDates(config, dependencies); // Ensure dates are loaded
-    const currentFingerprint = getSystemFingerprint(manifest);
-    const { absoluteEarliest } = DEFINITIVE_EARLIEST_DATES;
-    
-    // Dynamic Window
-    const today = new Date();
-    let dynamicDaysBack = 90; 
-    if (absoluteEarliest) {
-        const diffTime = Math.abs(today.getTime() - absoluteEarliest.getTime());
-        dynamicDaysBack = Math.ceil(diffTime / (1000 * 60 * 60 * 24)) + 2; 
-    }
-    const startDate = new Date();
-    startDate.setDate(today.getDate() - dynamicDaysBack);
-    const datesToCheck = getExpectedDateStrings(startDate, today);
-
-    // 3. Stats Accumulators
-    const manifestMap  = new Map(manifest.map(c => [normalizeName(c.name), c]));
-    const simHashCache = new Map();
-    const reverseGraph = new Map();
-    
-    // Graph for Blast Radius
-    manifest.forEach(c => {
-        const parentName = normalizeName(c.name);
-        if (c.dependencies) {
-            c.dependencies.forEach(dep => {
-                const depName = normalizeName(dep);
-                if (!reverseGraph.has(depName)) reverseGraph.set(depName, []);
-                reverseGraph.get(depName).push(parentName);
-            });
-        }
-    });
-
-    // Global Accumulators for Report
-    let totalRun = 0, totalReRun = 0, totalStable = 0, totalErrors = 0;
-    const globalMismatchStats = new Map(); // { stored: 0, mismatch: 0 }
-    const impossibleAnalysis  = new Map(); // { count: 0, dates: [], reasons: Set, category, pass }
-    const categoryStats       = new Map(); // { total: 0, impossible: 0 }
-    const runnablePerDate     = {};
-    const impossiblePerDate   = {};
-
-    const reportHeader = { 
-        buildId, 
-        sharded: true,
-        generatedAt: new Date().toISOString(), 
-        calculationPackageVersion: calcVersion,
-        bulltrackersModulePackageVersion: moduleVersion,
-        reporterEpoch: REPORTER_EPOCH,
-        status: 'IN_PROGRESS',
-        systemFingerprint: currentFingerprint,
-        earliestWindow: absoluteEarliest ? absoluteEarliest.toISOString().slice(0, 10) : 'UNKNOWN',
-        scanRange: `${datesToCheck[0]} to ${datesToCheck[datesToCheck.length-1]}`,
-        summary: {} 
-    };
-
-    await db.collection(BUILD_RECORDS_COLLECTION).doc(buildId).set(reportHeader);
-
-    // 4. Execution Loop
-    const limit = pLimit(10);
-    
-    for (let i = 0; i < datesToCheck.length; i += 5) {
-        const dateBatch = datesToCheck.slice(i, i + 5);
-        
-        const results = await Promise.all(dateBatch.map(dateStr => limit(async () => {
-            try {
-                // Fetch State
-                const fetchPromises = [
-                    fetchComputationStatus(dateStr, config, dependencies),
-                    checkRootDataAvailability(dateStr, config, dependencies, DEFINITIVE_EARLIEST_DATES)
-                ];
-
-                let prevDateStr = null;
-                if (manifest.some(c => c.isHistorical)) {
-                    const prevDate = new Date(dateStr + 'T00:00:00Z');
-                    prevDate.setUTCDate(prevDate.getUTCDate() - 1);
-                    prevDateStr = prevDate.toISOString().slice(0, 10);
-                    if (prevDate >= DEFINITIVE_EARLIEST_DATES.absoluteEarliest) {
-                        fetchPromises.push(fetchComputationStatus(prevDateStr, config, dependencies));
-                    }
-                }
-
-                const [dailyStatus, availability, prevRes] = await Promise.all(fetchPromises);
-                const prevDailyStatus = (prevDateStr && prevRes) ? prevRes : (prevDateStr ? {} : null);
-                const rootDataStatus  = availability ? availability.status : { hasPortfolio: false, hasHistory: false };
-
-                // Analyze
-                const analysis = analyzeDateExecution(dateStr, manifest, rootDataStatus, dailyStatus, manifestMap, prevDailyStatus);
-
-                const dateSummary = {
-                    run: [], rerun: [], stable: [], blocked: [], impossible: [], uptodate: []
-                };
-
-                // --- Metric Aggregation Logic ---
-                const processItem = (targetArray, item, extraReason) => {
-                    const calcManifest = manifestMap.get(item.name);
-                    if (calcManifest && isDateBeforeAvailability(dateStr, calcManifest)) return; // Skip invalid dates
-                    
-                    const entry = { name: item.name, reason: item.reason || extraReason, pass: calcManifest?.pass || '?' };
-                    
-                    // Stats for Mismatch Rate
-                    if (!globalMismatchStats.has(item.name)) globalMismatchStats.set(item.name, { stored: 0, mismatch: 0 });
-                    const stats = globalMismatchStats.get(item.name);
-                    
-                    // "Stored" implies we have a result or are about to run one. 
-                    // We count Stable + Rerun as "Stored History comparisons"
-                    // Runnable is "New", not "Stored".
-                    if (targetArray === dateSummary.rerun) {
-                         stats.stored++; 
-                         stats.mismatch++;
-                         entry.impact = calculateBlastRadius(item.name, reverseGraph);
-                    } else if (targetArray === dateSummary.stable) {
-                         stats.stored++;
-                    }
-
-                    targetArray.push(entry);
-                };
-
-                // Track Impossible Stats
-                analysis.impossible.forEach(item => {
-                    const m = manifestMap.get(item.name);
-                    if (!m) return;
-                    if (!impossibleAnalysis.has(item.name)) {
-                        impossibleAnalysis.set(item.name, { 
-                            count: 0, dates: [], reasons: new Set(), category: m.category, pass: m.pass 
-                        });
-                    }
-                    const imp = impossibleAnalysis.get(item.name);
-                    imp.count++;
-                    imp.dates.push(dateStr);
-                    imp.reasons.add(item.reason);
-                });
-
-                // Track Category Stats (Total vs Impossible)
-                const allEvaluated = [...analysis.runnable, ...analysis.reRuns, ...analysis.skipped, ...analysis.impossible]; // Stable often in skipped
-                allEvaluated.forEach(item => {
-                    const m = manifestMap.get(item.name);
-                    if (!m) return;
-                    if (!categoryStats.has(m.category)) categoryStats.set(m.category, { total: 0, impossible: 0 });
-                    const cat = categoryStats.get(m.category);
-                    cat.total++;
-                    if (analysis.impossible.find(x => x.name === item.name)) cat.impossible++;
-                });
-
-                analysis.runnable.forEach(item => processItem(dateSummary.run, item, "New Calculation"));
-
-                // Handle Re-Runs (SimHash Verification)
-                if (analysis.reRuns.length > 0) {
-                    const { trueReRuns, stableUpdates } = await verifyBehavioralStability(analysis.reRuns, manifestMap, dailyStatus, logger, simHashCache, db);
-                    trueReRuns.forEach(item => processItem(dateSummary.rerun, item, "Logic Changed"));
-                    stableUpdates.forEach(item => processItem(dateSummary.stable, item, "Logic Stable"));
-
-                    // Auto-Heal Status if Stable
-                    if (stableUpdates.length > 0) {
-                        const updatesPayload = {};
-                        for (const stable of stableUpdates) {
-                            const m = manifestMap.get(stable.name);
-                            const stored = dailyStatus[stable.name];
-                            
-                            // [FIX] Only auto-heal if we have valid result data
-                            // Otherwise, force re-run to regenerate everything properly
-                            const hasValidResults = stored?.resultHash && 
-                                                stored.resultHash !== 'empty' &&
-                                                stored.dependencyResultHashes &&
-                                                Object.keys(stored.dependencyResultHashes).length > 0;
-                            
-                            if (m && stored && hasValidResults) {
-                                updatesPayload[stable.name] = {
-                                    hash: m.hash, simHash: stable.simHash, resultHash: stored.resultHash, 
-                                    dependencyResultHashes: stored.dependencyResultHashes,
-                                    category: m.category, composition: m.composition, lastUpdated: new Date()
-                                };
-                            } else {
-                                // No valid results - treat as true re-run
-                                processItem(dateSummary.rerun, stable, "Epoch Change - Rebuilding");
-                            }
-                        }
-                        if (Object.keys(updatesPayload).length > 0) {
-                            await updateComputationStatus(dateStr, updatesPayload, config, dependencies);
-                        }
-                    }}
-
-                // Add skipped items to Stable count for metrics
-                analysis.skipped.forEach(item => processItem(dateSummary.stable, item, "Up To Date"));
-                
-                analysis.blocked.forEach(item => processItem(dateSummary.blocked, item));
-                analysis.failedDependency.forEach(item => processItem(dateSummary.blocked, item, "Dependency Missing"));
-                analysis.impossible.forEach(item => processItem(dateSummary.impossible, item));
-
-                // Per-Date Metrics
-                const runnableCount = dateSummary.run.length + dateSummary.rerun.length;
-                const impossibleCount = dateSummary.impossible.length;
-                
-                return { 
-                    date: dateStr,
-                    run: dateSummary.run.length, 
-                    rerun: dateSummary.rerun.length, 
-                    stable: dateSummary.stable.length,
-                    runnableCount,
-                    impossibleCount,
-                    error: false,
-                    summaryPayload: dateSummary
-                };
-
-            } catch (err) {
-                logger.log('ERROR', `[BuildReporter] Analysis failed for ${dateStr}: ${err.message}`);
-                return { run: 0, rerun: 0, stable: 0, error: true };
-            }
-        })));
-
-        // Accumulate Batch Results
-        for (const res of results) {
-            if (res.error) {
-                totalErrors++;
-            } else {
-                totalRun += res.run; 
-                totalReRun += res.rerun; 
-                totalStable += res.stable;
-                runnablePerDate[res.date] = res.runnableCount;
-                impossiblePerDate[res.date] = res.impossibleCount;
-                
-                // Write detailed record
-                await db.collection(BUILD_RECORDS_COLLECTION).doc(buildId).collection('details').doc(res.date).set(res.summaryPayload);
-            }
-        }
-
-        await db.collection(BUILD_RECORDS_COLLECTION).doc(buildId).update({ 
-            checkpoint: `Processed ${Math.min(i + dateBatch.length, datesToCheck.length)}/${datesToCheck.length} dates` 
-        });
-    }
-
-    // 5. Final Synthesis
-    const hashMismatchMetrics = {};
-    for (const [name, stats] of globalMismatchStats) {
-        if (stats.stored > 0) {
-            hashMismatchMetrics[name] = `${stats.mismatch}/${stats.stored}`;
-        }
-    }
-
-    const dynamicWarnings = generateDynamicWarnings(impossibleAnalysis, categoryStats, datesToCheck.length);
-
-    reportHeader.status = 'COMPLETED';
-    reportHeader.summary = { 
-        totalReRuns: totalReRun, 
-        totalNew: totalRun, 
-        totalStable: totalStable, 
-        totalErrors: totalErrors,
-        
-        // Expanded Metrics
-        runnablePerDate,
-        impossiblePerDate,
-        hashMismatches: hashMismatchMetrics,
-        dynamicWarnings: dynamicWarnings
-    };
-
-    // Save
-    await db.collection(BUILD_RECORDS_COLLECTION).doc(buildId).set(reportHeader);
-    await db.collection(BUILD_RECORDS_COLLECTION).doc('latest').set({ ...reportHeader, note: "Latest completed build report." });
-    
-    logger.log('SUCCESS', `[BuildReporter] Build ${buildId} completed. Warnings: ${dynamicWarnings.length}`);
-    
-    return { success: true, buildId, summary: reportHeader.summary };
-}
-
-module.exports = { requestBuildReport, handleBuildReportTrigger, generateBuildReport };

package/functions/computation-system/tools/ContractDiscoverer.js

@@ -1,144 +0,0 @@
-/**
- * @fileoverview Analyzes calculation behavior via Monte Carlo simulation 
- * to generate "Loose" but mathematically sound contracts.
- */
-const SimRunner = require('../simulation/SimRunner');
-const { MathPrimitives } = require('../layers/mathematics');
-const { normalizeName } = require('../utils/utils');
-
-class ContractDiscoverer {
-    
-    static async generateContract(calcManifest, fullManifestMap, iterations = 50) {
-        console.log(`[ContractDiscoverer] 🕵️‍♀️ Learning behavior for: ${calcManifest.name}`);
-        
-        const samples = [];
-        const errors = [];
-
-        // 1. Monte Carlo Simulation
-        // Run the code against 50 different "universes" of data to see how it behaves.
-        for (let i = 0; i < iterations; i++) {
-            try {
-                // We use your existing SimRunner, which uses Fabricator
-                // The SimRunner needs to return the RAW result, not the hash.
-                // You might need a small helper in SimRunner or just instantiate directly here:
-                const result = await this._runSimulationRaw(calcManifest, fullManifestMap, i);
-                if (result) samples.push(result);
-            } catch (e) {
-                errors.push(e.message);
-            }
-        }
-
-        if (samples.length < 5) {
-            console.warn(`[ContractDiscoverer] ⚠️ Insufficient samples for ${calcManifest.name}. Skipping.`);
-            return null;
-        }
-
-        // 2. Statistical Inference
-        // We now analyze the 50 outputs to find "Invariants"
-        return this._inferContractFromSamples(samples, calcManifest.type);
-    }
-
-    // Helper to bypass the hashing logic of SimRunner and get raw object
-    static async _runSimulationRaw(manifest, map, seed) {
-        const Fabricator = require('../simulation/Fabricator');
-        const fabricator = new Fabricator(manifest.name + '_seed_' + seed);
-        const context = await fabricator.generateContext(manifest, map, seed);
-        const instance = new manifest.class();
-        await instance.process(context);
-        return instance.getResult ? await instance.getResult() : (instance.results || {});
-    }
-
-    static _inferContractFromSamples(samples, type) {
-        // Flatten samples if it's a Standard (Batch) calculation
-        // We want to analyze "What does A USER result look like?"
-        let flattened = samples;
-        if (type === 'standard') {
-            flattened = [];
-            samples.forEach(batch => {
-                Object.values(batch).forEach(userResult => flattened.push(userResult));
-            });
-        }
-
-        // Initialize Rule Set
-        const contract = {
-            requiredKeys: new Set(),
-            numericBounds: {},  // { min, max, isInteger }
-            distributions: {},  // { mean, stdDev }
-            enums: {},          // { allowedValues }
-            dataTypes: {}       // { key: 'number' | 'string' | 'object' }
-        };
-
-        if (flattened.length === 0) return null;
-
-        // A. Structural Analysis (Keys & Types)
-        const first = flattened[0];
-        if (typeof first === 'object' && first !== null) {
-            Object.keys(first).forEach(key => contract.requiredKeys.add(key));
-            
-            Object.keys(first).forEach(key => {
-                contract.dataTypes[key] = typeof first[key];
-                
-                // Track all values for this key to find bounds
-                const values = flattened.map(item => item[key]).filter(v => v !== null && v !== undefined);
-                
-                // B. Numeric Analysis (The "Power" part)
-                if (typeof first[key] === 'number') {
-                    this._analyzeNumericField(key, values, contract);
-                }
-                
-                // C. Categorical Analysis
-                if (typeof first[key] === 'string') {
-                    const unique = new Set(values);
-                    if (unique.size < 10) { // If only a few distinct strings, it's an Enum
-                        contract.enums[key] = Array.from(unique);
-                    }
-                }
-            });
-        }
-
-        return {
-            ...contract,
-            requiredKeys: Array.from(contract.requiredKeys)
-        };
-    }
-
-    static _analyzeNumericField(key, values, contract) {
-        if (values.length === 0) return;
-
-        const min = Math.min(...values);
-        const max = Math.max(...values);
-        const avg = MathPrimitives.average(values);
-        const dev = MathPrimitives.standardDeviation(values);
-        
-        // 1. Detect "Hard" Physics Limits (Probability, Ratios)
-        // If the value NEVER goes below 0 or above 1 in 50 runs, assume it's a Ratio.
-        // We assume "Financial Volatility" creates large numbers, but "Ratios" stay small.
-        const isRatio = (min >= 0 && max <= 1.0);
-        const isPercentage = (min >= 0 && max <= 100.0 && max > 1.0); // e.g. RSI
-        const isPositive = (min >= 0);
-
-        contract.numericBounds[key] = {
-            // We do NOT set strict upper bounds for financial values (Price, Vol, PnL)
-            // because crypto/finance can do 1000x.
-            // We ONLY set strict bounds for Ratios/Percentages.
-            min: isPositive ? 0 : -Infinity, 
-            max: (isRatio ? 1.0 : (isPercentage ? 100.0 : Infinity))
-        };
-
-        // 2. Detect "Soft" Statistical Envelopes (6 Sigma)
-        // This handles the "Ridiculously Volatile" case. 
-        // 6 Sigma covers 99.9999998% of cases even in non-normal distributions (Chebyshev's inequality).
-        // If a value is 20 Sigma away, it's likely a bug (e.g., Unix Timestamp interpreted as Price).
-        if (dev > 0) {
-            contract.distributions[key] = {
-                mean: avg,
-                stdDev: dev,
-                // "Loose" Envelope: 10 Standard Deviations allowed.
-                // This allows for massive volatility but catches data corruption.
-                sigmaLimit: 10 
-            };
-        }
-    }
-}
-
-module.exports = ContractDiscoverer;