feat: crash recovery and warmup enforcement (v1.8.0)

- Add recovery.rs with RecoveryState (Normal/Shock/Coma) and RecoveryAnalyzer
- Detect unclean shutdown (shock) and prolonged inactivity (coma) on startup
- Write graceful shutdown marker before exit
- Add WarmupTracker to CommandHandler with Ping/Stats exemption
- Return WarmingUp error during resurrection for non-exempt ops
- Add shutdown marker read/write to AkashicStore
- Add stability benchmark (10 benchmarks, all sub-microsecond)
- 89 tests passing

Author: laphilosophia

CONTRIBUTING.md

@@ -84,8 +84,8 @@ Look for issues labeled `good first issue` - these are suitable for newcomers.
 
 ## Questions?
 
-- Open a [Discussion](https://github.com/laphilosophia/mindfry/discussions) for questions
-- Check existing [Issues](https://github.com/laphilosophia/mindfry/issues) before opening a new one
+- Open a [Discussion](https://github.com/cluster-127/mindfry/discussions) for questions
+- Check existing [Issues](https://github.com/cluster-127/mindfry/issues) before opening a new one
 
 ## License
 

Cargo.toml

@@ -5,7 +5,7 @@ edition = "2021"
 authors = ["Erdem Arslan <erdemarslan@ymail.com>"]
 description = "Memory with a Conscience"
 license = "Apache-2.0"
-repository = "https://github.com/laphilosophia/mindfry"
+repository = "https://github.com/cluster-127/mindfry"
 keywords = ["database", "graph", "cognitive", "ephemeral", "decay"]
 categories = ["database", "data-structures"]
 
@@ -73,6 +73,10 @@ harness = false
 name = "graph"
 harness = false
 
+[[bench]]
+name = "stability"
+harness = false
+
 # ═══════════════════════════════════════════════════════════════
 # BINARIES
 # ═══════════════════════════════════════════════════════════════

README.md

@@ -25,9 +25,9 @@ MindFry is **subjective** — it processes data through a simulated cognitive la
 - **Strengthen** frequently accessed data (Hebbian learning)
 - **Propagate** stimulation through neural bonds (synaptic chains)
 
-## 🧬 Core Principles
+## Core Principles
 
-### 🧠 Tri-Cortex Architecture
+### Tri-Cortex Architecture
 
 Decisions are made using **Balanced Ternary Logic** (Setun):
 
@@ -37,7 +37,7 @@ Decisions are made using **Balanced Ternary Logic** (Setun):
 
 The database has a **Personality Octet** (8 dimensions) and a **Mood** that affects data prioritization.
 
-### ❤️ Mood & Personality
+### Mood & Personality
 
 > **Note:** Mood affects which data surfaces first, not whether your requests succeed. All data remains accessible — mood just influences the "attention" priority.
 
@@ -48,7 +48,7 @@ Mood modulates the consciousness threshold:
 
 **Override anytime:** Use `BYPASS_FILTERS` flag for guaranteed access regardless of mood.
 
-### 🕸️ Synaptic Propagation
+### Synaptic Propagation
 
 When you `stimulate("A")`:
 
@@ -58,7 +58,7 @@ A (+1.0) → B (+0.5) → C (+0.25) → ... (damped)
 
 Touch one memory, its neighbors tremble.
 
-### 💾 Resurrection
+### Resurrection
 
 Shutdown and restart. The database remembers:
 
@@ -68,17 +68,17 @@ Shutdown and restart. The database remembers:
 
 ## Quick Start
 
-### 🐳 Docker (Recommended)
+### Docker (Recommended)
 
 ```bash
-docker run -d -p 9527:9527 ghcr.io/laphilosophia/mindfry:latest
+docker run -d -p 9527:9527 ghcr.io/cluster-127/mindfry:latest
 ```
 
 ### From Source
 
 ```bash
 # Clone
-git clone https://github.com/laphilosophia/mindfry.git
+git clone https://github.com/cluster-127/mindfry.git
 cd mindfry
 
 # Run server
@@ -125,7 +125,7 @@ console.log(associated.energy) // Increased by propagation
 
 ## License
 
-[Apache-2.0](LICENSE) © [Erdem Arslan](https://github.com/laphilosophia)
+[Apache-2.0](LICENSE) © [Erdem Arslan](https://github.com/cluster-127)
 
 ---
 

benches/stability.rs

@@ -0,0 +1,124 @@
+//! Stability Layer Benchmarks
+//!
+//! Benchmarks for crash recovery, warmup tracking, and exhaustion monitoring.
+
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use mindfry::stability::{
+    ExhaustionLevel, ExhaustionMonitor, RecoveryAnalyzer, RecoveryState, ShutdownMarker,
+    WarmupTracker,
+};
+
+// ═══════════════════════════════════════════════════════════════
+// RECOVERY BENCHMARKS
+// ═══════════════════════════════════════════════════════════════
+
+fn bench_recovery_analyzer_new(c: &mut Criterion) {
+    let marker = Some(ShutdownMarker::graceful());
+
+    c.bench_function("recovery_analyzer_new", |b| {
+        b.iter(|| black_box(RecoveryAnalyzer::new(marker.clone())))
+    });
+}
+
+fn bench_recovery_analyzer_analyze(c: &mut Criterion) {
+    let marker = Some(ShutdownMarker::graceful());
+    let analyzer = RecoveryAnalyzer::new(marker);
+
+    c.bench_function("recovery_analyzer_analyze", |b| {
+        b.iter(|| black_box(analyzer.analyze()))
+    });
+}
+
+fn bench_recovery_state_intensity(c: &mut Criterion) {
+    c.bench_function("recovery_state_intensity", |b| {
+        b.iter(|| {
+            black_box(RecoveryState::Normal.intensity());
+            black_box(RecoveryState::Shock.intensity());
+            black_box(RecoveryState::Coma.intensity());
+        })
+    });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// WARMUP BENCHMARKS
+// ═══════════════════════════════════════════════════════════════
+
+fn bench_warmup_tracker_new(c: &mut Criterion) {
+    c.bench_function("warmup_tracker_new", |b| {
+        b.iter(|| black_box(WarmupTracker::new()))
+    });
+}
+
+fn bench_warmup_tracker_is_ready(c: &mut Criterion) {
+    let tracker = WarmupTracker::new();
+
+    c.bench_function("warmup_tracker_is_ready", |b| {
+        b.iter(|| black_box(tracker.is_ready()))
+    });
+}
+
+fn bench_warmup_tracker_state(c: &mut Criterion) {
+    let tracker = WarmupTracker::new();
+
+    c.bench_function("warmup_tracker_state", |b| {
+        b.iter(|| black_box(tracker.state()))
+    });
+}
+
+fn bench_warmup_tracker_clone(c: &mut Criterion) {
+    let tracker = WarmupTracker::new();
+
+    c.bench_function("warmup_tracker_clone", |b| {
+        b.iter(|| black_box(tracker.clone()))
+    });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// EXHAUSTION BENCHMARKS
+// ═══════════════════════════════════════════════════════════════
+
+fn bench_exhaustion_level_from_energy(c: &mut Criterion) {
+    c.bench_function("exhaustion_level_from_energy", |b| {
+        b.iter(|| {
+            black_box(ExhaustionLevel::from_energy(0.9));
+            black_box(ExhaustionLevel::from_energy(0.5));
+            black_box(ExhaustionLevel::from_energy(0.1));
+        })
+    });
+}
+
+fn bench_exhaustion_allows_writes(c: &mut Criterion) {
+    c.bench_function("exhaustion_allows_writes", |b| {
+        b.iter(|| {
+            black_box(ExhaustionLevel::Normal.allows_writes());
+            black_box(ExhaustionLevel::Elevated.allows_writes());
+            black_box(ExhaustionLevel::Exhausted.allows_writes());
+            black_box(ExhaustionLevel::Emergency.allows_writes());
+        })
+    });
+}
+
+fn bench_exhaustion_monitor_default(c: &mut Criterion) {
+    c.bench_function("exhaustion_monitor_new", |b| {
+        b.iter(|| black_box(ExhaustionMonitor::default()))
+    });
+}
+
+criterion_group!(
+    benches,
+    // Recovery
+    bench_recovery_analyzer_new,
+    bench_recovery_analyzer_analyze,
+    bench_recovery_state_intensity,
+    // Warmup
+    bench_warmup_tracker_new,
+    bench_warmup_tracker_is_ready,
+    bench_warmup_tracker_state,
+    bench_warmup_tracker_clone,
+    // Exhaustion
+    bench_exhaustion_level_from_energy,
+    bench_exhaustion_allows_writes,
+    bench_exhaustion_monitor_default,
+);
+
+criterion_main!(benches);

src/bin/server.rs

@@ -84,6 +84,27 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         }
     };
 
+    // Step 1.5: Crash Recovery Detection
+    print!("  │ 🔍 Checking recovery state...");
+    std::io::Write::flush(&mut std::io::stdout())?;
+    let last_marker = store.read_shutdown_marker().ok().flatten();
+    let recovery_analyzer = mindfry::stability::RecoveryAnalyzer::new(last_marker);
+    let recovery_state = recovery_analyzer.analyze();
+    match recovery_state {
+        mindfry::stability::RecoveryState::Normal => println!(" ✓ (clean)"),
+        mindfry::stability::RecoveryState::Shock => {
+            println!(" ⚠ (SHOCK detected)");
+            warn!("🩹 Unclean shutdown detected - building resistance");
+        }
+        mindfry::stability::RecoveryState::Coma => {
+            println!(" ⚠ (COMA detected)");
+            warn!(
+                "😴 Prolonged downtime: {}s",
+                recovery_analyzer.downtime_secs()
+            );
+        }
+    }
+
     // Step 2: Initialize Psyche Arena (empty)
     print!("  │ 🧠 Initializing Psyche Arena...");
     std::io::Write::flush(&mut std::io::stdout())?;
@@ -175,7 +196,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // ═══════════════════════════════════════════════════════════════
 
     let shutdown_result = tokio::select! {
-        result = accept_loop(listener, Arc::clone(&db)) => {
+        result = accept_loop(listener, Arc::clone(&db), warmup.clone()) => {
             // Accept loop returned (error or explicit stop)
             result
         }
@@ -208,6 +229,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                         Ok(meta) => info!("💾 Pre-shutdown snapshot saved: {}", meta.id),
                         Err(e) => warn!("⚠️ Failed to save shutdown snapshot: {}", e),
                     }
+
+                    // Write graceful shutdown marker for crash recovery
+                    let marker = mindfry::stability::ShutdownMarker::graceful();
+                    match store.write_shutdown_marker(&marker) {
+                        Ok(_) => info!("✅ Graceful shutdown marker written"),
+                        Err(e) => warn!("⚠️ Failed to write shutdown marker: {}", e),
+                    }
                 }
             }
 
@@ -225,18 +253,20 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 async fn accept_loop(
     listener: TcpListener,
     db: Arc<RwLock<MindFry>>,
+    warmup: mindfry::stability::WarmupTracker,
 ) -> Result<mindfry::stability::ShutdownReason, Box<dyn std::error::Error + Send + Sync>> {
     loop {
         match listener.accept().await {
             Ok((socket, peer)) => {
                 info!("📥 New connection from {}", peer);
 
-                // Clone Arc for the handler
+                // Clone for the handler
                 let db_clone = Arc::clone(&db);
+                let warmup_clone = warmup.clone();
 
                 // Spawn connection handler
                 tokio::spawn(async move {
-                    if let Err(e) = handle_connection(socket, db_clone).await {
+                    if let Err(e) = handle_connection(socket, db_clone, warmup_clone).await {
                         error!("Connection error: {}", e);
                     }
                     info!("📤 Connection closed: {}", peer);
@@ -254,8 +284,9 @@ async fn accept_loop(
 async fn handle_connection(
     mut socket: TcpStream,
     db: Arc<RwLock<MindFry>>,
+    warmup: mindfry::stability::WarmupTracker,
 ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
-    let mut handler = CommandHandler::new(db);
+    let mut handler = CommandHandler::with_warmup(db, warmup);
     let mut buffer = vec![0u8; 4096];
     let mut read_buf = Vec::new();
 

src/persistence/akashic.rs

@@ -293,6 +293,34 @@ impl AkashicStore {
         &self.indexer
     }
 
+    // ═══════════════════════════════════════════════════════════════
+    // SHUTDOWN MARKER (for crash recovery)
+    // ═══════════════════════════════════════════════════════════════
+
+    /// Write a graceful shutdown marker
+    pub fn write_shutdown_marker(&self, marker: &crate::stability::ShutdownMarker) -> Result<()> {
+        let meta_tree = self.db.open_tree("meta")?;
+        let data = bincode::serialize(marker)?;
+        meta_tree.insert("shutdown_marker", data)?;
+        self.db.flush()?;
+        Ok(())
+    }
+
+    /// Read and clear the shutdown marker
+    /// Returns None if no marker exists (first run or clean startup)
+    pub fn read_shutdown_marker(&self) -> Result<Option<crate::stability::ShutdownMarker>> {
+        let meta_tree = self.db.open_tree("meta")?;
+        match meta_tree.get("shutdown_marker")? {
+            Some(data) => {
+                let marker: crate::stability::ShutdownMarker = bincode::deserialize(&data)?;
+                // Clear the marker so next unclean shutdown is detected
+                meta_tree.remove("shutdown_marker")?;
+                Ok(Some(marker))
+            }
+            None => Ok(None),
+        }
+    }
+
     // ═══════════════════════════════════════════════════════════════
     // SERIALIZATION HELPERS
     // ═══════════════════════════════════════════════════════════════

src/protocol/handler.rs

@@ -9,6 +9,7 @@ use std::time::Instant;
 
 use crate::arena::Lineage;
 use crate::graph::Bond;
+use crate::stability::WarmupTracker;
 use crate::MindFry;
 
 use super::message::*;
@@ -25,6 +26,8 @@ pub struct CommandHandler {
     /// Exhaustion monitor for backpressure
     #[allow(dead_code)] // Reserved for operation cost tracking
     exhaustion: crate::stability::ExhaustionMonitor,
+    /// Warmup tracker for progressive availability
+    warmup: WarmupTracker,
 }
 
 impl CommandHandler {
@@ -35,11 +38,36 @@ impl CommandHandler {
             start_time: Instant::now(),
             is_frozen: false,
             exhaustion: crate::stability::ExhaustionMonitor::default(),
+            warmup: WarmupTracker::new(),
+        }
+    }
+
+    /// Create a new command handler with warmup tracker
+    pub fn with_warmup(db: Arc<RwLock<MindFry>>, warmup: WarmupTracker) -> Self {
+        Self {
+            db,
+            start_time: Instant::now(),
+            is_frozen: false,
+            exhaustion: crate::stability::ExhaustionMonitor::default(),
+            warmup,
         }
     }
 
     /// Handle a request and return a response
     pub fn handle(&mut self, request: Request) -> Response {
+        // ═══════════════════════════════════════════════════════════════
+        // WARMUP CHECK (Progressive Availability)
+        // ═══════════════════════════════════════════════════════════════
+        // Allow Ping and Stats during warmup (always accessible)
+        let is_warmup_exempt = matches!(request, Request::Ping | Request::Stats);
+
+        if !is_warmup_exempt && !self.warmup.is_ready() {
+            return Response::Error {
+                code: ErrorCode::WarmingUp,
+                message: "Server warming up - cognitively unavailable".into(),
+            };
+        }
+
         // ═══════════════════════════════════════════════════════════════
         // EXHAUSTION CHECK (Backpressure)
         // ═══════════════════════════════════════════════════════════════