[nexus] Clean up API versioning: chain conversions, fix module docs

This PR refactors a set of versioned type conversions to properly follow the
[API versioning guide's](https://github.com/oxidecomputer/dropshot-api-manager/blob/main/guides/new-version.md)
recommendations, including chaining through consecutive versions, ordering
conventions, and aligning types to correctly match the ranges and
where they should be defined.

Changes:
  - Chain InstanceCreate conversions: v2025122300 → v2026010300 →
    v2026010500 → params
  - Update endpoint handlers to delegate through the version chain
  - Add per-section validity docs for modules where types have different
    supersession versions
  - Remove empty v2026011501.rs after types moved to v2026010500

Author: zeeshanlakhani

nexus/external-api/src/lib.rs

@@ -41,7 +41,6 @@ mod v2025122300;
 mod v2026010100;
 mod v2026010300;
 mod v2026010500;
-mod v2026011501;
 
 #[cfg(test)]
 mod test_utils;
@@ -1610,8 +1609,8 @@ pub trait NexusExternalApi {
         floating_params: TypedBody<v2026010300::FloatingIpCreate>,
     ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
         let floating_params =
-            floating_params.try_map(v2026011501::FloatingIpCreate::try_from)?;
-        Self::v2026011501_floating_ip_create(
+            floating_params.try_map(v2026010500::FloatingIpCreate::try_from)?;
+        Self::v2026010500_floating_ip_create(
             rqctx,
             query_params,
             floating_params,
@@ -1627,10 +1626,10 @@ pub trait NexusExternalApi {
         tags = ["floating-ips"],
         versions = VERSION_POOL_SELECTION_ENUMS..VERSION_RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR,
     }]
-    async fn v2026011501_floating_ip_create(
+    async fn v2026010500_floating_ip_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        floating_params: TypedBody<v2026011501::FloatingIpCreate>,
+        floating_params: TypedBody<v2026010500::FloatingIpCreate>,
     ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
         Self::floating_ip_create(
             rqctx,
@@ -2161,44 +2160,32 @@ pub trait NexusExternalApi {
 
     /// Create instance
     #[endpoint {
-        operation_id = "disk_create",
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions = ..VERSION_LOCAL_STORAGE,
+        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
     }]
-    async fn v2025112000_instance_create(
+    async fn instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2025112000::InstanceCreate>,
-    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        Self::v2025121200_instance_create(
-            rqctx,
-            query_params,
-            new_instance.map(Into::into),
-        )
-        .await
-    }
+        new_instance: TypedBody<params::InstanceCreate>,
+    ) -> Result<HttpResponseCreated<Instance>, HttpError>;
 
     /// Create instance
     #[endpoint {
         operation_id = "instance_create",
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions = VERSION_LOCAL_STORAGE..VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS,
+        versions = VERSION_POOL_SELECTION_ENUMS..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
     }]
-    async fn v2025121200_instance_create(
+    async fn v2026010500_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2025121200::InstanceCreate>,
+        new_instance: TypedBody<v2026010500::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        Self::v2026010100_instance_create(
-            rqctx,
-            query_params,
-            new_instance.map(Into::into),
-        )
-        .await
+        Self::instance_create(rqctx, query_params, new_instance.map(Into::into))
+            .await
     }
 
     /// Create instance
@@ -2207,16 +2194,19 @@ pub trait NexusExternalApi {
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions =
-            VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS..VERSION_DUAL_STACK_NICS,
+        versions = VERSION_DUAL_STACK_NICS..VERSION_POOL_SELECTION_ENUMS,
     }]
-    async fn v2026010100_instance_create(
+    async fn v2026010300_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2026010100::InstanceCreate>,
+        new_instance: TypedBody<v2026010300::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        let new_instance = new_instance.try_map(TryInto::try_into)?;
-        Self::instance_create(rqctx, query_params, new_instance).await
+        Self::v2026010500_instance_create(
+            rqctx,
+            query_params,
+            new_instance.try_map(TryInto::try_into)?,
+        )
+        .await
     }
 
     /// Create instance
@@ -2225,15 +2215,20 @@ pub trait NexusExternalApi {
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions = VERSION_DUAL_STACK_NICS..VERSION_POOL_SELECTION_ENUMS,
+        versions =
+            VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS..VERSION_DUAL_STACK_NICS,
     }]
-    async fn v2026010300_instance_create(
+    async fn v2025122300_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2026010300::InstanceCreate>,
+        new_instance: TypedBody<v2025122300::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        let new_instance = new_instance.try_map(TryInto::try_into)?;
-        Self::instance_create(rqctx, query_params, new_instance).await
+        Self::v2026010300_instance_create(
+            rqctx,
+            query_params,
+            new_instance.try_map(TryInto::try_into)?,
+        )
+        .await
     }
 
     /// Create instance
@@ -2242,29 +2237,41 @@ pub trait NexusExternalApi {
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions = VERSION_POOL_SELECTION_ENUMS..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
+        versions = VERSION_LOCAL_STORAGE..VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS,
     }]
-    async fn v2026010500_instance_create(
+    async fn v2025120300_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<v2026010500::InstanceCreate>,
+        new_instance: TypedBody<v2025120300::InstanceCreate>,
     ) -> Result<HttpResponseCreated<Instance>, HttpError> {
-        Self::instance_create(rqctx, query_params, new_instance.map(Into::into))
-            .await
+        Self::v2025122300_instance_create(
+            rqctx,
+            query_params,
+            new_instance.map(Into::into),
+        )
+        .await
     }
 
     /// Create instance
     #[endpoint {
+        operation_id = "instance_create",
         method = POST,
         path = "/v1/instances",
         tags = ["instances"],
-        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
+        versions = ..VERSION_LOCAL_STORAGE,
     }]
-    async fn instance_create(
+    async fn v2025112000_instance_create(
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::ProjectSelector>,
-        new_instance: TypedBody<params::InstanceCreate>,
-    ) -> Result<HttpResponseCreated<Instance>, HttpError>;
+        new_instance: TypedBody<v2025112000::InstanceCreate>,
+    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
+        Self::v2025120300_instance_create(
+            rqctx,
+            query_params,
+            new_instance.map(Into::into),
+        )
+        .await
+    }
 
     /// Fetch instance
     #[endpoint {

nexus/external-api/src/v2025112000.rs

@@ -2,9 +2,10 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-//! Nexus external types that changed from 2025112000 to 2025120300
+//! Nexus external types that changed from 2025112000 (INITIAL) to 2025120300
+//! (LOCAL_STORAGE).
 
-use crate::v2025121200;
+use crate::v2025120300;
 use crate::v2026010100;
 use nexus_types::external_api::params;
 use omicron_common::api::external;
@@ -220,9 +221,9 @@ pub struct InstanceCreate {
     /// By default, all instances have outbound connectivity, but no inbound
     /// connectivity. These external addresses can be used to provide a fixed,
     /// known IP address for making inbound connections to the instance.
-    // Delegates through v2025121200 → params::ExternalIpCreate
+    // Delegates through v2025120300 → params::ExternalIpCreate
     #[serde(default)]
-    pub external_ips: Vec<v2025121200::ExternalIpCreate>,
+    pub external_ips: Vec<v2025120300::ExternalIpCreate>,
 
     /// The multicast groups this instance should join.
     ///
@@ -302,9 +303,9 @@ pub struct InstanceCreate {
     pub cpu_platform: Option<external::InstanceCpuPlatform>,
 }
 
-impl From<InstanceCreate> for v2025121200::InstanceCreate {
-    fn from(old: InstanceCreate) -> v2025121200::InstanceCreate {
-        v2025121200::InstanceCreate {
+impl From<InstanceCreate> for v2025120300::InstanceCreate {
+    fn from(old: InstanceCreate) -> v2025120300::InstanceCreate {
+        v2025120300::InstanceCreate {
             identity: old.identity,
             ncpus: old.ncpus,
             memory: old.memory,