bulltrackers-module 1.0.282 → 1.0.283

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

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Enforces the contracts discovered by the offline tool.
+ * Designed to be permissive with volatility ("Anomalies") but strict with logic ("Violations").
+ */
+class ContractValidator {
+
+    /**
+     * @param {Object} result - The production output (single item or batch).
+     * @param {Object} contract - The loaded contract JSON.
+     * @returns {Object} { valid: boolean, reason: string }
+     */
+    static validate(result, contract) {
+        if (!result || !contract) return { valid: true };
+
+        // Handle Batches (StandardExecutor produces map of User -> Result)
+        const items = Object.values(result);
+        if (items.length === 0) return { valid: true };
+
+        // We check a sample to save CPU, or check all if critical
+        // For "Cohort" logic, we usually check all because one bad apple spoils the average.
+        for (const item of items) {
+            const check = this._validateItem(item, contract);
+            if (!check.valid) return check;
+        }
+
+        return { valid: true };
+    }
+
+    static _validateItem(item, contract) {
+        // 1. Structure Check
+        if (contract.requiredKeys) {
+            for (const key of contract.requiredKeys) {
+                if (item[key] === undefined) {
+                    return { valid: false, reason: `Schema Violation: Missing key '${key}'` };
+                }
+            }
+        }
+
+        // 2. Numeric Physics Check (Hard Bounds)
+        if (contract.numericBounds) {
+            for (const [key, bounds] of Object.entries(contract.numericBounds)) {
+                const val = item[key];
+                if (typeof val !== 'number') continue;
+
+                if (val < bounds.min) {
+                    return { valid: false, reason: `Physics Violation: ${key} (${val}) is below hard limit ${bounds.min}` };
+                }
+                if (val > bounds.max) {
+                    return { valid: false, reason: `Physics Violation: ${key} (${val}) is above hard limit ${bounds.max}` };
+                }
+            }
+        }
+
+        // 3. Statistical Sanity Check (Soft Bounds)
+        // We generally DO NOT BLOCK on this for financial data, unless it's egregious.
+        // We block if it's "Mathematically Impossible" based on the distribution.
+        if (contract.distributions) {
+            for (const [key, dist] of Object.entries(contract.distributions)) {
+                const val = item[key];
+                if (typeof val !== 'number') continue;
+
+                const diff = Math.abs(val - dist.mean);
+                const sigmas = diff / dist.stdDev;
+
+                // 15 Sigma is our "Ridiculousness Threshold".
+                // Even crypto doesn't move 15 standard deviations in one calculation step 
+                // unless the data is corrupt (e.g. integer overflow, or bad scraping).
+                if (sigmas > 15 && diff > 1.0) { // Ensure diff is material
+                    return { 
+                        valid: false, 
+                        reason: `Statistical Impossibility: ${key} is ${sigmas.toFixed(1)} sigmas from mean. Value: ${val}, Mean: ${dist.mean}` 
+                    };
+                }
+            }
+        }
+
+        return { valid: true };
+    }
+}
+
+module.exports = ContractValidator;

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

@@ -4,6 +4,7 @@
  * 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).
  */
 const { commitBatchInChunks, generateDataHash } = require('../utils/utils');
@@ -11,6 +12,7 @@ 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 validationOverrides                  = require('../config/validation_overrides'); 
 const pLimit                               = require('p-limit'); 
 const zlib                                 = require('zlib'); 
@@ -20,6 +22,7 @@ const NON_RETRYABLE_ERRORS = [
 ];
 
 const SIMHASH_REGISTRY_COLLECTION = 'system_simhash_registry';
+const CONTRACTS_COLLECTION        = 'system_contracts'; // [NEW]
 
 /**
  * Commits results to Firestore.
@@ -40,6 +43,10 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
 
     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));
+
     for (const name in stateObj) {
         const calc      = stateObj[name];
         const execStats = calc._executionStats || { processedUsers: 0, skippedUsers: 0 };
@@ -68,7 +75,23 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 };
             }
 
-            // Validation
+            // 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) {
@@ -87,15 +110,11 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             let simHash = null;
             if (calc.manifest.hash && flushMode !== 'INTERMEDIATE') {
                 try {
-                    // Fast O(1) lookup using Code Hash
-                    // We simply check if the BuildReporter has already stamped this code version
                     const regDoc = await db.collection(SIMHASH_REGISTRY_COLLECTION).doc(calc.manifest.hash).get();
                     if (regDoc.exists) {
                         simHash = regDoc.data().simHash;
                     } else {
-                        // Fallback: This happens if BuildReporter didn't run or is out of sync.
-                        // We do NOT run SimRunner here to protect production performance.
-                        logger.log('WARN', `[ResultCommitter] SimHash not found in registry for ${name} (Hash: ${calc.manifest.hash}). Is BuildReporter skipped?`);
+                        logger.log('WARN', `[ResultCommitter] SimHash not found in registry for ${name}.`);
                     }
                 } catch (regErr) {
                     logger.log('WARN', `[ResultCommitter] Failed to read SimHash registry: ${regErr.message}`);
@@ -110,7 +129,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 if (calc.manifest.hash) { 
                     successUpdates[name] = { 
                         hash:        calc.manifest.hash,
-                        simHash:     simHash, // [NEW] Populated from Registry
+                        simHash:     simHash, 
                         resultHash:  resultHash, 
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
                         category:    calc.manifest.category, 
@@ -145,7 +164,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
                         hash:        calc.manifest.hash, 
-                        simHash:     simHash, // [NEW] Populated from Registry
+                        simHash:     simHash,
                         resultHash:  resultHash, 
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
                         category:    calc.manifest.category, 
@@ -173,7 +192,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
                         hash:        calc.manifest.hash, 
-                        simHash:     simHash, // [NEW] Populated from Registry
+                        simHash:     simHash,
                         resultHash:  resultHash,
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
                         category:    calc.manifest.category,
@@ -209,6 +228,30 @@ 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}`);
+    }
+    return map;
+}
+
 async function writeSingleResult(result, docRef, name, dateContext, logger, config, deps, startShardIndex = 0, flushMode = 'STANDARD', isInitialWrite = false) {
     
     // Transition & Cleanup Logic

package/functions/computation-system/scripts/UpdateContracts.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Discovery Script: UpdateContracts.js
+ * Runs offline simulations to "learn" the behavioral contracts of all calculations.
+ * Saves these contracts to Firestore for the Runtime Enforcer (ResultCommitter) to use.
+ * * USAGE: 
+ * node computation-system/scripts/UpdateContracts.js [--calc=CalcName]
+ */
+
+const path = require('path');
+const admin = require('firebase-admin');
+
+// Initialize Firebase (Standard Env Check)
+if (!admin.apps.length) {
+    if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+        admin.initializeApp();
+    } else {
+        // Fallback for local dev if key path isn't set in env
+        console.warn("⚠️ No GOOGLE_APPLICATION_CREDENTIALS. Attempting default init...");
+        admin.initializeApp();
+    }
+}
+
+const db = admin.firestore();
+const { StructuredLogger } = require('../logger/logger');
+const { getManifest } = require('../topology/ManifestLoader');
+const ContractDiscoverer = require('../tools/ContractDiscoverer');
+
+// Load Calculations Package
+let calculationPackage;
+try {
+    // Adjust path if necessary for your local monorepo structure
+    calculationPackage = require('aiden-shared-calculations-unified');
+} catch (e) {
+    console.error("FATAL: Could not load 'aiden-shared-calculations-unified'. Ensure you are in the correct directory or npm link is active.");
+    process.exit(1);
+}
+
+const CONTRACTS_COLLECTION = 'system_contracts';
+
+async function main() {
+    const logger = new StructuredLogger({ enableConsole: true });
+    
+    // 1. Setup Dependencies
+    // The ManifestLoader and Discoverer need a mock dependency object
+    const mockDeps = {
+        db,
+        logger,
+        // Mock specific utils if needed by your calculations during instantiation
+        calculationUtils: {
+            loadInstrumentMappings: async () => ({ instrumentToTicker: {}, tickerToInstrument: {} })
+        }
+    };
+
+    console.log("🚀 Starting Contract Discovery...");
+
+    // 2. Load Manifest
+    const calculations = calculationPackage.calculations;
+    const manifest = getManifest([], calculations, mockDeps);
+    const manifestMap = new Map(manifest.map(c => [c.name, c]));
+
+    console.log(`ℹ️ Loaded manifest with ${manifest.length} calculations.`);
+
+    // 3. Filter Target (Optional CLI Arg)
+    const targetArg = process.argv.find(a => a.startsWith('--calc='));
+    const targetName = targetArg ? targetArg.split('=')[1] : null;
+
+    let calcsToProcess = manifest;
+    if (targetName) {
+        calcsToProcess = manifest.filter(c => c.name.toLowerCase() === targetName.toLowerCase());
+        if (calcsToProcess.length === 0) {
+            console.error(`❌ Calculation '${targetName}' not found.`);
+            process.exit(1);
+        }
+    }
+
+    // 4. Run Discovery Loop
+    let successCount = 0;
+    let skipCount = 0;
+
+    for (const calc of calcsToProcess) {
+        // Skip computations that don't produce data (like aggregators without schema)
+        if (!calc.class.getSchema && !calc.dependencies) {
+            console.log(`⏭️ Skipping ${calc.name} (No schema/outputs to analyze).`);
+            skipCount++;
+            continue;
+        }
+
+        try {
+            // A. Discover Contract via Simulation
+            // We run 50 iterations to get a statistically significant sample
+            const contract = await ContractDiscoverer.generateContract(calc, manifestMap, 50);
+
+            if (contract) {
+                // B. Enrich with Metadata
+                // FIX: Create a NEW object to satisfy Type Checking (avoid mutating the inferred shape)
+                const finalContract = {
+                    ...contract,
+                    lastUpdated: new Date(),
+                    generatedBy: 'UpdateContracts.js',
+                    version: '1.0'
+                };
+
+                // C. Save to Firestore
+                // Use finalContract instead of contract
+                await db.collection(CONTRACTS_COLLECTION).doc(calc.name).set(finalContract);
+                console.log(`✅ [SAVED] Contract for ${calc.name}`);
+                successCount++;
+            } else {
+                console.warn(`⚠️ [EMPTY] No contract generated for ${calc.name} (Insufficient data/samples).`);
+                skipCount++;
+            }
+
+        } catch (err) {
+            console.error(`❌ [ERROR] Failed to generate contract for ${calc.name}:`, err.message);
+        }
+    }
+
+    console.log("\n============================================");
+    console.log(`🎉 Discovery Complete.`);
+    console.log(`   Updated: ${successCount}`);
+    console.log(`   Skipped: ${skipCount}`);
+    console.log("============================================");
+}
+
+main().catch(err => {
+    console.error("FATAL SCRIPT ERROR:", err);
+    process.exit(1);
+});

package/functions/computation-system/simulation/Fabricator.js

@@ -112,11 +112,11 @@ class Fabricator {
             id: String(userId),
             type: type || 'all',
             portfolio: {
-                today: isSpeculator ? this._genSpecPortfolio(userId) : this._genNormalPortfolio(userId),
+                today: isSpeculator     ? this._genSpecPortfolio(userId) : this._genNormalPortfolio(userId),
                 yesterday: isSpeculator ? this._genSpecPortfolio(userId) : this._genNormalPortfolio(userId)
             },
             history: {
-                today: { PublicHistoryPositions: this._genHistoryTrades(userId) },
+                today:     { PublicHistoryPositions: this._genHistoryTrades(userId) },
                 yesterday: { PublicHistoryPositions: this._genHistoryTrades(userId) }
             }
         };

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

@@ -3,6 +3,7 @@
  * Generates a "Pre-Flight" report of what the computation system WILL do.
  * UPGRADED: Implements Behavioral Hashing (SimHash) to detect Cosmetic vs Logic changes.
  * OPTIMIZED: Caches SimHashes and actively updates status for Stable items to prevent re-runs.
+ * OPTIMIZED (V2): Implements System Fingerprinting to skip 90-day scan if manifest is identical.
  */
 
 const { analyzeDateExecution }                                             = require('../WorkflowOrchestrator');
@@ -12,12 +13,23 @@ const { checkRootDataAvailability }                                        = req
 const SimRunner                                                            = require('../simulation/SimRunner');
 const pLimit                                                               = require('p-limit');
 const path                                                                 = require('path');
+const crypto                                                               = require('crypto');
 const packageJson                                                          = require(path.join(__dirname, '..', '..', '..', 'package.json'));
 const packageVersion                                                       = packageJson.version;
 
 // Persistent Registry for SimHashes (so Workers don't have to recalc)
 const SIMHASH_REGISTRY_COLLECTION = 'system_simhash_registry';
 
+/**
+ * Helper: Generates a unique signature for the entire computation system state.
+ * If ANY calculation logic or dependency changes, this hash changes.
+ */
+function getSystemFingerprint(manifest) {
+    // Sort to ensure determinism
+    const sortedHashes = manifest.map(c => c.hash).sort().join('|');
+    return crypto.createHash('sha256').update(sortedHashes).digest('hex');
+}
+
 /**
  * Helper: Determines if a calculation should be excluded from the report.
  */
@@ -148,8 +160,40 @@ async function ensureBuildReport(config, dependencies, manifest) {
 
         if (!shouldRun) { logger.log('INFO', `[BuildReporter] 🔒 Report for v${packageVersion} locked. Skipping.`); return; }
 
-        logger.log('INFO', `[BuildReporter] 🚀 Running Pre-flight Report for v${packageVersion}...`);
-        await generateBuildReport(config, dependencies, manifest, 90, buildId);
+        // [NEW] 1. Calculate Current System Fingerprint
+        const currentSystemHash = getSystemFingerprint(manifest);
+
+        // [NEW] 2. Fetch Last Build's Fingerprint
+        const latestBuildDoc = await db.collection('computation_build_records').doc('latest').get();
+        
+        if (latestBuildDoc.exists) {
+            const latestData = latestBuildDoc.data();
+            
+            // [OPTIMIZATION] If signatures match, we can clone the report or just skip
+            if (latestData.systemFingerprint === currentSystemHash) {
+                logger.log('INFO', `[BuildReporter] ⚡ System Fingerprint (${currentSystemHash.substring(0,8)}) matches latest build. Skipping Report.`);
+                
+                // Create a "Skipped" record for the new version so we know it deployed
+                await db.collection('computation_build_records').doc(buildId).set({
+                    buildId,
+                    packageVersion,
+                    systemFingerprint: currentSystemHash,
+                    status: 'SKIPPED_IDENTICAL',
+                    referenceBuild: latestData.buildId, // Pointer to the build that actually did the work
+                    generatedAt: new Date().toISOString()
+                });
+                
+                // Release lock and exit
+                lockRef.update({ status: 'SKIPPED', completedAt: new Date() }).catch(() => {});
+                return;
+            }
+        }
+
+        logger.log('INFO', `[BuildReporter] 🚀 Change Detected. Running Pre-flight Report for v${packageVersion}...`);
+        
+        // Pass the fingerprint to generateBuildReport so it can save it
+        await generateBuildReport(config, dependencies, manifest, 90, buildId, currentSystemHash);
+        
         lockRef.update({ status: 'COMPLETED', completedAt: new Date() }).catch(() => {});
 
     } catch (e) {
@@ -160,11 +204,14 @@ async function ensureBuildReport(config, dependencies, manifest) {
 /**
  * Generates the report, writes to Firestore, AND FIXES STABLE UPDATES.
  */
-async function generateBuildReport(config, dependencies, manifest, daysBack = 90, customBuildId = null) {
+async function generateBuildReport(config, dependencies, manifest, daysBack = 90, customBuildId = null, systemFingerprint = null) {
     const { db, logger } = dependencies;
     const buildId = customBuildId || `manual_${Date.now()}`;
     
-    logger.log('INFO', `[BuildReporter] Generating Build Report: ${buildId} (Scope: ${daysBack} days)...`);
+    // Calculate fingerprint if not provided (for manual runs)
+    const finalFingerprint = systemFingerprint || getSystemFingerprint(manifest);
+
+    logger.log('INFO', `[BuildReporter] Generating Build Report: ${buildId} (Scope: ${daysBack} days, Fingerprint: ${finalFingerprint.substring(0,8)})...`);
 
     const today     = new Date();
     const startDate = new Date();
@@ -188,7 +235,14 @@ async function generateBuildReport(config, dependencies, manifest, daysBack = 90
         }
     });
 
-    const reportHeader = { buildId, packageVersion, generatedAt: new Date().toISOString(), summary: {}, _sharded: true };
+    const reportHeader = { 
+        buildId, 
+        packageVersion, 
+        systemFingerprint: finalFingerprint, // Saved to Firestore
+        generatedAt: new Date().toISOString(), 
+        summary: {}, 
+        _sharded: true 
+    };
 
     let totalRun = 0, totalReRun = 0, totalStable = 0;
     const detailWrites = []; 

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

@@ -0,0 +1,144 @@
+/**
+ * @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;

package/package.json

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