# Cross-Domain Support

Beneath the six customer-facing verticals
([Customer-Facing Domains](./customer-domains.md)) and the six platform
substrates sit a set of **cross-domain subsystems** — Aja, Yemaya, Themis,
Bellona, Hathor, and Neith. These are not first-class V1 customer domains: a
member never navigates to "Bellona" the way they open Tara or Metis. They are
launch-blocking _enablers_ — embodied-instruction services, rendering
substrates, integrity adjudicators, engine bridges, narrative authoring trees,
and inverse-modeling pipelines — that the shipping customer features and Oshun
Studio depend on. This page sits below the
[High-Level Architecture](./high-level-architecture.md) and beside
[Customer-Facing Domains](./customer-domains.md); it deliberately separates the
thin adapter seam each subsystem exposes from the large domain tree that lives
behind it.

## Why a separate tier exists

The V1 architecture draws a hard line between **customer domains** (own a
surface tree, a BFF route prefix, a registry entry, and a persistence boundary)
and **cross-domain subsystems** (own none of those at the customer edge; they
are consumed _through_ a customer domain or _inside_ Oshun Studio). The reason
is governance and blast radius. A customer domain is something a member sees and
trusts; a cross-domain subsystem is an implementation detail that several
domains share. By keeping them off the customer surface map, V1 can let these
subsystems be large, polyglot, and fast-moving — Bellona alone spans Unreal,
Unity, Godot, Blender, DaVinci, and OpenUSD — without each engine bridge needing
its own customer-facing contract, route, and trust posture. The cost of that
freedom is that the customer features which _do_ depend on them inherit those
dependencies as **launch-blocking**: Metis embodied pedagogy cannot ship if the
Aja adapter is broken, even though "Aja" never appears in the product.

A second, subtler reason: each row in the table below is presented as a single
adapter file, but every one of these subsystems is in reality a **multi-package
collection** — a domain tree of dozens of npm-scoped libraries, not one library.
The adapter is just the narrow, contract-stable seam a V1 consumer imports. The
sections after the table make that explicit, because "`libs/themis/*`" hides the
fact that Themis is ~71 sub-packages under the `@themis/*` scope.

## The cross-domain support matrix

| Subsystem   | Adapter / entry seam                                                                   | V1 role                                                                                                                                                                                           |
| ----------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Aja**     | `libs/oshun/embodiment-aja/src/adapter.ts` (+ `canonical-adapter.ts`)                  | Embodied-instruction services that Metis hooks for movement- and practice-based pedagogy — demonstrations, coaching overlays, and session handoffs across six physical domains.                   |
| **Yemaya**  | `libs/yemaya/sdk` (consumed via the SDK and a BFF route)                               | Rendering and media-generation substrate for media surfaces consumed by Metis and other V1 domains — itself a 60+ top-level-module domain (case pipeline, ComfyUI, A/V sync, assets).             |
| **Themis**  | `libs/themis/*` (~71 packages under `@themis/*`, no top-level package)                 | Academic-integrity adjudication referenced by Metis assessments and tutoring; spans academic-integrity, arbitration, accountability, analytics, civic, community, constitutions, …                |
| **Bellona** | `libs/bellona/*` (~40 sub-libs) via `apps/oshun/web/src/app/studio/bellona/`           | Engine-bridge and build substrate for Studio creation: live bridges to Unreal, Unity, Godot, Blender, 3ds Max, DaVinci; OpenUSD asset interchange; build/export and cross-DCC consistency.        |
| **Hathor**  | `libs/hathor/*` (~18 sub-libs) via `apps/oshun/web/src/app/studio/hathor/`             | Narrative, world, and lore-authoring substrate for Studio storytelling: characters, narrative and narrative-generation, lore-compiler, pre-production, simulation, lore validation.               |
| **Neith**   | `apps/oshun/web/src/app/studio/neith/inverse-modeling/` (`libs/neith/*`, ~71 sub-libs) | Inverse-modeling substrate: image-to-parameter estimation (feature extraction, parameter estimation, confidence scoring) feeding Studio asset and motion pipelines; also audio runtimes/animator. |

These subsystems are **not first-class V1 customer domains** but are
launch-blocking for the customer features that depend on them. Bellona, Hathor,
and Neith are **Studio-only V1 substrates** (confirmed in-v1 2026-05-29, per
[`V1/features.md` § Subsystem Glossary](../features.md)): they expose no
customer-facing surface and render exclusively through Oshun Studio routes.
There is no `apps/oshun/web/src/app/{bellona,hathor,neith}` top-level customer
route, only `apps/oshun/web/src/app/studio/{bellona,hathor,neith}/` sub-route
trees; nor is there a `studio/themis` or top-level Themis customer route. The
walked surface inventory lives at
`WALKTHROUGH/studio/domain-bridges/{bellona,hathor,neith}/`; the verification
backlog is §34.

## Aja — embodied instruction for Metis

Aja is the one cross-domain subsystem that feeds a _customer_ domain directly
rather than only Studio. Metis (structured learning) hooks Aja for movement- and
practice-based pedagogy: showing a demonstration, layering a coaching overlay
onto a learner's attempt, and handing a session off cleanly.

The V1 seam is the **canonical Aja adapter** in `libs/oshun/embodiment-aja/`.
The package `@oshun/embodiment-aja` re-exports two entry points — `./adapter`
and `./canonical-adapter` — and the adapter imports its types from
`@oshun/contracts/aja` (the contract tree at `libs/contracts/src/aja/`:
`embodied-instruction.ts`, `formats.ts`, `jobs.ts`, `primitives.ts`). The
adapter declares the exact six physical domains it supports and the exact four
consumers allowed to call it:

```ts
// libs/oshun/embodiment-aja/src/adapter.ts
const SUPPORTED_DOMAINS: EmbodiedInstructionDomain[] = [
  'fitness',
  'yoga',
  'dance',
  'martial-arts',
  'sports',
  'rehabilitation',
];
export type AjaEmbodiedInstructionConsumer =
  | 'metis'
  | 'assistant'
  | 'studio'
  | 'admin';
```

Each request/response pair is a typed contract —
`EmbodiedInstructionDemonstrationRequest` / `Response`,
`EmbodiedInstructionCoachingOverlayRequest` / `Response`,
`EmbodiedInstructionSessionHandoffRequest` / `Response`, plus an
`EmbodiedInstructionCapabilities` probe — and the adapter wraps payloads in
`@oshun/types`' versioned envelope (`versionOshunContractPayload`,
`buildOshunContractVersionDescriptor`) so a Metis consumer and an Aja service
can verify they agree on the contract version. The adapter also models health:
`AjaEmbodiedInstructionAdapterHealthStatus` rolls per-service statuses
(capabilities / demonstration / overlay / handoff / contracts) into a single
`healthy | degraded | unhealthy` view. This is a **fail-loud, contract-typed
boundary**: the adapter defines the shape and the health envelope; the actual
embodied-instruction _service_ on the other side is a dependency the deployment
wires in.

## Yemaya — rendering and media substrate

Yemaya is the rendering substrate for media surfaces consumed by Metis and other
V1 domains. The single-line "used through `libs/yemaya/sdk` and a BFF route"
description is accurate but understates the current scope: `libs/yemaya` is now
a **60+ top-level-module domain**, not one rendering library. Alongside `sdk` it
carries an entire detective-case pipeline (`case-compiler`, `case-contracts`,
`case-director`, `case-engine`, `case-eval`, `case-localization`, and more
`case-*` modules), a `comfyui-integration`, `asset-generation` and
`asset-library`, `av-sync`, `blend-kernel`, `autonomous-pipelines`,
`budget-management`, `canon-enforcement` / `canon-graph`, and others. V1
consumers reach all of this through the stable `libs/yemaya/sdk` package and a
BFF route; the breadth behind the SDK is why the "rendering substrate" framing
is best read as the _V1-facing slice_ of a much larger domain.

## Themis — academic-integrity adjudication

Themis is the integrity-adjudication subsystem that Metis assessments and
tutoring reference — for example, the `@themis/academic-integrity` package. It
is the clearest illustration of the "tree, not a library" point: Themis has **no
top-level `package.json`**; it is ~71 sub-packages under the `@themis/*` npm
scope (`academic-integrity`, `accountability`, `analytics`, `arbitration`,
`civic`, `community`, `constitutions`, …). V1 consumes only the integrity slice
relevant to Metis; the rest of the tree is out of V1 scope. Themis exposes no
Studio route and no customer route — it is referenced as adjudication logic from
inside Metis flows.

## Bellona, Hathor, Neith — the Studio-only substrates

These three are **Studio-only**: they render exclusively through Oshun Studio
routes and never touch a customer surface. Each is, again, a domain tree:

- **Bellona** (~40 sub-libs) is the engine-bridge and build substrate. It holds
  live bridges to multiple DCC engines (`blender`, `blender-agent`, `godot`,
  plus Unreal / Unity / `3dsmax`), OpenUSD asset interchange, an
  `artifact-store`, `asset-export`, `creative-flows`, `bridge-core`, and
  `cross-dcc-consistency`. Studio reaches it via
  `apps/oshun/web/src/app/studio/bellona/`. (Bellona is also the on-box UE
  authoring substrate referenced elsewhere in the repo; see the engine notes in
  the project memory rather than re-deriving them here.)
- **Hathor** (~18 sub-libs) is the narrative/world/lore-authoring substrate:
  `characters`, `narrative` and `narrative-generation`, `lore-compiler`,
  `llm-npc`, `pre-production`, `domain-models`, and event publish/handle
  infrastructure. Studio reaches it via `apps/oshun/web/src/app/studio/hathor/`.
- **Neith** (~71 sub-libs) is presented in V1 as the **inverse-modeling**
  substrate — image-to-parameter estimation (feature extraction, parameter
  estimation, confidence scoring) feeding Studio asset and motion pipelines —
  surfaced at `apps/oshun/web/src/app/studio/neith/inverse-modeling/`. The
  broader Neith tree also carries audio runtimes and animation tooling
  (`audio-runtime`, `animator`, `ai-runtime`, foley/host modules); V1 uses the
  inverse-modeling slice.

A practical caveat the V1 docs keep candid about: these subsystems are large
enough that this architecture page **does not assert** whether _every_ sub-lib
is uniformly production-grade or partially scaffolded. The V1 claim is narrower
and verifiable — the _adapter seam_ each exposes is real, the _Studio route_
each renders through is real, and there is _no_ customer surface. Deeper
per-sub-lib readiness is tracked in §34 and the Studio walkthrough inventory,
not promised here.

## Data-flow: how a customer feature reaches a cross-domain subsystem

The pattern is uniform and worth stating once:

1. A **customer domain** (e.g. Metis) needs an embodied demonstration, a
   rendered media asset, or an integrity ruling.
2. It calls the **adapter seam** — for Aja, `@oshun/embodiment-aja`'s
   contract-typed adapter; for Yemaya, the `libs/yemaya/sdk` package plus a BFF
   route — never the subsystem's internals directly.
3. The adapter wraps the payload in a **versioned contract envelope** so both
   sides agree on the schema, and (for Aja) reports a rolled-up **health
   status** so a degraded subsystem fails loud rather than silently.
4. For Studio-only substrates (Bellona/Hathor/Neith), the call originates from a
   **Studio route** under `apps/oshun/web/src/app/studio/<subsystem>/`, never
   from a customer route.

This keeps the customer-facing trust boundary thin and stable while the heavy,
polyglot subsystem behind it is free to evolve.

## Related

- [Customer-Facing Domains](./customer-domains.md)
- [High-Level Architecture](./high-level-architecture.md)
- [Subsystem Glossary](./glossary.md)
- [Oshun Studio — Authoring, Editorial, Curation](./oshun-studio.md)
- [Persona, Avatar, and Voice Packs](./persona-avatar-voice-packs.md)
- [`V1/features.md` § Subsystem Glossary](../features.md)
- [Hub: V1 Architecture](../ARCHITECTURE.md)