introduce operational scaffold (conventions + 7 sub-dir stubs) Mirrors the nimmerverse.eachpath.local structure for nimmerworld-specific operational concerns. The fresh conventions/development-conventions.md inherits from the platform-wide nimmerverse conventions and only defines what's nimmerworld-specific: - Service identity: UID range 10300-10399 (gameserver/compositor/ director/gm) - Port allocation: +0100/+0200/+0300/+0400 within env-blocks - NATS subjects: under {env}.world.{domain}.{service}.{detail} - K8s namespaces: world-{env} - Deployment topology: dioscuri-as-substrate (per 2026-04-26 housekeeping clarification — old nimmersky/SkyrimNet retired; treat dioscuri empty) - Database conventions: nimmerworld_* table-prefix in shared phoebe-{env} Other 7 sub-dirs are stubs pointing at planned content + referencing platform conventions for shared patterns.

2026-04-26 08:49:28 +02:00
parent 0fa597c25b
commit 6acdeb7b37
8 changed files with 322 additions and 0 deletions
--- a/conventions/development-conventions.md
+++ 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
--- a/database/README.md
+++ 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
--- a/deployments/README.md
+++ 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
--- a/identity/README.md
+++ 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
--- a/k8s/README.md
+++ 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
--- a/networking/README.md
+++ 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
--- a/runbooks/README.md
+++ 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
--- a/storage/README.md
+++ 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