refactor: [#281] encapsulate RuntimeOutputs with semantic setters

- Make all RuntimeOutputs fields private (instance_ip, provision_method,
  service_endpoints)
- Add RuntimeOutputs::new() constructor for empty outputs
- Add semantic setters that indicate when data is set:
  - record_provisioning(ip) - after provision command
  - record_registration(ip) - after register command
  - record_services_started(endpoints) - after run command
- Add low-level setters (set_instance_ip, set_provision_method) for
  compatibility with existing code
- Add getter methods: instance_ip(), provision_method(), service_endpoints()
- Implement Default trait for RuntimeOutputs

The setter names now clearly document when data is populated during
the deployment lifecycle, improving code readability and traceability.

Author: josecelano

src/domain/environment/context.rs

@@ -204,11 +204,7 @@ impl EnvironmentContext {
             user_inputs: UserInputs::new(name, provider_config, ssh_credentials, ssh_port)
                 .expect("UserInputs::new with defaults should never fail - default config always passes validation"),
             internal_config: InternalConfig::new(name),
-            runtime_outputs: RuntimeOutputs {
-                instance_ip: None,
-                provision_method: None,
-                service_endpoints: None,
-            },
+            runtime_outputs: RuntimeOutputs::new(),
         }
     }
 
@@ -250,11 +246,7 @@ impl EnvironmentContext {
                 &params.environment_name,
                 working_dir,
             ),
-            runtime_outputs: RuntimeOutputs {
-                instance_ip: None,
-                provision_method: None,
-                service_endpoints: None,
-            },
+            runtime_outputs: RuntimeOutputs::new(),
         })
     }
 
@@ -407,13 +399,13 @@ impl EnvironmentContext {
     /// Returns the instance IP address if available
     #[must_use]
     pub fn instance_ip(&self) -> Option<std::net::IpAddr> {
-        self.runtime_outputs.instance_ip
+        self.runtime_outputs.instance_ip()
     }
 
     /// Returns the provision method
     #[must_use]
     pub fn provision_method(&self) -> Option<crate::domain::environment::ProvisionMethod> {
-        self.runtime_outputs.provision_method
+        self.runtime_outputs.provision_method()
     }
 
     /// Returns the creation timestamp

src/domain/environment/mod.rs

@@ -694,7 +694,7 @@ impl<S> Environment<S> {
     /// ```
     #[must_use]
     pub fn with_instance_ip(mut self, ip: IpAddr) -> Self {
-        self.context_mut().runtime_outputs.instance_ip = Some(ip);
+        self.context_mut().runtime_outputs.set_instance_ip(ip);
         self
     }
 
@@ -713,7 +713,9 @@ impl<S> Environment<S> {
     /// Returns the environment with the provision method set.
     #[must_use]
     pub fn with_provision_method(mut self, method: runtime_outputs::ProvisionMethod) -> Self {
-        self.context_mut().runtime_outputs.provision_method = Some(method);
+        self.context_mut()
+            .runtime_outputs
+            .set_provision_method(method);
         self
     }
 
@@ -1125,11 +1127,7 @@ mod tests {
                     data_dir: data_dir.clone(),
                     build_dir: build_dir.clone(),
                 },
-                runtime_outputs: RuntimeOutputs {
-                    instance_ip: None,
-                    provision_method: None,
-                    service_endpoints: None,
-                },
+                runtime_outputs: RuntimeOutputs::new(),
                 created_at: chrono::Utc::now(),
             };
 
@@ -1569,7 +1567,7 @@ mod tests {
                     .build();
 
                 // Runtime outputs start empty
-                assert_eq!(env.context.runtime_outputs.instance_ip, None);
+                assert_eq!(env.context.runtime_outputs.instance_ip(), None);
             }
 
             #[test]
@@ -1582,7 +1580,7 @@ mod tests {
                 let ip = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1));
                 let env = env.with_instance_ip(ip);
 
-                assert_eq!(env.context.runtime_outputs.instance_ip, Some(ip));
+                assert_eq!(env.context.runtime_outputs.instance_ip(), Some(ip));
             }
 
             #[test]

src/domain/environment/runtime_outputs.rs

@@ -218,8 +218,17 @@ impl ServiceEndpoints {
 /// Runtime outputs generated during deployment operations
 ///
 /// This struct contains fields that are generated during deployment operations
-/// and represent the runtime state of deployed infrastructure. These fields
-/// are mutable as operations progress.
+/// and represent the runtime state of deployed infrastructure. Fields are
+/// private to protect invariants and provide semantic clarity through setters.
+///
+/// # Lifecycle
+///
+/// Fields are populated at different stages of the deployment lifecycle:
+/// - **Creation**: All fields are `None` (use `RuntimeOutputs::new()`)
+/// - **After Provisioning**: `instance_ip` and `provision_method` are set
+///   (use `record_provisioning()` or `record_registration()`)
+/// - **After Run Command**: `service_endpoints` is set
+///   (use `record_services_started()`)
 ///
 /// # Future Fields
 ///
@@ -233,19 +242,23 @@ impl ServiceEndpoints {
 /// use torrust_tracker_deployer_lib::domain::environment::runtime_outputs::{RuntimeOutputs, ProvisionMethod};
 /// use std::net::{IpAddr, Ipv4Addr};
 ///
-/// let runtime_outputs = RuntimeOutputs {
-///     instance_ip: Some(IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100))),
-///     provision_method: Some(ProvisionMethod::Provisioned),
-///     service_endpoints: None,
-/// };
+/// // Create empty runtime outputs
+/// let mut runtime_outputs = RuntimeOutputs::new();
+/// assert!(runtime_outputs.instance_ip().is_none());
+///
+/// // After provisioning, record the IP and method
+/// let ip = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100));
+/// runtime_outputs.record_provisioning(ip);
+/// assert_eq!(runtime_outputs.instance_ip(), Some(ip));
+/// assert_eq!(runtime_outputs.provision_method(), Some(ProvisionMethod::Provisioned));
 /// ```
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RuntimeOutputs {
     /// Instance IP address (populated after provisioning)
     ///
     /// This field stores the IP address of the provisioned instance and is
     /// `None` until the environment has been successfully provisioned.
-    pub instance_ip: Option<IpAddr>,
+    instance_ip: Option<IpAddr>,
 
     /// How the instance was provisioned
     ///
@@ -257,7 +270,7 @@ pub struct RuntimeOutputs {
     /// - `Some(Provisioned)`: Instance was created via `provision` command
     /// - `Some(Registered)`: Instance was connected via `register` command
     #[serde(default)]
-    pub provision_method: Option<ProvisionMethod>,
+    provision_method: Option<ProvisionMethod>,
 
     /// Service endpoints populated after services are started
     ///
@@ -267,5 +280,130 @@ pub struct RuntimeOutputs {
     /// - `None`: Services not yet started or legacy state
     /// - `Some(endpoints)`: URLs for all running services
     #[serde(default)]
-    pub service_endpoints: Option<ServiceEndpoints>,
+    service_endpoints: Option<ServiceEndpoints>,
+}
+
+impl RuntimeOutputs {
+    /// Creates new empty runtime outputs
+    ///
+    /// All fields are initialized to `None`, representing an environment
+    /// that has not yet been provisioned or run.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use torrust_tracker_deployer_lib::domain::environment::runtime_outputs::RuntimeOutputs;
+    ///
+    /// let outputs = RuntimeOutputs::new();
+    /// assert!(outputs.instance_ip().is_none());
+    /// assert!(outputs.provision_method().is_none());
+    /// assert!(outputs.service_endpoints().is_none());
+    /// ```
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            instance_ip: None,
+            provision_method: None,
+            service_endpoints: None,
+        }
+    }
+
+    // =========================================================================
+    // Getters - Access runtime output values
+    // =========================================================================
+
+    /// Returns the instance IP address if available
+    ///
+    /// This is `None` until the environment has been provisioned or registered.
+    #[must_use]
+    pub fn instance_ip(&self) -> Option<IpAddr> {
+        self.instance_ip
+    }
+
+    /// Returns how the instance was provisioned
+    ///
+    /// - `None`: Unknown or legacy state
+    /// - `Some(Provisioned)`: Created via `provision` command
+    /// - `Some(Registered)`: Connected via `register` command
+    #[must_use]
+    pub fn provision_method(&self) -> Option<ProvisionMethod> {
+        self.provision_method
+    }
+
+    /// Returns the service endpoints if available
+    ///
+    /// This is `None` until the `run` command has started services successfully.
+    #[must_use]
+    pub fn service_endpoints(&self) -> Option<&ServiceEndpoints> {
+        self.service_endpoints.as_ref()
+    }
+
+    // =========================================================================
+    // Semantic Setters - Record deployment lifecycle events
+    // =========================================================================
+
+    /// Records that provisioning has completed with the given instance IP
+    ///
+    /// Call this after the `provision` command successfully creates infrastructure.
+    /// Sets both `instance_ip` and `provision_method` to `Provisioned`.
+    ///
+    /// # Arguments
+    ///
+    /// * `ip` - The IP address of the newly provisioned instance
+    pub fn record_provisioning(&mut self, ip: IpAddr) {
+        self.instance_ip = Some(ip);
+        self.provision_method = Some(ProvisionMethod::Provisioned);
+    }
+
+    /// Records that an existing instance has been registered
+    ///
+    /// Call this after the `register` command connects to existing infrastructure.
+    /// Sets both `instance_ip` and `provision_method` to `Registered`.
+    ///
+    /// # Arguments
+    ///
+    /// * `ip` - The IP address of the registered instance
+    pub fn record_registration(&mut self, ip: IpAddr) {
+        self.instance_ip = Some(ip);
+        self.provision_method = Some(ProvisionMethod::Registered);
+    }
+
+    /// Records that services have been started with the given endpoints
+    ///
+    /// Call this after the `run` command successfully starts all services.
+    /// The endpoints can then be displayed to users or used for health checks.
+    ///
+    /// # Arguments
+    ///
+    /// * `endpoints` - The URLs for all running services
+    pub fn record_services_started(&mut self, endpoints: ServiceEndpoints) {
+        self.service_endpoints = Some(endpoints);
+    }
+
+    // =========================================================================
+    // Low-level setters - For backward compatibility and state restoration
+    // =========================================================================
+
+    /// Sets the instance IP directly
+    ///
+    /// Prefer `record_provisioning()` or `record_registration()` which also
+    /// set the provision method. This method is provided for cases where
+    /// only the IP needs to be updated (e.g., deserialization workarounds).
+    pub fn set_instance_ip(&mut self, ip: IpAddr) {
+        self.instance_ip = Some(ip);
+    }
+
+    /// Sets the provision method directly
+    ///
+    /// Prefer `record_provisioning()` or `record_registration()` which also
+    /// set the instance IP. This method is provided for backward compatibility.
+    pub fn set_provision_method(&mut self, method: ProvisionMethod) {
+        self.provision_method = Some(method);
+    }
+}
+
+impl Default for RuntimeOutputs {
+    fn default() -> Self {
+        Self::new()
+    }
 }

src/domain/environment/state/mod.rs

@@ -510,7 +510,7 @@ impl AnyEnvironmentState {
     /// - `None` if the environment hasn't been provisioned yet
     #[must_use]
     pub fn instance_ip(&self) -> Option<std::net::IpAddr> {
-        self.context().runtime_outputs.instance_ip
+        self.context().runtime_outputs.instance_ip()
     }
 
     /// Get when the environment was created
@@ -538,7 +538,7 @@ impl AnyEnvironmentState {
     /// - `None` if the provision method hasn't been set yet (legacy or pre-provisioned state)
     #[must_use]
     pub fn provision_method(&self) -> Option<ProvisionMethod> {
-        self.context().runtime_outputs.provision_method
+        self.context().runtime_outputs.provision_method()
     }
 
     /// Get the service endpoints if available, regardless of current state
@@ -552,7 +552,7 @@ impl AnyEnvironmentState {
     /// - `None` if services haven't been started yet or URLs weren't recorded
     #[must_use]
     pub fn service_endpoints(&self) -> Option<&ServiceEndpoints> {
-        self.context().runtime_outputs.service_endpoints.as_ref()
+        self.context().runtime_outputs.service_endpoints()
     }
 
     /// Get the Prometheus configuration if enabled, regardless of current state

src/domain/environment/state/released.rs

@@ -37,7 +37,9 @@ impl Environment<Released> {
         mut self,
         service_endpoints: ServiceEndpoints,
     ) -> Environment<Running> {
-        self.context.runtime_outputs.service_endpoints = Some(service_endpoints);
+        self.context
+            .runtime_outputs
+            .record_services_started(service_endpoints);
         self.with_state(Running)
     }
 

src/domain/environment/testing.rs

@@ -170,11 +170,7 @@ impl EnvironmentTestBuilder {
                 data_dir: data_dir.clone(),
                 build_dir: build_dir.clone(),
             },
-            runtime_outputs: crate::domain::environment::RuntimeOutputs {
-                instance_ip: None,
-                provision_method: None,
-                service_endpoints: None,
-            },
+            runtime_outputs: crate::domain::environment::RuntimeOutputs::new(),
         };
 
         let environment = Environment {