# OSHUN Studio Domain Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0013-oshun-studio-information-architecture.md`

Scope note: this document remains a Studio-layer dependency and contract map.
For current cross-product OSHUN V1 shell and subsystem ownership boundaries, use
`docs/releases/v1/specs/program-charter.md` and
`docs/releases/v1/specs/web-app-admin-v1-prd.md`. Do not treat
`docs/reference/data-ownership-matrix.md` as the normative V1 ownership matrix.

## Purpose

This document defines canonical dependencies and data contracts for Studio
workflows spanning:

- Yemaya
- Isis
- Hathor
- Aja
- Bellona
- Project Obsidian program layer

It is the execution artifact for `OST-00002`:

- Map domain dependencies and data contracts.

## Sources Used

- `docs/domains/yemaya/README.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/yemaya/api/README.md`
- `docs/domains/isis/README.md`
- `docs/domains/isis/features.md`
- `docs/domains/isis/api/README.md`
- `docs/domains/hathor/README.md`
- `docs/domains/hathor/features.md`
- `docs/domains/hathor/api/README.md`
- `docs/domains/aja/README.md`
- `docs/domains/aja/features.md`
- `docs/domains/aja/api/README.md`
- `docs/domains/bellona/README.md`
- `docs/domains/bellona/features.md`
- `docs/domains/bellona/api/README.md`
- `docs/reference/cross-domain-integration.md`
- `docs/reference/data-ownership-matrix.md` (legacy pre-V1 cross-domain
  snapshot)
- `docs/releases/v1/specs/program-charter.md`
- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `RESPONSIBILITY_SPLIT_RECOMMENDATION.md`
- `TODOS.md` (Project Obsidian phase)

## 1. Dependency Overview

### 1.1 Primary Control Plane

`Yemaya` is the primary studio orchestration surface. It coordinates:

- generation requests to `Isis`
- world and narrative inputs from `Hathor`
- motion processing requests to `Aja`
- build/export/runtime operations in `Bellona`

### 1.2 Dependency Graph (Normative)

- `Yemaya -> Isis`: generation jobs, workflows, outputs, model registry.
- `Yemaya -> Hathor`: worlds, timelines, factions, narrative and simulation
  artifacts.
- `Yemaya -> Aja`: motion pipeline jobs, retargeting outputs, quality reports.
- `Yemaya -> Bellona`: engine sync, build jobs, exports, runtime integration.
- `Hathor -> Isis`: optional asset generation constrained by lore/world rules.
- `Isis -> Bellona`: generated assets ingested into build/runtime pipelines.
- `Aja -> Bellona`: motion/animation outputs packaged for target engines.
- `Project Obsidian -> all`: program-level orchestration, governance, and
  release readiness.

## 2. Ownership and Contracts Matrix

| Domain           | Owns (Authoritative)                                                    | Consumes                                          | Produces For                      | Primary Contract Families                                                             |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------- |
| Yemaya           | projects, assets, collaboration, production operations                  | Isis/Hathor/Aja/Bellona outputs                   | Studio users + downstream domains | `ProjectContext`, `AssetDescriptor`, `ProductionPlan`, `ApprovalRecord`               |
| Isis             | generation jobs, workflows, outputs, provenance, retention              | prompts/constraints from Yemaya/Hathor            | Yemaya, Bellona                   | `GenerationRequest`, `GenerationJob`, `OutputManifest`, `LineageEdge`                 |
| Hathor           | world state, narrative graphs, simulation results, lore validation      | research/citations and optional generation assets | Yemaya, Bellona, Isis             | `WorldModel`, `NarrativeGraph`, `SimulationSnapshot`, `ValidationReport`              |
| Aja              | motion jobs, retargeted animations, motion QA and delivery              | source videos/mocap/skeleton maps                 | Yemaya, Bellona                   | `MotionJobRequest`, `MotionJobStatus`, `MotionOutputPackage`, `MotionQualityReport`   |
| Bellona          | build/export jobs, bridge sessions, runtime packaging                   | assets from Yemaya/Isis/Aja/Hathor                | Yemaya and engine targets         | `BuildRequest`, `BuildStatus`, `ExportRequest`, `EngineSyncState`, `ArtifactManifest` |
| Project Obsidian | franchise program plans, milestones, release gates, compliance evidence | all domain artifacts and statuses                 | program stakeholders              | `ProgramContext`, `ProgramMilestone`, `ReleaseGate`, `EvidenceBundle`                 |

## 3. Canonical Cross-Domain Contracts

These contracts are required in Studio API/BFF and adapter boundaries.

### 3.1 ProjectContext

```ts
export interface ProjectContext {
  programId: string;
  projectId: string;
  workspaceId: string;
  tenantId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona';
  actorId: string;
  traceId: string;
  requestId: string;
}
```

### 3.2 AssetDescriptor

```ts
export interface AssetDescriptor {
  assetId: string;
  projectId: string;
  assetType:
    | 'image'
    | 'video'
    | 'audio'
    | 'model_3d'
    | 'animation'
    | 'material'
    | 'scene'
    | 'script'
    | 'document';
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona';
  version: string;
  uri: string;
  metadata: Record<string, string | number | boolean>;
}
```

### 3.3 GenerationRequest and OutputManifest

```ts
export interface GenerationRequest {
  context: ProjectContext;
  generationType:
    | 'text-to-image'
    | 'image-to-image'
    | 'text-to-video'
    | 'image-to-video'
    | 'text-to-3d'
    | 'image-to-3d'
    | 'text-to-audio'
    | 'voice-synthesis'
    | 'music-generation';
  workflowId?: string;
  prompt?: string;
  negativePrompt?: string;
  inputAssets?: AssetDescriptor[];
  policyTags?: string[];
  callbackUrl?: string;
}

export interface OutputManifest {
  outputId: string;
  jobId: string;
  context: ProjectContext;
  qualityTier: 'draft' | 'standard' | 'high' | 'production' | 'master';
  files: Array<{
    uri: string;
    format: string;
    sizeBytes: number;
    checksum: string;
  }>;
  lineage: {
    parentOutputIds: string[];
    provider: string;
    model: string;
    modelVersion: string;
  };
}
```

### 3.4 World and Narrative Contracts

```ts
export interface WorldModel {
  worldId: string;
  projectId: string;
  genre: string[];
  timelineVersionId: string;
  factions: string[];
  locations: string[];
  validationState: 'pass' | 'warn' | 'fail';
}

export interface NarrativeGraph {
  graphId: string;
  worldId: string;
  nodes: number;
  arcs: number;
  branchCount: number;
  exportTargets: Array<'ink' | 'yarn' | 'json'>;
}
```

### 3.5 Motion Contracts

```ts
export interface MotionJobRequest {
  context: ProjectContext;
  configId?: string;
  domain: 'yoga' | 'fitness' | 'dance' | 'martial-arts' | 'general';
  qualityPreset: 'draft' | 'standard' | 'high' | 'ultra';
  inputVideoUrl?: string;
  sourceFormat?: string;
  targetFormat: 'bvh' | 'fbx' | 'glb' | 'usd';
}

export interface MotionOutputPackage {
  jobId: string;
  context: ProjectContext;
  outputs: Array<{
    format: 'bvh' | 'fbx' | 'glb' | 'usd';
    uri: string;
    checksum: string;
  }>;
  qualityReportId: string;
}
```

### 3.6 Build and Export Contracts

```ts
export interface BuildRequest {
  context: ProjectContext;
  engine: 'unity' | 'unreal' | 'godot' | 'blender' | 'houdini';
  platforms: Array<
    | 'windows'
    | 'macos'
    | 'linux'
    | 'ios'
    | 'android'
    | 'webgl'
    | 'playstation'
    | 'xbox'
    | 'switch'
  >;
  assets: AssetDescriptor[];
  optimization: 'none' | 'size' | 'speed' | 'balanced';
}

export interface ArtifactManifest {
  buildId: string;
  context: ProjectContext;
  artifacts: Array<{
    artifactType:
      | 'texture'
      | 'mesh'
      | 'shader'
      | 'audio'
      | 'animation'
      | 'scene'
      | 'project'
      | 'package';
    uri: string;
    checksum: string;
    sizeBytes: number;
  }>;
}
```

### 3.7 Program (Project Obsidian) Contracts

```ts
export interface ProgramContext {
  programId: string;
  codename: 'project-obsidian' | string;
  milestoneId: string;
  releaseTrainId: string;
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
}

export interface ReleaseGate {
  gateId: string;
  programId: string;
  name: string;
  state: 'pending' | 'in_review' | 'blocked' | 'approved';
  requiredEvidence: string[];
  approverRoles: string[];
}
```

## 4. Event Contracts and Routing

Studio integration must prefer domain event contracts for async coordination.

### 4.1 Required Event Families

- Yemaya:
  - `yemaya.project.created`
  - `yemaya.build.requested`
  - `yemaya.export.requested`
- Isis:
  - `isis.job.submitted`
  - `isis.job.completed`
  - `isis.job.failed`
  - `isis.asset.generated`
- Hathor:
  - `hathor.world.published`
  - `hathor.simulation.completed`
- Bellona:
  - `bellona.build.completed`
  - `bellona.export.ready`
- Aja:
  - `aja.motion.job.completed`
  - `aja.motion.job.failed`

### 4.2 Event Envelope (Normative)

```ts
export interface StudioEventEnvelope<TPayload> {
  eventId: string;
  eventType: string;
  sourceDomain: string;
  occurredAt: string;
  context: ProjectContext;
  payload: TPayload;
}
```

## 5. Failure and Consistency Model

- Cross-domain workflows must be eventually consistent and traceable.
- Every cross-domain step must emit status and compensating action metadata.
- UI must show partial-failure states without losing project context.
- All long-running actions require resumable status polling and/or streaming.

## 6. Governance Rules

1. No direct cross-domain database access.
2. Domain-owned writes only through owning domain APIs.
3. Cross-domain writes must use explicit contracts and typed adapters.
4. Breaking contract changes require versioning and migration notes.
5. Every contract change requires parity updates in web UI and tests.

## 7. Acceptance Criteria (OST-00002)

`OST-00002` is complete only when all criteria below are true:

1. A domain dependency graph exists for Yemaya, Isis, Hathor, Aja, Bellona, and
   Project Obsidian.
2. Ownership matrix defines each domain's authoritative entities and
   cross-domain consumers.
3. Canonical data contract families are defined for project, asset, generation,
   world/narrative, motion, build/export, and program gating.
4. Required event families and envelope schema are documented.
5. Consistency and failure semantics are explicitly defined.
6. Governance rules prohibit direct cross-domain DB writes and enforce contract
   versioning.
7. Document references current domain docs and repository architecture sources.

## 8. Next Implementation Hooks

- Implement shared contract package (e.g. `libs/oshun/studio-contracts`).
- Generate typed clients for contract-aligned endpoints in `apps/oshun/bff`.
- Add CI checks that validate Studio route-to-contract parity.
- Add telemetry schema checks for required context fields.
