doc comments explaining new arg

Author: jgallagher

nexus/reconfigurator/preparation/src/lib.rs

@@ -96,7 +96,38 @@ pub struct PlanningInputFromDb<'a> {
 }
 
 impl PlanningInputFromDb<'_> {
-    // TODO-john docs
+    /// Read the current set of database state needed to assemble a new
+    /// [`PlanningInput`].
+    ///
+    /// The caller is required to pass `parent_blueprint` in so that we
+    /// statically enforce that any `PlanningInput` information we read from the
+    /// database is _at least as new_ as the parent blueprint on which the
+    /// planner will operate. This is particularly important for the planner's
+    /// "garbage collection" phase where it drops expunged items for which all
+    /// cleanup is complete: if the `PlanningInput` is read before the parent
+    /// blueprint, some of the "is cleanup complete" information that doesn't
+    /// have explicit generation numbers (or equivalent) could show a state
+    /// where the planner believes cleanup is complete when actually it hasn't
+    /// yet had a chance to run; e.g..
+    ///
+    /// * Nexus A constructs a `PlanningInput` that has no record of zone Z.
+    /// * Nexus A goes out to lunch.
+    /// * Nexus B constructs a new blueprint that adds zone Z, makes it the
+    ///   target, and executes it.
+    /// * Zone Z runs, and inserts some records that we'd see in `PlanningInput`
+    ///   indicating it is not yet cleaned up.
+    /// * Nexus B constructs a new blueprint that expunges zone Z, makes it the
+    ///   target, and executes it.
+    /// * At this point zone Z is expunged and ready for cleanup, but cleanup is
+    ///   not yet complete - we still have records related to zone Z in the db.
+    /// * Nexus A resumes. It loads the current target blueprint (which shows
+    ///   zone Z is expunged) and has a `PlanningInput` with no records
+    ///   indicating zone Z is _not_ ready for cleanup, so incorrectly garbage
+    ///   collects zone Z.
+    ///
+    /// We could enforce this instead by loading `parent_blueprint` ourselves
+    /// with a note that it must come first, but in practice our caller has
+    /// already loaded it.
     pub async fn assemble(
         opctx: &OpContext,
         datastore: &DataStore,

nexus/types/src/deployment/planning_input.rs

@@ -1601,7 +1601,6 @@ pub struct PlanningInputBuilder {
 }
 
 impl PlanningInputBuilder {
-    // TODO-john docs
     pub fn new(
         parent_blueprint: Arc<Blueprint>,
         policy: Policy,