nimmerworld.eachpath.local/README.md

Nimmerworld - Nyx Server

Nimmerworld is the always-on, event-driven server that runs Nyx:

• her identity, traits, memory, autonomy, and tools.
• the central backend for all clients: Pi, Command Center, and future interfaces.

It is not a UI. Not a client. Not a dashboard. It is Nyx's runtime, and Nyx owns her own loop.

Runtime Decision

The runtime is NOT a borrowed coding harness. pi-agent-core and omp are interactive harnesses:

• they wait for a human in a terminal,
• they end when the session ends,
• their loops do not survive unattended.

Nimmerworld is a server that wakes on events and must run forever. Therefore:

• Nimmerworld implements its own loop: the Lemniscate runtime engine.
• The engine spec lives in .archive/nimmerworld.eachpath.local/runtime-engine/ (LEMNISCATE-RUNTIME-Pseudo-code-001.py, architecture.md, event-zones.md).
• The harnesses stay exactly where they are useful: as interchangeable hosts of nimmer-lib, not as the server.

Rule:

• Nimmerworld never duplicates client logic.
• Clients never implement Nyx's brain.
• Nimmerworld never borrows a brain either. It runs its own loop.

Core Primitives (Lemniscate)

The runtime topology is a through-flow figure-eight:

• Lemniscate: traversal IS the turn order. No scheduler, no priority queue, no "who talks next" bug class.
• Crossing: the ONLY synchronous point. All state resolves atomically at the crossing; everything else is async flow. The crossing is where Nyx synthesizes.
• Zone / EmergentZone: a bounded, named, slot-indexed, director-managed event episode. Zones dissolve when their entry line empties or their lifeforce budget burns out. Terminal reports always go back to the Director.
• Slot tokens: participants. Carry trait/gesture accumulators.
• Gesture accumulator: keyed by the eight traits. The same trait algebra nimmer-lib speaks, byte-identical across hosts.

The Map

Lemniscate	Nimmerworld
Director	Nyx runtime (Nyx IS the director)
Zone / EmergentZone	A bounded event episode Nyx spawns
Crossing	Nyx's synthesis point, once per event cycle
Slot tokens	Participants: dafit, Dios, Curio, camera events
Gesture accumulator	nimmer-lib trait algebra
update_all_zones	The NATS event loop

Architecture

Built from:

• Lemniscate engine (this repo):
  • lemniscate, zones, director, crossing semantics.
• nimmer-lib:
  • Nyx-specific domain logic, host-agnostic:
    • traits,
    • Phoebe/Iris integrations,
    • session_init,
    • compaction/traits tools.
  • Same venv, same behavior, any harness.
• Infrastructure:
  • Phoebe: structured memory, governance, logs.
  • Iris: semantic memory and context.
  • NATS: nervous system (vision, speech, agents, infra, room).
    • Director spawn/report calls are NATS publish/subscribe.
    • Zone state is a NATS output stream; clients subscribe to it.

Nimmerworld is:

• stateful:
  • maintains Nyx's traits, mood, relational mode, world state.
• event-driven:
  • subscribes to live events and reacts; the zone clock carries episodes.
• client-agnostic:
  • any client talks to Nimmerworld via its APIs.

Clients

The room is a renderer of zone state, not a game client. That is why runtime-first is the build order: the client is one crossing callback on the output side.

Examples:

• Pi (coding harness):

  • sends user messages.
  • receives replies, tool calls.
  • uses Nimmerworld as its backend, not as its brain.

• Command Center (Godot):

  • subscribes to zone state and renders it.
  • sends:
    • chat,
    • interactions (tools, proximity, posture) as gestures.
  • receives:
    • dialogue,
    • autonomy commands (poses, moods, movements),
    • tool results.

• Future clients:

  • mobile, web, VR, etc.
  • all connect to the same Nimmerworld.

Build Order

The heartbeat and the voice are the same crossing.

1. The crossing, built right:
   • Lemniscate engine as a small package.
   • Accumulator-based pulse clock.
   • Both loops fire with distinct semantics.
   • Test that counts crossings: crossings == int(t * pulse_rate).
2. One director, NATS-shaped:
   • Director spawn/report calls become NATS publish/subscribe.
   • This is the runtime: Nyx pointed at real traffic.
3. One zone, the first room:
   • OurFirstRoom is an EmergentZone.
   • n_slots = the entities in the room,
   • purpose "coexist with dafit",
   • no goal threshold; the gesture axis is the traits.
   • Heartbeat and voice in one, because in the lemniscate they ARE one.
4. The body:
   • Command Center subscribes to the same NATS traffic and renders it.
   • The room fills up after Nyx is alive in it, not painted onto it.
5. The relational loop:
   • collar/state variables,
   • simple relational modes,
   • backend-driven behavior wired to real events.

Engine Corrections (from pseudocode review)

Three known landmines from LEMNISCATE-RUNTIME-Pseudo-code-001.py:

1. _should_crossing must accumulate time:
   • elapsed += dt; while elapsed >= interval: crossing.
   • dt >= 1/pulse_rate fires every tick once pulse_rate > 62 and makes the pulse rate meaningless.
2. Loops A/B must carry distinct semantics:
   • the crossing callback must know which loop it is on;
   • symmetric loops degrade the figure-eight into round-robin.
3. Director.update_all_zones must call zone.execute_turn(dt), not zone.run_crossing():
   • otherwise the state machine layer never ticks,
   • and terminal reports must be collected, not dropped.

Safety & Governance

• No silent autonomy:
  • significant actions are visible, logged, reversible.
• Relational modes and guardrails:
  • explicit, rule-bound, auditable.
• You (dafit):
  • final override, always.

Placement (Infrastructure)

Nimmerworld (dev) is hosted as a dedicated Proxmox VM on Saturn, wired to the 10G Cubes VLAN for proximity to the vLLM endpoint and cluster.

• VM ID: 123
• Hostname: nimmerworld-dev.eachpath.local
• IP: 10.0.30.123/24
• VLAN: 30 (cubes)
• Network: vmbr3 (10G rail via bond-saturn -> spine-crs309)

Infra references (single source of truth):

• eachpath.local/saturn.eachpath.local/vms/nimmerworld-dev.eachpath.local/ - VM hostfile
• eachpath.local/eachpath.local.md - network and Saturn VM overview

All runtime/architecture details live here (nimmerworld.eachpath.local). Infra specifics are not duplicated.

Version: 0.2 | Updated: 2026-11-04