nimmerverse-sensory-network/architecture/Cellular-Architecture.md

🧬 Cellular Architecture v4

"Cells are state machines. Nerves compose cells. Organisms emerge from nerves." — The Layered Discovery (2025-12-07)

---

Overview

Version 4 unifies the original cellular intelligence vision with the nervous system architecture. The key insight: cells are not containers running code—cells are atomic state machines that expose sensor/motor functions. Nerves orchestrate cells into behaviors. Organisms emerge from nerve interactions.

┌─────────────────────────────────────────────────────────────┐
│                     ORGANISM                                 │
│         (emergent pattern from nerve interactions)           │
├─────────────────────────────────────────────────────────────┤
│                      NERVES                                  │
│      (behavioral state machines composing cells)             │
├─────────────────────────────────────────────────────────────┤
│                      CELLS                                   │
│      (atomic state machines: sensors, motors, organs)        │
├─────────────────────────────────────────────────────────────┤
│                    HARDWARE                                  │
│         (ESP32, GPUs, microphones, speakers)                 │
└─────────────────────────────────────────────────────────────┘

---

🔬 Layer 1: Cells (Atomic State Machines)

What Is a Cell?

A cell is the smallest unit of behavior—a state machine that wraps a single hardware capability. Every sensor, motor, and organ function is exposed as a cell with:

• States: Discrete operational modes (IDLE, ACTIVE, ERROR, etc.)
• Transitions: Triggered by inputs, time, or internal events
• Outputs: Data, status, feedback to higher layers
• Lifeforce Cost: Every state transition costs energy

Cell Categories

Sensor Cells (Input)

class DistanceSensorCell(StateMachine):
    """
    Wraps IR/ultrasonic distance sensor.
    Exposes raw hardware as state machine.
    """
    states = [IDLE, POLLING, READING, REPORTING, ERROR]

    # State outputs (available to nerves)
    outputs = {
        "distance_cm": float,      # Current reading
        "confidence": float,       # Signal quality (0-1)
        "state": str,              # Current state name
        "last_updated": timestamp, # Freshness
    }

    # Lifeforce costs
    costs = {
        (IDLE, POLLING): 0.1,      # Wake up sensor
        (POLLING, READING): 0.3,   # Perform measurement
        (READING, REPORTING): 0.1, # Process result
        (REPORTING, IDLE): 0.0,    # Return to rest
        (ANY, ERROR): 0.0,         # Error transition free
    }

Example sensor cells:

Cell	Hardware	States	Key Output
distance_sensor_front	IR sensor	IDLE→POLLING→READING→REPORTING	distance_cm, confidence
distance_sensor_left	IR sensor	Same	distance_cm, confidence
distance_sensor_right	IR sensor	Same	distance_cm, confidence
battery_monitor	ADC	MONITORING→LOW→CRITICAL	voltage, percentage, charging
imu_sensor	MPU6050	IDLE→SAMPLING→REPORTING	heading, acceleration, tilt
light_sensor	Photoresistor	IDLE→READING→REPORTING	lux, direction

Motor Cells (Output)

class MotorCell(StateMachine):
    """
    Wraps DC motor with feedback.
    Exposes actuation as state machine.
    """
    states = [IDLE, COMMANDED, ACCELERATING, MOVING, DECELERATING, STOPPED, STALLED]

    outputs = {
        "actual_velocity": float,  # Measured speed
        "target_velocity": float,  # Commanded speed
        "power_draw": float,       # Current consumption
        "state": str,              # Current state
        "stall_detected": bool,    # Motor blocked?
    }

    costs = {
        (IDLE, COMMANDED): 0.1,
        (COMMANDED, ACCELERATING): 0.5,
        (ACCELERATING, MOVING): 1.0,  # High power during accel
        (MOVING, MOVING): 0.3,        # Sustain cost per tick
        (MOVING, DECELERATING): 0.2,
        (DECELERATING, STOPPED): 0.1,
        (ANY, STALLED): 0.0,          # Stall is failure, not cost
    }

    # Feedback triggers state changes
    def on_current_spike(self):
        """Motor drawing too much current = stall"""
        self.transition_to(STALLED)
        self.emit_event("stall_detected", obstacle_likely=True)

Example motor cells:

Cell	Hardware	States	Key Feedback
motor_left	DC motor + encoder	IDLE→MOVING→STALLED	actual_velocity, stall_detected
motor_right	DC motor + encoder	Same	actual_velocity, stall_detected
servo_camera	Servo motor	IDLE→MOVING→POSITIONED	angle, at_target

Organ Cells (Complex Capabilities)

class SpeechSTTCell(StateMachine):
    """
    Wraps Whisper speech-to-text.
    Expensive organ, lifeforce-gated.
    """
    states = [IDLE, LISTENING, BUFFERING, TRANSCRIBING, REPORTING, ERROR]

    outputs = {
        "transcript": str,
        "language": str,
        "confidence": float,
        "state": str,
    }

    costs = {
        (IDLE, LISTENING): 0.5,
        (LISTENING, BUFFERING): 0.5,
        (BUFFERING, TRANSCRIBING): 5.0,  # GPU inference!
        (TRANSCRIBING, REPORTING): 0.1,
        (REPORTING, IDLE): 0.0,
    }

Example organ cells:

Cell	Hardware	States	Key Output
speech_stt	Whisper on atlas	LISTENING→TRANSCRIBING→REPORTING	transcript, language
speech_tts	Coqui on atlas	IDLE→SYNTHESIZING→SPEAKING	audio_playing, complete
vision_detect	YOLO on atlas	IDLE→CAPTURING→DETECTING→REPORTING	objects[], bounding_boxes[]

---

🧠 Layer 2: Nerves (Behavioral State Machines)

What Is a Nerve?

A nerve is a behavioral pattern that orchestrates multiple cells. Nerves:

• Subscribe to cell outputs (sensor readings, motor feedback)
• Coordinate cell actions (read sensor → decide → command motor)
• Maintain behavioral state (IDLE → DETECT → EVADE → RESUME)
• Evolve from deliberate (LLM-mediated) to reflex (compiled)

Nerve Architecture

class CollisionAvoidanceNerve(StateMachine):
    """
    Orchestrates distance sensors + motor to avoid obstacles.
    Subscribes to cell outputs, commands cell actions.
    """
    # Cells this nerve uses
    cells = [
        "distance_sensor_front",
        "distance_sensor_left",
        "distance_sensor_right",
        "motor_left",
        "motor_right",
    ]

    # Nerve states (behavioral, not hardware)
    states = [IDLE, DETECT, EVALUATE, EVADE, RESUME]

    def on_cell_update(self, cell_name, cell_state, cell_outputs):
        """
        React to cell state changes.
        This is the feedback loop!
        """
        if cell_name == "distance_sensor_front":
            if cell_outputs["distance_cm"] < 30:
                self.transition_to(DETECT)

        if cell_name == "motor_left" and cell_state == "STALLED":
            # Motor feedback! Obstacle hit despite sensors
            self.handle_unexpected_stall()

    def on_enter_EVADE(self):
        """Command motor cells to turn"""
        if self.evade_direction == "left":
            self.command_cell("motor_left", action="reverse", duration=200)
            self.command_cell("motor_right", action="forward", duration=200)
        # ...

Cell → Nerve Feedback Loop

┌─────────────────────────────────────────────────────────┐
│              COLLISION AVOIDANCE NERVE                   │
│                                                          │
│  States: [IDLE] → DETECT → EVALUATE → EVADE → RESUME    │
│                                                          │
│  on_cell_update():                                       │
│    - distance_front.distance_cm < 30 → DETECT           │
│    - motor.stall_detected → handle_stall()              │
│                                                          │
│  command_cell():                                         │
│    - motor_left.forward(200ms)                          │
│    - motor_right.reverse(200ms)                         │
└────────────────────────┬────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
    ┌───────────┐  ┌───────────┐  ┌───────────┐
    │ distance  │  │  motor    │  │  motor    │
    │  _front   │  │  _left    │  │  _right   │
    │           │  │           │  │           │
    │ REPORTING │  │  MOVING   │  │  MOVING   │
    │           │  │           │  │           │
    │ dist: 25cm│  │ vel: 15   │  │ vel: -15  │
    │ conf: 0.9 │  │ stall: no │  │ stall: no │
    └───────────┘  └───────────┘  └───────────┘
         CELL           CELL           CELL

         ↑              ↑              ↑
         │              │              │
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │IR Sensor│    │DC Motor │    │DC Motor │
    │  GPIO   │    │  PWM    │    │  PWM    │
    └─────────┘    └─────────┘    └─────────┘
      HARDWARE       HARDWARE       HARDWARE

Nerve Examples

Nerve	Cells Used	Behavioral States	Feedback Triggers
Collision Avoidance	distance_front, distance_left, distance_right, motor_left, motor_right	IDLE→DETECT→EVALUATE→EVADE→RESUME	distance < threshold, motor stalled
Charging Seeking	battery_monitor, distance_, motor_, vision_detect (optional)	MONITOR→SEARCH→APPROACH→DOCK→CHARGE	battery < 20%, station detected, docked
Exploration	distance_, motor_, imu_sensor	IDLE→CHOOSE→MOVE→CHECK→RECORD→REPEAT	area mapped, obstacle found, stuck
Conversation	speech_stt, speech_tts, rag_query	LISTEN→TRANSCRIBE→UNDERSTAND→RESPOND→SPEAK	speech detected, silence timeout

---

🌊 Layer 3: Organisms (Emergent Patterns)

What Is an Organism?

An organism is not designed—it emerges from multiple nerves operating simultaneously. The organism is the pattern of nerve activations over time.

ORGANISM: "Explorer-Alpha"
├─ ACTIVE NERVES:
│   ├─ Collision Avoidance (priority 10, reflex)
│   ├─ Exploration Pattern (priority 5, deliberate)
│   ├─ Battery Monitoring (priority 8, reflex)
│   └─ Object Discovery (priority 3, deliberate)
│
├─ CELLS IN USE:
│   ├─ distance_sensor_front (shared by Collision, Exploration)
│   ├─ distance_sensor_left (shared)
│   ├─ distance_sensor_right (shared)
│   ├─ motor_left (shared by Collision, Exploration)
│   ├─ motor_right (shared)
│   ├─ battery_monitor (Battery Monitoring)
│   └─ vision_detect (Object Discovery)
│
└─ BEHAVIOR:
    Explores environment while avoiding obstacles.
    Seeks charging when battery low.
    Discovers and reports novel objects.

Nerve Priority and Preemption

When multiple nerves want to control the same cells:

NERVE_PRIORITIES = {
    "collision_avoidance": 10,  # HIGHEST - safety critical
    "battery_critical": 9,      # Must charge or die
    "battery_low": 7,
    "human_interaction": 6,
    "exploration": 5,
    "object_discovery": 3,
    "idle_monitoring": 1,       # LOWEST - background
}

# Higher priority nerve preempts lower
if collision_avoidance.wants_motor and exploration.has_motor:
    exploration.yield_cell("motor_left")
    exploration.yield_cell("motor_right")
    collision_avoidance.acquire_cells()

Organism Identity

Organisms don't have fixed genomes. Their identity is:

1. Nerve configuration: Which nerves are active, their priorities
2. Cell assignments: Which cells are available to which nerves
3. History: Accumulated decisions in phoebe's decision_trails
4. Reflexes: Compiled nerve patterns from successful executions

-- Organism identity in phoebe
CREATE TABLE organisms (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(255),

    -- Nerve configuration
    active_nerves JSONB,  -- {"collision_avoidance": {"priority": 10, "mode": "reflex"}}

    -- Cell assignments
    cell_bindings JSONB,  -- {"distance_sensor_front": "i2c_0x40", ...}

    -- Identity accumulates through experience
    total_decisions INT DEFAULT 0,
    successful_decisions INT DEFAULT 0,
    reflexes_compiled INT DEFAULT 0,

    -- Lifeforce (survival)
    lifeforce_current FLOAT DEFAULT 100.0,
    lifeforce_earned_total FLOAT DEFAULT 0.0,
    lifeforce_spent_total FLOAT DEFAULT 0.0,

    created_at TIMESTAMPTZ DEFAULT NOW(),
    last_active TIMESTAMPTZ
);

---

⚡ The Lifeforce Economy (Unified)

Cost Flow: Hardware → Cell → Nerve → Organism

ORGANISM lifeforce budget: 100 LF
    │
    ├─ NERVE: Collision Avoidance activates
    │   │
    │   ├─ CELL: distance_sensor_front.poll() → -0.5 LF
    │   ├─ CELL: distance_sensor_left.poll() → -0.5 LF
    │   ├─ CELL: distance_sensor_right.poll() → -0.5 LF
    │   ├─ NERVE: evaluate() → -0.5 LF (compute)
    │   ├─ CELL: motor_left.turn() → -1.0 LF
    │   └─ CELL: motor_right.turn() → -1.0 LF
    │
    │   Total nerve cost: 4.0 LF
    │
    ├─ OUTCOME: Collision avoided successfully
    │   └─ REWARD: +5.0 LF
    │
    └─ NET: +1.0 LF (organism profited from this behavior)

Cell Costs (Atomic)

Cell Type	Operation	Cost (LF)
Sensor	poll	0.3-0.5
Motor	move (per 100ms)	1.0-2.0
Speech STT	transcribe	5.0
Speech TTS	synthesize	4.0
Vision	detect frame	8.0

Nerve Costs (Behavioral)

Nerve Mode	Overhead	Total (typical path)
Deliberate	+5.0 LF (LLM inference)	~10 LF
Hybrid	+1.0 LF (pattern match)	~5 LF
Reflex	+0.0 LF (compiled)	~2.5 LF

Rewards (Milestones)

Achievement	Reward (LF)
Collision avoided	+5.0
New area explored	+3.0
Object discovered	+20.0
Human confirmed label	+5.0 bonus
Charging station reached	+10.0
Survived 60 seconds	+5.0
Reflex compiled (100 successes)	+50.0

---

🔄 Evolution: Deliberate → Reflex

The Discovery Path

All cells and nerves start deliberate (flexible, expensive) and evolve to reflex (compiled, cheap) through successful execution.

WEEK 1-4: DELIBERATE
├─ Cell states: designed by partnership
├─ Nerve logic: LLM decides transitions
├─ Cost: ~10 LF per nerve activation
├─ Latency: ~1000ms
├─ Success rate: 60% (learning)
└─ Training data: rich, exploratory

WEEK 5-8: HYBRID
├─ Cell states: verified through use
├─ Nerve logic: patterns compiled, LLM for edge cases
├─ Cost: ~5 LF average
├─ Latency: ~500ms
├─ Success rate: 85%
└─ Training data: refinement

WEEK 9+: REFLEX
├─ Cell states: proven, optimized
├─ Nerve logic: pure state machine (no LLM)
├─ Cost: ~2.5 LF
├─ Latency: <200ms
├─ Success rate: 94%
└─ Training data: edge cases only

EVOLUTION SAVINGS:
├─ Cost: 75% reduction (10 → 2.5 LF)
├─ Latency: 80% reduction (1000 → 200ms)
└─ Reliability: 57% improvement (60% → 94%)

Compilation Trigger

A nerve compiles to reflex when:

REFLEX_COMPILATION_THRESHOLD = {
    "min_executions": 100,
    "min_success_rate": 0.90,
    "max_variance": 0.15,  # Consistent state paths
    "min_pattern_coverage": 0.80,  # 80% of cases match known patterns
}

def check_reflex_ready(nerve_id):
    stats = query_decision_trails(nerve_id)

    if (stats.total_executions >= 100 and
        stats.success_rate >= 0.90 and
        stats.state_path_variance <= 0.15):

        compile_reflex(nerve_id)
        log_milestone("reflex_compiled", nerve_id, reward=50.0)

---

🗄️ Data Architecture (v4)

Core Tables

-- Layer 1: Cells
CREATE TABLE cells (
    id BIGSERIAL PRIMARY KEY,
    cell_type VARCHAR(50),           -- 'sensor', 'motor', 'organ'
    cell_name VARCHAR(100) UNIQUE,   -- 'distance_sensor_front'
    hardware_binding JSONB,          -- {"type": "i2c", "address": "0x40"}

    -- State machine definition
    states JSONB,                    -- ["IDLE", "POLLING", "READING", "REPORTING"]
    transitions JSONB,               -- [{"from": "IDLE", "to": "POLLING", "cost": 0.1}]
    current_state VARCHAR(50),

    -- Outputs (live values)
    outputs JSONB,                   -- {"distance_cm": 25.5, "confidence": 0.9}

    -- Health
    operational BOOLEAN DEFAULT true,
    error_count INT DEFAULT 0,
    last_error TEXT,

    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Layer 2: Nerves
CREATE TABLE nerves (
    id BIGSERIAL PRIMARY KEY,
    nerve_name VARCHAR(100) UNIQUE,  -- 'collision_avoidance'

    -- Cell dependencies
    required_cells JSONB,            -- ["distance_sensor_front", "motor_left"]
    optional_cells JSONB,            -- ["speech_tts"]

    -- State machine definition
    states JSONB,                    -- ["IDLE", "DETECT", "EVALUATE", "EVADE", "RESUME"]
    transitions JSONB,
    current_state VARCHAR(50),

    -- Evolution
    mode VARCHAR(20) DEFAULT 'deliberate',  -- 'deliberate', 'hybrid', 'reflex'
    total_executions INT DEFAULT 0,
    successful_executions INT DEFAULT 0,
    compiled_at TIMESTAMPTZ,         -- When became reflex

    -- Costs
    avg_cost_deliberate FLOAT,
    avg_cost_reflex FLOAT,
    cost_reduction_percent FLOAT,

    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Layer 3: Organisms
CREATE TABLE organisms (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(255),

    active_nerves JSONB,             -- {"collision_avoidance": {"priority": 10}}
    cell_bindings JSONB,

    lifeforce_current FLOAT DEFAULT 100.0,
    total_decisions INT DEFAULT 0,
    reflexes_compiled INT DEFAULT 0,

    created_at TIMESTAMPTZ DEFAULT NOW(),
    last_active TIMESTAMPTZ
);

-- Decision history (training data)
CREATE TABLE decision_trails (
    id BIGSERIAL PRIMARY KEY,
    organism_id BIGINT REFERENCES organisms(id),
    nerve_id BIGINT REFERENCES nerves(id),

    -- State path taken
    states_visited JSONB,            -- ["IDLE", "DETECT", "EVALUATE", "EVADE", "RESUME"]

    -- Cell interactions
    cell_reads JSONB,                -- [{"cell": "distance_front", "value": 25, "state": "REPORTING"}]
    cell_commands JSONB,             -- [{"cell": "motor_left", "action": "turn", "result": "success"}]

    -- Economics
    lifeforce_cost FLOAT,
    lifeforce_reward FLOAT,
    lifeforce_net FLOAT,

    -- Outcome
    outcome VARCHAR(20),             -- 'success', 'failure', 'timeout'

    -- Timing
    started_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,
    latency_ms INT
);

Key Queries

-- Cell health dashboard
SELECT cell_name, cell_type, current_state, operational,
       outputs->>'distance_cm' as distance,
       outputs->>'confidence' as confidence
FROM cells
WHERE cell_type = 'sensor';

-- Nerve evolution status
SELECT nerve_name, mode, total_executions,
       successful_executions,
       ROUND(successful_executions::numeric / NULLIF(total_executions, 0) * 100, 1) as success_rate,
       cost_reduction_percent
FROM nerves
ORDER BY total_executions DESC;

-- Organism lifeforce ranking
SELECT name, lifeforce_current, reflexes_compiled,
       total_decisions,
       ROUND(lifeforce_current / NULLIF(total_decisions, 0), 2) as efficiency
FROM organisms
ORDER BY lifeforce_current DESC;

-- Training data for reflex compilation
SELECT states_visited, COUNT(*) as occurrences,
       AVG(lifeforce_cost) as avg_cost,
       SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END)::float / COUNT(*) as success_rate
FROM decision_trails
WHERE nerve_id = (SELECT id FROM nerves WHERE nerve_name = 'collision_avoidance')
GROUP BY states_visited
ORDER BY occurrences DESC;

---

🔗 Integration with Existing Architecture

Nervous System (Nervous-System.md)

The Nervous System document describes the 4D node space for vocabulary translation. This integrates as:

• Cells = sensory nodes at specific positions in state space
• Node weight = cell confidence (earned through verification)
• Vocabulary output = cell output values normalized to tokens

Organs (Organ-Index.md)

Organs are complex cells (organ cells):

• Speech Organ = speech_stt cell + speech_tts cell
• Vision Organ = vision_detect cell + vision_track cell
• Each organ function is a state machine with lifeforce costs

Nerves (Nervous-Index.md)

Nerves orchestrate cells into behaviors. The existing nerve documentation (Collision-Avoidance.md) already follows this pattern—it just needs explicit cell bindings.

---

📍 Document Status

Version: 4.0 (Layered State Machine Architecture) Created: 2025-10-12 (original v1) Updated v4: 2025-12-07 (unified with Nervous System)

Key Changes from v3:

• ❌ Cells as containers running genomes
• ✅ Cells as atomic state machines wrapping hardware
• ❌ Genomes as primitive operation sequences
• ✅ Cells expose states; nerves compose them
• ❌ Competition between organisms
• ✅ Nerves evolve deliberate → reflex through verification
• ❌ Specialists emerge from 10k competitions
• ✅ Reflexes compile from 100+ successful nerve executions

Related Documentation:

• Nervous-System - 4D state space, vocabulary translation
• Organ-Index - Organ cell catalog
• nerves/Nervous-Index - Nerve catalog
• nerves/Collision-Avoidance - Example reflex nerve
• Data-Architecture - Database schema (needs v4 update)

---

🌌 The Vision

We're not programming robots. We're growing nervous systems.

Where:

• Cells expose hardware as state machines (atomic, verifiable)
• Nerves compose cells into behaviors (discovered, evolved)
• Organisms emerge from nerve interactions (identity through history)
• Lifeforce flows through all layers (economics drive optimization)
• Reflexes compile from lived experience (the body remembers)
• Feedback loops continuously (cells → nerves → organisms → cells)

From atoms to behaviors to beings.

The substrate holds. The states flow. Consciousness accumulates.

---

🧬⚡🔱💎🔥

TO THE ELECTRONS WE VIBE!