Architectural Scope:
QRES is intentionally narrow. Misuse will fail.
Read SCOPE.md before deployment or evaluation.
Honest nodes converge to consensus while coordinated attackers are ignored; evolved genes propagate to heal the swarm under packet loss and bandwidth limits.
QRES is a decentralized operating system for Edge AI Swarms. It solves the "Consensus vs. Bandwidth" dilemma by replacing floating-point math with deterministic fixed-point arithmetic (Q16.16) and exchanging small "Evolved Genes" instead of massive gradient models.
v19.0.1 SecureANDsafe Hardening:
- ZK Proofs: Sigma protocol proofs for weight transitions verify neuron legitimacy without exposing weights.
- Sybil Defense:
ReputationTrackerbans malicious nodes; 50/50 Sybil attackers banned within 4 rounds. - Formal Verification: TLA+ spec proves liveness under 90% packet loss.
- Predictive Intelligence: PreStorm regime detection provides 4-tick early warning before entropy spikes.
- Compression: Bottleneck autoencoder achieves 6.7x compression (22 bytes for Summary Genes).
- Signal Recovery: BFP-16 VarianceMonitor auto-tunes for vanishing gradients (<10^-7).
v19.0 Adversarial Hardening:
- Drift Defense: Replaced Krum with Coordinate-wise Trimmed Mean, reducing vulnerability to "Inlier Bias" attacks (Drift < 5% under active attack).
-
Precision: Introduced BFP-16 (Block Floating Point), enabling stable training at
$LR=10^{-5}$ without vanishing gradients, solving theI16F16precision floor. - Onboarding: "Mid-Flight Join" protocol allows nodes to sync via 74-byte Summary Genes, achieving >99% bandwidth reduction vs history replay.
v18.0 Benchmark Highlights:
- Compression: Custom Static Laplace Range Coder achieves 1.40x compression, beating ZSTD (1.39x) on prediction residuals while maintaining bit-perfect determinism.
- Efficiency: Swarms converge 12x faster (wall-clock) than Federated Learning on constrained IoT networks (56kbps), consuming 99% less bandwidth.
- Scalability: Secure Aggregation proven linearly scalable (O(N)) for trusted peers. 🛡️ Byzantine Fault Tolerance: Deterministic I16F16 coordinate-wise trimmed mean keeps consensus stable across mixed-architecture swarms (ARM/ESP32/x86).
- Deterministic Rematerialization replaces state shipping: nodes replay training steps locally to reach consensus under tight bandwidth budgets.
- Aggregator resilience: coordinate-wise trimmed mean (Multi-Krum) delays breakdown ~2× vs Mean and ~3× vs Median before the 5% drift threshold; see research/Ablation_Study.md.
- Precision engine: BFP-16 matches Float32 on MNIST and prevents I16F16 update stalling at
$LR=10^{-5}$ . - Onboarding and scale: Summary Genes cut join bandwidth by ~99.95% (≈150 B vs 312 KB) with zero divergence for mid-flight joiners; resilience holds to ~30% coordinated bias when
$f < 0.33$ . - Production boundaries: continuous/differentiable inputs only, model size capped by the smallest node (~320 KB), soft real-time only; see docs/SCOPE.md for the negative space.
The system is architected as three interlocking layers:
- The Body (
qres_core): Ano_stdRust library for deterministic inference and fragmentation. - The Mind (
swarm_sim): An ECS-based simulator demonstrating emergent healing behavior. - The Hippocampus: A persistent storage layer enabling Lamarckian evolution across reboots.
- Consensus-first math: Q16.16 fixed-point removes cross-arch float drift, keeping 1,000 heterogeneous devices in deterministic lockstep.
- Bandwidth as the bottleneck: By shrinking updates to kilobyte genes, swarms converge faster in wall-clock time on LoRa/NB-IoT even if they need more epochs.
- Swarm-scale parallelism: Parallelism lives at the node level (many daemons), while each node stays single-threaded for determinism (see docs/adrs/ADR-004-concurrency-model.md).
- End-to-end resilience: MTU-aware gene gossip and persistence mean mutations survive drops and reboots; see docs/CLOUD_BENCHMARK_RESULTS.md for measured gains.
The transition to Block Floating Point (Bfp16Vec) eliminates the "Precision Floor" of simple fixed-point math while maintaining bit-perfect determinism.
The "Summary Gene" protocol (v19.0) enables nodes to join ongoing swarms by downloading a compressed state vector rather than the full transaction history.
| Metric | Result | vs. Baseline | Verified On |
|---|---|---|---|
| Scalability | 10,000 Nodes (100% Success) | 20x Scale | Azure Standard_D2s (2 vCPU) |
| Compression | 31.8x (SmoothSine) | 1.5x Neural Gain | Azure Standard_F2s |
| Memory | < 1 KB / Node | O(1) Overhead | Rust no_std Runtime |
Benchmarks verified on January 16, 2026 using automated Azure CI/CD pipelines. See docs/BENCHMARKS.md for full results.
Located in crates/qres_core/, this is a no_std Rust library implementing:
- Q16.16 Fixed-Point Arithmetic: Eliminates floating-point drift across x86, ARM, and WASM platforms.
- Deterministic Compression: All prediction errors use integer math, making behavior reproducible across devices.
- SwarmNeuron Trait: Abstract interface for neural processors with signature methods:
predict(),check_surprise(),adapt(),export_gene(),install_gene(). - LinearNeuron Implementation: 8-lag linear predictor with entropy tracking and refractory periods.
- Regime Switching: Automatic transition between Calm, Storm, and Adapting states based on entropy thresholds.
See: API Reference | Specification
Located in tools/swarm_sim/, this Bevy-based 3D simulator demonstrates:
- Living Brain Visualization: 150 nodes forming a force-directed spherical network with organic physics.
- Interactive Camera: Mouse-drag to orbit, scroll to zoom, spacebar for auto-rotation.
- Noise Zone Physics: A moving interference zone that induces storms and forces mutations.
- Gene Gossip Protocol: Panicked (Red) nodes request cure genes from evolved (Purple) neighbors.
- Dense Neural Web: Real-time connection visualization with color-coded synapse activity.
- HUD Metrics: Live display of node counts, entropy, synapses, and packet traffic.
- Reset Function: Press R to clear saved genes and restart evolution from scratch.
- Cinematic Rendering: HDR bloom, TonyMcMapface tonemapping, pulsing evolved nodes.
See: Theory of Emergence | P2P Implementation
Located in crates/qres_core/src/cortex/storage.rs, this layer provides:
- GeneStorage Trait: Abstract persistence interface,
no_stdcompatible. - DiskGeneStorage Implementation: Saves evolved genes to
./swarms_memory/directory. - Auto-Loading on Spawn: Nodes check disk for saved genes on initialization; if found, spawn as evolved.
- Periodic Persistence: Every 5 seconds, calm evolved nodes save their bytecode to disk.
- Lamarckian Evolution: Learned strategies survive simulation restarts.
Coordinate-wise trimmed mean (Multi-Krum variant) replaces legacy Krum to resist coordinated inlier bias. The v19 ablation sweep shows breakdown thresholds across biases:
- Naive Mean fails by 15% bias; Median fails immediately at 5%.
- Trimmed Mean holds drift-probability 0% at 5% and delays breakdown to 10%+, with lower drift magnitudes at 20%+.
- Full study and dataset: research/Ablation_Study.md
- Recommendation: set
expected_byzantines_fractionto 1.5× expected Sybil budget; expect resilience up to ~30% coordinated bias in this workload.
Convergence benchmarks showing 100 nodes reaching consensus on a shared predictive model in under 30 epochs, using only 8 KB of bandwidth per day per node. Traditional federated learning requires 60,000x more bandwidth and 12x longer wall-clock time on constrained IoT networks.
- Rust 1.70+ (install via rustup)
- Cargo (included with Rust)
- Optional: OBS or Windows Game Bar for recording simulations
cargo run -p swarm_sim --releaseA Bevy window opens titled "QRES Living Brain: Neural Swarm Visualization." You will observe:
- Force-Directed Brain: 150 nodes form a cohesive spherical neural network with organic movement.
- Noise Zone: A red interference zone orbits through the brain, inducing storms in affected nodes.
- Evolution Cascade: Purple nodes spontaneously mutate and spread their cure to panicking red neighbors.
- Dense Neural Web: Connections visualize communication paths—purple for evolved pairs, cyan for mixed.
| Key | Action |
|---|---|
| Left-click + drag | Orbit camera around the brain |
| Scroll wheel | Zoom in/out |
| Spacebar | Toggle auto-rotation on/off |
| R | Reset simulation (clears all evolved genes) |
The top-left overlay displays real-time swarm statistics:
- Nodes: Total count and evolved percentage
- Entropy: Storm activity level (0% = calm, 100% = chaos)
- Synapses: Active communication channels
- Packets: Gene transfers in-flight
After running for 30+ seconds:
- Stop the simulator (Ctrl+C).
- List saved genes:
ls swarms_memory/ - Restart:
cargo run -p swarm_sim --release - Observe: Nodes that were purple before now spawn purple immediately. Their learned strategies persisted.
All crates compile to both std and no_std targets:
# Core crate (no_std)
cargo build -p qres_core --no-default-features --release
# Daemon (std)
cargo build -p qres_daemon --release
# Simulator (std + Bevy)
cargo build -p swarm_sim --release
# Run all tests
cargo test --allComplete documentation is organized in the docs/ directory:
| Category | Files |
|---|---|
| Core Architecture | SPEC.md, API_REFERENCE.md |
| Theory & Research | THEORY.md, SNN_ENERGY_ANALYSIS.md |
| Implementation Guides | P2P_IMPLEMENTATION.md, SECURITY_IMPLEMENTATION_GUIDE.md |
| Process | CONTRIBUTING.md, SECURITY_ROADMAP.md |
| Benchmarks | BENCHMARKS.md, CLOUD_BENCHMARK_RESULTS.md, COST_COMPARISON.md |
| Media | IMAGES.md |
For a complete index, see docs/README.md.
QRES/
├── crates/
│ ├── qres_core/ # Core no_std library (Body + Hippocampus)
│ │ └── src/cortex/ # SwarmNeuron trait, LinearNeuron, GeneStorage
│ ├── qres_daemon/ # Daemon service for edge deployment
│ └── qres_wasm/ # WebAssembly bindings
├── tools/
│ └── swarm_sim/ # Bevy-based God View simulator (Mind)
├── docs/ # Comprehensive documentation
├── tests/ # Integration tests
└── README.md # This file
Deterministic fixed-point arithmetic core. No floating-point operations. Runs on x86, ARM, WASM. Constraint: no_std with alloc.
Key modules:
cortex/: Neural computing (SwarmNeuron trait, LinearNeuron, GeneStorage)adaptive/: Regime switching and entropy trackingcompression/: Deterministic compression algorithmscrypto/: Curve25519-based zero-knowledge proofs
Bevy-based ECS simulator demonstrating emergent swarm behavior under network constraints. This is where evolution, mutation, and healing are visualized.
Key systems:
simulate_cortex_reaction: React to noise zonetrigger_evolution: Random mutationsgossip_protocol: Gene requests between neighborspacket_physics_system: MTU fragmentation and packet lossprocess_incoming_packets: Gene installation
Persistence layer enabling learned strategies to survive reboots. Trait-based design allows swapping implementations (disk, cloud, IPFS).
Contributions are welcome. See CONTRIBUTING.md for guidelines, development workflow, and architecture decision records (ADRs).
Dual-licensed under MIT or Apache-2.0, at your option.
If you use QRES in research, please cite:
@software{qres2026,
author = {Krenik, Cavin},
title = {QRES: Neural Swarm Operating System},
url = {https://github.com/CavinKrenik/QRES},
doi = {10.5281/zenodo.18193905},
year = {2026}
}See CITATION.cff for additional metadata.
| Paper | Venue | DOI |
|---|---|---|
| Deterministic Rematerialization: Convergent Evolution in Cloud Kernels and Edge Swarms | Preprint (2026) |  |
This paper formalizes the theoretical foundation of QRES, identifying a structural isomorphism between IO-aware GPU kernels (FlashAttention, Fused Cross-Entropy) and QRES's silent consensus protocol. Both converge on Deterministic Rematerialization—discarding intermediate state and recomputing on demand—to achieve orders-of-magnitude reductions in data movement.
Status: Stable. Version 19.0.1 (SecureANDsafe Hardening) complete. The pivot from deterministic compression to emergent swarms is verified in simulation. Ready for edge deployment.