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 catalog (9)#
The 9 tracked Nx projects in v6, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 9 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
service (7)#
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.
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.
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 ticks 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.
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.
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.
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.
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.
web (2)#
V6 Pixel Streaming entry.
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.
V6 Tier-2 fallback entry.
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.