xypriss 9.0.13 → 9.1.1

package/docs/core/MEMORY_DETECTION.md

@@ -0,0 +1,206 @@
+# Cross-Platform Memory Detection
+
+XyPriss uses a sophisticated cross-platform memory detection system to provide accurate memory information across all operating systems.
+
+## Architecture
+
+### 1. **MCLI (Memory CLI) Binary** (Primary Method)
+
+-   **Location**: Downloaded to `bin/` directory during installation
+-   **Accuracy**: Highest - uses native OS APIs
+-   **Platforms**: Linux, macOS, Windows (x64 and ARM64)
+-   **Size**: ~3MB per binary
+
+### 2. **Node.js Fallback** (Secondary Method)
+
+-   **Trigger**: When Go CLI is unavailable
+-   **Accuracy**: Good on Linux (uses `/proc/meminfo`), limited on other platforms
+-   **Platforms**: All Node.js supported platforms
+-   **Size**: No additional overhead
+
+## Installation Process
+
+### Automatic Installation (Recommended)
+
+```bash
+npm install xypriss
+# Automatically downloads platform-specific binary during postinstall
+```
+
+### Manual Installation
+
+```bash
+npm run install-memory-cli
+# Downloads binary for current platform
+# Or create a `bin` folder in your projet, download the lastest version of MCLI (choose bellow) then, add it inside the created folder "bin".
+```
+
+### Skip Binary Download (not recommanded)
+
+```bash
+CI=true npm install
+# or
+SKIP_BINARY_DOWNLOAD=true npm install
+```
+
+## Binary Distribution
+
+### CDN Hosting
+
+-   **Base URL**: `https://dll.nehonix.com/dl/mds/xypriss/bin/`
+-   **Binaries**:
+    -   [memory-cli-linux-x64](https://dll.nehonix.com/dl/mds/xypriss/bin/memory-cli-linux-x64)
+    -   [memory-cli-darwin-x64](https://dll.nehonix.com/dl/mds/xypriss/bin/memory-cli-linux-x64)
+    -   [memory-cli-darwin-arm64](https://dll.nehonix.com/dl/mds/xypriss/bin/memory-cli-linux-x64)
+    -   [memory-cli-windows-x64.exe](https://dll.nehonix.com/dl/mds/xypriss/bin/memory-cli-linux-x64)
+    -   [memory-cli-windows-arm64.exe](https://dll.nehonix.com/dl/mds/xypriss/bin/memory-cli-linux-x64)
+
+### Platform Detection
+
+```javascript
+const platform = process.platform; // 'linux', 'darwin', 'win32'
+const arch = process.arch; // 'x64', 'arm64'
+```
+
+## Memory Information Provided
+
+### MCLI Output (JSON)
+
+This is the output based on our test, results may be different based on your system informations.
+
+```json
+{
+    "platform": "linux", // your plateforme type
+    "totalMemory": 8080842752,
+    "availableMemory": 2674950144, // Available for applications
+    "freeMemory": 610963456, // Truly free memory
+    "usedMemory": 5405892608,
+    "usagePercentage": 66.9,
+    "buffersMemory": 72757248, // Linux/Unix only
+    "cachedMemory": 3027869696, // Linux/Unix only
+    "swapTotal": 8334077952,
+    "swapUsed": 1614811136,
+    "swapFree": 6719266816
+}
+```
+
+### Platform-Specific Details
+
+#### Linux
+
+-   **Source**: `/proc/meminfo`
+-   **Key Metric**: `MemAvailable` (includes freeable buffers/cache)
+-   **Accuracy**: Excellent
+
+#### macOS
+
+-   **Source**: `vm_stat` + `sysctl`
+-   **Key Metric**: Free + Inactive + Speculative pages
+-   **Accuracy**: Very Good
+
+#### Windows
+
+-   **Source**: `wmic` + Performance Counters
+-   **Key Metric**: Available Bytes counter
+-   **Accuracy**: Very Good
+
+## Usage in Code
+
+### Basic Usage
+
+```typescript
+import { CrossPlatformMemory as CPM } from "./src/cluster/modules/CrossPlatformMemory";
+
+const memory = new CPM(true); // Enable fallback
+const info = await memory.getMemoryInfo();
+
+console.log(
+    `Available: ${CrossPlatformMemory.formatMemory(info.availableMemory)}`
+);
+```
+
+### Integration with MemoryManager
+
+```typescript
+// Automatically used by MemoryManager (M2)
+const memoryManager = new M2(config);
+const stats = await memoryManager.getSystemMemoryStats();
+```
+
+## Troubleshooting
+
+### Binary Not Found
+
+```
+Memory CLI binary not found. Searched:
+  - /path/to/bin/memory-cli-linux-x64
+  - /path/to/bin/memory-cli
+  - /path/to/tools/memory-cli/../../bin/memory-cli-linux-x64
+Run 'npm run install-memory-cli' or use fallback mode.
+```
+
+**Solutions**:
+
+1. Run `npm run install-memory-cli`
+2. Check internet connectivity
+3. Verify CDN accessibility
+4. Use fallback mode (automatic)
+
+### Permission Issues
+
+```bash
+chmod +x bin/memory-cli-*
+```
+
+### CI/CD Environments
+
+Set `CI=true` or `SKIP_BINARY_DOWNLOAD=true` to skip binary download and use fallback mode.
+
+## Performance Comparison
+
+| Method               | Linux        | macOS        | Windows      | Accuracy | Speed |
+| -------------------- | ------------ | ------------ | ------------ | -------- | ----- |
+| MCLI                 | ✅ Excellent | ✅ Excellent | ✅ Excellent | 95%+     | Fast  |
+| Node.js + /proc      | ✅ Very Good | ❌ Limited   | ❌ Limited   | 90%      | Fast  |
+| Node.js os.freemem() | ⚠️ Poor      | ⚠️ Poor      | ⚠️ Poor      | 60%      | Fast  |
+
+## Memory Detection Accuracy
+
+## Build Process
+
+### Local Development
+
+```bash
+cd tools/memory-cli
+./build.sh
+```
+
+### Cross-Platform Builds
+
+```bash
+# Linux
+GOOS=linux GOARCH=amd64 go build -o memory-cli-linux-x64
+
+# macOS
+GOOS=darwin GOARCH=amd64 go build -o memory-cli-darwin-x64
+GOOS=darwin GOARCH=arm64 go build -o memory-cli-darwin-arm64
+
+# Windows
+GOOS=windows GOARCH=amd64 go build -o memory-cli-windows-x64.exe
+GOOS=windows GOARCH=arm64 go build -o memory-cli-windows-arm64.exe
+```
+
+## Security Considerations
+
+1. **Binary Verification**: CLI includes `--help` verification
+2. **CDN Security**: HTTPS-only downloads
+3. **Fallback Safety**: Graceful degradation to Node.js methods
+4. **No Elevation**: No admin/root privileges required
+
+## Future Enhancements
+
+1. **Binary Signing**: Code signing for enhanced security
+2. **Compression**: Reduce binary sizes with UPX
+3. **Caching**: Local cache for repeated downloads
+4. **Auto-Updates**: Automatic binary updates
+

package/docs/core/MIDDLEWARE_ARCHITECTURE.md

@@ -0,0 +1,227 @@
+# Middleware Architecture
+
+## Overview
+
+XyPriss uses a **clean, layered middleware architecture** with a single source of truth for all middleware implementations.
+
+## Architecture Layers
+
+```
+┌─────────────────────────────────────────────────┐
+│         User Configuration (config.ts)          │
+│    ServerOptions.security.cors, helmet, etc.    │
+└────────────────┬────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────┐
+│        SecurityMiddleware (Orchestrator)        │
+│   - Reads SecurityConfig from ServerOptions     │
+│   - Applies security logic and policies         │
+│   - Delegates to BuiltInMiddleware              │
+└────────────────┬────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────┐
+│   BuiltInMiddleware (Single Source of Truth)    │
+│   - Wraps external libraries (cors, helmet)     │
+│   - Provides consistent defaults                │
+│   - Handles all middleware initialization       │
+└────────────────┬────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────┐
+│      External Libraries (cors, helmet, etc.)    │
+└─────────────────────────────────────────────────┘
+```
+
+## Key Principles
+
+### 1. Single Source of Truth
+**`BuiltInMiddleware`** is the ONLY place that imports external middleware libraries:
+- ✅ `cors`
+- ✅ `helmet`
+- ✅ `express-rate-limit`
+- ✅ `compression`
+- ✅ `hpp`
+- ✅ `express-mongo-sanitize`
+- ✅ `csrf-csrf`
+- ✅ `multer`
+
+### 2. No Duplicate Imports
+❌ **NEVER** import middleware libraries directly in other files
+✅ **ALWAYS** use `BuiltInMiddleware.cors()`, `BuiltInMiddleware.helmet()`, etc.
+
+### 3. Clear Separation of Concerns
+
+#### BuiltInMiddleware (`src/middleware/built-in/BuiltInMiddleware.ts`)
+- **Purpose**: Wrapper layer for external libraries
+- **Responsibility**: Provide consistent defaults and interfaces
+- **Example**:
+```typescript
+static cors(options: any = {}) {
+    const defaultOptions = {
+        origin: true,
+        methods: ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"],
+        credentials: false,
+        maxAge: 86400,
+    };
+    return cors({ ...defaultOptions, ...options });
+}
+```
+
+#### SecurityMiddleware (`src/middleware/security-middleware.ts`)
+- **Purpose**: Security orchestration and policy enforcement
+- **Responsibility**: Apply security configurations and combine middleware
+- **Example**:
+```typescript
+private initializeMiddleware(): void {
+    if (this.cors !== false) {
+        this.corsMiddleware = BuiltInMiddleware.cors(corsConfig);
+    }
+}
+```
+
+## Configuration Flow
+
+### 1. User Configuration
+```typescript
+// config.ts
+export const config = {
+    security: {
+        enabled: true,
+        cors: {
+            origin: "*",
+            methods: ["GET", "POST"],
+            allowedHeaders: ["Content-Type", "Authorization"],
+            credentials: true,
+        },
+    },
+};
+```
+
+### 2. Server Initialization
+```typescript
+// ServerFactory.ts → FastServer.ts
+const server = new XyPrissServer(options);
+// FastServer.initializeSecurity() creates SecurityMiddleware
+```
+
+### 3. SecurityMiddleware Initialization
+```typescript
+// SecurityMiddleware constructor
+this.cors = config.cors !== false ? (config.cors || true) : false;
+this.initializeMiddleware();
+```
+
+### 4. BuiltInMiddleware Usage
+```typescript
+// SecurityMiddleware.initializeMiddleware()
+this.corsMiddleware = BuiltInMiddleware.cors(corsConfig);
+```
+
+### 5. Middleware Application
+```typescript
+// SecurityMiddleware.applySecurityStack()
+if (this.cors !== false && this.corsMiddleware) {
+    middlewareStack.push(this.corsMiddleware);
+}
+```
+
+## Multi-Server Mode
+
+In multi-server mode, security configuration is properly deep-merged:
+
+```typescript
+// MultiServerManager.mergeServerConfig()
+merged.security = {
+    ...merged.security,
+    ...serverConfig.security,
+    // Deep merge CORS config
+    cors: serverConfig.security.cors !== undefined
+        ? (typeof serverConfig.security.cors === 'object' && 
+           typeof merged.security?.cors === 'object'
+            ? { ...merged.security.cors, ...serverConfig.security.cors }
+            : serverConfig.security.cors)
+        : merged.security?.cors
+};
+```
+
+## Benefits
+
+### ✅ Maintainability
+- Single place to update middleware wrappers
+- Easy to add new middleware
+- Clear dependency management
+
+### ✅ Consistency
+- All middleware uses same configuration pattern
+- Consistent defaults across the application
+- Predictable behavior
+
+### ✅ Testability
+- Easy to mock BuiltInMiddleware
+- Clear interfaces for testing
+- Isolated concerns
+
+### ✅ Developer Experience
+- Simple, intuitive configuration
+- Type-safe with TypeScript
+- Clear documentation
+
+## Adding New Middleware
+
+To add new middleware to the system:
+
+1. **Add to BuiltInMiddleware**:
+```typescript
+// src/middleware/built-in/BuiltInMiddleware.ts
+static newMiddleware(options: any = {}) {
+    const defaultOptions = { /* defaults */ };
+    return externalLibrary({ ...defaultOptions, ...options });
+}
+```
+
+2. **Update SecurityConfig** (if security-related):
+```typescript
+// src/types/mod/security.ts
+export interface SecurityConfig {
+    // ... existing fields
+    newFeature?: boolean | NewFeatureConfig;
+}
+```
+
+3. **Use in SecurityMiddleware**:
+```typescript
+// src/middleware/security-middleware.ts
+if (this.newFeature) {
+    this.newFeatureMiddleware = BuiltInMiddleware.newMiddleware(config);
+}
+```
+
+## Migration Guide
+
+If you find code that imports middleware libraries directly:
+
+### ❌ Before (Bad)
+```typescript
+import cors from 'cors';
+import helmet from 'helmet';
+
+const corsMiddleware = cors({ origin: "*" });
+```
+
+### ✅ After (Good)
+```typescript
+import { BuiltInMiddleware } from './built-in/BuiltInMiddleware';
+
+const corsMiddleware = BuiltInMiddleware.cors({ origin: "*" });
+```
+
+## Summary
+
+The refactored architecture provides:
+- **Single Source of Truth**: BuiltInMiddleware
+- **Clean Separation**: Configuration → Security → BuiltIn → External
+- **Easy Maintenance**: One place to update
+- **Type Safety**: Full TypeScript support
+- **Developer Friendly**: Simple, intuitive API

package/docs/core/SERVER_CORE_ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Server Core Architecture
+
+XyPriss features a unique **Hybrid Architecture** that combines the raw performance of Rust with the high-level productivity of TypeScript. This dual-core approach ensures microsecond routing latency while maintaining the rich ecosystem of Node.js.
+
+## The Hybrid Strategy
+
+XyPriss is composed of two primary layers that work in tandem:
+
+### 1. XHSC (XyPriss Hyper-System Core) - The Rust engine
+
+The "hot path" of the server is implemented in Rust. This layer is responsible for:
+
+- **Direct Network Handling**: Manages the low-level TCP/HTTP(S) stack for maximum throughput.
+- **Nano-Routing**: Uses a high-performance **Radix Tree** implementation to match incoming requests to their handlers with microsecond precision.
+- **System Intelligence**: Real-time hardware telemetry and system-level monitoring (CPU, RAM, Disk).
+- **Static Asset Delivery**: Ultra-fast serving of static files directly from Rust memory.
+
+### 2. TypeScript/Node.js Layer - The Application core
+
+The high-level logic where developers spend most of their time. This layer handles:
+
+- **Business Logic**: Complex application rules and data processing.
+- **Security Middlewares**: A stack of 12+ enterprise-grade security modules (CSRF, XSS, etc.).
+- **Plugin Management**: Permission-based extensions that enhance server capabilities.
+- **IPC Bridge**: Communicates with XHSC via a high-speed inter-process communication bridge to receive and respond to HTTP requests.
+
+---
+
+## Request Lifecycle
+
+1.  **Ingress**: A request hits the **XHSC (Rust)** engine.
+2.  **Fast Match**: XHSC immediately performs a Radix Tree lookup to identify the route.
+3.  **Dispatch**: The request is bridged to the **Node.js** layer via a high-performance IPC mechanism.
+4.  **Enhancement**: Node.js decorates the raw message with `RequestEnhancer` and `ResponseEnhancer` for Express-compatible APIs.
+5.  **Middleware Stack**: The request passes through the configured security and utility middlewares.
+6.  **Handler**: The route handler or plugin logic executes and produces a response.
+7.  **Egress**: The response is sent back through the bridge to XHSC, which delivers it to the client.
+
+## Core Components
+
+### XHSCBridge
+
+The specialized component in Node.js that manages the lifecycle of the Rust binary and handles the binary-level communication.
+
+### HttpServer (Virtual Server)
+
+A virtualized server implementation in Node.js that mimics the native Node.js `http.Server` API while delegating actual network listening to XHSC.
+
+### Request & Response Enhancers
+
+Modules that transform low-level IPC messages into feature-rich objects supported by the XyPriss API, providing methods like `res.json()`, `res.send()`, and cookie management.
+
+### Trust Proxy System
+
+A high-performance utility integrated into the request lifecycle to handle IP-based security and identification, supporting IPv4/IPv6 CIDR and multi-layer proxy setups.
+
+---
+
+## Performance Benefits
+
+- **Eliminated Node.js Event Loop Blockage**: Low-level networking doesn't compete with application JS for the event loop.
+- **Parallel Routing**: XHSC matching happens in native threads, allowing high concurrency even under heavy load.
+- **Reduced Memory Overhead**: Static assets and routing tables are handled in Rust's efficient memory model.
+
+---
+
+[← Back to Features Overview](./FEATURES_OVERVIEW.md) • [Deep Dive into XHSC Intelligence](./XHSC_CORE.md)
+

package/docs/core/WORKSPACE_SYSTEM.md

@@ -0,0 +1,97 @@
+# XyPriss Internal & Plugin Workspace System
+
+## Overview
+
+The XyPriss Workspace System provides a mechanism for developers and plugin contributors to define specialized system instances (like `$plug`) with restricted filesystem access and isolated logic execution. This is particularly useful for building plugins that need to manage their own workspace without interfering with the main project root.
+
+## Configuration
+
+Specialized systems are configured in the `xypriss.config.json` file under the `$internal` key.
+
+### Example Configuration
+
+```json
+{
+    "__sys__": {
+        "__name__": "My-App"
+    },
+    "$internal": {
+        "$plug": {
+            "__xfs__": {
+                "path": "#$/.private"
+            },
+            "__meta__": {
+                "path": "#$/.private/.meta"
+            }
+        }
+    }
+}
+```
+
+### Configuration Parameters
+
+| Parameter       | Type     | Description                                                                                      |
+| :-------------- | :------- | :----------------------------------------------------------------------------------------------- |
+| `__xfs__`       | `object` | Defines a specialized xypriss filesystem instance.                                               |
+| `__xfs__.path`  | `string` | The root path for the specialized filesystem. Supports `#$` or `$#` for project root resolution. |
+| `__meta__`      | `object` | Defines logic execution paths.                                                                   |
+| `__meta__.path` | `string` | Path to a file or directory containing `+xypriss.meta.ts` logic.                                 |
+
+## Usage in Code
+
+Once configured, the specialized system is automatically added to the global `__sys__` object.
+
+### Accessing the Workspace FileSystem
+
+You can access the specialized filesystem using the name defined in the config (e.g., `$plug`).
+
+```typescript
+import { type XyPrissSys } from "xypriss";
+
+export function myPlugin() {
+    // Both properties point to the same specialized workspace
+    const workspaceA = (__sys__ as XyPrissSys).$plug;
+    const workspaceB = (__sys__ as XyPrissSys).$plg;
+
+    // Using the short alias for file operations
+    const files = workspaceB?.$lsDirs(".");
+}
+```
+
+## Distributed Configuration & Auto-Discovery
+
+XyPriss supports a distributed configuration model, allowing plugins and internal modules to provide their own `xypriss.config.json` files. The system automatically scans for these files in standard project directories:
+
+-   Project Root
+-   `/plugins/*`
+-   `/mods/*`
+-   `/simulations/*`
+-   `/shared/*`
+
+This enables plugin contributors to define their own workspaces and meta-logic without requiring manual configuration from the end-user.
+
+## Path Resolution Placeholders
+
+The path resolver supports two main types of resolution:
+
+-   **Project Root Resolution**: Using `#$` or `$#` will resolve the path relative to the **Global Project Root** (the highest directory containing a `xypriss.config.json` or `package.json`).
+-   **Local Resolution**: Any standard relative path (e.g., `./.private` or `workspace/data`) will be resolved relative to the **directory containing the specific configuration file** being processed.
+
+### Format Flexibility
+
+The resolver is whitespace-aware and robust against extra spaces around slashes or placeholders.
+
+-   `"$ # / simulations"` resolves correctly to the project's simulations folder.
+-   `"./ .meta"` (in a plugin folder) resolves correctly to that specific plugin's `.meta` directory.
+
+## Error Reporting
+
+The system provides detailed error logs if a configuration cannot be parsed or if a defined `__xfs__` or `__meta__` path is unresolvable, facilitating easier debugging for plugin developers.
+
+## Meta Logic Execution
+
+The system automatically scans defined `__meta__` paths for `+xypriss.meta.ts/js` files.
+
+-   If the path is a file, it executes the exported `run()` function.
+-   If the path is a directory, it searches for `+xypriss.meta.ts/js` within that directory (and specialized subfolders like `.meta`).
+

package/docs/core/XHSC_CORE.md

@@ -0,0 +1,90 @@
+# XHSC: XyPriss Hyper-System Core
+
+**XHSC** is the high-performance cornerstone of the XyPriss framework. Written in **Rust**, it is designed to be a lean, ultra-fast, and secure networking engine that powers the underlying infrastructure of XyPriss applications.
+
+## Key Responsibilities
+
+### 1. High-Performance Routing
+
+Unlike traditional middleware-based routers that iterate sequentially, XHSC uses a **Radix Tree (Trie)** for route matching.
+
+- **Latency**: Nanosecond-to-microsecond lookup times.
+- **Concurrency**: Lock-free read operations allow multiple requests to be routed in parallel without lock contention.
+- **Support**: Handles static paths, dynamic parameters (`:id`), and wildcards (`*`).
+
+### 2. IPC Bridge Architecture
+
+XHSC communicates with one or more Node.js worker processes via a specialized **IPC Bridge**.
+
+- **Efficiency**: Optimized binary communication over Unix Domain Sockets or Pipes.
+- **Isolation**: Crashes in the application layer (Node.js) do not affect the stability of the gateway (XHSC).
+- **Control**: Handles request timeouts and connection keep-alive at the native level.
+
+### 3. Native Telemetry
+
+XHSC provides high-precision system metrics without the overhead of spawner-based collectors.
+
+- **Real-time Stats**: Memory usage, CPU load, and network throughput.
+- **Hardware Info**: Built-in discovery of CPU cores, architecture, and disk topology.
+- **Cache-Optimized**: Intelligent caching of system calls to reduce kernel overhead.
+
+### 4. Security Gateway
+
+Embedded security features at the native level:
+
+- **Request Validation**: Early rejection of malformed or oversized requests before they hit the JS engine.
+- **Concurrency Control**: Native-level tracking of active requests per IP and server-wide to prevent starvation.
+- **TLS/SSL**: Capability to handle encryption natively for industry-standard performance.
+
+## Unified Timeout Management
+
+XHSC implements a multi-layer timeout strategy that synchronizes native enforcement with application-level callbacks.
+
+- **Native Enforcement**: Rust handles the gateway timeout, ensuring system resources are freed even if a worker process hangs.
+- **Node.js Synchronization**: The bridge automatically calculates the maximum timeout across all routes and applies it to the Rust gateway with a **+2 second buffer**.
+- **Callback Support**: The buffer ensures that JavaScript `onTimeout` handlers have the chance to execute and return custom responses before the native layer cuts the connection.
+- **Infinite Mode**: Setting `enabled: false` in the configuration instructs Rust to use an "unlimited" timeout (100 years), effectively disabling the enforcement layer while maintaining the structured IPC protocol.
+
+## Ultra-Low Latency Concurrency Control
+
+XHSC leverages Rust's async runtime to provide concurrency controls that are orders of magnitude faster than JavaScript-based middleware.
+
+- **Zero-Overhead Semaphores**: Uses `tokio::sync::Semaphore` to manage concurrent request limits with virtually zero CPU cost.
+- **Atomic Queue Tracking**: Queue depth is tracked using atomic integers, ensuring thread safety and extreme performance.
+- **Fail-Fast Queuing**: Requests waiting in the queue for longer than the configured `queueTimeout` are automatically rejected with a `503 Service Unavailable` error, preserving system stability under load.
+- **Per-IP Limits**: Native tracking of **active requests** per IP address prevents single-source DoS attacks from starving the system.
+
+## Design Philosophy
+
+- **Zero-Cost Abstractions**: Leveraging Rust to ensure that the infrastructure doesnt become a bottleneck.
+- **Thread Safety**: Built on top of the `Tokio` runtime for scalable asynchronous I/O.
+- **Memory Safety**: Guaranteed memory safety without a garbage collector.
+
+### 5. Intelligence Engine
+
+The **Intelligence Engine** is a proactive system stability manager embedded within the Rust core. It is designed to prevent "hard crashes" and mitigate the impact of OOM (Out-of-Memory) killers.
+
+- **Pre-Allocation & Reserve**: XHSC acts as a "Resource Guardian" by pre-allocating a configurable chunk of memory (default ~25% of max) at startup.
+    - **Behavior**: This memory is held in reserve and is guaranteed to be available to the system.
+    - **Activation**: When system memory pressure reaches **critical levels (>90%)**, the engine _releases_ this reserved memory back to the OS. This sudden influx of free memory provides a crucial buffer window for the OS and Node.js GC to recover without killing the process.
+- **Proactive GC Signaling**: The engine continuously monitors worker resource usage.
+    - **High Pressure (>75%)**: Automatically broadcasts `ForceGC` signals to Node.js workers, triggering garbage collection before limits are hit.
+- **Rescue Mode**: If all worker processes crash simultaneously (e.g., due to a bad deployment or fatal error), XHSC instantly enters **Rescue Mode**.
+    - It serves a fallback `503 Service Unavailable` response directly from Rust (zero allocation).
+    - It automatically attempts to respawn workers in the background.
+    - Once workers notify readiness, traffic is seamlessly resumed.
+
+---
+
+## Technical Specifications
+
+- **Language**: Rust
+- **Runtime**: Tokio (Multi-threaded)
+- **Router**: Matchit-based Radix Trie
+- **Communication**: Custom IPC Protocol
+- **Telemetry**: Pure native syscalls
+
+---
+
+[← Back to Core Architecture](./SERVER_CORE_ARCHITECTURE.md)
+