nimmerverse-sensory-network/architecture/Message-Protocol-Design.md

Message Protocol Design: Router-Centric Architecture

ONE JOB: THE WIRE — NATS topics, JSON schemas, bootstrap sequence.

Overview

This document outlines the design for the Nimmerverse message protocol. The core principle: the router is dumb infrastructure, not smart cognition. All intelligence lives at the edges - in clients that connect to the router.

This follows the Unix philosophy: each component does one thing well. The router routes. Clients subscribe, publish, and think.

Connection to Gateway: The Escalation Service described in this document IS the Gateway (thalamus pattern). It implements the weight-based tier routing defined in Gateway-Architecture.md.

---

Core Principle: Dumb Core, Smart Edges

The router (NATS) is dumb infrastructure — it routes based on topic patterns and knows nothing about meaning. All intelligence lives at the edges: cells publish, the Escalation Service (Gateway) watches and routes, Nyx subscribes and thinks.

Routing logic: → Gateway-Architecture.md (tier routing, escalation patterns)

---

Guiding Principles

1. Dumb Core, Smart Edges: The router has zero intelligence. All logic lives in clients.
2. Clients are Equal: Nyx is just another subscriber. So is the Command Center. So is the Escalation Service.
3. Decoupling: Publishers don't know who subscribes. Subscribers don't know who publishes.
4. Hierarchy: Topics follow a hierarchical structure for flexible pattern subscriptions.
5. Lifeforce at the Edges: The router doesn't track Lifeforce. Clients manage their own budgets.
6. Fail Simple: If the router dies, everything stops cleanly. No half-smart failures.

---

Two Channels of Attention

Messages split into nimmerverse.low.* (background heartbeats) and nimmerverse.high.* (cognitive events). The Escalation Service promotes from low → high based on rules.

Attention philosophy: → Attention-Flow.md (budget allocation, preemption rules)

---

Topic Hierarchy

nimmerverse.
├── low.                          # Low-attention channel
│   └── heartbeat.
│       └── <garden>.             # real | virtual
│           └── <entity_type>.    # cell | nerve | organ
│               └── <entity_id>   # e.g., distance_sensor_front
│
├── high.                         # High-attention channel
│   └── event.
│       └── <garden>.
│           └── <entity_type>.
│               └── <entity_id>
│
├── command.                      # Commands TO entities
│   └── <target>.
│       └── <command_type>
│
└── meta.                         # System-level messages
    ├── attention.focus           # Nyx's attention configuration
    ├── escalation.rules          # Escalation Service configuration
    └── health.                   # Client health/registration

---

Message Schemas

1. HeartbeatSignal (Low-Attention)

Published by: Cells, Nerves, Organs Subscribed by: Escalation Service, Command Center

Topic: nimmerverse.low.heartbeat.<garden>.<entity_type>.<entity_id>

{
  "header": {
    "message_id": "uuid",
    "message_type": "HeartbeatSignal",
    "version": "1.0",
    "timestamp_real": "ISO8601",
    "timestamp_virtual": 123456
  },
  "body": {
    "entity_id": "distance_sensor_front",
    "status": "NOMINAL",
    "value": 25.5,
    "unit": "cm",
    "context": {
      "battery_pct": 85,
      "temperature_c": 22
    }
  }
}

Status values: NOMINAL, WARNING, CRITICAL, OFFLINE, ERROR

---

2. StateChangeDetail (High-Attention)

Published by: Cells/Nerves (when requested), Escalation Service (when escalating) Subscribed by: Young Nyx, Command Center

Topic: nimmerverse.high.event.<garden>.<entity_type>.<entity_id>

{
  "header": {
    "message_id": "uuid",
    "message_type": "StateChangeDetail",
    "version": "1.0",
    "timestamp_real": "ISO8601",
    "timestamp_virtual": 123456,
    "source_entity": {
      "id": "distance_sensor_front",
      "type": "cell",
      "layer": "1"
    },
    "correlation_id": "uuid",
    "escalated_by": "escalation_service"
  },
  "body": {
    "previous_state": "POLLING",
    "current_state": "REPORTING",
    "lifeforce_cost": 0.3,
    "outputs": {
      "distance_cm": 25.5,
      "confidence": 0.92,
      "raw_value": 456,
      "visual_state": [255, 0, 0, "Solid"]
    },
    "possible_actions": [
      {
        "action_id": "read_distance_history",
        "description": "Query historical distance data."
      },
      {
        "action_id": "trigger_nerve:collision_avoidance",
        "description": "Activate collision avoidance."
      }
    ],
    "trigger_reason": "distance < 30cm threshold"
  }
}

---

3. AttentionFocus (Nyx's Configuration)

Published by: Young Nyx Subscribed by: Escalation Service

This is how Nyx tells the Escalation Service what she cares about. The router doesn't interpret this - it just delivers it to subscribers.

Topic: nimmerverse.meta.attention.focus

{
  "header": {
    "message_id": "uuid",
    "message_type": "AttentionFocus",
    "version": "1.0",
    "timestamp_real": "ISO8601",
    "source_entity": {
      "id": "nyx_core",
      "type": "cognitive_core"
    }
  },
  "body": {
    "focus_mode": "EXPLORATION",
    "escalation_rules": [
      {
        "rule_id": "distance_alert_front",
        "source_pattern": "nimmerverse.low.heartbeat.real.cell.distance_sensor_*",
        "condition": "body.value < 30 AND body.status == 'NOMINAL'",
        "action": "escalate",
        "priority": 8
      },
      {
        "rule_id": "battery_critical",
        "source_pattern": "nimmerverse.low.heartbeat.real.cell.battery_*",
        "condition": "body.status == 'CRITICAL'",
        "action": "escalate_and_trigger",
        "trigger_nerve": "charging_seeking",
        "priority": 10
      }
    ],
    "direct_subscriptions": [
      "nimmerverse.high.event.real.cell.speech_stt"
    ],
    "default_action": "log_only"
  }
}

---

Clients

Publishers: Cells, Nerves, Organs (publish heartbeats and state changes) Router: NATS (dumb pipe, topic-based routing) Gateway/Escalation Service: Watches low-attention, escalates to high-attention, routes to tiers

Client architecture: → Gateway-Architecture.md (routing tiers, Function Gemma boundary)

---

Workflow: Message Flow

1. Cell publishes HeartbeatSignal
   └─→ Router delivers to: Escalation Service, Command Center

2. Escalation Service evaluates rules
   └─→ If condition matches: publishes StateChangeDetail to high-attention
   └─→ Router delivers to: Young Nyx, Command Center

3. Young Nyx processes StateChangeDetail
   └─→ Makes decision
   └─→ Publishes command to nimmerverse.command.<target>

4. Target nerve/cell receives command
   └─→ Executes action
   └─→ Publishes new HeartbeatSignal reflecting new state

5. Nyx adjusts attention (optional)
   └─→ Publishes new AttentionFocus
   └─→ Escalation Service updates its rules

---

Advantages of Router-Centric Architecture

1. Dumb core can't fail smart: The router either works or crashes. No subtle bugs from misunderstood logic.

2. Clients are replaceable: Swap out the Escalation Service. Replace the Command Center. Nyx doesn't care.

3. Testable in isolation: Each client can be tested independently against a mock NATS.

4. Observable: Command Center sees everything by subscribing to nimmerverse.>.

5. Scalable: Add more cells, more nerves - just more publishers. Router handles it.

6. Bootstrap-friendly: Router exists before any intelligence. Escalation Service can start with hardcoded rules. Nyx connects later.

---

Bootstrap Sequence

1. Start Router (NATS) - Infrastructure first
2. Start Escalation Service - With minimal hardcoded rules
3. Start Cells/Nerves - Begin publishing heartbeats
4. Start Command Center - Observe the system
5. Start Young Nyx - Connect, subscribe, begin cognition
6. Nyx publishes AttentionFocus - Takes control of her attention

The system can run at any step. Earlier steps are "reflexive" only. Nyx adds deliberation.

---

Implementation Notes

Router: Use NATS (https://nats.io). Lightweight, fast, designed for this.

• Consider NATS JetStream for message persistence if needed
• Topic wildcards: > matches all, * matches one level

Message Format: JSON for human readability during development. Consider MessagePack or Protobuf for production if performance requires.

Escalation Service: Python asyncio daemon using nats-py and simpleeval for rule evaluation. Stateless except for current rules. Can be restarted without losing system state. (Go considered for future optimization if scale demands.)

Command Center: Godot application connecting to NATS via GDScript or native plugin.

---

Version: 1.1 | Created: 2025-12-13 | Updated: 2026-02-14

"Dumb core, smart edges. The router routes. Clients think."