feat: introduce topology readiness and initialization

Adds a `ensure_ready` method to the `Topology` trait to ensure the infrastructure is prepared before score execution.

- Introduces a new `Outcome` status to indicate the result of the readiness check.
- Implements a `topology_preparation_result` field in `Maestro` to track initialization status.
- Adds a check in `interpret` to warn if the topology isn't fully initialized.
- Provides detailed documentation for the `Topology` trait and `ensure_ready` method, including recommended patterns for complex setups.
- Adds `async_trait` dependency.

harmony/src/domain/topology/mod.rs

@@ -5,6 +5,7 @@ mod load_balancer;
 pub mod openshift;
 mod router;
 mod tftp;
+use async_trait::async_trait;
 pub use ha_cluster::*;
 pub use load_balancer::*;
 pub use router::*;
@@ -17,8 +18,38 @@ pub use tftp::*;
 
 use std::net::IpAddr;
 
-pub trait Topology {
+use super::interpret::{InterpretError, Outcome};
+
+/// Represents a logical view of an infrastructure environment providing specific capabilities.
+///
+/// A Topology acts as a self-contained "package" responsible for managing access
+/// to its underlying resources and ensuring they are in a ready state before use.
+/// It defines the contract for the capabilities it provides through implemented
+/// capability traits (e.g., `HasK8sCapability`, `HasDnsServer`).
+#[async_trait]
+pub trait Topology: Send + Sync {
+    /// Returns a unique identifier or name for this specific topology instance.
+    /// This helps differentiate between multiple instances of potentially the same type.
     fn name(&self) -> &str;
+
+    /// Ensures that the topology and its required underlying components or services
+    /// are ready to provide their declared capabilities.
+    ///
+    /// Implementations of this method MUST be idempotent. Subsequent calls after a
+    /// successful readiness check should ideally be cheap NO-OPs.
+    ///
+    /// This method encapsulates the logic for:
+    /// 1.  **Checking Current State:** Assessing if the required resources/services are already running and configured.
+    /// 2.  **Discovery:** Identifying the runtime environment (e.g., local Docker, AWS, existing cluster).
+    /// 3.  **Initialization/Bootstrapping:** Performing necessary setup actions if not already ready. This might involve:
+    ///     *   Making API calls.
+    ///     *   Running external commands (e.g., `k3d`, `docker`).
+    ///     *   **Internal Orchestration:** For complex topologies, this method might manage dependencies on other sub-topologies, ensuring *their* `ensure_ready` is called first. Using nested `Maestros` to run setup `Scores` against these sub-topologies is the recommended pattern for non-trivial bootstrapping, allowing reuse of Harmony's core orchestration logic.
+    ///
+    /// # Returns
+    /// - `Ok(Outcome)`: Indicates the topology is now ready. The `Outcome` status might be `SUCCESS` if actions were taken, or `NOOP` if it was already ready. The message should provide context.
+    /// - `Err(TopologyError)`: Indicates the topology could not reach a ready state due to configuration issues, discovery failures, bootstrap errors, or unsupported environments.
+    async fn ensure_ready(&self) -> Result<Outcome, InterpretError>;
 }
 
 pub type IpAddress = IpAddr;