bulltrackers-module 1.0.281 → 1.0.283

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.281",
+  "version": "1.0.283",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [