@@ -62,30 +62,30 @@ the type of the agent's state. In principle, we could make it as simple as this:
63However, when you update your agent as described in the [Lifecycle](#lifecycle)
63However, when you update your agent as described in the [Lifecycle](#lifecycle)
64section, you may want to change the type of the state itself. This means
64section, you may want to change the type of the state itself. This means
65−`on-load` might find old versions of the state in the `vase` it receives. Over
65+`on-load` might find different versions of the state in the `vase` it receives,
66−time, as you make further changes to the type of the state, this becomes quite
66+and it might not be able to distinguish between them.
69For example, if you were creating an agent for a To-Do task management app, your
68For example, if you were creating an agent for a To-Do task management app, your
70−tasks might initially have a simple `?` to specify whether they're complete or
69+tasks might initially have a `?(%todo %done)` union to specify whether they're
71−not. Something like:
70+complete or not. Something like:
74−(map task=@t done=?)
73+(map task=@t status=?(%todo %done))
77At some point, you might want to add a third status to represent "in progress",
76At some point, you might want to add a third status to represent "in progress",
78−which might involve changing `done` to a tagged union like:
77+which might involve changing `status` like:
81(map title=@t status=?(%todo %done %work))
80(map title=@t status=?(%todo %done %work))
84−The conventional way to keep this managable is to have _versioned states_. The
83+The conventional way to keep this managable and reliably differentiate possible
84+state types is to have _versioned states_. The first version of the state would
85−first version of the state would typically be called `state-0`, and its head
85+typically be called `state-0`, and its head would be tagged with `%0`. Then,
86−would be tagged with `%0`. Then, when you change the state's type in an update,
86+when you change the state's type in an update, you'd add a new structure called
87−you'd add a new structure called `state-1` and tag its head with `%1`. The next
88−would then be `state-2`, and so on.
87+`state-1` and tag its head with `%1`. The next would then be `state-2`, and so
90In addition to each of those individual state versions, you'd also define a
90In addition to each of those individual state versions, you'd also define a
91structure called `versioned-state`, which just contains a union of all the
91structure called `versioned-state`, which just contains a union of all the
@@ -101,7 +101,7 @@ For example, your state definition core might initially look like:
101+$ versioned-state
101+$ versioned-state
102 $% state-0
102 $% state-0
104−+$ state-0 [%0 tasks=(map title=@t done=?)]
104++$ state-0 [%0 tasks=(map title=@t status=?(%todo %done))]
@@ -113,7 +113,7 @@ When you later update your agent with a new state version, you'd change it to:
113 $% state-0
113 $% state-0
116−+$ state-0 [%0 tasks=(map title=@t done=?)]
116++$ state-0 [%0 tasks=(map title=@t status=?(%todo %done))]
117+$ state-1 [%1 tasks=(map title=@t status=?(%todo %done %work))]
117+$ state-1 [%1 tasks=(map title=@t status=?(%todo %done %work))]