86 lines
4.6 KiB
Markdown
86 lines
4.6 KiB
Markdown
# Nimmerworld: Runtime Server
|
|
|
|
Always-on, event-driven server for the agent (Nyx). Central backend for Pi, Command Center, and future clients. Not a UI, not a client, not a dashboard.
|
|
|
|
## Architecture
|
|
|
|
| Paper | Scope |
|
|
|---|---|
|
|
| [architecture/lemniscate.md](./architecture/lemniscate.md) | Runtime loop: topology, crossings, data flow, pulse clock, engine corrections. |
|
|
| [architecture/gates.md](./architecture/gates.md) | Gate layer: state, injection loop, closure guard, tags, probes, persistence. |
|
|
| [architecture/register.md](./architecture/register.md) | Registry: sensors, gates, actuators, clients, `drives`, arbitration, pods, placement. |
|
|
| [architecture/gates_index.md](./architecture/gates_index.md) | Reserved. |
|
|
| [schemas/README.md](./schemas/README.md) | Identity, impulse row, gate state, tag row, evidence request. |
|
|
| [schemas/gate_table.md](./schemas/gate_table.md) | Gate registry and state schema in Phoebe. |
|
|
| [runtime/stack.md](./runtime/stack.md) | Stack layers, two buses, JetStream replay, dependency budget. |
|
|
| [style/house-style.md](./style/house-style.md) | Paper register: engineer style rules, allowed voices per surface. |
|
|
|
|
## Folders
|
|
|
|
| Folder | Holds |
|
|
|---|---|
|
|
| architecture/ | Runtime engine and subsystem papers |
|
|
| runtime/ | Stack, pseudocode and successor, engine build order |
|
|
| storage/ | Storage layout and retention |
|
|
| database/ | Database schemas and migrations |
|
|
| schemas/ | Typed contracts and message schemas |
|
|
| tools/ | Runtime tooling |
|
|
| style/ | Voice, register, trait presentation |
|
|
|
|
## Infrastructure boundary (truth of record)
|
|
|
|
Host information is NOT held in this paper.
|
|
- Host truth: [eachpath.local](../eachpath.local/eachpath.local.md)
|
|
(topology) and `eachpath.local/saturn.eachpath.local/vms/<host>.eachpath.local/`
|
|
(per-host records). Missing host file for a host we run on? Create it
|
|
from host-onboarding facts, the same day.
|
|
- This repo's `architecture/` papers describe the SERVICES we run on
|
|
those hosts and their relationships; each such paper links its host
|
|
record instead of duplicating host facts.
|
|
- Paper follows reality: any claim about a host in this repo must be
|
|
host-verified against eachpath.local records.
|
|
|
|
## Learning (per-technology resources)
|
|
|
|
Every piece of technology we run gets a learning folder, so we can drill
|
|
down on the subject itself before the next round-trip builds on it.
|
|
|
|
- Folder per technology (see curriculum below).
|
|
- Ritual per folder: source of truth (official docs/spec first, never
|
|
second-hand), estate mapping (our host, port, version, config quoted
|
|
from the host record in eachpath.local), drills (hands-on questions
|
|
answered on OUR estate), and the ten-word understood-check said back.
|
|
- Learning gate: a primitive runs for real only after its paper is read
|
|
and explained back. We build ON knowledge, not around it.
|
|
|
|
Curriculum, in strict dependency order:
|
|
|
|
| # | Technology | Host record (eachpath.local) | Status |
|
|
|---|------------|------------------------------|--------|
|
|
| 1 | NATS + JetStream | `saturn.eachpath.local/vms/nats-dev.eachpath.local/` | open |
|
|
| 2 | Python asyncio + nats-py | runtime: nimmerworld-dev | next |
|
|
| 3 | PostgreSQL (Phoebe) | `.../phoebe-dev.eachpath.local/` | later |
|
|
| 4 | Godot client (GDScript, WebSocketPeer) | mimas/lab; boundary rule: pure client | later |
|
|
| 5 | FreeIPA / DNS / VLANs | athena, remus, romolus, spine+access | later |
|
|
| 6 | OPNsense (vulkan) | `vulkan.eachpath.local/` | later |
|
|
|
|
## Clients
|
|
|
|
Client = one crossing callback on the effect side. Runtime-first build order.
|
|
|
|
- Pi: sends user messages, receives replies and tool calls. Uses runtime as backend, not brain.
|
|
- Harness RPC (`omp --mode rpc`): long-lived headless JSONL session; host tools, URIs, UI callbacks. Harness is host, not brain.
|
|
- Command Center (Godot): pure client, no core logic. Renders worlds, bodies, tools, moods. Sends chat and interactions as gestures. Receives dialogue, autonomy commands, tool results as action calls. Subscribes to zone state and effect streams. See [command-center/README.md](../command-center/README.md).
|
|
- Future clients: mobile, web, VR; same runtime.
|
|
|
|
Interaction loop: chat -> text gate; room gestures -> switchboard; L1 admits; L2 action call drives body and dialogue the room renders.
|
|
|
|
## Safety and governance
|
|
|
|
- No silent autonomy: significant actions visible, logged, reversible.
|
|
- Relational modes and guardrails: explicit, rule-bound, auditable.
|
|
- Operator (dafit): final override, always.
|
|
- Gate switchboard: operator presence is a gate input above the runtime attention policy; rule-bound, no LLM in loop. Physical form of final override.
|
|
|
|
Version: 0.13 | Updated: 2026-11-04
|