Eve library

OSHUN Studio Domain Dependency and Data Contract Map

Spec

Revision 1

On this page

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.