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
GateDefinitions 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.