code: func PlannedStateUpdate(mgr Transient, planned *states.State) *statefile.File {
  	ret := &statefile.File{
  		State: planned.DeepCopy(),
  	}
  
  	// If the given manager uses snapshot metadata then we'll save that
  	// in our file so we can check it again during WritePlannedStateUpdate.
  	if mr, ok := mgr.(PersistentMeta); ok {
  		m := mr.StateSnapshotMeta()
  		ret.Lineage = m.Lineage
  		ret.Serial = m.Serial
  	}
  
  	return ret
  }
docs: // PlannedStateUpdate is a special helper to obtain a statefile representation
  // of a not-yet-written state snapshot that can be written later by a call
  // to the companion function WritePlannedStateUpdate.
  //
  // The statefile object returned here has an unusual interpretation of its
  // metadata that is understood only by WritePlannedStateUpdate, and so the
  // returned object should not be used for any other purpose.
  //
  // If the state manager implements Locker then it is the caller's
  // responsibility to hold the lock at least for the duration of this call.
  // It is not safe to modify the given state concurrently while
  // PlannedStateUpdate is running.