bulltrackers-module 1.0.281 → 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,12 +4,15 @@
  * 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');
 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'); 
@@ -18,6 +21,9 @@ const NON_RETRYABLE_ERRORS = [
     'PERMISSION_DENIED',     'DATA_LOSS',             'FAILED_PRECONDITION'
 ];
 
+const SIMHASH_REGISTRY_COLLECTION = 'system_simhash_registry';
+const CONTRACTS_COLLECTION        = 'system_contracts'; // [NEW]
+
 /**
  * Commits results to Firestore.
  */
@@ -31,12 +37,16 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     
     // Options defaults
     const flushMode        = options.flushMode || 'STANDARD';
-    const isInitialWrite   = options.isInitialWrite === true; // [NEW] Flag for clean run
+    const isInitialWrite   = options.isInitialWrite === true; 
     const shardIndexes     = options.shardIndexes || {};
     const nextShardIndexes = {};
 
     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 };
@@ -65,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) {
@@ -80,6 +106,21 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             const isEmpty = !result || (typeof result === 'object' && Object.keys(result).length === 0);
             const resultHash = isEmpty ? 'empty' : generateDataHash(result);
 
+            // [OPTIMIZATION] FETCH SimHash from Registry (Do NOT Calculate)
+            let simHash = null;
+            if (calc.manifest.hash && flushMode !== 'INTERMEDIATE') {
+                try {
+                    const regDoc = await db.collection(SIMHASH_REGISTRY_COLLECTION).doc(calc.manifest.hash).get();
+                    if (regDoc.exists) {
+                        simHash = regDoc.data().simHash;
+                    } else {
+                        logger.log('WARN', `[ResultCommitter] SimHash not found in registry for ${name}.`);
+                    }
+                } catch (regErr) {
+                    logger.log('WARN', `[ResultCommitter] Failed to read SimHash registry: ${regErr.message}`);
+                }
+            }
+
             if (isEmpty) { 
                 if (flushMode === 'INTERMEDIATE') {
                     nextShardIndexes[name] = currentShardIndex; 
@@ -88,6 +129,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 if (calc.manifest.hash) { 
                     successUpdates[name] = { 
                         hash:        calc.manifest.hash,
+                        simHash:     simHash, 
                         resultHash:  resultHash, 
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
                         category:    calc.manifest.category, 
@@ -115,8 +157,6 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                         .collection(config.computationsSubcollection)
                         .doc(name);
 
-                    // Note: Multi-date fan-out rarely hits sharding, and tracking isInitialWrite per-date is complex.
-                    // We assume standard merging here.
                     await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps, 0, 'STANDARD', false);
                 }));
                 await Promise.all(datePromises);
@@ -124,6 +164,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
                         hash:        calc.manifest.hash, 
+                        simHash:     simHash,
                         resultHash:  resultHash, 
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
                         category:    calc.manifest.category, 
@@ -151,6 +192,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 if (calc.manifest.hash) { 
                     successUpdates[name] = {  
                         hash:        calc.manifest.hash, 
+                        simHash:     simHash,
                         resultHash:  resultHash,
                         dependencyResultHashes: calc.manifest.dependencyResultHashes || {},
                         category:    calc.manifest.category,
@@ -186,12 +228,34 @@ 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) {
     
-    // [NEW] Transition & Cleanup Logic
-    // If this is the initial write of a run, we verify the existing state to prevent "Ghost Data".
+    // Transition & Cleanup Logic
     let wasSharded = false;
-    let hadRootData = false;
     let shouldWipeShards = false;
 
     // Default: Merge updates. But if Initial Write, overwrite (merge: false) to clear stale fields.
@@ -203,11 +267,7 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
             if (currentSnap.exists) {
                 const d = currentSnap.data();
                 wasSharded = (d._sharded === true);
-                // If it was sharded, we MUST wipe the old shards because we are re-writing from scratch.
-                // Even if we write new shards, we want to ensure shard_10 doesn't persist if we only write up to shard_5.
                 if (wasSharded) shouldWipeShards = true;
-                
-                // If it wasn't sharded, it had root data. overwriting (merge: false) handles that automatically.
             }
         } catch (e) { /* ignore read error */ }
     }
@@ -276,7 +336,7 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
         try {
             const updates = await prepareAutoShardedWrites(result, docRef, logger, constraints.bytes, constraints.keys, startShardIndex, flushMode);
             
-            // [NEW] Inject Cleanup Ops
+            // Inject Cleanup Ops
             if (shouldWipeShards) {
                  logger.log('INFO', `[Cleanup] ${name}: Wiping old shards before Write (Initial).`);
                  const shardCol = docRef.collection('_shards');
@@ -410,4 +470,4 @@ function calculateFirestoreBytes(value) {
     if (typeof value === 'object') { let sum = 0; for (const k in value) { if (Object.prototype.hasOwnProperty.call(value, k)) { sum += (Buffer.byteLength(k, 'utf8') + 1) + calculateFirestoreBytes(value[k]); } } return sum; } return 0;
 }
 
-module.exports = { commitResults };
+module.exports = { commitResults };

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

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview Generates deterministic mock contexts for Simulation Hashing.
+ * STRICTLY ALIGNED WITH SCHEMA.MD (Production V2 Schemas).
+ * UPGRADED: Supports Iteration (Seed Rotation) and Volume Scaling for Arrays.
+ */
+const SeededRandom = require('./SeededRandom');
+const { ContextFactory } = require('../context/ContextFactory');
+
+const FAKE_SECTORS = ['Technology', 'Healthcare', 'Financials', 'Energy', 'Crypto', 'Consumer Discretionary'];
+const FAKE_TICKERS = ['AAPL', 'GOOGL', 'MSFT', 'TSLA', 'AMZN', 'BTC', 'ETH', 'NVDA', 'META', 'AMD'];
+const FAKE_TOPICS  = ['AI', 'Earnings', 'Fed', 'Crypto', 'Macro'];
+
+class Fabricator {
+    constructor(calcName) {
+        this.baseSeed = calcName;
+        // Primary RNG for high-level structure
+        this.rng = new SeededRandom(calcName);
+    }
+
+    /**
+     * Generates a context for a specific user iteration.
+     * @param {number} iteration - The index of the user in the batch (0, 1, 2...).
+     */
+    async generateContext(calcManifest, dependenciesManifest, iteration = 0) {
+        // [CRITICAL] Rotate the RNG state based on iteration so User 1 != User 2
+        this.rng = new SeededRandom(`${this.baseSeed}_ITER_${iteration}`);
+
+        const FIXED_DATE = '2025-01-01'; // Fixed simulation date
+
+        // 1. Generate Root Data
+        const user = this._generateUser(calcManifest.userType, iteration);
+        const insights = this._generateInsights(FIXED_DATE);
+        
+        // 2. Generate Mock Dependencies (The "Schema Faking" Part)
+        const computed = {};
+        if (calcManifest.dependencies) {
+            for (const depName of calcManifest.dependencies) {
+                const depEntry = dependenciesManifest.get(depName);
+                if (depEntry && depEntry.class && depEntry.class.getSchema) {
+                    const schema = depEntry.class.getSchema();
+                    // [VOLUME UPGRADE] Dependencies usually represent aggregate data.
+                    computed[depName] = this._fakeFromSchema(schema, true); 
+                } else {
+                    computed[depName] = {};
+                }
+            }
+        }
+        
+        return ContextFactory.buildPerUserContext({
+            userId: user.id,
+            userType: user.type,
+            dateStr: FIXED_DATE,
+            todayPortfolio: user.portfolio.today,
+            yesterdayPortfolio: user.portfolio.yesterday,
+            todayHistory: user.history.today,
+            yesterdayHistory: user.history.yesterday,
+            metadata: calcManifest,
+            mappings: {
+                instrumentToTicker: this._generateMappings(),
+                instrumentToSector: this._generateSectorMappings()
+            },
+            insights: { today: insights },
+            socialData: { today: this._generateSocial(FIXED_DATE) },
+            computedDependencies: computed,
+            config: {},
+            deps: { logger: { log: () => {} } } 
+        });
+    }
+
+    // --- Schema Faker Logic (Unchanged) ---
+    _fakeFromSchema(schema, isHighVolume = false) {
+        if (!schema) return {};
+        if (schema.type === 'object') {
+            const obj = {};
+            if (schema.properties) {
+                for (const [key, propSchema] of Object.entries(schema.properties)) {
+                    obj[key] = this._fakeFromSchema(propSchema, isHighVolume);
+                }
+            }
+            if (schema.patternProperties) {
+                const count = isHighVolume ? this.rng.range(20, 50) : 3;
+                const propSchema = Object.values(schema.patternProperties)[0];
+                for (let i = 0; i < count; i++) {
+                    // Use deterministic ticker keys for stability
+                    const key = `${this.rng.choice(FAKE_TICKERS)}`; 
+                    // Note: In real scenarios tickers are unique, so we might need a suffix if count > tickers.length
+                    const safeKey = count > FAKE_TICKERS.length ? `${key}_${i}` : key;
+                    obj[safeKey] = this._fakeFromSchema(propSchema, isHighVolume);
+                }
+            }
+            return obj;
+        }
+        if (schema.type === 'array') {
+            const min = isHighVolume ? 50 : 1;
+            const max = isHighVolume ? 150 : 5;
+            const len = this.rng.range(min, max);
+            return Array.from({ length: len }, () => this._fakeFromSchema(schema.items, isHighVolume));
+        }
+        if (schema.type === 'number') return parseFloat(this.rng.next().toFixed(4)) * 100;
+        if (schema.type === 'string') return "SIMULATED_STRING";
+        if (schema.type === 'boolean') return this.rng.bool();
+        return null;
+    }
+
+    // --- PROD ALIGNED GENERATORS ---
+    
+    _generateUser(type, iteration) {
+        const userId = 1000000 + iteration; // Numeric ID to match Schema
+        const isSpeculator = (type === 'speculator');
+        
+        return {
+            id: String(userId),
+            type: type || 'all',
+            portfolio: {
+                today: isSpeculator     ? this._genSpecPortfolio(userId) : this._genNormalPortfolio(userId),
+                yesterday: isSpeculator ? this._genSpecPortfolio(userId) : this._genNormalPortfolio(userId)
+            },
+            history: {
+                today:     { PublicHistoryPositions: this._genHistoryTrades(userId) },
+                yesterday: { PublicHistoryPositions: this._genHistoryTrades(userId) }
+            }
+        };
+    }
+
+    // Schema 2: Speculator User Portfolio
+    _genSpecPortfolio(userId) {
+        const invested = this.rng.range(5000, 50000);
+        const netProfit = this.rng.range(-20, 30);
+        const equity = invested * (1 + (netProfit / 100));
+
+        return {
+            AverageOpen: this.rng.range(100, 3000),
+            Equity: parseFloat(equity.toFixed(4)),
+            Invested: parseFloat(invested.toFixed(4)),
+            NetProfit: parseFloat(netProfit.toFixed(4)),
+            PublicPositions: Array.from({ length: this.rng.range(2, 10) }, (_, i) => {
+                const openRate = this.rng.range(50, 500);
+                const isBuy = this.rng.bool();
+                return {
+                    Amount: parseFloat(this.rng.range(100, 1000).toFixed(4)),
+                    CID: userId,
+                    CurrentRate: parseFloat((openRate * (1 + (this.rng.next() - 0.5) * 0.1)).toFixed(2)),
+                    InstrumentID: 100 + (i % 20),
+                    IsBuy: isBuy,
+                    IsTslEnabled: this.rng.bool(0.1),
+                    Leverage: this.rng.choice([1, 2, 5, 10, 20]),
+                    MirrorID: 0,
+                    NetProfit: parseFloat(this.rng.range(-50, 50).toFixed(4)),
+                    OpenDateTime: '2024-12-01T10:00:00Z',
+                    OpenRate: parseFloat(openRate.toFixed(2)),
+                    ParentPositionID: 0,
+                    PipDifference: this.rng.range(-100, 100),
+                    PositionID: 3000000000 + i,
+                    StopLossRate: 0.01,
+                    TakeProfitRate: 0
+                };
+            })
+        };
+    }
+
+    // Schema 1: Normal User Portfolio
+    _genNormalPortfolio(userId) {
+        const positions = Array.from({ length: this.rng.range(3, 12) }, (_, i) => ({
+            Direction: "Buy",
+            InstrumentID: 100 + (i % 20),
+            Invested: parseFloat(this.rng.range(5, 20).toFixed(4)), // Percent
+            NetProfit: parseFloat(this.rng.range(-30, 40).toFixed(4)),
+            Value: parseFloat(this.rng.range(5, 25).toFixed(4)) // Percent (Invested + PnL approx)
+        }));
+
+        // [CRITICAL] DataExtractor.getPortfolioDailyPnl uses AggregatedPositionsByInstrumentTypeID
+        // We must generate this aggregation or PnL calcs return 0.
+        const aggByType = positions.map(p => ({
+            Direction: p.Direction,
+            InstrumentTypeID: 5, // Stock
+            Invested: p.Invested,
+            NetProfit: p.NetProfit,
+            Value: p.Value
+        }));
+
+        return {
+            AggregatedMirrors: [],
+            AggregatedPositions: positions,
+            AggregatedPositionsByInstrumentTypeID: aggByType, // Required for PnL
+            AggregatedPositionsByStockIndustryID: [],
+            CreditByRealizedEquity: 0,
+            CreditByUnrealizedEquity: 0
+        };
+    }
+
+    // Schema 3: Trade History
+    _genHistoryTrades(userId) {
+        return Array.from({ length: this.rng.range(5, 30) }, (_, i) => ({
+            PositionID: 4000000000 + i,
+            CID: userId,
+            OpenDateTime: '2024-12-01T10:00:00Z',
+            OpenRate: 100.50,
+            InstrumentID: 100 + (i % 20),
+            IsBuy: this.rng.bool(),
+            MirrorID: 0,
+            ParentPositionID: 0,
+            CloseDateTime: '2024-12-02T10:00:00Z',
+            CloseRate: 110.20,
+            CloseReason: this.rng.choice([1, 5, 0]), // 1=SL, 5=TP, 0=Manual
+            ParentCID: userId,
+            NetProfit: parseFloat(this.rng.range(-50, 50).toFixed(4)),
+            Leverage: this.rng.choice([1, 2, 5])
+        }));
+    }
+
+    // Schema 5: Insights
+    // [CRITICAL FIX] Must return object { fetchedAt, insights: [] }, not just array.
+    _generateInsights(dateStr) { 
+        const insightsArray = Array.from({ length: 50 }, (_, i) => ({
+            instrumentId: 100 + i,
+            total: this.rng.range(100, 50000), // Total owners
+            percentage: this.rng.next() * 0.05, // % of brokerage
+            growth: parseFloat((this.rng.next() * 10 - 5).toFixed(4)),
+            buy: this.rng.range(20, 95),
+            sell: 0, // Will calculate below
+            prevBuy: this.rng.range(20, 95),
+            prevSell: 0
+        }));
+
+        // Fix sell/prevSell math
+        insightsArray.forEach(i => {
+            i.sell = 100 - i.buy;
+            i.prevSell = 100 - i.prevBuy;
+        });
+
+        return {
+            fetchedAt: `${dateStr}T12:00:00Z`,
+            insights: insightsArray
+        };
+    }
+    
+    // Schema 4: Social Post Data
+    // Returns Map: { "postId": { ... } }
+    _generateSocial(dateStr) { 
+        const posts = {};
+        const count = this.rng.range(5, 20);
+        
+        for(let i=0; i<count; i++) {
+            const id = `post_${i}_${this.rng.next().toString(36).substring(7)}`;
+            const ticker = this.rng.choice(FAKE_TICKERS);
+            
+            posts[id] = {
+                commentCount: this.rng.range(0, 50),
+                createdAt: `${dateStr}T09:00:00Z`,
+                fetchedAt: `${dateStr}T10:00:00Z`,
+                fullText: `$${ticker} is looking bullish today!`,
+                language: 'en-gb',
+                likeCount: this.rng.range(0, 200),
+                postOwnerId: String(this.rng.range(100000, 999999)),
+                sentiment: {
+                    overallSentiment: this.rng.choice(['Bullish', 'Bearish', 'Neutral']),
+                    topics: [this.rng.choice(FAKE_TOPICS)]
+                },
+                textSnippet: `$${ticker} is looking...`,
+                tickers: [ticker]
+            };
+        }
+        return posts;
+    }
+    
+    _generateMappings() {
+        const map = {};
+        // Map ID 100-150 to FAKE_TICKERS deterministically
+        for(let i=0; i<50; i++) {
+            // cycle through tickers
+            map[100+i] = FAKE_TICKERS[i % FAKE_TICKERS.length];
+        }
+        return map;
+    }
+    
+    _generateSectorMappings() {
+        const map = {};
+        for(let i=0; i<50; i++) {
+            map[100+i] = FAKE_SECTORS[i % FAKE_SECTORS.length];
+        }
+        return map;
+    }
+}
+
+module.exports = Fabricator;