bulltrackers-module 1.0.306 → 1.0.307

package/functions/computation-system/features.md

@@ -1,395 +0,0 @@
-# Complete Feature Inventory of BullTrackers Computation System
-
-## Core DAG Engine Features
-
-### 1. **Topological Sorting (Kahn's Algorithm)**
-- **Files**: `ManifestBuilder.js:187-205`
-- **Implementation**: Builds execution passes by tracking in-degrees, queuing zero-dependency nodes
-- **Niche aspect**: Dynamic pass assignment (line 201: `neighborEntry.pass = currentEntry.pass + 1`)
-- **Common in**: Airflow, Prefect, Dagster (all use topological sort)
-
-### 2. **Cycle Detection (Tarjan's SCC Algorithm)**
-- **Files**: `ManifestBuilder.js:98-141`
-- **Implementation**: Strongly Connected Components detection with stack-based traversal
-- **Niche aspect**: Returns human-readable cycle chain (line 137: `cycle.join(' -> ') + ' -> ' + cycle[0]`)
-- **Common in**: Academic graph libraries, rare in production DAG systems (most use simpler DFS)
-
-### 3. **Auto-Discovery Manifest Building**
-- **Files**: `ManifestBuilder.js:143-179`, `ManifestLoader.js:9-42`
-- **Implementation**: Scans directories, instantiates classes, extracts metadata via `getMetadata()` static method
-- **Niche aspect**: Singleton caching with multi-key support (ManifestLoader.js:9)
-- **Common in**: Plugin systems (Airflow providers), less common for computation graphs
-
-## Dependency Management & Optimization
-
-### 4. **Multi-Layered Hash Composition**
-- **Files**: `ManifestBuilder.js:56-95`, `HashManager.js:25-36`
-- **Implementation**: Composite hash from code + epoch + infrastructure + layers + dependencies
-- **Niche aspect**: Infrastructure hash (recursive file tree hashing, HashManager.js:38-79)
-- **Common in**: Build systems (Bazel, Buck), **very rare** in data pipelines
-
-### 5. **Content-Based Dependency Short-Circuiting**
-- **Files**: `WorkflowOrchestrator.js:51-73`
-- **Implementation**: Tracks `resultHash` (output data hash), skips re-run if output unchanged despite code change
-- **Niche aspect**: `dependencyResultHashes` tracking (line 59-67)
-- **Common in**: **Extremely rare** - only seen in specialized incremental computation systems
-
-### 6. **Behavioral Stability Detection (SimHash)**
-- **Files**: `BuildReporter.js:55-89`, `SimRunner.js:12-42`, `Fabricator.js:20-244`
-- **Implementation**: Runs code against deterministic mock data, hashes output to detect "logic changes" vs "cosmetic changes"
-- **Niche aspect**: Seeded random data generation (SeededRandom.js:1-38) for reproducible simulations
-- **Common in**: **Unique** - haven't seen this elsewhere. Conceptually similar to property-based testing but for optimization
-
-### 7. **System Epoch Forcing**
-- **Files**: `system_epoch.js:1-2`, `ManifestBuilder.js:65`
-- **Implementation**: Manual version bump to force global re-computation
-- **Niche aspect**: Single-line file that invalidates all cached results
-- **Common in**: Cache invalidation patterns, but unusual to have a dedicated module
-
-## Execution & Resource Management
-
-### 8. **Streaming Execution with Batch Flushing**
-- **Files**: `StandardExecutor.js:86-158`
-- **Implementation**: Async generators yield data chunks, flush to DB every N users
-- **Niche aspect**: Adaptive flushing based on V8 heap pressure (line 128-145)
-- **Common in**: ETL tools (Spark, Flink use micro-batching), **heap-aware flushing is rare**
-
-### 9. **Memory Heartbeat (Flight Recorder)**
-- **Files**: `computation_worker.js:30-53`
-- **Implementation**: Background timer writes memory stats to Firestore every 2 seconds
-- **Niche aspect**: Uses `.unref()` to prevent blocking process exit (line 50)
-- **Common in**: APM tools (DataDog, New Relic), **embedding in workers is custom**
-
-### 10. **Forensic Crash Analysis & Intelligent Routing**
-- **Files**: `computation_dispatcher.js:31-68`
-- **Implementation**: Reads last memory stats from failed runs, routes to high-mem queue if OOM suspected
-- **Niche aspect**: Parses telemetry to distinguish crash types (line 44-50)
-- **Common in**: Kubernetes autoscaling heuristics, **application-level routing is rare**
-
-### 11. **Circuit Breaker Pattern**
-- **Files**: `StandardExecutor.js:164-173`
-- **Implementation**: Tracks error rate, fails fast if >10% failures after 100 items
-- **Niche aspect**: Runs mid-stream (not just at job start)
-- **Common in**: Microservices (Hystrix, Resilience4j), uncommon in data pipelines
-
-### 12. **Incremental Auto-Sharding**
-- **Files**: `ResultCommitter.js:234-302`
-- **Implementation**: Dynamically splits results into Firestore subcollection shards, tracks shard index across flushes
-- **Niche aspect**: `flushMode: INTERMEDIATE` flag (line 150) to avoid pointer updates mid-stream
-- **Common in**: Database sharding, **dynamic document sharding is custom**
-
-### 13. **GZIP Compression Strategy**
-- **Files**: `ResultCommitter.js:128-157`
-- **Implementation**: Compresses results >50KB, stores as binary blob if <900KB compressed
-- **Niche aspect**: Falls back to sharding if compression fails or exceeds limit
-- **Common in**: Storage layers, integration at application level is custom
-
-## Data Quality & Validation
-
-### 14. **Heuristic Validation (Grey Box)**
-- **Files**: `ResultsValidator.js:8-96`
-- **Implementation**: Statistical analysis (zero%, null%, flatline detection) without knowing schema
-- **Niche aspect**: Weekend mode (line 57-64) - relaxes thresholds on Saturdays/Sundays
-- **Common in**: Data quality tools (Great Expectations, Soda), **weekend-aware thresholds are domain-specific**
-
-### 15. **Contract Discovery & Enforcement**
-- **Files**: `ContractDiscoverer.js:11-120`, `ContractValidator.js:9-64`
-- **Implementation**: Monte Carlo simulation learns behavioral bounds, enforces at runtime
-- **Niche aspect**: Distinguishes "physics limits" (ratios 0-1) from "statistical envelopes" (6-sigma)
-- **Common in**: **Unique** - closest analogue is schema inference (Pandas Profiling) but this is probabilistic + enforced
-
-### 16. **Semantic Gates**
-- **Files**: `ResultCommitter.js:118-127`
-- **Implementation**: Blocks results that violate contracts before writing
-- **Niche aspect**: Differentiated error handling - `SEMANTIC_GATE` errors are non-retryable (line 210-225)
-- **Common in**: Type systems (TypeScript, Mypy), **runtime probabilistic checks are rare**
-
-### 17. **Root Data Availability Tracking**
-- **Files**: `AvailabilityChecker.js:49-87`, `utils.js:11-17`
-- **Implementation**: Centralized index (`system_root_data_index`) tracks what data exists per day
-- **Niche aspect**: Granular user-type checks (speculator vs normal portfolio, line 23-47)
-- **Common in**: Data catalogs (Amundsen, DataHub), **day-level granularity is custom**
-
-### 18. **Impossible State Propagation**
-- **Files**: `WorkflowOrchestrator.js:94-96`, `logger.js:77-93`
-- **Implementation**: Marks calculations as `IMPOSSIBLE` instead of failing them, allows graph to continue
-- **Niche aspect**: Separate "impossible" category in analysis reports (logger.js:86-91)
-- **Common in**: Workflow engines handle failures, **explicit impossible state is rare**
-
-## Orchestration & Coordination
-
-### 19. **Event-Driven Callback Pattern (Zero Polling)**
-- **Files**: `bulltrackers_pipeline.yaml:49-76`, `computation_worker.js:82-104`
-- **Implementation**: Workflow creates callback endpoint, worker POSTs on completion, workflow wakes
-- **Niche aspect**: IAM authentication for callbacks (computation_worker.js:88-91)
-- **Common in**: Cloud Workflows, AWS Step Functions (both support callbacks), **IAM-secured callbacks are best practice but not default**
-
-### 20. **Run State Counter Pattern**
-- **Files**: `computation_dispatcher.js:107-115`, `computation_worker.js:106-123`
-- **Implementation**: Shared Firestore doc tracks `remainingTasks`, workers decrement on completion
-- **Niche aspect**: Transaction-based decrement (computation_worker.js:109-119) ensures atomicity
-- **Common in**: Distributed systems, **Firestore-specific implementation is custom**
-
-### 21. **Audit Ledger (Ledger-DB Pattern)**
-- **Files**: `computation_dispatcher.js:143-163`, `RunRecorder.js:26-99`
-- **Implementation**: Write-once ledger per task (`computation_audit_ledger/{date}/passes/{pass}/tasks/{calc}`)
-- **Niche aspect**: Stores granular timing breakdown (RunRecorder.js:64-70)
-- **Common in**: Event sourcing systems, **granular profiling in ledger is uncommon**
-
-### 22. **Poison Message Handling (DLQ)**
-- **Files**: `computation_worker.js:36-60`
-- **Implementation**: Max retries check via Pub/Sub `deliveryAttempt`, moves to dead letter queue
-- **Niche aspect**: Differentiates deterministic errors (line 194-222) from transient failures
-- **Common in**: Message queues (RabbitMQ, SQS), **logic-aware routing is custom**
-
-### 23. **Catch-Up Logic (Historical Scan)**
-- **Files**: `computation_dispatcher.js:65-81`
-- **Implementation**: Scans full date range (earliest data → target date) instead of just target date
-- **Niche aspect**: Parallel analysis with concurrency limit (line 85)
-- **Common in**: Data pipelines (backfill mode), **integrated into dispatcher is convenient**
-
-## Observability & Debugging
-
-### 24. **Structured Logging System**
-- **Files**: `logger.js:27-118`
-- **Implementation**: Dual output (human-readable + JSON), process tracking, context inheritance
-- **Niche aspect**: `ProcessLogger` class (line 120-148) for scoped logging with auto-stats
-- **Common in**: Production apps (Winston, Bunyan), **process-scoped loggers are nice touch**
-
-### 25. **Date Analysis Reports**
-- **Files**: `logger.js:77-132`
-- **Implementation**: Per-date breakdown of runnable/blocked/impossible/skipped calculations
-- **Niche aspect**: Unicode symbols for visual parsing (line 103)
-- **Common in**: DAG visualization tools, **inline CLI reports are developer-friendly**
-
-### 26. **Build Report Generator**
-- **Files**: `BuildReporter.js:138-248`
-- **Implementation**: Pre-deployment impact analysis showing blast radius of code changes
-- **Niche aspect**: Blast radius calculation (line 62-77) - finds all downstream dependents
-- **Common in**: CI/CD tools (GitHub's "affected projects"), **calculation-level granularity is detailed**
-
-### 27. **System Fingerprinting**
-- **Files**: `BuildReporter.js:28-51`, `HashManager.js:80-111`
-- **Implementation**: SHA-256 hash of entire codebase + manifest, triggers report on change
-- **Niche aspect**: Recursive directory walk with ignore patterns (HashManager.js:44-60)
-- **Common in**: Docker layer caching, **for change detection at deploy-time is creative**
-
-### 28. **Execution Statistics Tracking**
-- **Files**: `StandardExecutor.js:64-71`, `RunRecorder.js:57-70`
-- **Implementation**: Tracks processed/skipped users, setup/stream/processing time breakdowns
-- **Niche aspect**: Profiler-ready structure (RunRecorder.js:64-70) for BigQuery analysis
-- **Common in**: Profilers (cProfile, pyflame), **baked into business logic is pragmatic**
-
-## Data Access Patterns
-
-### 29. **Smart Shard Indexing**
-- **Files**: `data_loader.js:152-213`
-- **Implementation**: Maintains `instrumentId → shardId` index to avoid scanning all shards
-- **Niche aspect**: 24-hour TTL with rebuild logic (line 167-172)
-- **Common in**: Database indexes, **application-level shard routing is custom**
-
-### 30. **Async Generator Streaming**
-- **Files**: `data_loader.js:130-150`
-- **Implementation**: `async function*` yields data chunks, caller consumes with `for await`
-- **Niche aspect**: Supports pre-provided refs (line 132) for dependency injection
-- **Common in**: Node.js streams, **generator-based approach is modern/clean**
-
-### 31. **Cached Data Loader**
-- **Files**: `CachedDataLoader.js:14-73`
-- **Implementation**: Execution-scoped cache for mappings/insights/social data
-- **Niche aspect**: Decompression helper (line 24-32) for transparent GZIP handling
-- **Common in**: Data layers (Apollo Client, React Query), **per-execution scope is appropriate**
-
-### 32. **Deferred Hydration**
-- **Files**: `DependencyFetcher.js:23-66`
-- **Implementation**: Fetches metadata documents, hydrates sharded data on-demand
-- **Niche aspect**: Parallel hydration promises (line 44-47)
-- **Common in**: ORMs (lazy loading), **manual shard hydration is low-level**
-
-## Domain-Specific Intelligence
-
-### 33. **User Classification Engine**
-- **Files**: `profiling.js:24-236`
-- **Implementation**: "Smart Money" scoring with 18+ behavioral signals
-- **Niche aspect**: Multi-factor scoring (portfolio allocation + trade history + execution timing)
-- **Common in**: Fintech risk models, **granularity is impressive**
-
-### 34. **Convex Hull Risk Geometry**
-- **Files**: `profiling.js:338-365`
-- **Implementation**: Monotone Chain algorithm for efficient frontier analysis
-- **Niche aspect**: O(n log n) algorithm choice (profiling.js:345-363)
-- **Common in**: Computational geometry libraries, **integration into user profiling is domain-specific**
-
-### 35. **Kadane's Maximum Drawdown**
-- **Files**: `extractors.js:27-52`
-- **Implementation**: O(n) single-pass algorithm for peak-to-trough decline
-- **Niche aspect**: Returns indices for visualization (line 47)
-- **Common in**: Finance libraries (QuantLib), **clean implementation**
-
-### 36. **Fast Fourier Transform (Cooley-Tukey)**
-- **Files**: `mathematics.js:148-184`
-- **Implementation**: O(n log n) frequency domain analysis with zero-padding
-- **Niche aspect**: Recursive implementation (line 163-183)
-- **Common in**: Signal processing (NumPy, SciPy), **JavaScript implementation is rare**
-
-### 37. **Sliding Window Extrema (Monotonic Queue)**
-- **Files**: `mathematics.js:227-259`
-- **Implementation**: O(n) min/max calculation using deque
-- **Niche aspect**: Dual deques (one for min, one for max, line 236-237)
-- **Common in**: Competitive programming, **production usage is uncommon**
-
-### 38. **Geometric Brownian Motion Simulator**
-- **Files**: `mathematics.js:99-118`
-- **Implementation**: Box-Muller transform for normal random variates, Monte Carlo simulation
-- **Niche aspect**: Returns `Float32Array` for memory efficiency (line 106)
-- **Common in**: Quant finance (Black-Scholes), **typed arrays are performance-conscious**
-
-### 39. **Hit Probability Calculator**
-- **Files**: `mathematics.js:75-97`
-- **Implementation**: Closed-form barrier option pricing formula
-- **Niche aspect**: Custom `normCDF` implementation (line 85-89) avoids external deps
-- **Common in**: Options pricing libraries, **standalone implementation is self-contained**
-
-### 40. **Kernel Density Estimation**
-- **Files**: `mathematics.js:263-288`
-- **Implementation**: Gaussian kernel with weighted samples
-- **Niche aspect**: 3-bandwidth cutoff for performance (line 276)
-- **Common in**: Stats packages (SciPy, R), **production KDE is uncommon**
-
-## Schema & Type Management
-
-### 41. **Schema Capture System**
-- **Files**: `schema_capture.js:28-68`
-- **Implementation**: Batch stores class-defined schemas to Firestore
-- **Niche aspect**: Pre-commit validation (line 32-34) prevents batch failures
-- **Common in**: Schema registries (Confluent), **lightweight alternative**
-
-### 42. **Production Schema Validators**
-- **Files**: `validators.js:14-137`
-- **Implementation**: Structural validation matching schema.md definitions
-- **Niche aspect**: Separate validators per data type (portfolio/history/social/insights/prices)
-- **Common in**: Data quality frameworks, **schema.md alignment is discipline**
-
-### 43. **Legacy Mapping System**
-- **Files**: `HashManager.js:8-23`, `ContextFactory.js:12-17`
-- **Implementation**: Alias mapping for backward compatibility (e.g., `extract` → `DataExtractor`)
-- **Niche aspect**: Dual injection into context (line 14-16)
-- **Common in**: API versioning, **maintaining during refactor is good practice**
-
-## Infrastructure & Operations
-
-### 44. **Self-Healing Sharding Strategy**
-- **Files**: `ResultCommitter.js:234-302`
-- **Implementation**: Progressively stricter sharding on failure (900KB → 450KB → 200KB → 100KB)
-- **Niche aspect**: Strategy array iteration (line 241-246)
-- **Common in**: Resilience patterns, **adaptive sharding is creative**
-
-### 45. **Initial Write Cleanup Logic**
-- **Files**: `ResultCommitter.js:111-127`, `StandardExecutor.js:122-124`
-- **Implementation**: `isInitialWrite` flag triggers shard deletion before first write
-- **Niche aspect**: Transition detection (line 115-121) from sharded → compressed
-- **Common in**: Migration scripts, **baked into write path is convenient**
-
-### 46. **Firestore Byte Calculator**
-- **Files**: `ResultCommitter.js:319-324`
-- **Implementation**: Estimates document size for batch limits
-- **Niche aspect**: Handles `DocumentReference` paths (line 322)
-- **Common in**: Firestore SDKs (internal), **custom implementation for control**
-
-### 47. **Retry with Exponential Backoff**
-- **Files**: `utils.js:65-79`
-- **Implementation**: Async retry wrapper with configurable attempts and backoff
-- **Niche aspect**: 1s → 2s → 4s progression (line 75)
-- **Common in**: HTTP clients (axios, got), **standalone utility is reusable**
-
-### 48. **Batch Commit Chunker**
-- **Files**: `utils.js:86-128`
-- **Implementation**: Splits writes into Firestore 500-op/10MB batches
-- **Niche aspect**: Supports DELETE operations (line 103-108)
-- **Common in**: ORMs (SQLAlchemy bulk), **DELETE support is complete**
-
-### 49. **Date Range Generator**
-- **Files**: `utils.js:131-139`
-- **Implementation**: UTC-aware date string generation
-- **Niche aspect**: Forces UTC via `Date.UTC()` constructor (line 133-134)
-- **Common in**: Date libraries (date-fns, Luxon), **UTC enforcement is critical for finance**
-
-### 50. **Earliest Date Discovery**
-- **Files**: `utils.js:158-207`
-- **Implementation**: Scans multiple collections to find first available data
-- **Niche aspect**: Handles both flat and sharded collections (line 142-157, 160-174)
-- **Common in**: Data discovery tools, **multi-source aggregation is thorough**
-
-## Advanced Patterns
-
-### 51. **Tarjan's Stack Management**
-- **Files**: `ManifestBuilder.js:98-141`
-- **Implementation**: Manual stack tracking for SCC detection
-- **Niche aspect**: `onStack` Set for O(1) membership checks (line 106)
-- **Common in**: Graph algorithm implementations, **production usage is advanced**
-
-### 52. **Dependency-Injection Context Factory**
-- **Files**: `ContextFactory.js:17-61`
-- **Implementation**: Separate builders for per-user vs meta contexts
-- **Niche aspect**: Math layer injection with legacy aliases (line 12-17)
-- **Common in**: DI frameworks (Spring, Guice), **manual factory is lightweight**
-
-### 53. **Price Batch Executor**
-- **Files**: `PriceBatchExecutor.js:12-104`
-- **Implementation**: Specialized executor for price-only calculations (optimization pass)
-- **Niche aspect**: Outer concurrency (2) + shard batching (20) + write batching (50) nested limits
-- **Common in**: MapReduce systems, **three-level batching is complex**
-
-### 54. **Deterministic Mock Data Fabrication**
-- **Files**: `Fabricator.js:20-244`, `SeededRandom.js:8-38`
-- **Implementation**: LCG PRNG seeded by calculation name for reproducible fakes
-- **Niche aspect**: Iteration-based seed rotation (Fabricator.js:29)
-- **Common in**: Property-based testing (Hypothesis, QuickCheck), **for optimization is novel**
-
-### 55. **Schema-Driven Fake Generation**
-- **Files**: `Fabricator.js:48-71`
-- **Implementation**: Recursively generates data matching JSON schema
-- **Niche aspect**: Volume scaling flag (line 49) for aggregate vs per-item data
-- **Common in**: Schema-based generators (JSF, json-schema-faker), **custom to domain**
-
-### 56. **Migration Cleanup Hook**
-- **Files**: `ResultCommitter.js:81-83`, `ResultCommitter.js:305-317`
-- **Implementation**: Deletes old category data when calculation moves
-- **Niche aspect**: `previousCategory` tracking in manifest (WorkflowOrchestrator.js:50-54)
-- **Common in**: Schema migration tools (Alembic, Flyway), **inline cleanup is pragmatic**
-
-### 57. **Non-Retryable Error Classification**
-- **Files**: `ResultCommitter.js:18-21`, `computation_worker.js:194-225`
-- **Implementation**: Distinguishes deterministic failures from transient errors
-- **Niche aspect**: `error.stage` property for categorization (computation_worker.js:205-209)
-- **Common in**: Error handling libraries (Sentry), **semantic error types are good practice**
-
-### 58. **Reverse Adjacency Graph**
-- **Files**: `BuildReporter.js:62-77`
-- **Implementation**: Maintains child → parent edges for impact analysis
-- **Niche aspect**: Used for blast radius calculation (line 66-74)
-- **Common in**: Dependency analyzers (npm-why), **runtime maintenance is useful**
-
-### 59. **Multi-Key Manifest Cache**
-- **Files**: `ManifestLoader.js:9-14`
-- **Implementation**: Cache key is JSON-stringified sorted product lines
-- **Niche aspect**: Handles `['ALL']` vs `['crypto', 'stocks']` as different keys
-- **Common in**: Memoization libraries (lodash.memoize), **cache key design is thoughtful**
-
-### 60. **Workflow Variable Restoration**
-- **Files**: `bulltrackers_pipeline.yaml:11-17`
-- **Implementation**: Comment notes a bug fix restoring `passes` and `max_retries` variables
-- **Niche aspect**: T-1 date logic (line 13-15) for "process yesterday" pattern
-- **Common in**: Production YAML configs, **inline documentation is helpful**
-
----
-
-## Summary Statistics
-
-- **Total Features Identified**: 60
-- **Unique/Rare Features**: ~15 (SimHash, content-based short-circuit, forensic routing, contract discovery, weekend validation, behavioral stability, heap-aware flushing, monotonic queue extrema, FFT, KDE, smart shard indexing, recursive infra hash, semantic gates, impossible propagation, blast radius)
-- **Advanced CS Algorithms**: 8 (Kahn's, Tarjan's, Convex Hull, Kadane's, FFT, Box-Muller, Monotonic Queue, LCG)
-- **Common Patterns (Elevated)**: ~25 (executed exceptionally well or with domain-specific twist)
-- **Standard Infrastructure**: ~22 (logging, retries, batching, streaming, caching, validation, etc.)
-
-**Verdict**: About 25% truly novel, 40% common patterns elevated to production-grade, 35% standard infrastructure executed well.

package/functions/computation-system/paper.md

@@ -1,93 +0,0 @@
-# The BullTrackers Computation System: An Advanced DAG-Based Architecture for High-Fidelity Financial Simulation
-
-## Abstract
-
-This paper details the design, implementation, and theoretical underpinnings of the BullTrackers Computation System, a proprietary high-performance execution engine designed for complex financial modeling and user behavior analysis. The system leverages a Directed Acyclic Graph (DAG) architecture to orchestrate interdependent calculations, employing Kahn’s Algorithm for topological sorting and Tarjan’s Algorithm for cycle detection. Key innovations include "Content-Based Dependency Short-Circuiting" for massive optimization, a "System Epoch" and "Infrastructure Hash" based auditing system for absolute reproducibility, and a batch-flushing execution model designed to mitigate Out-Of-Memory (OOM) errors during high-volume processing. We further explore the application of this system in running advanced psychometric and risk-geometry models ("Smart Money" scoring) and how the architecture supports self-healing workflows through granular state management.
-
-## 1. Introduction
-
-In modern financial analytics, derived data often depends on a complex web of varying input frequencies—real-time price ticks, daily portfolio snapshots, and historical trade logs. Traditional linear batch processing protocols fail to capture the nuances of these interdependencies, often leading to race conditions or redundant computations.
-
-The BullTrackers Computation System was devised to solve this by treating the entire domain logic as a **Directed Acyclic Graph (DAG)**. Every calculation is a node, and every data requirement is an edge. By resolving the topography of this graph dynamically at runtime, the system ensures that:
-1.  Data is always available before it is consumed (referential integrity).
-2.  Only necessary computations are executed (efficiency).
-3.  Changes in code or infrastructure propagate deterministically through the graph (auditability).
-
-## 2. Theoretical Foundations
-
-The core utility of the system is its ability to turn a collection of loosely coupled JavaScript classes into a strictly ordered execution plan.
-
-### 2.1 Directed Acyclic Graphs (DAGs)
-We model the computation space as a DAG where $G = (V, E)$.
-*   **Vertices ($V$)**: Individual Calculation Units (e.g., `NetProfit`, [SmartMoneyScore](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/layers/profiling.js#24-236)).
-*   **Edges ($E$)**: Data dependencies, where an edge $(u, v)$ implies $v$ requires the output of $u$.
-
-### 2.2 Topological Sorting (Kahn’s Algorithm)
-To execute the graph, we must linearize it such that for every dependency $u \rightarrow v$, $u$ precedes $v$ in the execution order. We implement **Kahn’s Algorithm** within [ManifestBuilder.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/context/ManifestBuilder.js) to achieve this:
-1.  Calculate the **in-degree** (number of incoming edges) for all nodes.
-2.  Initialize a queue with all nodes having an in-degree of 0 (independent nodes).
-3.  While the queue is not empty:
-    *   Dequeue node $N$ and add it to the `SortedManifest`.
-    *   For each neighbor $M$ dependent on $N$, decrement $M$'s in-degree.
-    *   If $M$'s in-degree becomes 0, enqueue $M$.
-4.  This generates a series of "Passes" or "Waves" of execution, allowing parallel processing of independent nodes within the same pass.
-
-### 2.3 Cycle Detection (Tarjan’s Algorithm)
-A critical failure mode in DAGs is the introduction of a cycle (e.g., A needs B, B needs A), effectively turning the DAG into a DCG (Directed Cyclic Graph), which is unresolvable.
-If Kahn’s algorithm fails to visit all nodes (indicating a cycle exists), the system falls back to **Tarjan’s Strongly Connected Components (SCC) Algorithm**. This uses depth-first search to identify the exact cycle chain (e.g., `Calc A -> Calc B -> Calc C -> Calc A`), reporting the "First Cycle Found" to the developer for immediate remediation.
-
-## 3. System Architecture & "Source of Truth"
-
-The architecture is centered around the **Manifest**, a dynamic, immutable registry of all capabilities within the system.
-
-### 3.1 The Dynamic Manifest
-Unlike static build tools, the Manifest is built at runtime by [ManifestLoader.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/topology/ManifestLoader.js) and [ManifestBuilder.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/context/ManifestBuilder.js). It employs an **Auto-Discovery** mechanism that scans directories for calculation classes.
-*   **Static Metadata**: Each class exposes `getMetadata()` and `getDependencies()`.
-*   **Product Line Filtering**: The builder can slice the graph, generating a subgraph relevant only to specific product lines (e.g., "Crypto", "Stocks"), reducing overhead.
-
-### 3.2 Granular Hashing & The Audit Chain
-To ensure that "if the code hasn't changed, the result shouldn't change," the system implements a multi-layered hashing strategy ([HashManager.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/topology/HashManager.js)):
-1.  **Code Hash**: The raw string content of the calculation class.
-2.  **Layer Hash**: Hashes of shared utility layers (`mathematics`, `profiling`) used by the class.
-3.  **Dependency Hash**: A composite hash of all upstream dependencies.
-4.  **Infrastructure Hash**: A hash representing the underlying system environment.
-5.  **System Epoch**: A manual versioning flag to force global re-computation.
-
-This results in a `Composite Hash`. If this hash matches the `storedHash` in the database, execution can be skipped entirely.
-
-## 4. Execution Engine: Flow, Resilience & Optimization
-
-The `WorkflowOrchestrator` acts as the runtime kernel, utilizing [StandardExecutor](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/executors/StandardExecutor.js#16-257) and [MetaExecutor](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/executors/MetaExecutor.js#12-83) for the heavy lifting.
-
-### 4.1 Content-Based Dependency Short-Circuiting
-A major optimization (O(n) gain) is the **Content-Based Short-Circuiting** logic found in [WorkflowOrchestrator.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/WorkflowOrchestrator.js):
-Even if an upstream dependency *re-runs* (e.g., its timestamp changed), its *output* might be identical to the previous run.
-1.  The system tracks `ResultHash` (hash of the actual output data).
-2.  When checking dependencies for Node B (which depends on A), if A has re-run but its `ResultHash` is unchanged from what B used last time, B **does not need to re-run**.
-3.  This effectively stops "change propagation" dead in its tracks if the data change is semantically null.
-
-### 4.2 Batch Flushing & OOM Prevention
-Financial datasets (processing 100k+ users with daily portfolios) often exceed Node.js heap limits. The [StandardExecutor](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/executors/StandardExecutor.js#16-257) implements a **Streaming & Flushing** architecture:
-*   **Streams** inputs (Portfolio/History) using generators (`yield`), preventing loading all users into memory.
-*   **Buffers** results in a `state` object.
-*   **Flushes** to the database (Firestore/Storage) every $N$ users (e.g., 5000), clearing the internal buffer helps avoid Out-Of-Memory crashes.
-*   **Incremental Sharding**: It manages shard indices dynamically to split massive result sets into retrievable chunks.
-
-### 4.3 Handling "Impossible" States
-If a dependency fails or is missing critical data, the Orchestrator marks dependent nodes as `IMPOSSIBLE` rather than failing them. This allows the rest of the graph (independent branches) to continue execution, maximizing system throughput even in a partially degraded state.
-
-## 5. Advanced Application: Psychometrics & Risk Geometry
-
-The capabilities of this computation engine are best demonstrated by the [profiling.js](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/layers/profiling.js) layer it powers. Because the DAG ensures all historical and portfolio data is perfectly aligned, we can run sophisticated O(n^2) or O(n log n) algorithms on user data reliably.
-
-### 5.1 "Smart Money" & Cognitive Profiling
-The system executes a [UserClassifier](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/layers/profiling.js#382-399) that computes:
-*   **Risk Geometry**: Using the **Monotone Chain** algorithm to compute the Convex Hull of a user's risk/reward performance (Efficient Frontier analysis).
-*   **Psychometrics**: Detecting "Revenge Trading" (increasing risk after losses) and "Disposition Skew" (holding losers too long).
-*   **Attribution**: Separating "Luck" (market beta) from "Skill" (Alpha) by comparing performance against sector benchmarks.
-
-These complex models depend on the *guarantee* provided by the DAG that all necessary history and price data is pre-computed and available in the [Context](file:///C:/Users/aiden/Desktop/code_projects/Bulltrackers2025/Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/computation-system/simulation/Fabricator.js#20-69).
-
-## 6. Conclusion
-
-The BullTrackers Computation System represents a shift from "Action-Based" to "State-Based" architecture. By encoding the domain logic into a Directed Acyclic Graph, we achieve a system that is self-healing, massively scalable via short-circuiting and batching, and capable of supporting deep analytical models. It provides the robustness required for high-stakes financial simulation, ensuring that every decimal point is traceable, reproducible, and verifiable.