A migration plan: how one execution's position crosses from one chart to another, as data.

ADR-0013 (docs/adr/0013-the-migration-plan.md) decides the plan. This module implements its decision 1 (the plan's fields and its one map encoding) and the static half of its decision 3 (the validation against the two machines). It does not migrate anything and reads no execution; applying a plan to an execution is Executions' job, not this module's.

This is the plan for moving an execution between charts. It has nothing to do with StatifierPersistence.Ecto.Migrations, the helper that creates and upgrades this package's tables.

The fields

A plan names the chart it moves from and the chart it moves to by content hash, and says how every part of a position crosses between them (ADR-0013 decision 1):

• :from and :to - the two content hashes.
• :states - a source state id to a target state id. A state the plan does not name maps to the state of the same id in the to chart, when there is one.
• :drop - source state ids the plan removes on purpose.
• :history - a source history state id to a target history state id, with the same default as :states.
• :invocations - one {from_state_id, from_ordinal, to_state_id, to_ordinal} per moved invocation; the ordinal is the engine's within-state document-order ordinal of an <invoke>, counted from 0.
• :timers - %{keep_mapped: true}, the only value the format admits (ADR-0013 decision 6).
• :datamodel - an ordered list of {:add, key, value}, {:rename, from_key, to_key} and {:remove, key} on top-level datamodel keys. A value is a JSON literal, never an expression, and a key that begins with _ is refused because those are the engine's system variables.

The struct is the in-memory form. What crosses a package boundary or reaches storage is the map form to_map/1 writes and from_map/1 reads: string keys only, an invocation as the four-element list [from_state_id, from_ordinal, to_state_id, to_ordinal], and a datamodel operation as an object with an "op" key.

An example

A library hold waits in awaiting_pickup for copy.collected or pickup.expired. The library then renames that state ready_for_pickup and gives the routing step before it a transferred outcome leading to a new state. The plan that moves a waiting hold across that edit renames one state and adds one datamodel key:

{:ok, plan} =
  Plan.new(
    from: from_hash,
    to: to_hash,
    states: %{"awaiting_pickup" => "ready_for_pickup"},
    datamodel: [{:add, "transfer_branch", nil}]
  )

:ok = Plan.validate(plan, from_machine, to_machine)

In the map form the same plan is:

%{
  "from" => from_hash,
  "to" => to_hash,
  "states" => %{"awaiting_pickup" => "ready_for_pickup"},
  "drop" => [],
  "history" => %{},
  "invocations" => [],
  "timers" => %{"keep_mapped" => true},
  "datamodel" => [%{"op" => "add", "key" => "transfer_branch", "value" => nil}]
}