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.mddocs/domains/yemaya/features.mddocs/domains/yemaya/api/README.mddocs/domains/isis/README.mddocs/domains/isis/features.mddocs/domains/isis/api/README.mddocs/domains/hathor/README.mddocs/domains/hathor/features.mddocs/domains/hathor/api/README.mddocs/domains/aja/README.mddocs/domains/aja/features.mddocs/domains/aja/api/README.mddocs/domains/bellona/README.mddocs/domains/bellona/features.mddocs/domains/bellona/api/README.mddocs/reference/cross-domain-integration.mddocs/reference/data-ownership-matrix.md(legacy pre-V1 cross-domain snapshot)docs/releases/v1/specs/program-charter.mddocs/releases/v1/specs/web-app-admin-v1-prd.mdRESPONSIBILITY_SPLIT_RECOMMENDATION.mdTODOS.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#
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#
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#
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#
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#
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#
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#
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.createdyemaya.build.requestedyemaya.export.requested
- Isis:
isis.job.submittedisis.job.completedisis.job.failedisis.asset.generated
- Hathor:
hathor.world.publishedhathor.simulation.completed
- Bellona:
bellona.build.completedbellona.export.ready
- Aja:
aja.motion.job.completedaja.motion.job.failed
4.2 Event Envelope (Normative)#
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#
- No direct cross-domain database access.
- Domain-owned writes only through owning domain APIs.
- Cross-domain writes must use explicit contracts and typed adapters.
- Breaking contract changes require versioning and migration notes.
- 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:
- A domain dependency graph exists for Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
- Ownership matrix defines each domain's authoritative entities and cross-domain consumers.
- Canonical data contract families are defined for project, asset, generation, world/narrative, motion, build/export, and program gating.
- Required event families and envelope schema are documented.
- Consistency and failure semantics are explicitly defined.
- Governance rules prohibit direct cross-domain DB writes and enforce contract versioning.
- 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.