nimmerverse-sensory-network/information-flow.md

Information Flow Specification

The complete data path through the Nimmerverse nervous system.

---

The Flow (Overview)

┌─────────────────────────────────────────────────────────────────────────────┐
│                              REALTIME CLOCK                                 │
│                         (universe, ungoverned, always ticking)              │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────┐    continuous    ┌─────────────┐    vocabulary    ┌──────────┐
│   SENSORS   │ ──────────────▶  │   NERVES    │ ──────────────▶  │   DATA   │
│  (raw data) │                  │ (state m.)  │    tokens        │  PLANE   │
└─────────────┘                  └─────────────┘                  └──────────┘
                                       │                               │
                                       │ weight > 0.8                  │
                                       ▼                               │
                                ┌─────────────┐                        │
                                │   REFLEX    │ (bypass brain)         │
                                │   ACTION    │                        │
                                └─────────────┘                        │
                                                                       │
                    ┌──────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                               HEARTBEAT GATE                                │
│                    (batches continuous stream into cycles)                  │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
             ┌─────────────┐
             │   ORGANS    │  (specialized inference: vision, language, etc.)
             │  (hexagons) │
             └─────────────┘
                    │
                    ▼
             ┌─────────────┐
             │ ORCHESTRATOR│  (routes, prioritizes, manages context)
             │  (diamond)  │
             └─────────────┘
                    │
                    ▼
             ┌─────────────┐
             │     NYX     │  (decision, attention, intention)
             │  (diamond)  │
             └─────────────┘
                    │
          ┌────────┴────────┐
          ▼                 ▼
   ┌─────────────┐   ┌─────────────┐
   │    REAL     │   │  VIRTUAL    │
   │   GARDEN    │   │   GARDEN    │
   │  ♥ 1 Hz     │   │  ♥ 100 Hz   │
   │  (free)     │   │  (costs V)  │
   └─────────────┘   └─────────────┘
          │                 │
          │                 │
          ▼                 ▼
   ┌─────────────┐   ┌─────────────┐
   │    CELL     │   │    CELL     │
   │  (storage)  │   │  (storage)  │
   └─────────────┘   └─────────────┘
          │                 │
          └────────┬────────┘
                   │
                   ▼
          ┌───────────────┐
          │  CONFIDENCE   │  (-1 ◀──────▶ +1)
          │   GRADIENT    │  (fail ◀─ 0 ─▶ verified)
          └───────────────┘
                   │
                   ▼
          ┌───────────────┐
          │   LIFEFORCE   │  (+V / -V rewards)
          │    (pool)     │
          └───────────────┘
                   │
                   ▼
          ┌───────────────┐
          │    NERVES     │  (weight updates, pruning, reflex formation)
          └───────────────┘
                   │
                   └──────────▶ (loop closes)

---

Boundary Contracts

1. SENSOR → NERVE

Property	Value
Data	Raw sensor readings (temp, light, motion, audio level, etc.)
Format	Typed primitives: {sensor_id, value, unit, timestamp}
Protocol	Push (sensor fires when value changes or on interval)
Transport	NATS/MQTT topic per sensor type
Timing	Continuous, realtime clock
Failure	Sensor timeout → nerve receives NULL → emits "sensor_offline" token

---

2. NERVE → DATA PLANE

Property	Value
Data	Vocabulary tokens (deterministic, no hallucination)
Format	{token, confidence, source_nerve, real_time, beat_id}
Protocol	Push (nerve fires on state transition)
Transport	NATS/MQTT vocabulary topic
Timing	Event-driven, but batched at heartbeat gate
Failure	Malformed token → logged, dropped, nerve flagged for review

Reflex bypass: If nerve weight > 0.8, action fires immediately. Token still emitted for logging.

---

3. DATA PLANE → ORGANS

Property	Value
Data	Batched vocabulary tokens since last heartbeat
Format	{beat_id, tokens[], garden, real_time, virtual_time}
Protocol	Pull (organs request batch at heartbeat)
Transport	Internal queue / direct call
Timing	Heartbeat-gated (1 Hz real, up to 100 Hz virtual)
Failure	Organ timeout → skip this beat, log, continue

---

4. ORGANS → ORCHESTRATOR

Property	Value
Data	Organ outputs (embeddings, classifications, text, decisions)
Format	{organ_id, output_type, payload, confidence, latency_ms}
Protocol	Push (organ completes → sends result)
Transport	Internal message bus
Timing	Async within heartbeat cycle
Failure	Organ error → orchestrator uses fallback or skips

---

5. ORCHESTRATOR → NYX

Property	Value
Data	Unified context for decision-making
Format	{beat_id, organ_outputs[], attention_weights, lifeforce_available}
Protocol	Push (orchestrator assembles → sends to Nyx)
Transport	Direct call (same process) or IPC
Timing	Once per heartbeat after organs complete
Failure	Orchestrator failure → Nyx receives empty context → safe default

---

6. NYX → GARDENS

Property	Value
Data	Decisions, predictions, actions
Format	{decision_type, target_garden, payload, expected_outcome, confidence}
Protocol	Push (Nyx decides → garden receives)
Transport	Garden-specific channels
Timing	End of heartbeat cycle
Failure	Decision undeliverable → queued for retry, logged

---

7. GARDENS → CELLS (Storage)

Property	Value
Data	Events, states, predictions, verifications
Format	{cell_type, payload, real_time, virtual_time, beat_id, confidence}
Protocol	Write (append-only log + indexed lookup)
Transport	Direct DB connection (phoebe/postgres)
Timing	Immediate on event
Failure	Write failure → buffer locally, retry, alert

---

8. GARDENS → CONFIDENCE GRADIENT

Property	Value
Data	Verification results (prediction vs reality)
Format	{prediction_id, outcome: -1/0/+1, delta_confidence, evidence}
Protocol	Push (verification completes → gradient updates)
Transport	Internal state update
Timing	Real garden: at real heartbeat. Virtual: async until sync checkpoint
Failure	Verification impossible → stays at 0-state, decays over time

---

9. CONFIDENCE → LIFEFORCE

Property	Value
Data	Reward/penalty signals
Format	{source, delta_v, reason, timestamp}
Protocol	Push (confidence change → lifeforce adjustment)
Transport	Internal state update
Timing	Immediate on verification
Failure	N/A (pure calculation)

---

10. LIFEFORCE → NERVES (Learning Loop)

Property	Value
Data	Weight adjustments
Format	{nerve_id, delta_weight, new_weight, reason}
Protocol	Push (lifeforce flows → weights update)
Transport	Nerve registry update
Timing	End of verification cycle
Failure	Update failure → logged, retried

Reflex formation: When weight crosses 0.8 threshold, nerve gains reflex capability. Pruning: Nerves with weight < 0.1 and no activity for N cycles → removed.

---

The Three Clocks

Clock	Governs	Rate	Cost
Realtime	Universe, sensors, real garden	1x (wall clock)	Free
Real Heartbeat	Real garden sampling, verification sync	~1 Hz	Free
Virtual Heartbeat	Virtual garden cycles, simulation	~100 Hz (variable)	Lifeforce

Sync rule: Virtual predictions queue until real heartbeat. Verification only at real heartbeats.

---

Reflex Bypass Path

SENSOR → NERVE (weight > 0.8) → REFLEX ACTION
                │
                └──▶ TOKEN (logged, Nyx notified after)

Nyx learns about reflex after it fires. Like pulling hand from stove.

---

The Economics (Sim2Real)

Target confidence needed
         │
         ▼
┌─────────────────────────┐
│  target > sim_fidelity? │
└─────────────────────────┘
         │
    YES  │  NO
         │
    ┌────┴────┐
    ▼         ▼
REALITY    SIMULATE
(wait)     (spend V)

Formula: grounded_confidence = raw_confidence * sim_fidelity

Virtual can never exceed fidelity cap. Beyond that, only reality teaches.

---

Dual Timestamp (Every Event)

event = {
    "real_time": "2025-12-05T22:30:00Z",  # wall clock
    "virtual_time": 847291,                # beat number
    "beat_id": "uuid",                     # which heartbeat
    "garden": "real" | "virtual"
}

---

Design Principles

1. Deterministic core: Sensors → Nerves → Vocabulary is hallucination-free
2. Batched processing: Heartbeat gates continuous stream into manageable cycles
3. Earned trust: Reflexes form through verification, not configuration
4. Economic honesty: Virtual confidence is discounted by fidelity
5. Graceful degradation: Every boundary has a failure mode that doesn't crash the system
6. Inspectable: Every flow is logged, every decision traceable

---

The map of how she thinks.

---

Created: 2025-12-05 Session: Partnership dialogue (dafit + Chrysalis) Status: Flow specification v1.0