[api] Fix some doc comments

nexus/external-api/src/lib.rs

@@ -87,6 +87,7 @@ api_versions!([
     // |  date-based version should be at the top of the list.
     // v
     // (next_yyyy_mm_dd_nn, IDENT),
+    (2026_08_28_00, SILO_USER_DOCS),
     (2026_08_19_01, BGP_PEER_SRC_ADDR),
     (2026_08_17_00, SUPPORT_BUNDLES_STABLE),
     (2026_08_14_00, ALERT_LIST),
@@ -739,7 +740,7 @@ pub trait NexusExternalApi {
 
     // Silo-specific user endpoints
 
-    /// List built-in (system) users in silo
+    /// List users in silo
     #[endpoint {
         method = GET,
         path = "/v1/system/users",
@@ -751,7 +752,7 @@ pub trait NexusExternalApi {
         query_params: Query<PaginatedById<latest::silo::SiloSelector>>,
     ) -> Result<HttpResponseOk<ResultsPage<latest::user::User>>, HttpError>;
 
-    /// List built-in (system) users in silo
+    /// List users in silo
     #[endpoint {
         operation_id = "silo_user_list",
         method = GET,
@@ -776,7 +777,7 @@ pub trait NexusExternalApi {
         )
     }
 
-    /// Fetch built-in (system) user
+    /// Fetch user in silo
     #[endpoint {
         method = GET,
         path = "/v1/system/users/{user_id}",
@@ -789,7 +790,7 @@ pub trait NexusExternalApi {
         query_params: Query<latest::silo::SiloSelector>,
     ) -> Result<HttpResponseOk<latest::user::User>, HttpError>;
 
-    /// Fetch built-in (system) user
+    /// Fetch user in silo
     #[endpoint {
         operation_id = "silo_user_view",
         method = GET,
@@ -8985,10 +8986,10 @@ pub trait NexusExternalApi {
     ///
     /// Audit log entries are designed to be immutable: once you see an entry,
     /// fetching it again will never get you a different result. The list is
-    /// ordered by `time_completed`, not `time_started`. If you fetch the audit
-    /// log for a time range that is fully in the past, the resulting list is
-    /// guaranteed to be complete, i.e., fetching the same timespan again later
-    /// will always produce the same set of entries.
+    /// ordered and filtered by `time_completed`, not `time_started`. If
+    /// you fetch the audit log for a time range that is fully in the past,
+    /// the resulting list is guaranteed to be complete, i.e., fetching the
+    /// same timespan again later will always produce the same set of entries.
     #[endpoint {
         method = GET,
         path = "/v1/system/audit-log",

nexus/types/versions/src/external_jumbo_frames/system_networking.rs

@@ -13,7 +13,7 @@ use serde::{Deserialize, Serialize};
 pub struct SystemNetworkingSettings {
     /// When true, end users may opt in to jumbo frames (8500 byte MTU) on the
     /// primary interface of an instance. When false, instance-level opt-in is
-    /// ignored and OPTE ports are created with the default MTU.
+    /// ignored and the primary interface uses the default MTU.
     pub external_jumbo_frames_opt_in_enabled: bool,
 }
 

nexus/types/versions/src/initial/affinity.rs

@@ -106,12 +106,14 @@ pub struct AntiAffinityInstanceGroupMemberPath {
 )]
 #[serde(rename_all = "snake_case")]
 pub enum AffinityPolicy {
-    /// If the affinity request cannot be satisfied, allow it anyway.
-    ///
-    /// This enables a "best-effort" attempt to satisfy the affinity policy.
+    /// Best-effort: instances can start even when the group's constraints
+    /// cannot be satisfied.
     Allow,
 
-    /// If the affinity request cannot be satisfied, fail explicitly.
+    /// When the group's constraints cannot be satisfied, an instance start
+    /// request will fail and the instance will remain stopped. Starting the
+    /// instance may succeed later if conditions change, e.g., other instances
+    /// stop.
     Fail,
 }
 

nexus/types/versions/src/initial/audit.rs

@@ -103,8 +103,9 @@ pub struct AuditLogEntry {
 /// Audit log has its own pagination scheme because it paginates by timestamp.
 #[derive(Deserialize, JsonSchema, Serialize, PartialEq, Debug, Clone)]
 pub struct AuditLogParams {
-    /// Required, inclusive
+    /// Start of time range (inclusive). Filters on `time_completed`.
     pub start_time: DateTime<Utc>,
-    /// Exclusive
+    /// End of time range (exclusive). Filters on `time_completed`. If
+    /// omitted, the range extends to the present.
     pub end_time: Option<DateTime<Utc>>,
 }

nexus/types/versions/src/initial/silo.rs

@@ -82,8 +82,8 @@ pub struct Silo {
     #[serde(flatten)]
     pub identity: IdentityMetadata,
 
-    /// A silo where discoverable is false can be retrieved only by its id - it
-    /// will not be part of the "list all silos" output.
+    /// A non-discoverable silo can only be retrieved by ID - it will not be
+    /// part of the "list all silos" output.
     pub discoverable: bool,
 
     /// How users and groups are managed in this Silo
@@ -184,6 +184,8 @@ pub struct SiloCreate {
     #[serde(flatten)]
     pub identity: IdentityMetadataCreateParams,
 
+    /// A non-discoverable silo can only be retrieved by ID - it will not be
+    /// part of the "list all silos" output.
     pub discoverable: bool,
 
     pub identity_mode: SiloIdentityMode,

nexus/types/versions/src/instance_cpu_type_turin_v2/instance.rs

@@ -296,7 +296,7 @@ pub struct InstanceCreate {
     /// it is initially placed on.
     #[serde(default)]
     pub cpu_platform: Option<InstanceCpuPlatform>,
-    /// Enable jumbo frames (8500 byte MTU) on the instance's primary OPTE
+    /// Enable jumbo frames (8500 byte MTU) on the instance's primary network
     /// interface. Requires the fleet-wide jumbo-frames opt-in to be enabled
     /// by an operator; otherwise this field must be `false`. Changes only take
     /// effect on the next instance restart.

openapi/nexus/nexus-2026081901.0.0-e5e4f5.json.gitstub

@@ -0,0 +1 @@
+6b1ca22b4066024f8ac2c04bd678d6e09bf50a6f:openapi/nexus/nexus-2026081901.0.0-e5e4f5.json

openapi/nexus/nexus-2026081901.0.0-e5e4f5.json → openapi/nexus/nexus-2026082800.0.0-d863f1.json

@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "2026081901.0.0"
+    "version": "2026082800.0.0"
   },
   "paths": {
     "/device/auth": {
@@ -7342,13 +7342,13 @@
           "system/audit-log"
         ],
         "summary": "View audit log",
-        "description": "A single item in the audit log represents both the beginning and end of the logged operation (represented by `time_started` and `time_completed`) so that clients do not have to find multiple entries and match them up by request ID to get the full picture of an operation. Because timestamps may not be unique, entries have also have a unique `id` that can be used to deduplicate items fetched from overlapping time intervals.\n\nAudit log entries are designed to be immutable: once you see an entry, fetching it again will never get you a different result. The list is ordered by `time_completed`, not `time_started`. If you fetch the audit log for a time range that is fully in the past, the resulting list is guaranteed to be complete, i.e., fetching the same timespan again later will always produce the same set of entries.",
+        "description": "A single item in the audit log represents both the beginning and end of the logged operation (represented by `time_started` and `time_completed`) so that clients do not have to find multiple entries and match them up by request ID to get the full picture of an operation. Because timestamps may not be unique, entries have also have a unique `id` that can be used to deduplicate items fetched from overlapping time intervals.\n\nAudit log entries are designed to be immutable: once you see an entry, fetching it again will never get you a different result. The list is ordered and filtered by `time_completed`, not `time_started`. If you fetch the audit log for a time range that is fully in the past, the resulting list is guaranteed to be complete, i.e., fetching the same timespan again later will always produce the same set of entries.",
         "operationId": "audit_log_list",
         "parameters": [
           {
             "in": "query",
             "name": "end_time",
-            "description": "Exclusive",
+            "description": "End of time range (exclusive). Filters on `time_completed`. If omitted, the range extends to the present.",
             "schema": {
               "nullable": true,
               "type": "string",
@@ -7385,7 +7385,7 @@
           {
             "in": "query",
             "name": "start_time",
-            "description": "Required, inclusive",
+            "description": "Start of time range (inclusive). Filters on `time_completed`.",
             "schema": {
               "type": "string",
               "format": "date-time"
@@ -13465,7 +13465,7 @@
         "tags": [
           "system/silos"
         ],
-        "summary": "List built-in (system) users in silo",
+        "summary": "List users in silo",
         "operationId": "silo_user_list",
         "parameters": [
           {
@@ -13534,7 +13534,7 @@
         "tags": [
           "system/silos"
         ],
-        "summary": "Fetch built-in (system) user",
+        "summary": "Fetch user in silo",
         "operationId": "silo_user_view",
         "parameters": [
           {
@@ -16208,14 +16208,14 @@
         "description": "Affinity policy used to describe \"what to do when a request cannot be satisfied\"\n\nUsed for both Affinity and Anti-Affinity Groups",
         "oneOf": [
           {
-            "description": "If the affinity request cannot be satisfied, allow it anyway.\n\nThis enables a \"best-effort\" attempt to satisfy the affinity policy.",
+            "description": "Best-effort: instances can start even when the group's constraints cannot be satisfied.",
             "type": "string",
             "enum": [
               "allow"
             ]
           },
           {
-            "description": "If the affinity request cannot be satisfied, fail explicitly.",
+            "description": "When the group's constraints cannot be satisfied, an instance start request will fail and the instance will remain stopped. Starting the instance may succeed later if conditions change, e.g., other instances stop.",
             "type": "string",
             "enum": [
               "fail"
@@ -23111,7 +23111,7 @@
             }
           },
           "enable_jumbo_frames": {
-            "description": "Enable jumbo frames (8500 byte MTU) on the instance's primary OPTE interface. Requires the fleet-wide jumbo-frames opt-in to be enabled by an operator; otherwise this field must be `false`. Changes only take effect on the next instance restart.",
+            "description": "Enable jumbo frames (8500 byte MTU) on the instance's primary network interface. Requires the fleet-wide jumbo-frames opt-in to be enabled by an operator; otherwise this field must be `false`. Changes only take effect on the next instance restart.",
             "default": false,
             "type": "boolean"
           },
@@ -27594,7 +27594,7 @@
             "type": "string"
           },
           "discoverable": {
-            "description": "A silo where discoverable is false can be retrieved only by its id - it will not be part of the \"list all silos\" output.",
+            "description": "A non-discoverable silo can only be retrieved by ID - it will not be part of the \"list all silos\" output.",
             "type": "boolean"
           },
           "id": {
@@ -27700,6 +27700,7 @@
             "type": "string"
           },
           "discoverable": {
+            "description": "A non-discoverable silo can only be retrieved by ID - it will not be part of the \"list all silos\" output.",
             "type": "boolean"
           },
           "identity_mode": {
@@ -29943,7 +29944,7 @@
         "type": "object",
         "properties": {
           "external_jumbo_frames_opt_in_enabled": {
-            "description": "When true, end users may opt in to jumbo frames (8500 byte MTU) on the primary interface of an instance. When false, instance-level opt-in is ignored and OPTE ports are created with the default MTU.",
+            "description": "When true, end users may opt in to jumbo frames (8500 byte MTU) on the primary interface of an instance. When false, instance-level opt-in is ignored and the primary interface uses the default MTU.",
             "type": "boolean"
           }
         },

openapi/nexus/nexus-latest.json

@@ -1 +1 @@
-nexus-2026081901.0.0-e5e4f5.json
+nexus-2026082800.0.0-d863f1.json

workspace-hack/Cargo.toml

@@ -82,8 +82,7 @@ idna = { version = "1.1.0" }
 indexmap = { version = "2.14.0", features = ["serde"] }
 ipnet = { version = "2.12.0", features = ["serde"] }
 ipnetwork = { version = "0.21.1", features = ["schemars", "serde"] }
-itertools-3575ec1268b04181 = { package = "itertools", version = "0.15.0" }
-itertools-594e8ee84c453af0 = { package = "itertools", version = "0.13.0" }
+itertools = { version = "0.13.0" }
 jiff = { version = "0.2.34", features = ["serde"] }
 lalrpop-util = { version = "0.19.12" }
 lazy_static = { version = "1.5.0", default-features = false, features = ["spin_no_std"] }
@@ -237,8 +236,7 @@ idna = { version = "1.1.0" }
 indexmap = { version = "2.14.0", features = ["serde"] }
 ipnet = { version = "2.12.0", features = ["serde"] }
 ipnetwork = { version = "0.21.1", features = ["schemars", "serde"] }
-itertools-3575ec1268b04181 = { package = "itertools", version = "0.15.0" }
-itertools-594e8ee84c453af0 = { package = "itertools", version = "0.13.0" }
+itertools = { version = "0.13.0" }
 jiff = { version = "0.2.34", features = ["serde"] }
 lalrpop-util = { version = "0.19.12" }
 lazy_static = { version = "1.5.0", default-features = false, features = ["spin_no_std"] }