Deterministic Physics Engine for Adaptive Traffic Orchestration
npm install atrion
R(t) = R_base + Pressure + Momentum + ScarTissue
`
| Component | What it does |
| --------------- | ---------------------------------------------------- |
| Pressure | Current load (latency, errors, saturation) |
| Momentum | Rate of change (detects problems _before_ they peak) |
| Scar Tissue | Historical trauma (remembers bad routes) |
---
Theory of Operation
> Why physics instead of heuristics?
Traditional circuit breakers and rate limiters introduce complex behavior that often leads to complex failures. Atrion takes a different approach: instead of arbitrary static limits, we model traffic as a physical system with predictable, mathematically guaranteed behavior.
$3
Atrion is built on Control Theory principles (specifically PID-like feedback loops without integral windup) and Fluid Dynamics.
`
Traffic ≈ Fluid with Pressure, Resistance, and Momentum
`
The system ensures stability via a Critical Damping approach. We calculate a 'Scar Tissue' metric that accumulates based on failure severity and decays over time. This creates a _mathematically guaranteed hysteresis loop_, preventing the 'flapping' (rapid open/close) that plagues standard circuit breakers.
$3
> "Dead services are easy. Zombie services are the killers."
Standard health checks fail when a service is _technically alive but behaviorally broken_—responding slowly, returning garbage, or stuck in cleanup loops. Atrion doesn't just count requests; it measures Service Resistance.
Consider this scenario:
1. A processing node receives a complex request
2. It takes longer than expected → upstream times out
3. The cancellation triggers cleanup that also takes too long
4. Meanwhile, upstream retries, but the node is still "cleaning up"
5. Requests queue, the original gets resent, and... cascade failure
A standard rate limiter fails here because RPS might be low, but concurrency saturation is high.
Atrion detects this through:
| Metric | What It Catches |
| -------------- | ----------------------------------- |
| Pressure | Current concurrency/latency stress |
| Resistance | Degraded responses (slow ≠ healthy) |
| Momentum | Rate of degradation (early warning) |
Even if the node is responding (but slowly/wrongly), the resistance spikes. This triggers protective measures _before_ the cascade begins.
$3
The "stuck cleanup" scenario has another killer: retry storms. Atrion implements Momentum-based throttling:
`
If a node is stuck cleaning up, its 'momentum' remains high
even if current RPS is zero.
`
This physically prevents upstream systems from dumping new retries into a node that hasn't "cooled down" yet, regardless of timeout settings. The physics model remembers recent stress even when instantaneous load looks normal.
$3
> "Idiots misconfiguring it" is a valid fear.
That's why Atrion uses Z-Score analysis instead of hardcoded thresholds:
`
dynamicBreak = μ(R) + 3σ(R)
`
The system calculates baseline latency (μ) and deviation (σ) in real-time. If behavior falls outside 3σ, it clamps down. This removes the "magic number guessing" that leads to misconfiguration:
| Scenario | Traditional | Atrion |
| --------------------------------- | ------------------------- | -------------------------- |
| Night traffic (low volume) | Fixed threshold too loose | Tight threshold (low μ) |
| Peak hours (high volume) | Fixed threshold too tight | Relaxed threshold (high μ) |
| New deployment (unknown baseline) | Guess and pray | Learns within minutes |
$3
| Failure Mode | Traditional CB | Atrion |
| -------------------------- | -------------------- | ----------------------- |
| Flapping during recovery | 49+ transitions | 1 transition |
| Zombie service detection | Miss (still "alive") | Catch (high resistance) |
| Retry storm amplification | Passthrough | Momentum blocks |
| Threshold misconfiguration | Silent failures | Self-adjusting |
---
Quick Start
`bash
npm install atrion
`
$3
`typescript
import { Atrion } from 'atrion'
const atrion = new Atrion()
await atrion.connect()
// Make routing decision
const decision = atrion.route('api/checkout', {
latencyMs: 45,
errorRate: 0.01,
saturation: 0.3,
})
if (!decision.allow) {
return res.status(503).json({ error: decision.reason })
}
// decision.resistance = current Ω
// decision.mode = 'BOOTSTRAP' | 'OPERATIONAL' | 'CIRCUIT_BREAKER'
`
$3
`typescript
import { AtrionGuard } from 'atrion'
const guard = new AtrionGuard()
if (!guard.canAccept('api/checkout')) {
return res.status(503).json({ error: 'Service busy' })
}
guard.reportOutcome('api/checkout', {
latencyMs: 45,
isError: false,
saturation: 0.3,
})
`
---
Performance (v2.0-alpha) 🚀
$3
Optional Rust-powered physics core for 1000x performance improvement:
`typescript
import { Atrion } from 'atrion'
const atrion = new Atrion({
useWasm: true, // Enable Rust/WASM engine (experimental)
})
`
#### Benchmark Results
| Function | TypeScript | Rust/WASM | Speedup |
| --------------------- | ---------- | -------------- | ------------ |
| calculateResistance | ~50μs | 2.11 ns | ~25,000x |
| Vector magnitude | ~15μs | 2.12 ns | ~7,000x |
| Throughput | ~20k ops/s | 586M ops/s | ~29,000x |
Rust Physics Core:
- Sub-nanosecond latencies
- SIMD optimization (AVX2 + SIMD128)
- Zero garbage collection
- 13.2KB WASM bundle
> See RFC-0009 for technical details.
---
Key Features (v2.0)
$3
Swappable state backends for different deployment scenarios:
`typescript
import { Atrion, InMemoryProvider } from 'atrion'
const atrion = new Atrion({
provider: new InMemoryProvider(), // Default
autoTuner: true, // Adaptive thresholds
})
`
| Provider | Use Case |
| -------------------- | ------------------------------- |
| InMemoryProvider | Single-node, development |
| RedisStateProvider | Multi-node cluster (basic sync) |
| Atrion Cloud | Smart sync, VIP Lanes, HotPatch |
$3
No more manual tuning. Atrion learns your baseline:
`
dynamicBreak = μ(R) + 3σ(R)
`
Night traffic (low μ) → tight threshold. Peak hours (high μ) → relaxed threshold.
$3
Different SLOs for different routes. Protect checkout, shed search:
`typescript
const checkoutGuard = new AtrionGuard({
config: { scarFactor: 2 }, // Stubborn VIP
})
const searchGuard = new AtrionGuard({
config: { scarFactor: 20 }, // Expendable
})
`
Result: 84% revenue efficiency during Black Friday stress test.
$3
Standard CB stays open until timeout. Atrion exits when resistance drops:
`
R < 50Ω → Exit CB automatically
`
---
Validated Results
| Test | Metric | Result |
| ----------------- | --------------------------- | --------------------- |
| Flapping | Transitions during recovery | 1 vs 49 (standard CB) |
| LOD Degradation | Time to quality switch | 41 ticks (was 91) |
| CB Recovery | Exit from circuit breaker | ✅ at R=49.7Ω |
| Priority Shedding | Revenue protected | 84% efficiency |
---
Documentation
| RFC | Topic |
| ------------------------------------------------------------------------ | ------------------- |
| RFC-0001 | Core Math Model |
| RFC-0007 | Adaptive Thresholds |
| RFC-0008 | Pluggable State |
Full index: documentation/rfc/README.md
---
Wind Tunnel (Lab)
Real-world scenario simulations:
`bash
E-Commerce: VIP priority during DB stress
npx tsx lab/ecommerce/ecommerce-server.ts
npx tsx lab/ecommerce/blackfriday-client.ts
Circuit Breaker: Recovery validation
npx tsx lab/cb-recovery/cb-server.ts
npx tsx lab/cb-recovery/recovery-client.ts
``