From 6acdeb7b3772a7bf0fbc8c9e2fd1100beb9617e1 Mon Sep 17 00:00:00 2001 From: dafit Date: Sun, 26 Apr 2026 08:49:28 +0200 Subject: [PATCH] =?UTF-8?q?introduce=20operational=20scaffold=20(conventio?= =?UTF-8?q?ns=20+=207=20sub-dir=20stubs)=20Mirrors=20the=20nimmerverse.eac?= =?UTF-8?q?hpath.local=20structure=20for=20nimmerworld-specific=20operatio?= =?UTF-8?q?nal=20concerns.=20The=20fresh=20conventions/development-convent?= =?UTF-8?q?ions.md=20inherits=20from=20the=20platform-wide=20nimmerverse?= =?UTF-8?q?=20conventions=20and=20only=20defines=20what's=20nimmerworld-sp?= =?UTF-8?q?ecific:=20-=20Service=20identity:=20UID=20range=2010300-10399?= =?UTF-8?q?=20(gameserver/compositor/=20director/gm)=20-=20Port=20allocati?= =?UTF-8?q?on:=20+0100/+0200/+0300/+0400=20within=20env-blocks=20-=20NATS?= =?UTF-8?q?=20subjects:=20under=20{env}.world.{domain}.{service}.{detail}?= =?UTF-8?q?=20-=20K8s=20namespaces:=20world-{env}=20-=20Deployment=20topol?= =?UTF-8?q?ogy:=20dioscuri-as-substrate=20(per=202026-04-26=20housekeeping?= =?UTF-8?q?=20clarification=20=E2=80=94=20old=20nimmersky/SkyrimNet=20reti?= =?UTF-8?q?red;=20treat=20dioscuri=20empty)=20-=20Database=20conventions:?= =?UTF-8?q?=20nimmerworld=5F*=20table-prefix=20in=20shared=20phoebe-{env}?= =?UTF-8?q?=20Other=207=20sub-dirs=20are=20stubs=20pointing=20at=20planned?= =?UTF-8?q?=20content=20+=20referencing=20platform=20conventions=20for=20s?= =?UTF-8?q?hared=20patterns.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- conventions/development-conventions.md | 160 +++++++++++++++++++++++++ database/README.md | 33 +++++ deployments/README.md | 26 ++++ identity/README.md | 15 +++ k8s/README.md | 27 +++++ networking/README.md | 15 +++ runbooks/README.md | 24 ++++ storage/README.md | 22 ++++ 8 files changed, 322 insertions(+) create mode 100644 conventions/development-conventions.md create mode 100644 database/README.md create mode 100644 deployments/README.md create mode 100644 identity/README.md create mode 100644 k8s/README.md create mode 100644 networking/README.md create mode 100644 runbooks/README.md create mode 100644 storage/README.md diff --git a/conventions/development-conventions.md b/conventions/development-conventions.md new file mode 100644 index 0000000..6060f2a --- /dev/null +++ b/conventions/development-conventions.md @@ -0,0 +1,160 @@ +# Nimmerworld Development Conventions + +**The nimmerworld-specific application of nimmerverse platform conventions.** + +This document defines port assignments, service identities, NATS subjects, K8s namespaces, and database conventions for **nimmerworld** — the dystopian sandbox RPG running on the eachpath nimmerverse infrastructure. + +> **Inherits from:** [`nimmerverse.eachpath.local/conventions/development-conventions.md`](../../nimmerverse.eachpath.local/conventions/development-conventions.md) for platform-wide conventions (env separation dev/staging/prod/training, port-block allocation 30k/40k/50k/60k, FreeIPA service-identity pattern, NATS subject hierarchy, K8s namespace pattern, VM ID allocation). +> +> **This doc only defines what's nimmerworld-specific.** Where the platform conventions cover something, those rules apply unchanged. + +--- + +## Service Identity + +Pattern follows nimmerverse `svc-{service}-{environment}`. UID range allocated for nimmerworld: + +| UID Range | Service | Accounts | +|-----------|---------|----------| +| 10300-10309 | World Server (per-district authoritative state) | `svc-gameserver-dev`, `svc-gameserver-staging`, `svc-gameserver-prod`, `svc-gameserver-training` | +| 10310-10319 | Compositor (stateless narrative-composition workers) | `svc-compositor-dev`, `svc-compositor-staging`, `svc-compositor-prod` | +| 10320-10329 | Director-routines (ephemeral per-event-chain workers) | `svc-director-dev`, `svc-director-staging`, `svc-director-prod` | +| 10330-10339 | GM / Governor (equilibrium-seeker, catalogue-event dispatch) | `svc-gm-dev`, `svc-gm-staging`, `svc-gm-prod` | + +> Reference: nimmerverse [Identity Procedures](../../nimmerverse.eachpath.local/identity/procedures.md) + +--- + +## Port Allocation + +Within the platform-wide environment blocks (30k dev / 40k staging / 50k prod / 60k training), nimmerworld claims: + +| Offset | Service | Example (prod) | Purpose | +|--------|---------|----------------|---------| +| +0100 | World Server | 50100 | Authoritative district state, NATS dispatch, lemniscate runtime | +| +0200 | Compositor | 50200 | Stateless workers — narrative composition, canon-write | +| +0300 | GM / Governor | 50300 | Equilibrium-seeker, catalogue-event dispatch, faction-policy broadcast | +| +0400 | Director-routines | 50400 | Ephemeral per-event-chain workers (spin-up + prune) | +| +0500-0599 | Future nimmerworld services | — | Reserved | + +> Reference: nimmerverse [Port Allocation](../../nimmerverse.eachpath.local/conventions/development-conventions.md#port-allocation) + +--- + +## NATS Subject Hierarchy + +Pattern: `{env}.world.{domain}.{service}.{detail}` — extends platform pattern with `world.` prefix. + +| Subject | Description | +|---------|-------------| +| `prod.world.zone.event` | Zone-event broadcast (lemniscate axis-crossing events) | +| `prod.world.zone.command` | Director ↔ World request-reply for zone management | +| `prod.world.npc.dialog` | NPC dialog turn (driver-tier LLM output) | +| `prod.world.npc.gesture` | Player-gesture-alignment-accumulator state delta | +| `prod.world.compositor.canon` | Composed canon-fragments (UID-keyed, paced) | +| `prod.world.gm.policy` | GM equilibrium-policy broadcasts | +| `prod.world.governor.heartbeat` | Governor liveness | +| `prod.world.district.{id}.state` | Per-district state broadcast | +| `prod.world.faction.{name}.broadcast` | Faction demand broadcasts | + +For JetStream streams, use `{ENVIRONMENT}_WORLD` (uppercase) — e.g., `PROD_WORLD`, `TRAINING_WORLD`. + +> Reference: nimmerverse [NATS Subject Hierarchy](../../nimmerverse.eachpath.local/conventions/development-conventions.md#nats-subject-hierarchy) + +--- + +## Kubernetes Namespaces + +Pattern: `world-{environment}` — extends platform pattern with `world` function. + +| Function | Dev | Staging | Prod | Training | +|----------|-----|---------|------|----------| +| world | `world-dev` | `world-staging` | `world-prod` | `world-training` | + +> Reference: nimmerverse [K8s Namespaces](../../nimmerverse.eachpath.local/conventions/development-conventions.md#kubernetes-namespaces) + +--- + +## Deployment Topology + +Per v0.10 architecture + 2026-04-26 housekeeping clarification (treat dioscuri as empty; old nimmersky/SkyrimNet workloads being retired): + +| Component | Where | Why | +|---|---|---| +| **GameServer (per-district)** | dioscuri (bare-metal) — Threadripper PRO 7955WX + 128GB RAM gives massive CPU/RAM substrate; OR saturn-VM if isolation preferred | Per-district authoritative state; lemniscate runtime; benefits from direct hardware access for NPC tick-loops + NATS dispatch | +| **Compositor** | K8s pod on dioscuri/theia (`world-{env}` namespace, requesting `nvidia.com/gpu`) | Stateless workers; horizontal-scale on demand; uses GPU for trait-LoRA inference at composition time | +| **Director-routines** | K8s pod on dioscuri (`world-{env}` namespace, ephemeral) | Per-event-chain spawn; spin up + prune; uses driver-tier LLM for dialog generation | +| **GM / Governor** | K8s pod (`world-{env}` namespace) | Singleton or sharded; equilibrium-seeker; long-running | +| **Driver-tier LLM (Gemma 4 E4B)** | dioscuri GPU 1 (or GPU 0) | Per-NPC dialog inference at axis-rate; 4.5B effective fits comfortably in 20GB VRAM with trait-LoRA hot-swap headroom | +| **Optional Ring-A upgrade — Gemma 4 26B-A4B** | dioscuri (single GPU at Q4 GGUF) | When upper-consumer Ring-A capacity is desired | +| **Theia-tier LLM** | theia (when needed) | Clasp-confessions / mythic moments / deep-emotional-register | + +**Hardware discipline preserved:** Threadrippers (theia/dioscuri) host GPU workloads + bare-metal CPU/RAM-heavy work; Saturn-VMs handle non-GPU workloads (databases, k8s-master, infra). The conventions' Bare-Metal-vs-VM split (per platform doc §Deployment Topology) is honored. + +--- + +## Database Conventions + +nimmerworld claims tables prefixed `nimmerworld_*` in shared `phoebe-{env}` PostgreSQL instances: + +| Schema area | Tables (proposed) | +|---|---| +| **Zones (runtime)** | `nimmerworld_zones`, `nimmerworld_zone_slot_occupancy`, `nimmerworld_zone_taxonomy`, `nimmerworld_emergent_signals` | +| **NPCs (identity)** | `nimmerworld_npcs`, `nimmerworld_shift_history`, `nimmerworld_mind_pool` | +| **World canon (narrative)** | `nimmerworld_world_canon`, `nimmerworld_district_canon`, `nimmerworld_event_canon_summaries`, `nimmerworld_canon_provenance` | +| **Cells / topology** | `nimmerworld_cells`, `nimmerworld_rail_segments`, `nimmerworld_interiors`, `nimmerworld_proximity_candidates` | +| **Mods / personhood** | `nimmerworld_mods`, `nimmerworld_npc_mod_slots`, `nimmerworld_mod_wear_history`, `nimmerworld_trait_colors` | +| **Imperial / political-register** | `nimmerworld_district_reports`, `nimmerworld_imperial_policies`, `nimmerworld_imperial_budget_ledger`, `nimmerworld_imperial_net_transactions`, `nimmerworld_overseer_reports`, `nimmerworld_overseer_deployments`, `nimmerworld_imperial_to_gm_formulations`, `nimmerworld_district_cheat_ops` | +| **Memorialism** | `nimmerworld_memorialist_true_ledger` (the four-column ground-truth archive) | +| **Decisions / audit** | `nimmerworld_decision_log` | +| **Player input + LLM-config** | `nimmerworld_player_llm_config`, `nimmerworld_player_lora_backups`, `nimmerworld_player_data_sharing_consent`, `nimmerworld_base_model_versions`, `nimmerworld_federated_gradient_uploads` | +| **Trait-circle + universal-translator** | `nimmerworld_trait_circle_corpus`, `nimmerworld_player_translator_state`, `nimmerworld_player_circle_profiles` | +| **v0.7+ runtime alignment** | `nimmerworld_gesture_alignment_accumulator` (per-slot-token verifier-flag), `nimmerworld_player_npc_alignment_edges`, `nimmerworld_hardstop_registry` | + +**ChromaDB (`iris-{env}`)** holds vector storage for memory-embedding work — NPC primary.sqlite vec-indexes, semantic-similarity queries against accumulated trait-engagement, etc. Per-collection naming: `nimmerworld_{purpose}_{environment}`. + +> See [`../schemas/findings.md`](../schemas/findings.md) for v0.4-era DDL drafts being progressively split per-domain into [`./database/schemas/`](../database/) as implementation begins. + +--- + +## DNS Naming + +Pattern: `{service}.{environment}.world.nimmerverse.eachpath.local` — extends nimmerverse pattern with `world.` zone. + +> Reference: nimmerverse [DNS Naming](../../nimmerverse.eachpath.local/conventions/development-conventions.md#dns-naming) + +--- + +## Implementation Checklist + +When creating a new nimmerworld service: + +1. **Allocate UID** from the 10300-10399 nimmerworld range (extend §Service Identity table above) +2. **Calculate port** from environment block + nimmerworld service-class offset (§Port Allocation table above) +3. **Define NATS subjects** under `{env}.world.{domain}.{service}.{detail}` (§NATS Subject Hierarchy above) +4. **Add to K8s namespace** `world-{env}` with required labels (per platform conventions §Namespace Labels) +5. **Add to deployment topology** table — bare-metal vs K8s pod, which host +6. **Document** in this file + relevant runbook in [`../runbooks/`](../runbooks/) + +--- + +## Related Documents + +### Operational (this repo) +- [Architecture Index](../architecture-index.md) — full nimmerworld v0.10 architecture +- [Style Index](../style/style-index.md) — visual language (color palette, trait-palette, etc.) +- [Schemas](../schemas/findings.md) — engineering DDL drafts +- [Database](../database/) — per-domain schema content +- [K8s](../k8s/) — Kubernetes configuration +- [Runbooks](../runbooks/) — operational procedures + +### Platform (nimmerverse.eachpath.local) +- [Development Conventions (platform-wide)](../../nimmerverse.eachpath.local/conventions/development-conventions.md) — the doc this file inherits from +- [Identity Procedures](../../nimmerverse.eachpath.local/identity/procedures.md) — service account creation + +### Architectural source +- [Endgame-Vision](../../nimmerverse-sensory-network/Endgame-Vision.md) — cognitive substrate vision (the why, the dream) + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/database/README.md b/database/README.md new file mode 100644 index 0000000..1b60233 --- /dev/null +++ b/database/README.md @@ -0,0 +1,33 @@ +# Database — Nimmerworld + +PostgreSQL (`phoebe-{env}`) and ChromaDB (`iris-{env}`) schema content for nimmerworld. + +## Schema architecture + +nimmerworld claims tables prefixed `nimmerworld_*` in shared `phoebe-{env}` instances. See [`../conventions/development-conventions.md`](../conventions/development-conventions.md#database-conventions) for the per-domain table allocation overview. + +## Sub-structure (planned) + +``` +database/ +├── README.md # this file +├── schemas/ +│ ├── phoebe/ # PostgreSQL DDL per architectural domain +│ │ ├── runtime-engine/ # zones, slot-occupancy, emergent_signals, gesture-alignment +│ │ ├── identity-and-personhood/ # NPC trait-vectors, mods, mod-slots, mind-pool +│ │ ├── political-register/ # district_reports, imperial_*, memorialist_true_ledger +│ │ ├── narrative-composition/ # event_canon_summaries, world_canon, district_canon +│ │ └── inference-and-memory/ # player-LoRA backups, sharing-consent, base-model versions +│ └── iris/ # ChromaDB collections for memory-vector storage +└── migrations/ # schema-evolution migration scripts +``` + +## Status + +⏳ **Stub** — [`../schemas/findings.md`](../schemas/findings.md) holds the v0.4 DDL drafts that will be progressively split per-domain into this directory as implementation begins. + +> **Platform database conventions:** [`../../nimmerverse.eachpath.local/database/`](../../nimmerverse.eachpath.local/database/) (overview, schema patterns). + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/deployments/README.md b/deployments/README.md new file mode 100644 index 0000000..3004ce6 --- /dev/null +++ b/deployments/README.md @@ -0,0 +1,26 @@ +# Deployments — Nimmerworld + +Kubernetes manifests + systemd unit files for nimmerworld services. + +## Sub-structure (planned) + +``` +deployments/ +├── README.md # this file +├── k8s/ # Kubernetes manifests per service per environment +│ ├── compositor-{env}.yaml # Stateless workers (autoscaling) +│ ├── governor-{env}.yaml # GM / Governor (singleton or sharded) +│ └── director-{env}.yaml # Ephemeral per-event-chain (Job pattern?) +└── systemd/ # systemd units for bare-metal / VM-bound services + └── gameserver-{env}.service # World Server (per-district authoritative state) +``` + +## Status + +⏳ **Stub** — manifests land here as services are implemented. + +> **Platform deployment patterns:** [`../../nimmerverse.eachpath.local/deployments/`](../../nimmerverse.eachpath.local/deployments/) + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/identity/README.md b/identity/README.md new file mode 100644 index 0000000..2110829 --- /dev/null +++ b/identity/README.md @@ -0,0 +1,15 @@ +# Identity — Nimmerworld Service Accounts + +FreeIPA-managed service accounts for nimmerworld services. + +UID range **10300-10399** reserved for nimmerworld. Current allocations live in [`../conventions/development-conventions.md`](../conventions/development-conventions.md#service-identity). + +> **Onboarding/offboarding procedure:** [`../../nimmerverse.eachpath.local/identity/procedures.md`](../../nimmerverse.eachpath.local/identity/procedures.md) (platform-wide; nimmerworld follows it unchanged). + +## Status + +⏳ **Stub** — accounts will be provisioned as services are implemented. Reserved space for nimmerworld-specific identity-procedure deviations if any arise (none anticipated; nimmerworld follows the platform pattern). + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/k8s/README.md b/k8s/README.md new file mode 100644 index 0000000..925cd52 --- /dev/null +++ b/k8s/README.md @@ -0,0 +1,27 @@ +# Kubernetes — Nimmerworld + +K8s configurations for nimmerworld services running as pods. + +## Namespace pattern + +`world-{environment}` per [`../conventions/development-conventions.md`](../conventions/development-conventions.md#kubernetes-namespaces). + +| Function | Dev | Staging | Prod | Training | +|----------|-----|---------|------|----------| +| world | `world-dev` | `world-staging` | `world-prod` | `world-training` | + +## Workloads (per v0.10 architecture) + +- **Compositor** — stateless workers; autoscaling on queue-depth (`transient-waiting-flag` backpressure); requests `nvidia.com/gpu` for trait-LoRA inference +- **Director-routines** — ephemeral per-event-chain; spin-up + prune; requests `nvidia.com/gpu` for driver-tier LLM +- **GM / Governor** — long-running singleton or sharded; equilibrium-seeker; catalogue-event dispatcher + +## Status + +⏳ **Stub** — manifests land in [`../deployments/k8s/`](../deployments/) as services are implemented. + +> **Platform K8s patterns:** [`../../nimmerverse.eachpath.local/k8s/`](../../nimmerverse.eachpath.local/k8s/) (Traefik ingress, storage PV/PVC, etc.). + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/networking/README.md b/networking/README.md new file mode 100644 index 0000000..346f083 --- /dev/null +++ b/networking/README.md @@ -0,0 +1,15 @@ +# Networking — Nimmerworld + +Nimmerworld-specific network configuration. + +Mostly inherits from platform networking. This directory exists for future-specific concerns (e.g., per-district network isolation, gameserver-to-NATS routing optimization, MTU tuning for high-frequency NPC chatter). + +> **Platform networking:** [`../../nimmerverse.eachpath.local/networking/`](../../nimmerverse.eachpath.local/networking/) (MetalLB pool, VLAN allocations, etc.). + +## Status + +⏳ **Stub** — populate as networking-specific concerns arise during implementation. + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/runbooks/README.md b/runbooks/README.md new file mode 100644 index 0000000..9baeea0 --- /dev/null +++ b/runbooks/README.md @@ -0,0 +1,24 @@ +# Runbooks — Nimmerworld Operations + +Battle-tested operational procedures for nimmerworld. + +## Planned runbooks + +- **District reset** — re-initialize a district to world-gen-fresh state +- **NPC mass-respawn** — mind-pool reseed after district silence +- **World-canon publish** — trigger Compositor sweep + paced propagation +- **GameServer hot-restart** — graceful drain + restart without losing player session +- **LoRA hot-swap** — deploy new trait-LoRA to driver-tier without restart +- **Imperial-Cult content update** — designer pushes new propaganda content +- **Compositor scale-out** — manually add Compositor workers under spike-load +- **Player-data deletion request** — honor opt-out / per-category deletion (per `inference-and-memory/architecture.md` §Custom nimmerworld-base model) + +## Status + +⏳ **Stub** — runbooks accumulate as operations are exercised in real deployments. + +> **Platform runbooks** (golden rules, NFS recovery, etc.): [`../../nimmerverse.eachpath.local/runbooks/`](../../nimmerverse.eachpath.local/runbooks/) + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26 diff --git a/storage/README.md b/storage/README.md new file mode 100644 index 0000000..4912be2 --- /dev/null +++ b/storage/README.md @@ -0,0 +1,22 @@ +# Storage — Nimmerworld + +Storage architecture for nimmerworld game artifacts and runtime state. + +## What lives here (planned) + +- **World-canon storage** — composed canonical narrative; replicated to player `primary.sqlite` via Compositor back-write +- **District-canon storage** — regional state; paced canon-propagation +- **Player-LoRA backup storage** — encrypted-client-side LoRA blobs (Ring-A backup service per [`inference-and-memory/architecture.md`](../inference-and-memory/architecture.md) §Three rings of inference) +- **Designer-authored content storage** — faction iconography, world physical layout, Imperial Cult content, gesture-corpus, sex-position catalog, NPC-bootstrap-cornerstone-memories +- **Per-player local-memory architecture documentation** — `primary.sqlite` + `fallback.sqlite` + `clasp.sqlite` + `waifu.sqlite` organization (per [`inference-and-memory/architecture.md`](../inference-and-memory/architecture.md) §Three sqlite stores per player) +- **Womb-storage integration** — nimmerworld artifacts under `/womb/world/` namespace per the platform Womb pattern + +## Status + +⏳ **Stub** — populate as storage decisions land. v0.7+ architecture has Compositor + back-write loop spec'd; details of physical hosting (Womb integration, backup cadence per environment) decided at implementation time. + +> **Platform storage architecture:** [`../../nimmerverse.eachpath.local/storage/womb-architecture.md`](../../nimmerverse.eachpath.local/storage/womb-architecture.md) (theia + dioscuri + NFS Womb pattern). + +--- + +**Version:** 0.1 | **Created:** 2026-04-26 | **Updated:** 2026-04-26