# V6 — Systems Deep Dive

> The `apps/v6/` area: the runnable edge of **Egbe** (the Districts-of-Orun
> agent society) — a seven-crate Rust backend of authoritative world, cognition,
> transport, streaming, identity, narrative, and foundry services, plus two
> Vite/TypeScript web entry clients.

## What this area is

V6 is the application tier of **Egbe** — Oshun's persistent agent-society
product where player-stewarded "Ori" agents live across solo homesteads and
shared Commons regions. Where the `libs/v6/` packages hold the reusable engine
and policy code (the protocol, the Moirai cognition kernel, the Ori model, agent
behaviour, narrative, grounding), `apps/v6/` holds the **deployable processes**
that wire those libraries into running services and shipped web clients. The
nine tracked Nx projects split cleanly into two technology families, reflected
in their tags: seven `type:rust-app` / `layer:service` crates and two
`layer:web` / `type:app` Vite bundles.

The seven Rust services form a single Cargo workspace rooted at
`apps/v6/Cargo.toml` (resolver 2, `unsafe_code = "forbid"`, edition 2021). Every
service crate declares `egbe-protocol` as a path dependency and an Nx
`implicitDependencies` edge to `@oshun/egbe-protocol`, so the wire types
(`wire::PerceptionBatch`, `wire::ActionBatch`, `ServiceDescriptor`,
`health_json`, `protocol_v6_0_0`) are shared identically across the fleet. Each
service follows the same runtime shape: a `SERVICE_DESCRIPTOR` constant naming
the service, its fixed port (46101–46107), and a capabilities list; a
`run_service()` that binds a blocking `std::net::TcpListener` and answers
`GET /health` with `health_json(&SERVICE_DESCRIPTOR)`. The substantive domain
work lives not in the HTTP handler but in the crate's **pure, unit-tested
functions and types** — the world tick, the dispatch fleet, the voice SFU, the
admission classifier, the Ori event store — which is where the real algorithms
and the `#[cfg(test)]` correctness assertions sit.

The two web clients are the player-facing entries. `@oshun/v6-egbe-web` is the
primary **UE Pixel Streaming** shell (port 3061), and
`@oshun/v6-egbe-web-fallback` is the **Tier-2 reduced-fidelity** path
(port 3062) that renders Orun locally in Three.js (WebGPU first, WebGL2
fallback) when pixel streaming is unavailable. Both are thin composition layers
over `libs/v6/` packages rather than self-contained logic.

## How it fits the wider system

The services are designed as a horizontally-scalable real-time backend: a player
client (either web entry, or a native UE pixel-streaming worker) connects
through `egbe-realtime-gateway`, which routes presence and voice and pins the
session to a world shard served by `egbe-world-server`; the world server's
perception batches are dispatched to the `egbe-moirai-cluster` cognition fleet
(built over `moirai-kernel`); agent identity, memory, and provenance are
persisted by `egbe-ori-service` (over the `ori-model` event log and a pgvector
index); `egbe-foundry-service` mints the agents that populate the world under
Isis governance; `egbe-clio-service` is the narrative/chronicle surface; and
`egbe-pxstream-relay` matchmakes UE render workers for the high-fidelity client.
The boundary between app and library is consistent: app crates own process
lifecycle, ports, HTTP edges, and orchestration; the engine/policy logic they
compose is owned by `libs/v6/`. The honest caveat throughout is that the Rust
services expose only a health endpoint (plus a couple of routed paths in
`foundry` and `pxstream`) — the rich capability surface is reachable today as a
tested in-crate API, not yet as a full network protocol.

## Entity reference

### v6-egbe-world-server

The authoritative world simulation (`apps/v6/egbe-world-server/src/lib.rs`,
~14.3K lines, 33 tests; port 46101). This is the largest and most substantive
service: it owns the 20 Hz world tick, `GroundState`/`GroundActorState` room
simulation with **real `rapier3d` rigid-body/collider physics** (`RigidBodySet`,
`ColliderSet`, `vector`) and `agent_behavior` execution-mode selection. It
implements solo-homestead instances with offline "Atropos" advance and
returning-player chronicles, co-op bridged sessions with visiting-Ori
reconciliation, shard-travel Ori rebind, a persistent regionally-sharded Commons
fleet with festivals and interest-managed cognition, cognition-capacity-pressure
degradation with a player-visible notice, deterministic seeded/golden replay
(`DeterministicCoreGoldenReplay*` against a fixture gate), the four-facet bond
model and wild-agent meet/learn/trust/choice discovery, residency routing, and
the Lilith/Themis reporting-review-appeal pipeline. The runtime `run_service()`
serves only `/health`; the simulation surface is the tested public API.

### v6-egbe-moirai-cluster

The cognition dispatch fleet (`apps/v6/egbe-moirai-cluster/src/lib.rs`, ~520
lines; port 46102). It wraps the `moirai-kernel` library into a horizontally
scalable cluster: `AgentShardedDispatchFleet` routes each
`wire::PerceptionFrame` to a worker node by **rendezvous (highest-random-weight)
hashing of the agent's `ori_id`** (FNV-1a `stable_hash`), so the same Ori stays
on the same kernel, nodes can be added live, and `mark_node_lost` rebalances
without dropping agents (verified by tests dispatching 3,000–4,000 agents). Each
worker holds a `MoiraiKernel` and `tick`s its routed sub-batch; results are
re-ordered to the original frame order and emitted as a `wire::ActionBatch`.
Returns `DispatchFleetError::NoActiveWorkers` when the fleet is empty rather
than fabricating output.

### v6-egbe-realtime-gateway

The realtime edge gateway (`apps/v6/egbe-realtime-gateway/src/lib.rs`, ~3.9K
lines, 23 tests; port 46103). It negotiates transport across WebTransport /
WebRTC / WebSocket from a `RealtimeClientNetworkProfile`, authenticates the
handshake with a **real HS256 JWT** implementation
(`sign_auth_primitives_hs256_jwt` / `verify_...` over the `hmac`, `sha2`, and
`base64` crates), routes clients to world shards via `WorldShardDirectory`, pins
sessions and retains them for reconnect resume, applies backpressure
(`apply_gateway_backpressure`), and fans out presence transforms at 20 Hz
(`PresenceFanoutHub`). A large `VoiceSfuModule` implements the "Pheme" voice
stack: positional proximity voice with distance attenuation and occluder mixing,
scriptable voice range, job-gated radio channels with squelch and push-to-talk,
phone calls, live captions, accessibility indicators, parental controls, and a
platform safety tap. As with the other services, the bound `TcpListener` only
answers `/health`.

### v6-egbe-pxstream-relay

The Unreal Engine Pixel Streaming relay/matchmaker
(`apps/v6/egbe-pxstream-relay/src/lib.rs`, ~1.3K lines, 9 tests; port 46104).
Unlike the health-only services, its `run_service()` routes a small real HTTP
surface through `route_http_request`: `/health`, a `GET`/`POST` match endpoint
(`match_pxstream_session` → worker-pool routing with a first-frame SLA), and a
`POST` admission-evaluate endpoint. `evaluate_v6_pxstream_admission` implements
entitlement- and abuse-aware admission control (reusing the V3 pixel-streaming
abuse posture), `evaluate_pxstream_idle_lifecycle` reclaims idle sessions, and
`classify_pxstream_abuse` / `validate_pxstream_abuse_classifier` provide the
abuse-signal classification with a self-validation harness.

### v6-egbe-ori-service

The Ori identity, memory, and provenance service
(`apps/v6/egbe-ori-service/src/lib.rs`, ~4.9K lines, 28 tests; port 46105).
Built over the `ori-model` event log, it provides a hash-partitioned Postgres
event store (`PartitionedPostgresOriEventStore`, 64 partitions, embedded
`CREATE TABLE` DDL with a P99 budget constant), a `PgVectorMemoryIndex` over a
1536-dim pgvector HNSW schema with episodic/semantic layers, Ori passport
minting with Isis signatures (`MintedOriPassport`), incarnation-journal
writeback, operator-read audit events, consent-scoped DSAR export and lawful
deletion under named policy refs, a V3 takedown-cascade router, cross-platform
continuity snapshots (no save reconciliation), and `steward-not-owner` authority
enforcement with a 512-iteration fuzz report. Heavily constant-driven (schema
versions, policy refs, SLAs) and event-sourced; the runtime again serves only
`/health`.

### v6-egbe-clio-service

The narrative / chronicle service descriptor
(`apps/v6/egbe-clio-service/src/lib.rs`, ~68 lines, 1 test; port 46106). **This
is the thinnest of the seven crates and honestly so:** its `SERVICE_DESCRIPTOR`
advertises thirteen narrative capabilities (chronicle generation, story-beat
ranking, Book-of-the-Ori long-form biography, emergent-arc surfacing, narrative
reconciliation, …), but the crate itself implements only the `health_document()`
/ `run_service()` health server and a test asserting the descriptor names the
service. The advertised narrative logic is implemented in the
`@oshun/clio-story` library (consumed directly by the web-fallback client via
`createReturningPlayerChronicle`, `surfaceEmergentArcPrompts`, etc.), not in
this service binary — so today this node is a capability/health shell in front
of that library rather than a service exposing the narrative API over the wire.

### v6-egbe-foundry-service

The agent foundry (`apps/v6/egbe-foundry-service/src/lib.rs`, ~700 lines, 6
tests; port 46107). It generates the world's initial population:
`launch_discovery_seeds()` mints 150 unique, validated discovery seeds across
six Wilds/Commons districts (each with personality, Sophia-grounded backstory,
appearance, relationships, and an Isis provenance bundle), exposed at the routed
`GET /discovery-seeds/launch` endpoint. `generate_player_raised_seed` implements
**Isis-governed player-raising** that refuses non-compliant premises with typed
reasons (`MissingSophiaGrounding`, `RealPersonLikeness`,
`ProtectedClassCaricature`) rather than fabricating an agent, and a
rearing-period model (`start_rearing_period` → `apply_rearing_observation` →
`complete_rearing_period` → `evaluate_rearing_value_shift`) shapes values in
basis points by observed steward behaviour while preserving adult autonomy
rights. `record_*_foundry_provenance` emits append-only provenance records for
both the seeded and raised creation paths.

### @oshun/v6-egbe-web

The primary UE Pixel Streaming web entry (`apps/v6/egbe-web/`, Vite/TypeScript;
dev port 3061). A thin shell composing `@oshun/egbe-web-pxstream` and
`@oshun/ori-model`: `src/main.ts` builds a `createPixelStreamingLaunchConfig`
from `VITE_EGBE_PXSTREAM_*` env vars and calls `renderEgbeWebShell`;
`src/app.ts` (`createEgbeWebViewModel`) maps the pixel-streaming client's status
machine (`idle → matching → matched → signalling → streaming`, plus `degraded`)
to a DOM view model with first-frame-budget telemetry and an "Enter Orun" /
"Retry stream" action. It carries Playwright e2e coverage
(`e2e/egbe-web-pxstream.spec.ts`) and ships a built `dist/` bundle. The
streaming client logic itself lives in the `@oshun/egbe-web-pxstream` library.

### @oshun/v6-egbe-web-fallback

The Tier-2 reduced-fidelity web client (`apps/v6/egbe-web-fallback/`,
Vite/Three.js; dev port 3062). The most code-heavy web entry (`src/app.ts` ~4.9K
lines, `src/orun-three-renderer.ts` ~480 lines): `orun-three-renderer.ts` is a
real Three.js scene runtime that requests WebGPU and falls back to WebGL2, while
`app.ts` negotiates `@oshun/egbe-protocol` (version handshake, perception→
action batches), builds Ori projections from `@oshun/ori-model`, schedules the
visible cognition tick through `@oshun/moirai-kernel`, caps the embodied agent
set per a density budget from `@oshun/egbe-engine-web-fallback`, and backfills
narrative for culled agents via `@oshun/clio-story`. It additionally composes
cognition localisation (`@oshun/cognition-stack`), Isis behaviour policy, Sophia
cultural grounding, and VAC intent (`@oshun/vac-intent`) — a genuine integration
surface across the V6 libraries — with Playwright canvas/fallback/focus e2e
coverage.