R(t) = R_base + Pressure + Momentum + ScarTissue

Atrion ⚡

Physics-based concurrency control for Node.js. Replaces static rate limits with Z-Score auto-tuning, deterministic backpressure, and priority-based load shedding.

---

The Problem

Traditional circuit breakers fail in three ways:

Problem	Symptom
Binary thinking	ON/OFF flapping during recovery
Static thresholds	Night traffic triggers alerts, peak traffic gets blocked
No memory	Same route fails 100x, system keeps trying

The Solution: Physics

Atrion models your system as an electrical circuit. Each route has resistance that changes based on telemetry:

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.

Mathematical Foundation

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.

Gray Failure Detection

"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.

Momentum-Based Retry Storm Prevention

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.

Auto-Tuning: Eliminating Magic Numbers

"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

What This Means in Production

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

npm install atrion

v2.0 API (Recommended)

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'

v1.x API (Still Supported)

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) 🚀

Rust/WASM Physics Engine

Optional Rust-powered physics core for 1000x performance improvement:

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)

🔌 Pluggable State Architecture (RFC-0008)

Swappable state backends for different deployment scenarios:

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

🔮 Adaptive Thresholds (RFC-0007)

No more manual tuning. Atrion learns your baseline:

dynamicBreak = μ(R) + 3σ(R)

Night traffic (low μ) → tight threshold. Peak hours (high μ) → relaxed threshold.

🛡️ Priority Load Shedding

Different SLOs for different routes. Protect checkout, shed search:

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.

🔌 Circuit Breaker That Heals

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:

# 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

See lab/README.md for all scenarios.

---

License

Apache-2.0