# Overview, Subsystem Glossary & Product Promise ```mermaid mindmap root((Lilith V3)) Shared substrate Identity and provenance Realtime world services Unreal and web clients Tara Studio Verified instructors Consent-shaped classes On-device Aja coaching Saraswati Stage Persistent artist personas Gated discography Sequencer concerts Lilith Commons Contemplative venues Community presence Live operations ``` The map is deliberately product-first: every tenant inherits the same identity, provenance, realtime, and client substrate, then adds a loop with its own safety or quality gates. Read down one branch for the player promise, then use the glossary below to resolve each label to its code and evidence surface. This is the orientation page for the V3 feature set — the page to read before any of the deeper feature pages, so that when a later page says "the launch decision comes back from `/api/v3/lilith/launch`" or "the concert export fails the `concert-quality` gate," the name already lands on something real you can open. V3 is **Lilith Metaverse** — an embodied, multi-user contemplative world built canonically on **Unreal Engine 5.5 LTS** and layered on top of the existing V1 Oshun platform. It is one coherent product, not three: a metaverse _substrate_ plus three flagship tenant experiences — **Tara Studio** (live and on-demand yoga / breathwork / meditation), **Saraswati Stage** (AI virtual bands and artists), and **Lilith Commons** (open contemplative spaces re-rendering V1 domain experiences in 3D). Every feature this set documents ultimately resolves to code in one of a small number of durable surfaces: a Rust realtime workspace under `apps/v3/`, eighteen TypeScript SDK / adapter libraries under `libs/v3/`, a 30-contract registry shared with the rest of the monorepo, and a single UE5.5 project at `V3/ue/`. This page is the **product-side companion** to the architecture glossary. Where the architecture page [../architecture/subsystem-glossary-and-layout.md](../architecture/subsystem-glossary-and-layout.md) reconciles the engine module graph against the compiler — load phases, the Cargo workspace, the Game Feature plugin shape, where each name lives on disk — this page reads the same disk from the player-feature angle: which named subsystem delivers which advertised capability, what V3 promises a user who walks into a class or a concert, and where the glossary's name and the disk's reality diverge. The single source of truth for completion state remains the backlog (`V3_TODOS.md`); this page is the index, not the checklist. It is the foundations companion to the feature catalogue at [../V3_features.md](../V3_features.md). ## What ships, honestly **Real and on-disk.** The cross-language contract spine is substantial: `libs/contracts/src/v3/` holds ten files and a `registry.ts` whose `V3_CONTRACT_REGISTRY` declares **30 contracts** (verified: `grep -c 'contract('` returns 30), each carrying a Zod schema, a fixture, a route segment, a `domain`, a `clientTenant`, and a Prisma model binding. The realtime backend is a real Rust workspace (`apps/v3/Cargo.toml`, `resolver = "2"`, Rust 1.82, with `unsafe_code = "forbid"` set workspace-wide) carrying **five services plus the shared protocol crate** — and the domain logic inside them is genuine: `lilith-world-server` pulls in `rapier3d 0.21` for physics authority, `sqlx 0.8` for Postgres, and `redis 0.27` streams; `saraswati-service` has thirteen performance-flow modules plus `c2pa 0.57` provenance signing; `lilith-commerce-service` has thirteen billing / royalty modules. The TypeScript SDK layer is real too — `avatar-pipeline` exports **41 functions** (independently verified) implementing a VRM 1.0 importer, an Oshun-60 skeleton retarget, viseme lip-sync, and costume-slot safety checks; `lilith-body-policy` re-binds V1's `@oshun/persona-policy-lilith` (crisis detection, voice-abuse signals, unsafe-claim classification, contemplative-tone evaluation) to embodied surfaces. The **Unreal client is a real, structured project**: `V3.uproject` enables **17 C++ modules**, there are **three build targets** (`V3.Target.cs`, `V3Editor.Target.cs`, `V3PixelStreamingWorker.Target.cs`), and **33 automation specs** under `V3/ue/Source/V3Tests/Private/`. **Where the product glossary and the disk diverge** (found by reading both): - **There is no `V3/services/` directory, and `V3/api/` is a single document, not a service.** The V3 feature catalogue and this glossary deliberately reuse V1 — the V3 client routes catalog, identity, and billing through the _existing_ V1 BFF. So the realtime-only new code lives in `apps/v3/` (five Rust services + two web shells), the SDK adapters in `libs/v3/`, and the BFF surface in the Lilith app (`apps/lilith/bff/src/routes/v3-lilith-*.ts`). `V3/api/` holds one file — `v3-bff-openapi.md`, the OpenAPI doc for `POST /api/v3/lilith/launch`, the tier router that returns a native / Pixel-Streaming / Tier-2 / static launch decision. Treat "V3 API" as _a route on the V1 BFF_, not a standalone service tree. - **The 21 Game Feature plugins are content-only.** They live under `V3/ue/Plugins/GameFeatures/` (one level deeper than the architecture monolith's tree implies), and none has a `Source/` directory — each is a `GameFeatureData` container whose "owns" really means _activation scope and data_, not C++ ownership. The gameplay machinery is in the always-loaded `V3*` modules; a plugin toggles on when a client joins the matching room. - **The 17 UE modules are not uniformly deep.** `V3UI` (14 source/header files), `V3Avatar` (11), `V3Editor` (10), `V3Core` (8), and `V3Input` (8) carry real implementation; `V3World`, `V3Audio`, `V3Net`, and `V3Voice` are mid-sized; and **seven modules** (`V3Animation`, `V3Cinematics`, `V3Gameplay`, `V3VFX`, `V3OnlineServices`, `V3Persistence`, `V3Telemetry`) are presently two-file compilable skeletons. Don't read the glossary's "Responsibility" column as a statement of present coverage for those seven. - **GA inventory figures are product targets, encoded as requirements — not shipped content.** "≥ 12 verified instructors, ≥ 6 artists, ≥ 8 venues" are real constants in the code (e.g. `TARA_GA_REQUIRED_VERIFIED_INSTRUCTOR_COUNT = 12` in `libs/v3/tara-studio/src/ga-inventory.ts`), but a constant is a _gate the content must clear_, not a claim that the content exists. Everything below is grounded in those files; where a claim is the glossary's intent rather than shipped code, it is labelled. ## The product promise V3's promise is **embodiment without compromise on V1 trust guarantees**. The contemplative tone, persona safety, crisis-aware behavior, provenance, and consent posture that Lilith enforced as a V1 policy substrate continue to govern every action a user, instructor, or AI persona can take inside the 3D space. The catalogue states the promise in seven commitments; each rests on code: - **Embodied contemplative practice.** A user takes a verified instructor's 60-minute Hatha sequence, gets alignment cues from Aja in real time, and leaves with practice continuity logged in their V1 Arete record. The session data models are the `tara` registry contracts (`LiveClassSession`, `AsanaSequence`, `AjaCueEvent`, `PracticePlan`); the cue delivery is `libs/v3/aja-pose`. - **AI artists as legitimate cultural participants.** A Saraswati persona has a grounded backstory, a provenance-tagged catalog, scheduled concerts, and a fan economy that routes royalties to the human creators who trained it. The `saraswati` contracts (`ArtistPersona`, `Track`, `Concert`, `SignedEdition`, `RemixRights`) and `apps/v3/saraswati-service` carry this; `c2pa` signing makes the provenance real, not asserted. - **V1 trust at body resolution.** Identity, memory, consent, residency, grounding, persona-policy, and provenance all inherit from V1. There is no second-class trust tier in the 3D space — `lilith-body-policy` imports the V1 persona policy _directly_ rather than re-implementing it. - **Live-service from day one** and **cross-platform, low-friction entry.** One UE5 project drives every premium surface; a browser tab reaches full fidelity via Pixel Streaming with no install; a three.js Tier-2 fallback means no one is locked out. The router that decides which path a user gets is `/api/v3/lilith/launch`. - **Safety at the body**, and **degrades safely.** Spatial harassment, voice abuse, costume and crisis-language violations route through the same review pipeline V1 already operates; if multiplayer fails, classes fall back to on-demand video, and if generative-music providers fail, concerts replay archived performances rather than going silent. ## The subsystem glossary, mapped to code The product glossary names twelve **platform substrates** with the `Lilith-` prefix, three **tenants**, and eight **cross-domain supports** carried from V1. Here each conceptual name is resolved to the directory that implements it. These are concept names, not import paths — `Lilith` is also the V1 persona-policy domain, which is the point: the frame that governs a meditation chat in V1 is the frame that governs an embodied room in V3. ### Platform substrates | Glossary name | Delivered by (on disk) | State | | ---------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **Lilith-World** | `apps/v3/lilith-world-server` (`axum`, `rapier3d`, `sqlx`, `redis`) | Real — physics authority + durable persistence | | **Lilith-Gateway** | `apps/v3/lilith-realtime-gateway` (`quinn` QUIC, `webrtc`, WebSocket) | Real — transport + voice SFU | | **Lilith-PxStream** | `apps/v3/lilith-pxstream-relay` + `libs/v3/lilith-web-pxstream` (client glue) | Real — matchmaker / signaller | | **Lilith-UE** | `V3/ue/` — 17 modules, 3 targets, 21 GameFeature plugins | Real, uneven depth (7 skeleton modules) | | **Lilith-WebFB** | `apps/v3/lilith-web-fallback` + `libs/v3/lilith-engine-web-fallback` (three.js) | Real — Tier-2 renderer | | **Lilith-Avatar** | `libs/v3/avatar-pipeline` (`@oshun/avatar-pipeline`, 41 fns, VRM 1.0) | Real — importer, retarget, viseme, costume safety | | **Lilith-Audio** | `libs/v3/spatial-audio` | Real — HRTF / spatial mix SDK | | **Lilith-Identity-Bridge** | `libs/v3/lilith-identity-bridge` | Real — V1 account → embodied identity | | **Lilith-Safety** | `libs/v3/lilith-body-policy` (re-binds `@oshun/persona-policy-lilith`) | Real — crisis / voice-abuse / tone at the body | | **Lilith-Rights** | `apps/v3/lilith-commerce-service` (`lilith_rights_takedown_cascade`) + `concert-quality` | Real — provenance / takedown gate | | **Lilith-Commerce** | `apps/v3/lilith-commerce-service` (13 billing / royalty modules, on V1 Aje) | Real — tickets, tips, royalty waterfall, signed editions | | **Lilith-Studio / Operator** | `apps/oshun/web/.../lilith-studio` + `apps/oshun/admin/.../lilith` + UE Editor widgets | V1 web subroute reuse + `V3Editor` module | ### Tenant experiences The three tenants are the deepest TypeScript libraries on disk by file count, and they are real implementation libraries — not just capability descriptors: - **Tara Studio** (`libs/v3/tara-studio`, `@oshun/tenant-tara-studio`) carries the asana library, an invitational-language linter, lineage grounding (via Sophia), physical-adjustment-consent gating, practice-plan adjustment, an eyes-open default policy, the supervised AI-persona sponsor / region-cap / sequence-script rules, and a five-file TTS-voice consent → contract → recording → scope-lock → royalty pipeline, on top of a `v3TaraStudioDescriptor` capability descriptor with readiness scoring. - **Saraswati Stage** (`libs/v3/saraswati-stage`, `@oshun/tenant-saraswati-stage`) carries the concert-authoring pipeline, discography-release flow, genre-cell registry / binding (the style-boundary system), persona-dossier editor, persona-policy lock, remix-rights catalog, Themis rights adjudication, track C2PA manifests, voice-signature build, and off-platform distribution rules. - **Lilith Commons** (`libs/v3/lilith-commons`, `@oshun/tenant-lilith-commons`) is the thinnest of the three — a tenant descriptor plus launch-locale HUD translations; its rooms run on the always-loaded `V3*` UE modules and the nine `V3Mode_Commons*` Game Feature plugins. Each tenant owns a Prisma schema (`libs/v3/{tara-studio,saraswati-stage,lilith-commons}/prisma/schema.prisma`); the Commons schema also holds the shared `lilith-platform` and cross-cutting contracts, so Commons rides the platform store rather than a tenant-private one. ### Cross-domain support (carried from V1, deepened in V3) | Glossary name | Delivered by (on disk) | Role in V3 | | ------------- | ----------------------------------------------------------------- | ----------------------------------------------- | | **Aja** | `libs/v3/aja-pose` | Pose estimation, alignment cues, asana coaching | | **Iris** | `libs/v3/memory-iris-spatial` | Scene memory, IK pose recall, DSAR coverage | | **Isis** | `libs/v3/isis-music`, `isis-motion`, `isis-world-asset` | Governed generation (music / motion / assets) | | **Sophia** | `libs/v3/sophia-saraswati-grounding` | Grounded backstories, lineage citations | | **Psyche** | `libs/v3/psyche-3d` | Real-time avatar runtime, lip-sync in 3D | | **Themis** | `libs/v3/saraswati-stage/src/themis-rights-adjudication.ts` | Sampled-riff / credential dispute adjudication | | **Yemaya** | V1 render substrate (referenced by stadium fallback + recording) | Non-real-time media (recap reels, signed video) | | **Aje** | V1 crypto-payment substrate (driven by `lilith-commerce-service`) | Tickets, tips, royalties, signed editions | The wire substrate that ties the client to the server is the **`multiplayer-protocol`** library (`@oshun/multiplayer-protocol`): a `buf`- generated protobuf codec at `proto/oshun/v3/multiplayer/v1/multiplayer.proto`, emitted to both TypeScript (`src/generated/`) and Rust (`rust/src/lib.rs`), with the C++ `V3Net` module as the third binding. That one-proto-three-bindings shape is the spine that lets a `SnapshotDeltaPacket` mean the same thing on the Rust server, the C++ client, and the Tier-2 fallback. (Counting `multiplayer-protocol`, `avatar-pipeline`, `spatial-audio`, the two identity/policy bridges, the two Tier-2 engine wrappers, `concert-quality`, the five V1-support bridges, and the three tenants gives the **18** libraries under `libs/v3/`.) ## Product surfaces, mapped to paths The catalogue's Surfaces table maps each product surface to a path. The honest state today: | Surface | Path | State | | ----------------------------- | --------------------------------------------------------- | --------------------------------------------- | | Lilith UE5 client (canonical) | `V3/ue/` | Real — all premium platforms from one project | | Web entry via Pixel Streaming | `apps/v3/lilith-web` (Next/React, `@oshun/v3-lilith-web`) | Real — thin WebRTC player shell | | Tier-2 lightweight fallback | `apps/v3/lilith-web-fallback` (three.js) | Real — WebGPU-first local renderer | | Lilith World Server | `apps/v3/lilith-world-server` | Real — Rust + axum + rapier3d | | Realtime Gateway | `apps/v3/lilith-realtime-gateway` | Real — QUIC / WebRTC + voice SFU | | Pixel Streaming relay fleet | `apps/v3/lilith-pxstream-relay` | Real — Rust matchmaker / signaller | | Lilith Studio (creator tools) | `apps/oshun/web/.../lilith-studio` + UE Editor widgets | V1 web reuse + `V3Editor` | | Lilith Operator Console | `apps/oshun/admin/.../lilith` | V1 admin reuse | | Tier router / V3 "API" | `POST /api/v3/lilith/launch` on the V1 BFF | Real route — _not_ a `V3/services` tree | | Concert ticketing & royalties | `apps/v3/lilith-commerce-service` | Real — Rust + V1 Aje | The deep treatment of each surface lives in the sibling feature pages — the client tiers and the no-install browser path in [./product-surfaces.md](./product-surfaces.md), and the embodied world model, rooms, sharding, presence, and multiplayer protocol in [./world-rooms-presence-multiplayer.md](./world-rooms-presence-multiplayer.md). ## Cross-reference convention Throughout the V3 docs, **bare `§N` and `§N.M` references resolve to `V3_TODOS.md`** — the only V3 document whose numbered section ids are used as hyperlinks. Explicit doc prefixes are used where ambiguity matters: - `deps§N` → `V3_DEPENDENCIES.md` §N (e.g. `deps§14` → generative-music providers). - `arch§""` → `V3_ARCHITECTURE.md` by named section anchor. - `features§""` → the feature catalogue, by named anchor. - `v1features§""` / `v1todos§N` → the V1 documents V3 reuses. The split architecture and feature pages use **named anchors, not numbers**, so they never drift from the backlog's numbering. When a page cites a feature by name, follow the anchor; when it cites a `§`, open the backlog. ## Where to go next - The product surfaces in depth — the tiered client stack, the no-install browser path, and the Tier-2 fidelity envelope: [./product-surfaces.md](./product-surfaces.md). - The embodied platform as a player feature — world model, rooms, sharding, presence, and real-time multiplayer: [./world-rooms-presence-multiplayer.md](./world-rooms-presence-multiplayer.md). - The authoritative subsystem-to-disk map, Cargo workspace, and Game Feature plugin topology — the architecture companion to this page: [../architecture/subsystem-glossary-and-layout.md](../architecture/subsystem-glossary-and-layout.md). - The feature catalogue this page indexes: [../V3_features.md](../V3_features.md).