# V3 — Systems Deep Dive

> The `libs/v3/` area: eighteen Nx libraries that make up **V3**, the embodied /
> 3D-metaverse generation of the Oshun platform — the Lilith Commons social-3D
> shell plus its Tara (yoga) and Saraswati (music) tenants, and the embodiment,
> generation, networking, audio, identity, memory, and safety packages they
> compose.

## What this area is

"V3" is Oshun's embodied tier: a real-time 3D world (the **Lilith Commons**) in
which members appear as avatars, attend live yoga classes in the **Tara Studio**
tenant, and watch AI-persona concerts on the **Saraswati Stage** tenant. The
`libs/v3/` directory is not one package but **eighteen separate Nx libraries**,
each tagged `scope:v3` and slotted into a named architectural `layer` (`avatar`,
`embodiment`, `generation`, `network`, `audio`, `identity`, `memory`,
`grounding`, `safety`, `web`, `tenant`, `domain`). Together they describe how an
avatar is imported and rigged, how it moves and lip-syncs, how it hears spatial
audio and talks to other clients, how its identity links back to a V1 account,
and how its embodied behaviour is kept safe.

The unifying spine across all eighteen is a single convention: every package's
`src/index.ts` exports a `V3PackageDescriptor` — a typed capability manifest of
`{ key, summary, operationalMetric }` entries plus `…CapabilityKeys()`,
`…ReadinessScore()`, and `…RequireCapability()` helpers. The `operationalMetric`
strings encode each capability's acceptance target (e.g.
`lip-sync:60hz-8ms-budget`, `music-stream-sync:<=25ms-p99-256pax-60m`,
`crisis-transcript-classifier:recall>=0.95-fpr<=0.02`). This makes the area
self-describing: a release gate can read a package's descriptor, check which
capability keys are active, and compute a readiness fraction. The descriptor is
the contract; what varies between packages is how much real domain logic sits
behind it.

That depth varies honestly. Most packages back their descriptor with substantial
domain implementations — `@oshun/avatar-pipeline` (a ~2,700-line VRM-1.0
importer/retargeter/blendshape/costume/provenance engine),
`@oshun/spatial-audio` (real HRTF convolution, ambisonic decoding, distance
attenuation, occlusion, Resonance-Audio runtime, and NTP-style music sync),
`@oshun/psyche-3d` (60 Hz voice-to-viseme lip-sync, chat-tone-to-expression,
gesture parsing), `@oshun/lilith-body-policy` (voice-transcript tone, crisis
classification, and impersonation safety), and the three tenant packages. A few
are still manifest-stage — `@oshun/isis-motion` and `@oshun/isis-world-asset`
are presently **descriptor-only**, declaring capability budgets with no
implementation modules behind them yet. Each block below states which it is.

## How it fits the wider system

V3 packages sit above the cross-cutting Oshun libraries and compose them at the
seams: `@oshun/lilith-body-policy` imports `@oshun/persona-policy-lilith` and
`@oshun/avatar-pipeline`; `@oshun/memory-iris-spatial` adapts
`@oshun/memory-iris` and `@oshun/contracts/iris`; `@oshun/v3-concert-quality`
plugs into the V1 `@oshun/content-quality-judge` and
`@oshun/content-release-gates` suites; the tenant packages
(`@oshun/tenant-lilith-commons`, `@oshun/tenant-saraswati-stage`,
`@oshun/tenant-tara-studio`) carry Prisma-generated clients over `V3*` data
models. `implicitDependencies` in each `project.json` record the upstream edges
(an avatar package depends on `@oshun/embodiment-aja`, a generation package on
`@oshun/generation-control-isis`, and so on). The clients of this area are the
V3 world server, the web/Pixel-Streaming fallback runtime, and the tenant
studios; walk the "used by" edges on any node below to see exactly who depends
on it.

## Entity reference

### @oshun/aja-pose

The Tara `embodiment` pose package (`libs/v3/aja-pose/src`). Beyond the
`v3AjaPoseDescriptor` (11 capabilities covering on-device MediaPipe/MoveNet pose
estimation, the canonical-asana classifier, alignment-cue generation, Psyche TTS
voice cues, and the on-device privacy/Iris-aggregate boundary), it ships real
implementation modules re-exported from `index.ts`: `classifier.ts` (an
18-feature asana classifier over ~30 canonical asana ids with a `>=0.92`
per-asana accuracy target), `cue-generator.ts`, `voice-cue.ts`,
`risk-flagger.ts`, `privacy.ts`, and `runtime.ts`. This is a thick, implemented
package, not a manifest.

### @oshun/avatar-pipeline

The `avatar`-layer import-and-rig engine
(`libs/v3/avatar-pipeline/src/index.ts`, ~2,700 lines, plus `retarget/` and
`premium/` submodules). It parses VRM-1.0 glTF documents (`importVrm1Document`,
`parseVrm1Json`), verifies identity-preserving round trips, builds the canonical
60-bone `oshun-60` retarget table and runs reference-animation regression, maps
visemes/emotions/gaze/brow blendshapes and scores reference-phrase lip-sync,
binds 12 costume material slots with realm-scoped Lilith safety checks,
publishes the Tara/Saraswati/Commons costume packs and the Oshun base-avatar
gallery, bridges Ready Player Me avatars, and attaches provenance bundles. One
of the largest and most heavily-composed nodes in the area (consumed by
`@oshun/lilith-body-policy`, among others).

### @oshun/v3-concert-quality

The `domain`-layer concert quality + diversity gates
(`libs/v3/concert-quality/src`). Its `index.ts` re-exports
`concert-scene-quality-gate.ts`, `v3-concert-export.ts`, and
`concert-track-signer.ts`. As the source header documents, the Saraswati concert
authoring pipeline already enforces _readiness_ and the export flow enforces
_provenance + consent_; these gates add the missing _quality_ signal — each
scene/speech draft is scored by the real V1 `@oshun/content-quality-judge` panel
(`assessArtifactQuality`, `computeSlop`, `corpusDiversity`) and surfaced as
`GateDefinition`s in the same `@oshun/content-release-gates` export suite,
failing loud when a concert has no scene drafts rather than waving an empty
corpus through. Implemented, and cross-composed with the V1 content stack.

### @oshun/isis-motion

A `generation`-layer package that is currently **descriptor-only**
(`libs/v3/isis-motion/src/index.ts` is the entire source). It exports
`v3IsisMotionDescriptor` with three capabilities (`motion-brief`,
`retarget-pass`, `cue-export`, all declared as `*ms-budget` targets) plus the
standard readiness helpers, but ships no implementation modules behind them —
unlike its sibling `@oshun/isis-music`. Honestly a reserved manifest slot for
Isis-driven motion generation, not yet an implemented engine.

### @oshun/isis-music

A `generation`-layer package whose descriptor (`v3IsisMusicDescriptor`) mixes a
few placeholder budget capabilities (`music-brief`, `rights-check:16ms-budget`,
`stem-export:24ms-budget`) with real, implemented ones. `index.ts` re-exports
seven substantive Saraswati modules: `fingerprint-pre-release-check.ts` (Audible
Magic / Pex pre-release matching over a 50-track reference catalog),
`grounded-lyric-generation.ts` (Sophia-grounded lyric drafting with a factuality
validation set), `lyric-tone-policy.ts` (Lilith persona-policy tone review),
`mix-master-review-gate.ts`, `track-provenance-bundle.ts`, `provider-routing.ts`
(multi-provider cost/quality/failover routing), and `v1-isis-registration.ts`
(workflow registration + submit-job route). Substantially implemented; only a
handful of descriptor entries are forward-looking budgets.

### @oshun/isis-world-asset

A `generation`-layer package that, like `@oshun/isis-motion`, is currently
**descriptor-only** (`libs/v3/isis-world-asset/src/index.ts` is the whole
source). It declares `v3IsisWorldAssetDescriptor` with three budget capabilities
(`asset-brief`, `lod-budget`, `provenance`) and the readiness helpers, but has
no implementation modules. A reserved manifest slot for Isis world-asset
generation, shown as such rather than overclaimed.

### @oshun/lilith-body-policy

The `safety`-layer embodied-behaviour policy engine
(`libs/v3/lilith-body-policy/src/index.ts`, ~1,980 lines). Built with a `tsup`
ESM build (it externalises its `@oshun/avatar-pipeline` and
`@oshun/persona-policy-lilith` dependencies), it implements rolling 5-second
voice-transcript tone scoring against the V1 Lilith tone policy
(`evaluateV3VoiceTranscriptTonePolicy`), a crisis-language classifier with a
`recall>=0.95 / fpr<=0.02` release gate and an embodied crisis-routing handoff
(in-world soft prompt → V1 crisis pipeline → operator pager), realm-scoped
costume rule checks, protected-persona avatar-swap impersonation blocking, and a
Saraswati AI-persona enforcement suite with an adversarial prompt battery. A
thick, real safety package that composes the V1 Lilith persona-policy
primitives.

### @oshun/tenant-lilith-commons

The shared `tenant` package for the Lilith Commons
(`libs/v3/lilith-commons/src`; Nx project `@oshun/tenant-lilith-commons`). It
carries a Prisma-generated client under `src/generated/client` over the Commons'
`V3*` data models (`V3Room`, `V3Venue`, `V3Presence`, `V3LilithSession`,
`V3DebateSession`, `V3SpatialTranscript`, `V3EmbodiedConsent`,
`V3ProvenanceBundle3D`, `V3JournalEntry3D`, and more) plus the
`launch-locale-hud-translations.ts` localization module. It depends on
`@oshun/design-tokens` and `@oshun/navigation`. The shared substrate the two
flagship studio tenants build on.

### @oshun/lilith-engine-web-fallback

The `web`-layer non-native runtime (`libs/v3/lilith-engine-web-fallback/src`) —
the WebGPU/WebGL2 fallback for clients that cannot run the native engine. Its
descriptor enumerates 18 capabilities and `index.ts` re-exports eleven real
modules: `physics.ts` (Rapier prop-pickup prediction), `steadyFps.ts` (Tier-2
sustained-FPS profiles), `gateway.ts` (browser/network transport plan
selection), `renderer.ts` (a Three.js fallback renderer host + reference scene),
`parity.ts` (tenant parity envelopes), `ajaCueValidation.ts`, the Tara recording
suite (`taraInstructorHud`, `taraRecordingTimeline`, `taraRecordingPractice`,
`taraRecordingEngagement`). The descriptor's accessibility capabilities
(reduced-motion, color-vision palettes, photosensitive-safe, spatial-audio-off,
launch-localization) tie into the matching `@oshun/spatial-audio` and
pixel-stream controls. Thick and implemented.

### @oshun/lilith-identity-bridge

The `identity`-layer bridge between V3 avatars and V1 accounts
(`libs/v3/lilith-identity-bridge/src/index.ts`, plus `per-region-rules` and
`recording-consent` modules, depends on `@oshun/auth-primitives`). It implements
external-OAuth account linking for Quest / Vision Pro / PSVR2
(`bindV3AvatarToV1Account` with per-platform issuer verification), realm
display-name override with V1 audit-log rows, a comprehensive V3-session DSAR
exporter covering eight data categories (avatar history, transcripts,
attendance, signed-edition holdings, recordings, Pixel-Streaming sessions,
consent decisions, ticket/refund/credit ledger) that flows into the V1
`admin-dsar-review` pipeline, and a reputation-band model
(`deriveV3ReputationSummary`) with operator-escalation ranking. A thick, real
package with genuine domain scoring formulas.

### @oshun/lilith-web-pxstream

The `web`-layer Pixel-Streaming client package
(`libs/v3/lilith-web-pxstream/src`). Its `v3LilithWebPxstreamDescriptor`
declares 12 capabilities (session match, WebRTC offer, input channel, plus the
same accessibility family as the web fallback — live captions, reduced-motion,
color-vision palettes, one-handed mobile, photosensitive-safe,
spatial-audio-off, cognitive-load reduction, keyboard/single-switch nav, launch
localization). `index.ts` re-exports a real `player.ts` module (with a companion
`player.spec.ts`). Implemented, focused on the streamed-client control/overlay
surface.

### @oshun/memory-iris-spatial

The `memory`-layer adapter that scopes Iris memory to 3D space
(`libs/v3/memory-iris-spatial/src/index.ts`, depends on `@oshun/memory-iris`).
It narrows Iris memory scopes to the spatial subset (`scene` and `pose`),
validates scope bindings against `MemoryScopeKeySchema` from
`@oshun/contracts/iris`, and provides round-trip encode/decode plus
`buildV3IrisSpatialWritePlan`, which wraps `buildIrisMemoryWritePlan` to mark
pose memories as `biometric`-sensitive and attach the spatial scope contract as
metadata. A thin but genuinely-implemented boundary adapter over the V1 Iris
memory engine, not a stub.

### @oshun/multiplayer-protocol

The `network`-layer wire protocol (`libs/v3/multiplayer-protocol/src/index.ts`,
with a `proto:gen` target generating `src/generated` from `proto/` via Buf).
Real implementation: it re-exports the generated protobuf codecs and implements
snapshot-delta encode/decode and application (`applySnapshotDelta`),
dead-reckoning prediction (`predictSnapshot`/`predictTransform`),
protocol-version negotiation (`negotiateProtocolVersion`, pinned to `v3.0.0`),
capacity tiers (class 32 kbps / stadium 256 kbps), and a decoder benchmark
harness over synthetic 256-participant traffic. The descriptor's three
`*ms-budget` capability labels are manifest-level, but the codec/netcode behind
them is genuinely implemented.

### @oshun/psyche-3d

The Psyche `embodiment` package (`libs/v3/psyche-3d/src/index.ts`, depends on
`@oshun/embodiment-psyche`). It implements real-time 60 Hz voice-to-viseme
lip-sync across web/mobile/VR surfaces (`classifyPsyche3dVoiceFrame`,
`buildPsyche3dLipsyncTracks` with a phoneme→viseme table, envelope fallback, and
per-surface look-ahead/release smoothing), a lexicon-based chat-tone classifier
mapped to emotion blendshapes (`classifyPsyche3dChatTone` →
`resolvePsyche3dExpressionStateFromChatTone`) with a 10-case coherence
validation set targeting `>=0.95` accuracy, and a gesture-command parser over
named mudra/ applause/snap presets with a cross-client consistency check
targeting `1.0`. A thick, real signal-processing package.

### @oshun/tenant-saraswati-stage

The Saraswati concert-stage `tenant` (`libs/v3/saraswati-stage/src`; Nx project
`@oshun/tenant-saraswati-stage`, depends on `@oshun/design-tokens` and
`@oshun/generation-control-isis`). Behind `v3SaraswatiStageDescriptor` it ships
a Prisma client over `V3*` models (`V3ArtistPersona`, `V3Concert`, `V3Setlist`,
`V3Track`, `V3SignedEdition`, `V3RemixRights`, `V3FanInteraction`, `V3Catalog`)
and many real modules: `persona-dossier-editor.ts`, `persona-policy-lock.ts`,
`voice-signature-build.ts`, `concert-authoring-pipeline.ts`,
`discography-release-flow.ts`, `genre-cell-registry.ts`/`genre-cell-binding.ts`,
`cross-persona-collaboration.ts`, `remix-rights-catalog.ts`,
`themis-rights-adjudication.ts`, `track-c2pa-manifests.ts`,
`off-platform-distribution.ts`, and `ga-inventory.ts`. Thick, implemented
tenant.

### @oshun/sophia-saraswati-grounding

The `grounding`-layer adapter (`libs/v3/sophia-saraswati-grounding/src`, depends
on `@oshun/evidence-sophia`). Its descriptor's first three capabilities are
`*ms-budget` labels, but `index.ts` re-exports a real `backstory-grounding.ts`
module: a Sophia adapter for Saraswati artist-backstory grounding
(`runSaraswatiBackstoryGroundingAdapter`,
`adaptSaraswatiBackstoryClaimsWithSophia`), a required-GA-persona-count review
(`reviewSaraswatiBackstoryGrounding`), a source registry and dossier builder,
and an audience-facing citation-surface audit for web/mobile/VR hover surfaces.
Implemented grounding adapter, not a stub.

### @oshun/spatial-audio

The `audio`-layer DSP package (`libs/v3/spatial-audio/src/index.ts`, ~1,680
lines). Genuinely implemented audio engineering: an Opus 24 kbps mono
web-receiver plan with a real SNR bench (`measureVoiceSignalToNoiseDb`),
listener-position HRTF panner derivation, FIR HRTF convolution with a validation
impulse response, first-order ambisonic-to-stereo decoding, a device-aware
HRTF-vs-ambisonic renderer selector, inverse-distance attenuation and AABB
scene-occlusion raycasts, a per-user mix-bus runtime with HUD control latency,
an accessibility audio-description bed, a flat-stereo spatial-audio-off mode
with QA gating, a Resonance-Audio Tier-2 fallback runtime, and an NTP-style
music-stream clock-sync simulator targeting `<=25ms` p99 drift across 256
attendees over a 60-minute concert. One of the most algorithm-dense nodes in the
area.

### @oshun/tenant-tara-studio

The Tara yoga-studio `tenant` (`libs/v3/tara-studio/src`; Nx project
`@oshun/tenant-tara-studio`, depends on `@oshun/design-tokens` and
`@oshun/embodiment-aja`). Behind `v3TaraStudioDescriptor` it ships a Prisma
client over `V3*` models (`V3Asana`, `V3AsanaSequence`, `V3InstructorProfile`,
`V3InstructorCredential`, `V3PracticePlan`, `V3LiveClassSession`,
`V3OnDemandClassRecording`, `V3AjaCueEvent`) and many real modules: the
canonical `asana-library.ts`, `practice-plan.ts`/`practice-plan-adjustment.ts`,
`lineage-grounding.ts` (Sophia-grounded lineage editor that blocks unsourced
claims), `invitational-language-linter.ts`, `eyes-open-policy.ts`,
`physical-adjustment-consent.ts`, `class-style-mode.ts`, and the AI-persona
governance suite (`ai-persona-sponsor`, `-sequence-script`, `-nameplate`,
`-region-cap`) plus the TTS-voice consent/contract/recording/scope-lock/royalty
modules. Thick, implemented tenant.