Cyclium.CheckpointSchema (Cyclium v0.1.11)

Copy Markdown View Source

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

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