Jidoka.Snapshot (Jidoka v0.9.0)

@type t() :: %Jidoka.Snapshot{
  agent_id: binary(),
  cursor: term(),
  metadata: map(),
  schema_version: integer(),
  snapshot_id: binary(),
  turn_state: term()
}

Functions

deserialize(input)

@spec deserialize(String.t()) :: {:ok, t()} | {:error, term()}

Restores a snapshot produced by serialize/1.

fork(snapshot, opts)

@spec fork(
  t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Copies a hibernation snapshot for a new session fork.

The copied snapshot keeps the exact turn state and effect journal. It gets a new snapshot id and records the source in metadata. Only resumable phase boundaries can be forked.

forkable_phases()

@spec forkable_phases() :: [atom()]

Returns the phase boundaries that support safe session forks.

from_input(snapshot)

@spec from_input(t() | String.t()) :: {:ok, t()} | {:error, term()}

Normalizes a snapshot struct or authenticated serialized snapshot.

from_turn_state(state, cursor, opts \\ [])

@spec from_turn_state(Jidoka.Turn.State.t(), Jidoka.Turn.Cursor.t(), keyword()) ::
  {:ok, t()} | {:error, term()}

Builds a phase-boundary snapshot from the current turn state.

from_turn_state!(state, cursor, opts \\ [])

@spec from_turn_state!(Jidoka.Turn.State.t(), Jidoka.Turn.Cursor.t(), keyword()) ::
  t()

Builds a phase-boundary snapshot and raises on invalid data.

new(attrs)

@spec new(keyword() | map()) :: {:ok, t()} | {:error, term()}

Builds a durable agent snapshot from keyword or map attributes.

new!(attrs)

@spec new!(keyword() | map()) :: t()

Builds an agent snapshot and raises if the attributes are invalid.

schema()

@spec schema() :: Zoi.schema()

Returns the Zoi schema for a durable agent snapshot.

schema_version()

@spec schema_version() :: pos_integer()

Returns the current snapshot schema version.

serialize(snapshot_input)

@spec serialize(t()) :: {:ok, String.t()} | {:error, term()}

Serializes a snapshot into an opaque durable string.

The format is intentionally internal to Jidoka. It preserves Elixir data fidelity across hibernate/resume while the schema version remains the public compatibility boundary.

serialize!(snapshot_input)

@spec serialize!(t()) :: String.t()

Serializes and signs a snapshot, or raises if serialization fails.