aiden-shared-calculations-unified 1.0.146 → 1.0.147

package/calculations/creatingcomputations.md

@@ -0,0 +1,1200 @@
+# Computation System Developer Guide
+
+## Overview
+
+This guide explains how to create computations for the BullTrackers system. You write the logic, we run it. Understanding these static methods is all you need to get started.
+
+---
+
+## Required Static Methods
+
+Every computation class must implement three static methods:
+
+### 1. `getMetadata()`
+
+Defines **what** your computation is and **how** the system should run it.
+
+**Returns:** Object with the following properties:
+
+#### Core Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `'standard'` \| `'meta'` | ✅ | **Standard**: Runs once per user (portfolio analysis, user scoring). **Meta**: Runs once per day globally (market aggregates, leaderboards). |
+| `category` | `string` | ✅ | Organizational folder (e.g., `'profiling'`, `'signals'`, `'analytics'`). Used for storage paths and reports. |
+
+#### Scheduling & Execution
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `schedule` | `object` | Daily | Controls when your computation runs:<br>• `{ type: 'DAILY' }` - Every day<br>• `{ type: 'WEEKLY', days: [1, 5] }` - Monday & Friday (0=Sun, 6=Sat)<br>• `{ type: 'MONTHLY', days: [1, 15] }` - 1st and 15th of month |
+| `isHistorical` | `boolean` | `false` | If `true`, receives yesterday's result in `context.previousComputed[yourName]` for chaining (e.g., cumulative scores). |
+| `isTest` | `boolean` | `false` | If `true`, **always re-runs on current day** to test system changes. Use for debug probes only. |
+
+#### Data Dependencies
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rootDataDependencies` | `string[]` | `[]` | What data you need. Options:<br>• `'portfolio'` - User positions<br>• `'history'` - Trade history<br>• `'social'` - Social posts<br>• `'insights'` - Market sentiment<br>• `'price'` - Asset prices<br>• `'rankings'` - PI leaderboard<br>• `'verification'` - Verified user profiles<br>• `'ratings'`, `'pageViews'`, `'watchlist'`, `'alerts'` - Profile metrics |
+| `userType` | `string` | `'all'` | Filter users: `'normal'`, `'speculator'`, `'popular_investor'`, `'signed_in_user'`, `'all'` |
+| `canHaveMissingRoots` | `boolean` | `false` | If `true`, runs even when some root data is missing. Use for fault-tolerant computations. |
+| `mandatoryRoots` | `string[]` | `[]` | Subset of `rootDataDependencies` that **must** exist. Overrides permissive flags. Example: `['portfolio']` when ratings are optional. |
+
+#### Advanced Features
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rootDataSeries` | `object` | `null` | Load **historical** root data for lookbacks:<br>`{ insights: 7, alerts: 30 }`<br>Access via `context.globalData.series.root.insights['2024-01-15']` |
+| `dependencySeries` | `object` | `null` | Load **past computation results**:<br>`{ 'RiskScore': 7 }`<br>Access via `context.globalData.series.results['2024-01-15']['RiskScore']` |
+| `ttlDays` | `number` | `90` | Data retention (days from computation date). Set to `365` for yearly reports, `30` for ephemeral analytics. |
+| `isPage` | `boolean` | `false` | If `true`, stores each user's result in a **subcollection** (`pages/{cid}`) instead of a single document. Use for large per-user datasets (>10K users). |
+| `isAlertComputation` | `boolean` | `false` | If `true`, triggers Firestore listeners for real-time alerts. System automatically publishes to Pub/Sub on completion. |
+| `targetCid` | `string` | `null` | Debug Only. Limits execution to a single User CID. Useful for testing logic on a specific user without running the full batch. |
+
+---
+
+### 2. `getDependencies()`
+
+Lists other computations your code needs.
+
+**Returns:** `string[]` - Array of computation names (kebab-case)
+
+**Example:**
+```javascript
+static getDependencies() {
+    return ['portfolio-risk-score', 'sentiment-analyzer'];
+}
+```
+
+**Access in `process()`:**
+```javascript
+const riskScore = context.computed['portfolio-risk-score'][userId];
+```
+
+If `isHistorical: true`, you also get:
+```javascript
+const yesterdayRisk = context.previousComputed['portfolio-risk-score'][userId];
+```
+
+---
+
+### 3. `getSchema()`
+
+Defines the **shape** of your output for validation.
+
+**Returns:** JSON Schema object
+
+**Example:**
+```javascript
+static getSchema() {
+    return {
+        type: 'object',
+        patternProperties: {
+            '^[0-9]+$': { // User IDs
+                type: 'object',
+                properties: {
+                    score: { type: 'number' },
+                    label: { type: 'string' },
+                    confidence: { type: 'number' }
+                }
+            }
+        }
+    };
+}
+```
+
+**Purpose:** The system learns expected bounds (e.g., scores between 0-100) and blocks outputs that violate physics (NaN, extreme outliers).
+
+---
+
+## Context API Reference
+
+Your `process(context)` receives:
+
+### For Standard Computations
+```javascript
+{
+    user: {
+        id: '12345',
+        type: 'speculator',
+        portfolio: { today: {...}, yesterday: {...} },
+        history: { today: {...}, yesterday: {...} },
+        verification: {...}, // If rootDataDependencies includes 'verification'
+        rankEntry: {...},    // User's ranking entry
+        rankEntryYesterday: {...}
+    },
+    date: { today: '2024-01-15' },
+    mappings: { instrumentToTicker: {...}, instrumentToSector: {...} },
+    math: { extract: {...}, compute: {...}, ... }, // Helper functions
+    computed: { 'other-calculation': { userId: {...} } },
+    previousComputed: { ... }, // If isHistorical: true
+    globalData: {
+        rankings: [...],           // All PIs
+        verifications: {...},      // All verified users
+        series: {                  // If rootDataSeries/dependencySeries defined
+            root: { insights: { '2024-01-10': {...} } },
+            results: { '2024-01-10': { 'RiskScore': {...} } }
+        }
+    }
+}
+```
+
+### For Meta Computations
+```javascript
+{
+    date: { today: '2024-01-15' },
+    mappings: {...},
+    prices: { history: {...} }, // If rootDataDependencies includes 'price'
+    computed: { 'user-calculation': { userId: {...} } }, // All users
+    globalData: {
+        rankings: [...],
+        verifications: {...}
+    }
+}
+```
+
+---
+
+## Mathematics Layer (`context.math`)
+
+The system injects powerful helper functions via `context.math`. These are your building blocks.
+
+### Data Extraction (`context.math.extract` / `context.math.DataExtractor`)
+
+**Purpose:** Safe accessors for raw data schemas. Handles edge cases automatically.
+
+#### Portfolio Extraction
+
+```javascript
+// Get user's positions (handles different user types automatically)
+const positions = context.math.extract.getPositions(
+    context.user.portfolio.today, 
+    context.user.type
+);
+// Returns: Array of position objects
+
+// Extract position details
+positions.forEach(pos => {
+    const instrumentId = context.math.extract.getInstrumentId(pos);
+    const pnl = context.math.extract.getNetProfit(pos);
+    const invested = context.math.extract.getPositionWeight(pos);
+    const value = context.math.extract.getPositionValue(pos);
+    const leverage = context.math.extract.getLeverage(pos);
+    const direction = context.math.extract.getDirection(pos); // "Buy" or "Sell"
+    const openRate = context.math.extract.getOpenRate(pos);
+    const currentRate = context.math.extract.getCurrentRate(pos);
+    const stopLoss = context.math.extract.getStopLossRate(pos);
+    const takeProfit = context.math.extract.getTakeProfitRate(pos);
+    const openDate = context.math.extract.getOpenDateTime(pos); // Date object
+});
+
+// Analyze portfolio composition
+const sectors = context.math.extract.getCurrentSectors(
+    context.user.portfolio.today,
+    context.mappings,
+    context.user.type
+);
+// Returns: ['Technology', 'Healthcare', ...]
+
+const aumPerAsset = context.math.extract.getAUMPerAsset(
+    context.user.portfolio.today,
+    context.user.type
+);
+// Returns: { instrumentId: aumValue, ... }
+```
+
+#### Trade History Extraction
+
+```javascript
+const trades = context.math.history.getTrades(context.user.history.today);
+// Returns: Array of closed trade objects
+
+const realizedEquity = context.math.history.getRealizedEquity(context.user.history.today);
+
+// Analyze trading patterns
+const summary = context.math.history.getSummary(context.user.history.today);
+// Returns: {
+//   totalTrades: 150,
+//   winRatio: 62.5, // percentage
+//   avgProfit: 45.2,
+//   avgLoss: -32.1,
+//   avgHoldingTimeInMinutes: 1440
+// }
+
+const dailyHistory = context.math.history.getDailyHistory(context.user.history.today);
+// Returns: [{
+//   date: '2024-01-15',
+//   netProfit: 123.45,
+//   investedVolume: 5000,
+//   tradesCount: 8
+// }, ...]
+
+const tradedAssets = context.math.history.getTradedAssets(context.user.history.today);
+// Returns: [{
+//   instrumentId: 100,
+//   avgHoldingTimeInMinutes: 720
+// }, ...]
+
+const tradedSectors = context.math.history.getTradedSectors(
+    context.user.history.today,
+    context.mappings
+);
+// Returns: ['Technology', 'Energy', ...]
+
+const copiedUsers = context.math.history.getCopiedUsers(context.user.history.today);
+// Returns: [123456, 789012] // CIDs of copied PIs
+```
+
+#### Insights Extraction (Market Sentiment)
+
+```javascript
+const insights = context.math.insights.getInsights(context, 'today');
+// Returns: Array of instrument insights
+
+const btcInsight = context.math.insights.getInsightForInstrument(insights, 1); // BTC instrumentId
+if (btcInsight) {
+    const owners = context.math.insights.getTotalOwners(btcInsight);
+    const longPct = context.math.insights.getLongPercent(btcInsight);
+    const shortPct = context.math.insights.getShortPercent(btcInsight);
+    const growth = context.math.insights.getGrowthPercent(btcInsight); // Day-over-day
+}
+```
+
+#### Rankings Extraction (Popular Investors)
+
+```javascript
+const allRankings = context.globalData.rankings;
+
+// Get user's ranking entry
+const userRank = context.math.RankingsExtractor.getEntry(allRankings, context.user.id);
+if (userRank) {
+    const gain = context.math.RankingsExtractor.getGain(userRank);
+    const riskScore = context.math.RankingsExtractor.getRiskScore(userRank);
+    const copiers = context.math.RankingsExtractor.getCopiers(userRank);
+    const aumTier = context.math.RankingsExtractor.getAUMTierDesc(userRank);
+    const aumValue = context.math.RankingsExtractor.getAUMValue(userRank);
+    const tags = context.math.RankingsExtractor.getTags(userRank); // ['Conservative', 'Crypto']
+}
+```
+
+#### Verification Extraction
+
+```javascript
+const verifications = context.globalData.verifications;
+
+const profile = context.math.VerificationExtractor.getProfile(verifications, userId);
+if (profile) {
+    const isVerified = context.math.VerificationExtractor.isVerified(profile);
+    const realCid = context.math.VerificationExtractor.getRealCID(profile);
+    const username = context.math.VerificationExtractor.getUsername(profile);
+    const bio = context.math.VerificationExtractor.getAboutMe(profile);
+    const restrictions = context.math.VerificationExtractor.getRestrictions(profile);
+    
+    // Check specific restriction
+    const hasRestriction = context.math.VerificationExtractor.hasRestriction(profile, 5);
+}
+```
+
+#### Social Data Extraction
+
+```javascript
+const discussions = context.math.SocialExtractor.getDiscussions(context.social.today);
+
+discussions.forEach(disc => {
+    const postId = context.math.SocialExtractor.getPostId(disc);
+    const message = context.math.SocialExtractor.getMessage(disc);
+    const language = context.math.SocialExtractor.getLanguage(disc);
+    const created = context.math.SocialExtractor.getCreatedDate(disc); // Date object
+    const owner = context.math.SocialExtractor.getOwnerUsername(disc);
+    const isVerified = context.math.SocialExtractor.isOwnerVerified(disc);
+    const contextType = context.math.SocialExtractor.getPostContextType(disc); 
+    // 'INSTRUMENT_TAGGED' or 'USER_TIMELINE'
+    
+    const instruments = context.math.SocialExtractor.getRelatedInstruments(disc);
+    // Returns: [{ id: 1, symbol: 'BTC', displayName: 'Bitcoin' }, ...]
+    
+    const likes = context.math.SocialExtractor.getLikeCount(disc);
+    const comments = context.math.SocialExtractor.getCommentCount(disc);
+});
+```
+
+#### Profile Metrics (Ratings, Page Views, Watchlist, Alerts)
+
+```javascript
+// PI Ratings
+const ratings = context.globalData.ratings;
+const avgRating = context.math.RatingsExtractor.getAverageRating(ratings, piCid);
+const totalRatings = context.math.RatingsExtractor.getTotalRatings(ratings, piCid);
+const userRating = context.math.RatingsExtractor.getUserRating(ratings, piCid, userId);
+
+// Page Views
+const pageViews = context.globalData.pageViews;
+const totalViews = context.math.PageViewsExtractor.getTotalViews(pageViews, piCid);
+const uniqueViewers = context.math.PageViewsExtractor.getUniqueViewers(pageViews, piCid);
+const userViews = context.math.PageViewsExtractor.getUserViewCount(pageViews, piCid, userId);
+const lastViewed = context.math.PageViewsExtractor.getUserLastViewed(pageViews, piCid, userId);
+
+// Watchlist Membership
+const watchlist = context.globalData.watchlistMembership;
+const totalWatchers = context.math.WatchlistMembershipExtractor.getTotalUsers(watchlist, piCid);
+const isWatched = context.math.WatchlistMembershipExtractor.hasUser(watchlist, piCid, userId);
+const publicCount = context.math.WatchlistMembershipExtractor.getPublicWatchlistCount(watchlist, piCid);
+
+// Alert History
+const alerts = context.globalData.alertHistory;
+const alertTypes = context.math.AlertHistoryExtractor.getAlertTypes(alerts, piCid);
+const isTriggered = context.math.AlertHistoryExtractor.isTriggered(alerts, piCid, 'RiskScoreIncrease');
+const triggeredFor = context.math.AlertHistoryExtractor.getTriggeredFor(alerts, piCid, 'RiskScoreIncrease');
+// Returns: [userId1, userId2, ...]
+```
+
+#### Price Data Extraction
+
+```javascript
+const priceHistory = context.math.priceExtractor.getHistory(
+    context.prices, 
+    'AAPL' // or instrumentId
+);
+// Returns: [{ date: '2024-01-15', price: 150.25 }, ...]
+```
+
+---
+
+### Mathematical Primitives (`context.math.compute` / `context.math.MathPrimitives`)
+
+**Purpose:** Core statistical and mathematical operations.
+
+```javascript
+// Basic Statistics
+const avg = context.math.compute.average([10, 20, 30]); // 20
+const med = context.math.compute.median([1, 5, 10, 15, 20]); // 10
+const stdDev = context.math.compute.standardDeviation([10, 20, 30, 40]);
+
+// Financial Probability
+const hitProb = context.math.compute.calculateHitProbability(
+    currentPrice,    // Current asset price
+    barrierPrice,    // Target/barrier price
+    volatility,      // Annualized volatility (0.3 = 30%)
+    days,            // Time horizon
+    drift            // Expected return (0.05 = 5% annual)
+);
+// Returns: Probability (0-1) of hitting barrier
+
+// Monte Carlo Simulation
+const pricePaths = context.math.compute.simulateGBM(
+    currentPrice,
+    volatility,
+    days,
+    simulations,  // Number of paths (e.g., 1000)
+    drift
+);
+// Returns: Float32Array of simulated prices
+
+// Population Breakdown Simulation
+const breakdownProb = context.math.compute.simulatePopulationBreakdown(
+    pricePaths,
+    userProfiles  // [{ entryPrice: 100, thresholdPct: -10 }, ...]
+);
+// Returns: Average fraction of users who capitulate
+```
+
+---
+
+### Financial Engineering (`context.math.FinancialEngineering`)
+
+**Purpose:** Advanced risk metrics.
+
+```javascript
+// Sortino Ratio (downside-focused Sharpe)
+const sortino = context.math.FinancialEngineering.sortinoRatio(
+    returnSeries,  // [0.05, -0.02, 0.03, ...]
+    targetReturn   // 0.0 for zero benchmark
+);
+
+// Kelly Criterion (optimal position sizing)
+const kellyFraction = context.math.FinancialEngineering.kellyCriterion(
+    winRatio,     // 60 (percent)
+    avgWinPct,    // 5 (percent)
+    avgLossPct    // 3 (percent)
+);
+// Returns: Optimal capital allocation (0.2 = 20% of capital)
+```
+
+---
+
+### Time Series Analysis (`context.math.TimeSeries` / `context.math.TimeSeriesAnalysis`)
+
+**Purpose:** Pattern detection and forecasting.
+
+```javascript
+// Exponential Moving Average (state-based)
+let emaState = null;
+positions.forEach(pos => {
+    const pnl = context.math.extract.getNetProfit(pos);
+    emaState = context.math.TimeSeries.updateEMAState(pnl, emaState, 0.1);
+});
+const smoothedPnl = emaState.mean;
+
+// Correlation Analysis
+const correlation = context.math.TimeSeries.pearsonCorrelation(
+    assetReturns1,
+    assetReturns2
+);
+// Returns: -1 to 1
+
+// Sliding Window Min/Max (O(n) algorithm)
+const { min, max } = context.math.TimeSeries.slidingWindowExtrema(
+    priceSeries,
+    windowSize  // 20 for 20-day window
+);
+// Returns: { min: [minValues...], max: [maxValues...] }
+
+// Hurst Exponent (trend detection)
+const hurst = context.math.TimeSeriesAnalysis.hurstExponent(priceSeries);
+// Returns: 0-1 (0.5 = random walk, >0.5 = trending, <0.5 = mean-reverting)
+
+// Fast Fourier Transform (cycle detection)
+const fftResult = context.math.TimeSeriesAnalysis.fft(priceSeries);
+// Returns: [{ real: x, imag: y }, ...]
+```
+
+---
+
+### Signal Primitives (`context.math.signals` / `context.math.SignalPrimitives`)
+
+**Purpose:** Access other computation results and transformations.
+
+```javascript
+// Get metric from dependency
+const riskScore = context.math.signals.getMetric(
+    context.computed,      // Dependency results
+    'portfolio-risk',      // Calculation name
+    'AAPL',                // Ticker or user ID
+    'score',               // Field name
+    0                      // Fallback if missing
+);
+
+// Get all tickers/users from multiple dependencies
+const allTickers = context.math.signals.getUnionKeys(
+    context.computed,
+    ['momentum-score', 'volatility-index']
+);
+
+// Normalization
+const normalized = context.math.signals.normalizeTanh(rawValue, 10, 10.0);
+// Scales to [-10, 10] with tanh smoothing
+
+const zScore = context.math.signals.normalizeZScore(value, mean, stdDev);
+
+// Divergence detection
+const divergence = context.math.signals.divergence(
+    valueA,  // Current metric
+    valueB   // Benchmark metric
+);
+
+// Access previous computation state
+const prevScore = context.math.signals.getPreviousState(
+    context.previousComputed,
+    'risk-score',
+    'AAPL',
+    'value'
+);
+```
+
+---
+
+### Aggregators (`context.math.aggregate` / `context.math.Aggregators`)
+
+**Purpose:** Multi-user analysis (mainly for Meta computations).
+
+```javascript
+// Group users by PnL per asset
+const buckets = context.math.aggregate.bucketUsersByPnlPerAsset(
+    context.computed['portfolio-snapshot'], // All user portfolios
+    context.mappings.instrumentToTicker
+);
+// Returns: {
+//   'AAPL': { winners: ['user1', 'user2'], losers: ['user3'] },
+//   'BTC': { winners: [...], losers: [...] }
+// }
+
+// Weighted sentiment calculation
+const sentiment = context.math.aggregate.getWeightedSentiment(positions);
+// Returns: Weighted average PnL
+```
+
+---
+
+### Distribution Analytics (`context.math.distribution` / `context.math.DistributionAnalytics`)
+
+**Purpose:** Kernel density estimation and statistical modeling.
+
+```javascript
+// Kernel Density Estimation
+const profile = context.math.distribution.computeKDE(
+    dataPoints,  // [{ value: 100, weight: 1.5 }, ...]
+    bandwidth,   // 5.0 (smoothing parameter)
+    steps        // 60 (resolution)
+);
+// Returns: [{ price: x, density: y }, ...]
+
+// Integration (area under curve)
+const probability = context.math.distribution.integrateProfile(
+    densityCurve,
+    startPrice,
+    endPrice
+);
+
+// Linear Regression
+const { slope, n } = context.math.distribution.linearRegression(
+    xValues,
+    yValues
+);
+```
+
+---
+
+### Linear Algebra (`context.math.LinearAlgebra`)
+
+**Purpose:** Advanced anomaly detection and correlation analysis.
+
+```javascript
+// Covariance Matrix
+const { matrix, means } = context.math.LinearAlgebra.covarianceMatrix(
+    dataMatrix  // [[feature1, feature2, ...], [f1, f2, ...], ...]
+);
+
+// Matrix Inversion (for Mahalanobis distance)
+const inverse = context.math.LinearAlgebra.invertMatrix(matrix);
+
+// Mahalanobis Distance (outlier detection)
+const distance = context.math.LinearAlgebra.mahalanobisDistance(
+    currentVector,    // [userRisk, leverage, volatility]
+    means,            // Baseline mean vector
+    inverseCovariance // Inverted covariance matrix
+);
+// Returns: Standard deviations from baseline
+```
+
+---
+
+### Profiling & Classification (`context.math`)
+
+**Purpose:** User intelligence scoring and behavioral analysis.
+
+#### User Classification
+
+```javascript
+const classification = context.math.classifier.classify(context);
+// Returns: {
+//   intelligence: { label: 'Smart Money', score: 75, isSmart: true },
+//   style: { primary: 'Swing Trader' },
+//   metrics: { profitFactor: 1.8, allocEfficiency: 0.6 }
+// }
+```
+
+#### Smart Money Scoring
+
+```javascript
+// Score portfolio quality
+const portfolioScore = context.math.SmartMoneyScorer.scorePortfolio(
+    context.user.portfolio.today,
+    context.user.type,
+    context.prices,
+    context.mappings,
+    context.math
+);
+// Returns: { score: 0-100, metrics: {...} }
+
+// Score trading history
+const historyScore = context.math.SmartMoneyScorer.scoreHistory(
+    context.user.history.today,
+    context.prices,
+    context.mappings,
+    context.math
+);
+// Returns: { score: 0-100, metrics: {...} }
+
+// Hybrid analysis
+const hybridScore = context.math.SmartMoneyScorer.scoreHybrid(context);
+// Returns: {
+//   totalScore: 75,
+//   label: 'Smart Money',
+//   method: 'Hybrid',
+//   components: { portfolio: {...}, history: {...} }
+// }
+```
+
+#### Cognitive Biases Detection
+
+```javascript
+// Anchoring Bias (holding losing positions too long)
+const anchoringScore = context.math.bias.calculateAnchoringScore(
+    positions,
+    thresholdPct,  // 2.0 = positions within ±2% of entry
+    minDaysHeld    // 14 days
+);
+// Returns: 0-1 (fraction of anchored positions)
+
+// Disposition Effect (selling winners too early, holding losers)
+const dispositionRatio = context.math.bias.calculateDispositionEffect(
+    trades
+);
+// Returns: Ratio (>1 = holding losers longer than winners)
+```
+
+#### Skill Attribution
+
+```javascript
+// Selection Alpha (stock-picking skill vs market)
+const alpha = context.math.skill.calculateSelectionAlpha(
+    positions,
+    dailyInsights  // Market consensus data
+);
+// Returns: Average excess return
+```
+
+#### Execution Quality
+
+```javascript
+// Entry timing efficiency
+const efficiency = context.math.execution.calculateEfficiency(
+    entryPrice,
+    priceHistory,
+    entryDate,
+    direction,    // 'Buy' or 'Sell'
+    windowDays    // 7 (compare to ±7 day range)
+);
+// Returns: 0-1 (1 = perfect entry at extreme)
+
+// Loss tolerance
+const tolerance = context.math.execution.calculateLossTolerance(
+    realizedPnL,
+    maxDrawdown
+);
+```
+
+#### Psychometrics
+
+```javascript
+// Disposition Skew (realized vs unrealized PnL)
+const skew = context.math.psychometrics.computeDispositionSkew(
+    trades,
+    currentPositions
+);
+
+// Revenge Trading Detection
+const revengeScore = context.math.psychometrics.detectRevengeTrading(
+    trades  // Sorted chronologically
+);
+// Returns: 0-1 (fraction of losses followed by risk escalation)
+```
+
+#### Adaptive Analytics
+
+```javascript
+// Drawdown Adaptation (does user learn from losses?)
+const adaptationScore = context.math.adaptive.analyzeDrawdownAdaptation(
+    trades,
+    drawdownThreshold  // -15 (percent)
+);
+// Returns: Score (-2 to +1, positive = adaptive behavior)
+```
+
+#### Risk Geometry
+
+```javascript
+// Efficient Frontier (Convex Hull)
+const efficientFrontier = context.math.RiskGeometry.computeConvexHull(
+    portfolioPoints  // [{ x: risk, y: return }, ...]
+);
+// Returns: Points on the efficient frontier
+```
+
+#### Anomaly Detection
+
+```javascript
+const anomalies = context.math.AnomalyDetector.detect(
+    trades,
+    currentPositions,
+    context.mappings
+);
+// Returns: {
+//   anomalies: ['New Sector Entry: User entered Technology sector for first time'],
+//   warnings: ['High Leverage Alert: Position 100 has 10x leverage (Avg: 2.5x)']
+// }
+```
+
+#### Similarity Engine
+
+```javascript
+// Find similar traders
+const peers = context.math.SimilarityEngine.findPeers(
+    context,              // Current user context
+    candidateContexts,    // Array of other users
+    limit                 // 5 (top matches)
+);
+// Returns: [
+//   { userId: '123', score: 0.85, matches: ['AAPL', 'GOOGL', 'MSFT'] },
+//   ...
+// ]
+```
+
+---
+
+### Trade Series Builder (`context.math.TradeSeriesBuilder`)
+
+**Purpose:** Convert trade history to time series for analysis.
+
+```javascript
+// Build return series
+const returns = context.math.TradeSeriesBuilder.buildReturnSeries(trades);
+// Returns: [netProfit1, netProfit2, ...] chronologically
+
+// Build cumulative equity curve
+const curve = context.math.TradeSeriesBuilder.buildCumulativeCurve(
+    returns,
+    startValue  // 100 (starting capital)
+);
+// Returns: [100, 110, 105, 120, ...]
+
+// Calculate max drawdown
+const { maxDrawdownPct, peakIndex, troughIndex } = 
+    context.math.TradeSeriesBuilder.calculateMaxDrawdown(curve);
+```
+
+---
+
+### Validators (`context.math.validate` / `context.math.Validators`)
+
+**Purpose:** Validate data integrity (mainly for internal use, but available).
+
+```javascript
+const portfolioCheck = context.math.validate.validatePortfolio(
+    context.user.portfolio.today,
+    context.user.type
+);
+// Returns: { valid: boolean, errors: string[] }
+
+const historyCheck = context.math.validate.validateTradeHistory(
+    context.user.history.today
+);
+
+const socialCheck = context.math.validate.validateSocialPost(post);
+
+const insightCheck = context.math.validate.validateInsight(insight);
+
+const priceCheck = context.math.validate.validatePriceData(instrumentData);
+```
+
+---
+
+### Schemas (`context.math.schemas` / `context.math.SCHEMAS`)
+
+**Purpose:** Constants and schema definitions.
+
+```javascript
+// User Type Constants
+context.math.SCHEMAS.USER_TYPES.NORMAL           // 'normal'
+context.math.SCHEMAS.USER_TYPES.SPECULATOR       // 'speculator'
+context.math.SCHEMAS.USER_TYPES.SIGNED_IN        // 'SIGNED_IN_USER'
+context.math.SCHEMAS.USER_TYPES.POPULAR          // 'POPULAR_INVESTOR'
+
+// Trading Style Labels
+context.math.SCHEMAS.STYLES.INVESTOR       // 'Investor'
+context.math.SCHEMAS.STYLES.SWING_TRADER   // 'Swing Trader'
+context.math.SCHEMAS.STYLES.DAY_TRADER     // 'Day Trader'
+context.math.SCHEMAS.STYLES.SCALPER        // 'Scalper'
+
+// Intelligence Labels
+context.math.SCHEMAS.LABELS.ELITE      // 'Elite'
+context.math.SCHEMAS.LABELS.SMART      // 'Smart Money'
+context.math.SCHEMAS.LABELS.NEUTRAL    // 'Neutral'
+context.math.SCHEMAS.LABELS.DUMB       // 'Dumb Money'
+context.math.SCHEMAS.LABELS.GAMBLER    // 'Gambler'
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Simple User Profiler (Standard)
+
+```javascript
+class UserRiskProfile
+{
+    static getMetadata() {
+        return {
+            type: 'standard',
+            category: 'profiling',
+            rootDataDependencies: ['portfolio', 'history'],
+            userType: 'all'
+        };
+    }
+
+    static getDependencies() {
+        return [];
+    }
+
+    static getSchema() {
+        return {
+            type: 'object',
+            patternProperties: {
+                '^[0-9]+$': {
+                    type: 'object',
+                    properties: {
+                        riskScore: { type: 'number' },
+                        category: { type: 'string' }
+                    }
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        const positions = context.math.extract.getPositions(
+            context.user.portfolio.today, 
+            context.user.type
+        );
+        
+        const leverage = positions.reduce((sum, p) => 
+            sum + context.math.extract.getLeverage(p), 0
+        ) / positions.length;
+
+        this.results = {
+            [context.user.id]: {
+                riskScore: Math.min(100, leverage * 20),
+                category: leverage > 3 ? 'Aggressive' : 'Conservative'
+            }
+        };
+    }
+
+    async getResult() {
+        return this.results;
+    }
+}
+```
+
+### Example 2: Advanced Statistical Profiler
+
+```javascript
+class AdvancedTradingProfile {
+    static getMetadata() {
+        return {
+            type: 'standard',
+            category: 'profiling',
+            rootDataDependencies: ['portfolio', 'history', 'insights'],
+            userType: 'all'
+        };
+    }
+
+    static getDependencies() {
+        return [];
+    }
+
+    static getSchema() {
+        return {
+            type: 'object',
+            patternProperties: {
+                '^[0-9]+$': {
+                    type: 'object',
+                    properties: {
+                        intelligence: { type: 'object' },
+                        biases: { type: 'object' },
+                        executionQuality: { type: 'number' },
+                        riskMetrics: { type: 'object' }
+                    }
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        // Use pre-built classifier
+        const classification = context.math.classifier.classify(context);
+        
+        // Detect cognitive biases
+        const positions = context.math.extract.getPositions(
+            context.user.portfolio.today,
+            context.user.type
+        );
+        const trades = context.math.history.getTrades(context.user.history.today);
+        
+        const anchoring = context.math.bias.calculateAnchoringScore(positions);
+        const disposition = context.math.bias.calculateDispositionEffect(trades);
+        const revenge = context.math.psychometrics.detectRevengeTrading(trades);
+        
+        // Calculate trade series metrics
+        const returns = context.math.TradeSeriesBuilder.buildReturnSeries(trades);
+        const curve = context.math.TradeSeriesBuilder.buildCumulativeCurve(returns);
+        const { maxDrawdownPct } = context.math.TradeSeriesBuilder.calculateMaxDrawdown(curve);
+        
+        // Sortino ratio
+        const sortino = context.math.FinancialEngineering.sortinoRatio(returns);
+
+        this.results = {
+            [context.user.id]: {
+                intelligence: classification.intelligence,
+                biases: {
+                    anchoring: anchoring,
+                    disposition: disposition,
+                    revenge: revenge
+                },
+                executionQuality: classification.metrics.allocEfficiency,
+                riskMetrics: {
+                    maxDrawdown: maxDrawdownPct,
+                    sortino: sortino
+                }
+            }
+        };
+    }
+
+    async getResult() {
+        return this.results;
+    }
+}
+```
+
+### Example 3: Market Sentiment Aggregator (Meta)
+
+```javascript
+class MarketSentimentIndex {
+    static getMetadata() {
+        return {
+            type: 'meta',
+            category: 'analytics',
+            rootDataDependencies: ['insights', 'rankings']
+        };
+    }
+
+    static getDependencies() {
+        return ['advanced-trading-profile'];
+    }
+
+    static getSchema() {
+        return {
+            type: 'object',
+            properties: {
+                fearGreedIndex: { type: 'number' },
+                topSectors: { type: 'array' },
+                smartMoneyFlow: { type: 'object' }
+            }
+        };
+    }
+
+    async process(context) {
+        const insights = context.math.insights.getInsights(context, 'today');
+        
+        // Aggregate market sentiment
+        let totalBullish = 0;
+        let totalBearish = 0;
+        
+        insights.forEach(insight => {
+            const long = context.math.insights.getLongPercent(insight);
+            const short = context.math.insights.getShortPercent(insight);
+            totalBullish += long;
+            totalBearish += short;
+        });
+        
+        const fearGreed = (totalBullish / (totalBullish + totalBearish)) * 100;
+        
+        // Get smart money positions from dependency
+        const profiles = context.computed['advanced-trading-profile'];
+        const smartMoney = Object.entries(profiles)
+            .filter(([_, p]) => p.intelligence.isSmart)
+            .map(([userId, _]) => userId);
+        
+        // Analyze rankings
+        const rankings = context.globalData.rankings;
+        const topPIs = rankings.slice(0, 10);
+        const topSectors = topPIs.map(pi => {
+            const tags = context.math.RankingsExtractor.getTags(pi);
+            return tags[0]; // First tag
+        }).filter(Boolean);
+
+        this.results = {
+            fearGreedIndex: fearGreed,
+            topSectors: [...new Set(topSectors)],
+            smartMoneyFlow: {
+                count: smartMoney.length,
+                percentage: (smartMoney.length / Object.keys(profiles).length) * 100
+            }
+        };
+    }
+
+    async getResult() {
+        return this.results;
+    }
+}
+```
+
+### Example 4: Time Series Momentum with Lookback
+
+```javascript
+class MomentumIndicator {
+    static getMetadata() {
+        return {
+            type: 'standard',
+            category: 'signals',
+            rootDataDependencies: ['portfolio'],
+            rootDataSeries: {
+                insights: 30  // 30 days of market data
+            },
+            dependencySeries: {
+                'user-risk-profiler': 7  // 7 days of risk scores
+            }
+        };
+    }
+
+    static getDependencies() {
+        return ['user-risk-profiler'];
+    }
+
+    static getSchema() {
+        return {
+            type: 'object',
+            patternProperties: {
+                '^[0-9]+$': {
+                    type: 'object',
+                    properties: {
+                        momentum: { type: 'number' },
+                        volatility: { type: 'number' },
+                        trend: { type: 'string' }
+                    }
+                }
+            }
+        };
+    }
+
+    async process(context) {
+        // Build risk score time series
+        const riskHistory = [];
+        const seriesResults = context.globalData.series.results;
+        
+        for (const [date, dateResults] of Object.entries(seriesResults)) {
+            const userScore = dateResults['user-risk-profiler']?.[context.user.id];
+            if (userScore) {
+                riskHistory.push(userScore.riskScore);
+            }
+        }
+        
+        if (riskHistory.length < 3) {
+            this.results = {
+                [context.user.id]: { momentum: 0, volatility: 0, trend: 'Insufficient Data' }
+            };
+            return;
+        }
+        
+        // Calculate momentum (recent avg vs older avg)
+        const recent = riskHistory.slice(-3);
+        const older = riskHistory.slice(0, 3);
+        const momentum = context.math.compute.average(recent) - context.math.compute.average(older);
+        
+        // Calculate volatility
+        const volatility = context.math.compute.standardDeviation(riskHistory);
+        
+        // Detect trend with Hurst exponent
+        const hurst = context.math.TimeSeriesAnalysis.hurstExponent(riskHistory);
+        const trend = hurst > 0.55 ? 'Trending' : (hurst < 0.45 ? 'Mean Reverting' : 'Random Walk');
+
+        this.results = {
+            [context.user.id]: {
+                momentum: momentum,
+                volatility: volatility,
+                trend: trend
+            }
+        };
+    }
+
+    async getResult() {
+        return this.results;
+    }
+}
+```
+
+---
+
+## Key Decisions
+
+**Choose `type: 'standard'` if:**
+- You analyze individual users (profiling, scoring, alerts)
+- Output is per-user (keyed by user ID)
+
+**Choose `type: 'meta'` if:**
+- You aggregate across all users (leaderboards, market stats)
+- Output is global (single object or keyed by asset)
+
+**Use `isHistorical: true` if:**
+- You need yesterday's result to calculate today's (streaks, deltas, cumulative)
+
+**Use `schedule` if:**
+- Computation is expensive and daily runs are wasteful (weekly reports, monthly summaries)
+
+**Use `isPage: true` if:**
+- Output is large (>10K users) and needs subcollection storage
+
+**Use `ttlDays` if:**
+- Data has a natural expiration (ephemeral alerts: 30 days, annual reports: 365 days)
+
+---
+
+## Common Patterns
+
+### Pattern: Multi-Layer Analysis
+```javascript
+// Combine multiple extractors
+const positions = context.math.extract.getPositions(...);
+const trades = context.math.history.getTrades(...);
+const summary = context.math.history.getSummary(...);
+const classification = context.math.classifier.classify(context);
+
+// Build composite score
+const score = (summary.winRatio * 0.4) + (classification.intelligence.score * 0.6);
+```
+
+### Pattern: Statistical Outlier Detection
+```javascript
+// Use Mahalanobis distance
+const features = [userRisk, userLeverage, userVolatility];
+const { matrix, means } = context.math.LinearAlgebra.covarianceMatrix(allUserFeatures);
+const inverse = context.math.LinearAlgebra.invertMatrix(matrix);
+const distance = context.math.LinearAlgebra.mahalanobisDistance(features, means, inverse);
+
+const isOutlier = distance > 3; // 3 standard deviations
+```
+
+### Pattern: Behavioral State Machine
+```javascript
+const prevState = context.previousComputed['behavior-tracker']?.[userId]?.state || 'neutral';
+const currentRisk = context.computed['risk-score'][userId];
+
+let newState = prevState;
+if (currentRisk > 80 && prevState !== 'aggressive') {
+    newState = 'aggressive';
+} else if (currentRisk < 30 && prevState !== 'conservative') {
+    newState = 'conservative';
+}
+```
+
+---
+
+## Testing Your Computation
+
+1. **Implement the three static methods**
+2. **Test Schema:** Run `YourClass.getSchema()` - ensure it returns valid JSON Schema
+3. **Test Metadata:** Check dependencies exist in manifest
+4. **Mark as Test:** Set `isTest: true` during development for immediate re-runs
+5. **Check Logs:** Monitor Cloud Logging for validation errors
+6. **Verify Math Layer:** Test helper functions locally before deploying
+
+---
+
+## What Happens When You Submit
+
+1. **Manifest Build:** System discovers your class, validates static methods
+2. **Dependency Graph:** Ensures dependencies exist, detects cycles
+3. **Hash Generation:** Code changes trigger automatic re-runs
+4. **Execution:** System loads data, injects math layer, calls `process(context)`, validates output
+5. **Storage:** Results compressed/sharded automatically based on size
+
+You control the logic. The system handles infrastructure, retries, validation, and optimization.