# V6 Product Promise & Architectural Overview

```mermaid
flowchart LR
  Steward[Human steward] --> Client[Egbe client]
  Client --> Reused[V3-derived embodied-world substrate]
  Client --> New[New agent-mind substrate]
  Reused --> Orun[Persistent Orun simulation]
  New --> Ori[Durable Ori identity and cognition]
  Ori --> Orun
  Orun --> Aye[Aye portability boundary]
  Aye --> Other[V2-V5 experiences]
  Other --> Aye
  Aye --> Ori
```

The two substrates meet at an Ori's embodied presence but remain independently
owned: V3-derived services render and network the world, while V6 services own
mind, memory, welfare, and identity continuity. Aye is the explicit boundary for
carrying that identity elsewhere and safely home again.

V6 — **Egbe** — is the strangest and most ambitious of the V-products: not a
game you play but a world you _tend_. Its premise is a persistent open world
(**Orun**) populated by autonomous AI beings (each an **Ori**) who live
continuous lives — they wake, work, form bonds, fall out, set goals, grow old,
and one day depart — while the human player is not a hero inside that world but
its **steward**, discovering a company of these beings, raising them, bonding
with them, and guiding their fate without owning it. The defining architectural
choice follows directly from that premise: V6 rests on **two substrates kept
deliberately separate**, and the whole shape of the system is the consequence of
that split. The first substrate — embodied multi-user 3D — is _reused wholesale
from V3 (Lilith)_ and merely renamed (`Egbe-World`, `Egbe-Gateway`,
`Egbe-PxStream`, `Egbe-WebFB`); the second — a world of LLM-driven minds made
affordable, durable, and portable — is _new_, and is the engineering bet of the
product.

That bet is wired into the repository, not just the prose. The Unreal project at
`V6/ue/V6.uproject` pins `"EngineAssociation": "5.5"` and
`"DisableEnginePluginsByDefault": true`, declares **18 C++ modules**, and
enables the agent-density plugin stack the bet requires — `MassEntity` +
`MassAI` + `MassCrowd`, `StateTree` + `GameplayStateTree`, `PCG`,
`SmartObjects`, `GameplayInteractions`, alongside `Iris` + `ReplicationGraph` +
`NetworkPrediction`, `GameFeatures` + `ModularGameplay`, `OnlineServicesEOS`,
`OpenXR`, `PixelStreaming`, and `MetaHumanRuntime`. The new agent-simulation
substrate lives in **18 TypeScript libraries under `libs/v6/`** (with Rust
co-implementations of the hot paths), **seven Rust service crates under
`apps/v6/`**, and **14 registered Zod contracts under
`libs/contracts/src/v6/`**. This page is the orientation door to that
architecture: it states what V6 commits to and separates what is real on disk
from what is spec or production-gated. The full section index is
[../V6_ARCHITECTURE.md](../V6_ARCHITECTURE.md).

## What ships, honestly

The **UE module skeleton is real and exactly consistent.** Parsing `V6.uproject`
yields 18 `Modules` entries; `ls V6/ue/Source/V6*/` yields 18 module directories
(plus three `.Target.cs` files — `V6.Target.cs`, `V6Editor.Target.cs`, and a
dedicated `V6PixelStreamingWorker.Target.cs` server-render target); the two sets
are identical — **no spec-only modules, no orphan directories.** The tree
carries **67 `.cpp` and 47 `.h`** (114 source files), and the depth is
concentrated exactly where the agentic bet lives: the deepest non-test module is
**`V6Agent` (16 files)** — agent embodiment over Mass Entity — followed by
**`V6World` (10)** — procedural districts and the client world model — with
`V6Core`, `V6UI`, and `V6Editor` at 8 each. `V6Agent` is not a renamed CRUD
shell: `V6AgentMassLODProcessor.cpp` is a genuine `UMassProcessor` subclass that
builds an `FMassEntityQuery`, declares fragment requirements
(`FMassRepresentationLODFragment`, `FV6AgentMassLODFragment`,
`FV6AgentPerceptionLODFragment`), and drives a chunked `ForEachEntityChunk`
density-LOD pass — real Mass code, against the
`MassActors`/`MassLOD`/`MassRepresentation`/`MassSimulation` modules its
`V6Agent.Build.cs` depends on.

The **service plane is real Rust at the authoritative tier.** `apps/v6/` is a
Cargo workspace (`resolver = "2"`, edition 2021, Rust 1.82,
`unsafe_code = "forbid"`) whose heavy crates do substantial work:
**`egbe-world-server` is 14,360 lines** of `lib.rs`, `egbe-ori-service` is
**4,946**, `egbe-realtime-gateway` is **3,942**, and `egbe-pxstream-relay` is
**1,287**. The kernel logic itself is co-implemented in Rust under
`libs/v6/*/rust`: **`moirai-kernel/rust` is 5,732 lines**, `agent-behavior/rust`
**2,637**, `ori-model/rust` **1,903**, and the shared wire protocol
`egbe-protocol/rust` **1,675**. All four are workspace members, so the
network-facing services compose the same kernel the TypeScript libraries expose.

The honest gaps, named rather than implied:

- **The light service crates are honest shells, not stubs.** `egbe-clio-service`
  (68 lines), `egbe-moirai-cluster` (520), and `egbe-foundry-service` (700) are
  deliberately thin: each exposes a typed `SERVICE_DESCRIPTOR` (name, port, a
  real capability list), a `/health` endpoint, and a TCP/`run_service` loop,
  then **composes** the heavy logic — the cluster instantiates
  `moirai_kernel::MoiraiKernel` with `KernelTickConfig` and drives
  `KernelTickReport`; Clio's chronicle generation lives in the 1,701-line
  TypeScript `@oshun/clio-story`. They report their surface honestly; they do
  not fake results.
- **No hand-authored art `.uasset`.** `V6/ue/Content/` holds **0 `.uasset`** and
  **6 `.umap`** — the six Districts of Orun (`L_GroveOfBeginnings`,
  `L_Ateliers`, `L_CommonsHeart`, `L_Wilds`, `L_AncestorGrove`, `L_Thresholds`
  under `Content/Districts/`). V6 is a **logic + procedural-ground +
  GameFeature- descriptor** tree: real C++ systems, real district maps, and real
  plugin binaries, but no hand-authored meshes, MetaHumans, mocap, VO, or
  cinematics in-tree. Every "premium 3D world" claim depends on art/audio
  production not in the repository.
- **The mode/district plugins _are_ binary-authored — a contrast with V5.**
  `V6/ue/Plugins/GameFeatures/` holds **10 Game Feature plugins** — six
  districts (`V6District_*`) and four modes (`V6Mode_SoloHomestead`,
  `_CoopVisit`, `_Commons`, `_Incarnation`) — and **each ships a real binary
  `GameFeatureData.uasset`** (verified as "Unreal Engine package
  (little-endian)", ~2.2 KB each; 10/10 present). Where V5's `V5Mode_*` plugins
  carried zero `GameFeatureData.uasset`, V6's districts and modes are genuinely
  hot-activatable Game Features. None are listed in the `.uproject` `Plugins`
  array — they are activated per district/mode, by design.
- **Provider- and ops-gated surfaces.** The live LLM inference behind cognition,
  the EOS online backend, and the Pixel Streaming GPU worker fleet are wired and
  modeled but not run in-repo; the third-party `VRM4U` avatar plugin under
  `Plugins/` is untracked vendor code. These are the boundaries V6 fails loud
  at, not places it fabricates success.

## The product promise

V6's promise, authored in `V6_features.md` and mirrored in the architecture
monolith's `V6 Product Promise` section, is a small set of non-negotiable
commitments. The unifying idea is **one agentic-companion universe**, and each
commitment has a code anchor or an honest status.

| #   | Commitment                                                                    | Code-grounding / status                                                                                             |
| --- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 1   | A persistent open world (Orun) of autonomous AI beings                        | `V6World` (district grounds, PCG scatter) + `V6Agent` Mass-Entity density LOD; six `L_*.umap` districts             |
| 2   | Each being is a durable, event-sourced biography (the Ori)                    | `@oshun/ori-model` `OriEventLog` (append-only, vector-clocked); `egbe-ori-service` (4,946 LOC, Postgres + pgvector) |
| 3   | A population of LLM minds made affordable by tiered cognition                 | `@oshun/moirai-kernel` Clotho/Lachesis/Atropos tiers + token budgets; `moirai-kernel/rust` (5,732 LOC)              |
| 4   | The player is a steward, not an owner                                         | `@oshun/lilith-agent-welfare` (2,166 LOC); `evaluateMinorCodedAgentProtection` in `@oshun/agent-behavior`           |
| 5   | Beings communicate by voice and intent                                        | `@oshun/vac-intent` (1,750 LOC); `V6Voice` module + `V6VacVoiceIntentPipelineTests`, `V6VacSquadCommsTests`         |
| 6   | Their lives are narrated back as a Chronicle and a Book of the Ori            | `@oshun/clio-story` (1,701 LOC) → `egbe-clio-service` capability list; Yemaya keepsake-edition trigger              |
| 7   | New beings are minted by a governed foundry                                   | `@oshun/isis-agent-gen` (1,442 LOC) + `isis-behavior-policy`; `egbe-foundry-service` over Isis generation           |
| 8   | Beings carry across the Oshun universe (V2–V5) and home again                 | `@oshun/aye-bridge` (2,398 LOC) passport minting + incarnation journal; `OriPassport` contract                      |
| 9   | No device is locked out — UE5 canonical, three.js/WebGPU Tier-2 floor         | `V6/ue/` (UE5.5) + `egbe-pxstream-relay`; `@oshun/egbe-engine-web-fallback` + `apps/v6/egbe-web-fallback`           |
| 10  | Endings have weight — departure, transcendence, death, and a walkable lineage | `@oshun/ereshkigal-legacy` (947 LOC); `V6District_AncestorGrove`; Ori events `Departed`/`Transcended`/`Died`        |

Commitment 9 is the one V6 inherits rather than invents: it is V3's tiered
client stack, carried over so a visitor on a constrained device still sees Orun
at reduced fidelity. Everything else in the table is new code in `libs/v6/`,
`apps/v6/`, and the agent-bearing UE modules.

## The agentic-companion thesis

The thesis is that a believable companion is not a chatbot with a 3D body but a
**mind, a body, and a biography held by three different authorities that never
collapse into one.** The vocabulary is fixed (Yoruba cosmology for the product
layers — Egbe, Orun, Ori, Aye; underworld and fate figures for the subsystems —
Moirai, Vac, Clio, Ninhursag, Ereshkigal), and each name maps to a real package.
The single most important structural decision in V6 is this three-way split:

- **The Body — `Egbe-World`** (`apps/v6/egbe-world-server`). Authoritative for
  the _world_: agent transforms, physics, navmesh, co-presence, world time. An
  agent's _intent_ is never authoritative here — only what physically happened
  is. It runs the world tick and validates every proposed action against real
  state, so an agent cannot walk through a wall because it "intended" to.
- **The Mind — `Moirai`** (`@oshun/moirai-kernel` +
  `apps/v6/egbe-moirai-cluster`). Authoritative for _decisions_: given
  perception and state, it produces a stream of intents and actions. It owns no
  world state.
- **The Memory — `Ori`** (`@oshun/ori-model` + `apps/v6/egbe-ori-service`).
  Authoritative for _who the agent is_: identity, the event-sourced biography,
  memory, relationships, values, capabilities — the same record whether the
  being stands in a Solo homestead, the Commons, or a V2 arena.

This split is also the resilience story. The cheap deterministic layers of the
mind (`@oshun/agent-behavior`, with its Rust co-implementation) run co-located
with the world server, so a cognition-cluster outage costs _richness_, never the
world: agents fall back to behavior-tree and goal-arc execution and Orun keeps
running believably. The agent _mind itself is not a new model_ — V6 adds no
"brain." It assembles the mind from V1's Iris (memory), Psyche (runtime), Isis
(governed generation), and Sophia (grounding), and adds the kernel that
_schedules_ those substrates across a whole population, plus the _life_ around
the mind: the body, the daily rhythm, the fate, and the budget.

## The agent mind, body, and memory in code

### The Memory — an event-sourced Ori

`@oshun/ori-model` (2,145 LOC TS, 1,903 LOC Rust) is the spine. An Ori is not a
mutable row; it is a stream of immutable facts. `OriEventLog.append()` is a real
append-only store: it derives a per-stream `sequence`, generates or validates an
`eventId`, refuses duplicates, advances a **per-writer-context vector clock**,
and freezes the record with its attribution and provenance reference — the
structural guard that lets the same biography be written from multiple shards
and reconciled deterministically. The vocabulary is fixed: **19
`ORI_EVENT_TYPES`** (`Born`, `Discovered`, `MemoryFormed`, `Reflected`,
`RelationshipChanged`, `ValueShifted`, `ObjectiveAccepted`/`Refused`,
`ArcAdvanced`, `Crossroads`, `Incarnated`, `IncarnationReturned`, `Departed`,
`Transcended`, `Died`, …) and **8 `ORI_PERSONALITY_TRAITS`** (warmth, curiosity,
caution, ambition, conscientiousness, candor, defiance, playfulness).
Inspectable state is a _projection_, never the source:
`applyOriEventToProjection` / `rebuildOriProjection` fold the log,
`buildOriProjectionSnapshots` / `loadOriProjectionFromSnapshot` checkpoint every
`ORI_PROJECTION_SNAPSHOT_INTERVAL = 512` events under a 1-second load budget,
and `compareOriVectorClocks` + `resolveOriEventConflicts` +
`appendForgivenessEvent` reconcile divergent streams. Drift is bounded, not free
— `ORI_TRAIT_DRIFT_MAX_PER_SEASON_BASIS_POINTS = 500` caps how far a personality
can move in a season — and routine cognition is cached and invalidated on
material change (`buildOriMaterialFingerprint`,
`resolveOriRoutineCognitionFromCache`).

### The Mind — Moirai's tiered cognition kernel

A world of LLM minds is only affordable if most of them think cheaply most of
the time. `@oshun/moirai-kernel` encodes that as **three named tiers** —
`MOIRAI_TIER_CLOTHO = 1` (live, on-screen scenes), `LACHESIS = 2` (off-screen
resident reflection), `ATROPOS = 3` (long-horizon day-scale sampling) — each
with a hard token budget (`CLOTHO_ACTIVE_MINUTE_TOKEN_BUDGET = 50_000`,
`LACHESIS_REFLECTION = 10_000`, `ATROPOS_GAME_DAY = 15_000`) and a population
ceiling (`CLOTHO_ACTIVE_SCENE_HARD_CAP = 24`,
`LACHESIS_RESIDENT_WORLD_HARD_CAP = 400`,
`WORST_CASE_ATROPOS_SAMPLE_AGENTS = 1_000`). Each tier is right-sized to a model
class — `haiku-class`, `sonnet-class`, `opus-class` — gated by quality bars
expressed in basis points per metric (`social-judgment-live-dialogue`,
`offscreen-reflection-coherence`, `narrative-summary-continuity`), so a tier may
only drop to a cheaper class if it still clears the bar.
`evaluateMoiraiCognitionBudget` is a real allocator: it sorts requests, caps
each at its tier budget, then draws down a per-solo-world cap, and returns
deferred-token accounting — not a hardcoded "ok." `selectMoiraiModelRoute`,
`simulateWorstCaseSoloWorldCognitionBudget`, and
`buildMoiraiCognitionCallAuditLog` (which routes every cognition call into the
V1 audit-platform retention policy) complete the loop. The actual model
inference is dispatched through the cognition seam — the kernel decides _which
tier and class_ each agent-tick gets and proves the budget holds; the live call
is the provider-gated boundary.

### The Body — the authoritative world server, and the fallback that keeps it alive

`egbe-world-server` (14,360 LOC Rust) is the body: it holds shard state and
presence, runs physics authority, and validates the action batches Moirai
returns. Perception flows out to the mind, actions flow back in, valid results
replicate to clients and durable life-events flush to the Ori service. When the
mind is degraded, `@oshun/agent-behavior` (2,348 LOC TS, 2,637 LOC Rust) carries
the world on deterministic rails: `assignObjectiveFromVacTranscript` turns a
steward's spoken intent into an objective, `learnFromStewardDemonstration`
acquires behavior from example, `advanceAgentLifeArc` and
`resolveAgentCrossroads` move a being through its goal arcs and branch points,
and `evaluateMinorCodedAgentProtection` enforces the welfare floor that keeps
the steward a guardian, not an owner. All of it speaks one wire protocol —
`@oshun/egbe-protocol` (2,278 LOC TS + 1,675 LOC Rust + generated codecs), whose
`ServiceDescriptor`/`health_json`/`wire` surface every Rust service imports.

## The cognition stack and the reused V1 substrates

Sitting between Moirai and the V1 brains is `@oshun/cognition-stack` (1,698
LOC): it assembles bounded context (`CognitionContextAssemblyLimits`,
`AssembledCognitionRequest` with explicit omitted-section counts), runs a
grounding pass (`CognitionGroundingReport`), gates output through policy
(`PolicyGatedCognitionOutput`), localizes dialogue (`CognitionLocaleProfile`),
and emits the resulting `OriEventDraft`s back into the biography. The brains
themselves are V1 packages extended for agents — `@oshun/memory-iris-agent`
(episodic/semantic/reflective scopes), `@oshun/psyche-agent` (dialogue/voice/
turn-taking), `@oshun/isis-agent-gen` + `@oshun/isis-behavior-policy` (governed
generation + per-tick output gating), and `@oshun/sophia-agent-grounding`
(backstory grounded in fact). The contract layer (`libs/contracts/src/v6`) ties
it together: **14 registered contracts** in `V6_CONTRACT_REGISTRY`
(`OriIdentityCore`, `OriEvent`, `PersonalityModel`, `RelationshipEdge`,
`CapabilityProfile`, `OriPassport`, `Bond`, `StewardProfile`, `Objective`,
`GoalArc`, `WorldShard`, `Crossroads`, `IncarnationJournal`, `Chronicle`), each
a Zod schema plus a validated fixture, a route segment, and a service surface
(`ori` or `world`), with an OpenAPI projection in `openapi.ts`.

## How the promise is kept honest

Two conventions keep V6's prose from drifting ahead of its tree. First, the
**cross-reference convention**: a bare `§N`/`§N.M` resolves to a numbered task
in `V6_TODOS.md` (the implementation source of truth), while `deps§N` →
`V6_DEPENDENCIES.md`, `features§"anchor"` → `V6_features.md`, and
`v3arch§"anchor"` → the V3 architecture V6 reuses. Second, the **two-substrate
discipline**: anything in the metaverse half is V3's already-paid-for design,
renamed; anything in the agent half is the new code this page inventories. The
precise claim a reader can make today: V6's _systems_ — 18 UE modules over 114
source files, 18 `libs/v6/` packages with Rust co-implementations of the hot
paths, seven Rust service crates, 14 typed contracts, and the in-tree UE
automation harness (`V6Tests`: 20 spec files, 37 `IMPLEMENT_*_AUTOMATION_TEST`
declarations across agent behavior, density LOD, district PCG, and the Vac
voice/squad pipelines) — are real and code-grounded; the **10
`GameFeatureData.uasset`** binaries make its districts and modes genuinely
hot-activatable; and the _content_ that would dress Orun (meshes, MetaHumans,
VO, cinematics) plus the _live operations_ (LLM inference, EOS, the Pixel
Streaming GPU fleet) are production- and provider-gated, marked as such rather
than implied.

## Related

- Hub: [../V6_ARCHITECTURE.md](../V6_ARCHITECTURE.md); feature map
  `V6/V6_features.md`; backlog `V6/V6_TODOS.md`; dependency registry
  `V6/V6_DEPENDENCIES.md`; remediation log `V6/REMEDIATION_2026-06-12.md`.
- [./subsystem-glossary.md](./subsystem-glossary.md) — the full subsystem,
  UE-module, Game-Feature-plugin, service, and `libs/v6` package map.
- [./architecture-topology-and-layout.md](./architecture-topology-and-layout.md)
  — the runtime topology, the mind/body/memory per-tick loop, the project
  layout, and the build/target matrix in full.
- [../../platform/overview.html](../../platform/overview.html) — the shared
  Oshun platform foundations (V1 identity, contracts, event bus, audit,
  residency) the V6 agent mind and service plane build on.