Naming and API Refinements: Current / Desired (Goal) States and Commands

[azriel91]

In 0.0.10 and earlier:

• StatesCurrent is stored as states_saved.yaml, and StatesDesired is stored as states_desired.yaml.
• It is a surprise / hard to discover when one wants to read the previously stored StatesCurrent, and has to remember to use StatesSavedReadCmd instead of StatesCurrent..Cmd.
• It is additional effort when one has StatesCurrent, and needs to pass in StatesSaved to EnsureCmd -- they have to map the data type (related: #59).
• "desired" doesn't capture the meaning that that is the state when the automation ensures.

To address these:

• "desired" should be renamed to "goal".

  • StatesDesired*Cmd renamed to StatesGoal*Cmd
  • states_desired.yaml renamed to states_goal.yaml
  • Update docs.

  Name bikeshedding:

  • leave as is
  • built / created (some things aren't built / created, and a bit obscure)
  • complete / finished this? (may confuse user that it is "done")
  • done (overloaded / hard to search / confusing)
  • formed (overloaded term)
  • forged (obscure)
  • goal this? (semantic overlap with "target"?)
  • manufactured (too long)

• Rename StatesSaved* to StatesCurrentStored.

• Add StatesGoalStored* to distinguish between StatesGoal and what was saved.

• Make sure it is easy to go from States*Stored to States*.

---

Out of scope:

• Rename DiffCmd to StatesDiffCmd (?) -- what about diffing parameters or specs.

• Store state for each item, even if it was not discovered.

  • Current states.
  • Goal states.
  • State diffs.

  Fixes the ordering in stored files.

• StatesDiffCmd API to make it obvious whether we are diffing:

  Single profile, single flow:

  • Discovered current and discovered goal states.
  • Discovered current and discovered goal states.
  • Saved current and discovered goal states.
  • Discovered current and saved goal states.

  Multi profile, single flow:

  • Current states of both profiles.
  • Goal states of both profiles.

  Arbitrary two states.