Macro for defining versioned checkpoint schemas with migration support.

Checkpoint schemas declare the current version and provide migrate/2 callbacks that transform state from older versions to the current one.

Usage

defmodule MyApp.Checkpoints.POInvestigation do
  use Cyclium.CheckpointSchema, version: 2

  def migrate(1, state) do
    contacts = (state["vendor_contacts"] || [])
               |> Enum.group_by(& &1["vendor_id"])
    {:ok, Map.put(state, "vendor_contacts", contacts)}
  end

  def migrate(2, state), do: {:ok, state}
  def migrate(_v, _state), do: {:error, :unsupported_version}
end

Registration

Declare the schema on the expectation (preferred — keeps it next to the strategy whose state it versions):

expectation(:investigate_po,
  strategy: MyApp.Strategies.POInvestigation,
  checkpoint_schema: MyApp.Checkpoints.POInvestigation,
  ...
)

Or register in app config, which takes precedence over the expectation declaration (useful as a deploy-time override):

config :cyclium, :checkpoint_schemas, %{
  {"my_actor", "investigate_po"} => MyApp.Checkpoints.POInvestigation
}

Guidelines

• Store IDs and refs, not full payloads
• Keep state flat — avoid deeply nested structures
• No raw tool responses in checkpoints
• Normalize early before checkpointing