Add design notes for build state

databuild/build_state.rs

@@ -7,6 +7,27 @@ use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 use std::error::Error;
 
+/**
+Design Notes
+
+The build state struct is the heart of the service and orchestrator, adapting build events to
+higher level questions about build state. One temptation is to implement the build state as a set
+of hierarchically defined reducers, to achieve information hiding and factor system capabilities and
+state tracking simply. Unfortunately, to update state based on an event, you need a mutable borrow
+of some part of the build state (that the reducer controls, for instance), and an immutable borrow
+of the whole state for read/query purposes. The whole state needs to be available to handle state
+updates like "this is the list of currently active job runs" in response to a job run event. Put
+simply, this isn't possible without introducing some locking of the whole state and mutable state
+subset, since they would conflict (the mutable subset would have already been borrowed, so can't
+be borrowed immutably as part of the whole state borrow). You might also define a "query" phase
+in which reducers query the state based on the received event, but that just increases complexity.
+
+Instead, databuild opts for an entity-component system (ECS) that just provides the whole build
+state mutably to all state update functionality, trusting that we know how to use it responsibly.
+This means no boxing or "query phase", and means we can have all state updates happen as map lookups
+and updates, which is exceptionally fast.
+*/
+
 #[derive(Debug)]
 pub struct BuildState {
     wants: BTreeMap<String, WantDetail>,