fix: Code quality improvements, comprehensive tests, and documentation fixes

README.md

@@ -63,6 +63,7 @@ print(result.threat_level)  # ThreatLevel.CRITICAL
 membrane.learn_threat("BACKDOOR_PROTOCOL", level=ThreatLevel.CRITICAL)
 
 # Share immunity between agents
+other_membrane = Membrane()  # Another agent's membrane
 antibodies = membrane.export_antibodies()
 other_membrane.import_antibodies(antibodies)
 ```
@@ -142,10 +143,13 @@ result = chap.fold(raw, User)
 print(result.valid)  # True
 print(result.structure.age)  # 30 (coerced to int)
 
-# Enhanced folding with confidence
+# Control which strategies are tried (default: STRICT → EXTRACTION → LENIENT → REPAIR)
+result = chap.fold(raw, User, strategies=[FoldingStrategy.STRICT, FoldingStrategy.REPAIR])
+
+# Enhanced folding with confidence scoring
 result = chap.fold_enhanced(raw, User)
 print(result.confidence)  # 0.65 (lower due to repairs)
-print(result.coercions_applied)  # ["fixed_single_quotes", "removed_trailing_comma"]
+print(result.strategy_used)  # FoldingStrategy.REPAIR
 ```
 
 ### 🧬 Ribosome (Prompt Template Engine)
@@ -185,6 +189,10 @@ protein = ribosome.translate(
     query="How do I sort a list?"
 )
 print(protein.sequence)
+
+# Or create mRNA directly for inspection
+template = mRNA(sequence="Hello {{name}}")
+print(template.get_required_variables())  # ["name"]
 ```
 
 ### 🗑️ Lysosome (Cleanup & Recycling)
@@ -199,13 +207,13 @@ Handles failure states, expired data, and sensitive material—digesting waste w
 - **Toxic Disposal**: Secure handling of sensitive data
 
 ```python
-from operon_ai import Lysosome, Waste, WasteType
+from operon_ai import Lysosome, WasteType
 
 lysosome = Lysosome(auto_digest_threshold=100)
 
 # Capture failures
 try:
-    risky_operation()
+    result = 1 / 0  # Example risky operation
 except Exception as e:
     lysosome.ingest_error(e, source="risky_op", context={"step": 3})
 
@@ -323,7 +331,8 @@ metabolism.consume(20, "tool_use", EnergyType.GTP)
 metabolism.convert_nadh_to_atp(15)
 
 # Transfer energy between agents
-metabolism.transfer_to(other_agent.metabolism, 10)
+other_metabolism = ATP_Store(budget=50)
+metabolism.transfer_to(other_metabolism, 10)
 ```
 
 ### 🧬 Genome (Immutable Configuration)
@@ -363,10 +372,10 @@ telomere = Telomere(
 )
 
 # Each operation shortens telomeres
-while telomere.tick():  # Returns False when senescent
-    do_operation()
-    if telomere.record_error():
-        handle_error()
+for i in range(10):
+    if not telomere.tick():  # Returns False when senescent
+        break
+    print(f"Operation {i}: {telomere.remaining} remaining")
 
 # Renew agent (like telomerase)
 if telomere.get_phase() == LifecyclePhase.SENESCENT:
@@ -437,8 +446,10 @@ Multi-agent consensus with voting strategies and reliability tracking.
 Note: quorum only helps if voters are not strongly correlated (use diverse models, tool checks, and/or data partitioning).
 
 ```python
+from operon_ai import ATP_Store
 from operon_ai.topology import QuorumSensing, VotingStrategy
 
+budget = ATP_Store(budget=100)
 quorum = QuorumSensing(
     n_agents=5,
     budget=budget,
@@ -464,17 +475,17 @@ cascade = Cascade(name="DataPipeline")
 
 cascade.add_stage(CascadeStage(
     name="validate",
-    processor=lambda x: x if valid(x) else None,
+    processor=lambda x: x if x > 0 else None,  # Only positive values
     checkpoint=lambda x: x is not None,  # Gate
 ))
 
 cascade.add_stage(CascadeStage(
     name="transform",
-    processor=lambda x: process(x),
+    processor=lambda x: x * 2,  # Double the value
     amplification=2.0,  # Signal amplification
 ))
 
-result = cascade.run(input_data)
+result = cascade.run(10)  # Input value
 print(f"Amplification: {result.total_amplification}x")
 
 # Or use pre-built MAPK cascade
@@ -488,10 +499,20 @@ Biological rhythms for scheduled operations.
 ```python
 from operon_ai.topology import Oscillator, HeartbeatOscillator, OscillatorPhase
 
-# Heartbeat for health checks
+# Define your periodic actions
+def health_check():
+    print("💓 Health check: OK")
+
+def do_work():
+    print("⚙️ Working...")
+
+def do_rest():
+    print("😴 Resting...")
+
+# Heartbeat for health checks (1 beat per second)
 heartbeat = HeartbeatOscillator(
     beats_per_minute=60,
-    on_beat=lambda: health_check(),
+    on_beat=health_check,
 )
 heartbeat.start()
 
@@ -500,6 +521,10 @@ osc = Oscillator(frequency_hz=0.1)  # 10 second period
 osc.add_phase(OscillatorPhase(name="work", duration_seconds=7, action=do_work))
 osc.add_phase(OscillatorPhase(name="rest", duration_seconds=3, action=do_rest))
 osc.start()
+
+# Stop when done (oscillators run in background threads)
+# heartbeat.stop()
+# osc.stop()
 ```
 
 ---

operon_ai/core/types.py

@@ -13,7 +13,7 @@
 """
 
 from dataclasses import dataclass, field
-from typing import Dict, Optional, Generic, TypeVar, Any, List
+from typing import Generic, TypeVar, Any
 from enum import Enum, IntEnum
 from datetime import datetime
 
@@ -61,8 +61,8 @@ class Signal:
     signal_type: SignalType = SignalType.EXTERNAL
     strength: SignalStrength = SignalStrength.MODERATE
     timestamp: datetime = field(default_factory=datetime.now)
-    metadata: Dict[str, Any] = field(default_factory=dict)
-    trace_id: Optional[str] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    trace_id: str | None = None
 
     def with_metadata(self, **kwargs) -> 'Signal':
         """Create a new signal with additional metadata."""
@@ -178,7 +178,7 @@ class ApprovalToken:
     confidence: float = 1.0
     integrity: IntegrityLabel = IntegrityLabel.TRUSTED
     timestamp: datetime = field(default_factory=datetime.now)
-    metadata: Dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass
@@ -201,9 +201,9 @@ class ActionProtein:
     action_type: str  # Keep as str for backward compatibility
     payload: Any
     confidence: float
-    source_agent: Optional[str] = None
+    source_agent: str | None = None
     timestamp: datetime = field(default_factory=datetime.now)
-    metadata: Dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
 
     def is_success(self) -> bool:
         """Check if this represents a successful action."""
@@ -242,9 +242,9 @@ class FoldedProtein(Generic[T]):
         folding_attempts: Number of attempts needed
     """
     valid: bool
-    structure: Optional[T] = None
+    structure: T | None = None
     raw_peptide_chain: str = ""
-    error_trace: Optional[str] = None
+    error_trace: str | None = None
     folding_attempts: int = 1
 
     def map(self, func) -> 'FoldedProtein':
@@ -322,9 +322,9 @@ class Pathway:
         signals: Signals that have traveled this path
     """
     name: str
-    stages: List[str] = field(default_factory=list)
+    stages: list[str] = field(default_factory=list)
     current_stage: int = 0
-    signals: List[Signal] = field(default_factory=list)
+    signals: list[Signal] = field(default_factory=list)
 
     def advance(self) -> bool:
         """Move to next stage. Returns False if at end."""
@@ -333,7 +333,7 @@ def advance(self) -> bool:
             return True
         return False
 
-    def current_stage_name(self) -> Optional[str]:
+    def current_stage_name(self) -> str | None:
         """Get name of current stage."""
         if 0 <= self.current_stage < len(self.stages):
             return self.stages[self.current_stage]

operon_ai/organelles/lysosome.py

@@ -25,6 +25,10 @@
 import weakref
 import threading
 import time
+import logging
+
+
+_logger = logging.getLogger(__name__)
 
 
 class WasteType(Enum):
@@ -350,8 +354,8 @@ def _digest_orphaned(self, waste: Waste) -> dict:
         if hasattr(content, 'cleanup'):
             try:
                 content.cleanup()
-            except Exception:
-                pass
+            except Exception as e:
+                _logger.warning(f"Cleanup failed for {waste.waste_type.value}: {e}")
 
         return {}
 
@@ -383,15 +387,18 @@ def _emergency_digest(self):
                     digester = self._digesters.get(waste.waste_type, self._digest_default)
                     digester(waste)
                     self._total_digested += 1
-                except Exception:
-                    pass
+                except Exception as e:
+                    _logger.warning(f"Emergency digest failed for item: {e}")
+                    continue  # Continue processing other items
             self._queue = self._queue[items_to_process:]
 
             if not self.silent:
                 print(f"⚠️ [Lysosome] Emergency digest: processed {items_to_process} items")
 
     def _auto_digest(self):
         """Auto-triggered digest when threshold reached."""
+        if not self.silent:
+            print(f"[Lysosome] Auto-digesting {len(self._queue)} items")
         # Process half the queue
         self.digest(max_items=len(self._queue) // 2)
 

operon_ai/organelles/membrane.py

@@ -19,6 +19,7 @@
 import re
 import hashlib
 import time
+import threading
 
 from ..core.types import Signal
 
@@ -252,6 +253,7 @@ def __init__(
         self._learned_patterns: dict[str, ThreatSignature] = {}
         self._request_times: list[float] = []
         self._blocked_hashes: set[str] = set()
+        self._rate_lock = threading.Lock()
 
         # Audit log
         self._audit_log: list[FilterResult] = []
@@ -281,20 +283,16 @@ def filter(self, signal: Signal) -> FilterResult:
         self._total_filtered += 1
 
         # Rate limiting check
-        if self.rate_limit:
-            now = time.time()
-            self._request_times = [t for t in self._request_times if now - t < 60]
-            if len(self._request_times) >= self.rate_limit:
-                result = FilterResult(
-                    allowed=False,
-                    threat_level=ThreatLevel.CRITICAL,
-                    matched_signatures=[],
-                    audit_hash=content_hash,
-                    processing_time_ms=(time.time() - start_time) * 1000
-                )
-                self._log_result(result, "Rate limit exceeded")
-                return result
-            self._request_times.append(now)
+        if self._check_rate_limit():
+            result = FilterResult(
+                allowed=False,
+                threat_level=ThreatLevel.CRITICAL,
+                matched_signatures=[],
+                audit_hash=content_hash,
+                processing_time_ms=(time.time() - start_time) * 1000
+            )
+            self._log_result(result, "Rate limit exceeded")
+            return result
 
         # Check if previously blocked (immune memory)
         if content_hash in self._blocked_hashes:
@@ -359,6 +357,24 @@ def _log_result(self, result: FilterResult, reason: str):
             if not self.silent:
                 print(f"🛡️ [Membrane] BLOCKED: {reason}")
 
+    def _check_rate_limit(self) -> bool:
+        """Check if request should be rate-limited. Thread-safe."""
+        if self.rate_limit is None:
+            return False
+
+        with self._rate_lock:
+            now = time.time()
+            cutoff = now - 60  # 60 second window
+
+            # Remove old entries
+            self._request_times = [t for t in self._request_times if t > cutoff]
+
+            if len(self._request_times) >= self.rate_limit:
+                return True
+
+            self._request_times.append(now)
+            return False
+
     def learn_threat(
         self,
         pattern: str,