Custom Snapshots in MoonBit

Golem agents can implement the Snapshottable trait to support manual (snapshot-based) updates and snapshot-based recovery.

When to Use Snapshotting

Snapshotting solves two distinct problems:

1. Manual / snapshot-based component updates — required when updating agents between incompatible component versions.
2. Fast recovery and oplog compaction — for long-running agents whose oplog grows over time (heartbeats, polling loops, recurring tasks, agents with frequent state changes). Without snapshotting, every recovery replays the full oplog from the beginning, which becomes increasingly expensive. With periodic snapshotting (every_n(N)), recovery starts from the latest snapshot and replays only the entries after it.

You cannot opt out of oplog writes for a durable agent. If you are worried about oplog volume or replay cost, do not try to skip persistence — enable snapshot-based recovery here instead.

Automatic JSON Snapshotting (Default)

When the agent struct derives ToJson and @json.FromJson, the SDK’s code generation automatically provides JSON-based snapshotting. Enable it via the snapshotting attribute on #derive.agent:

#derive.agent(snapshotting="every_n(1)")
struct Counter {
  name : String
  mut value : UInt64
} derive(ToJson, @json.FromJson)
 
fn Counter::new(name : String) -> Counter {
  { name, value: 0 }
}
 
pub fn Counter::increment(self : Self) -> Unit {
  self.value += 1
}
 
pub fn Counter::get_value(self : Self) -> UInt64 {
  self.value
}

The code generation tool detects both ToJson and @json.FromJson derives and generates JSON saving plus a restoration factory. Automatic loading is generated only when the complete agent type is JSON-deserializable.

Snapshotting Modes

The snapshotting attribute accepts these values:

An ephemeral agent takes no snapshots, whatever its snapshotting value. Snapshots are for durable agents only.

Custom Snapshotting

For custom binary serialization or cross-version migration, implement the saving-only Snapshottable trait and define a separate static restoration factory:

pub(open) trait Snapshottable {
  save_snapshot(Self) -> Bytes
}
 
pub fn Agent::load_snapshot(
  bytes : Bytes,
  context : @agents.SnapshotRestoreContext,
) -> Result[Agent, String]

Example

#derive.agent(snapshotting="every_n(1)")
struct Counter {
  name : String
  mut value : UInt64
}
 
fn Counter::new(name : String) -> Counter {
  { name, value: 0 }
}
 
pub fn Counter::increment(self : Self) -> Unit {
  self.value += 1
}
 
pub fn Counter::get_value(self : Self) -> UInt64 {
  self.value
}
 
///|
pub impl @agents.Snapshottable for Counter with save_snapshot(self) {
  // Serialize value as 8 big-endian bytes
  let arr : Array[Byte] = []
  for i = 7; i >= 0; i = i - 1 {
    arr.push(((self.value >> (i * 8)).to_int() & 0xff).to_byte())
  }
  Bytes::from_array(arr)
}
 
///|
pub fn Counter::load_snapshot(
  bytes : Bytes,
  context : @agents.SnapshotRestoreContext,
) -> Result[Counter, String] {
  if bytes.length() != 8 {
    return Err("Expected an 8-byte long snapshot")
  }
  let mut v : UInt64 = 0
  for i = 0; i < 8; i = i + 1 {
    v = v | (bytes[i].to_uint64() << ((7 - i) * 8))
  }
  let name : String = context.identity(0) catch {
    error => return Err(error.to_string())
  }
  Ok({ name, value: v })
}

Method Signatures

// Save: serialize the agent's current state to bytes
save_snapshot(Self) -> Bytes
 
// Load: static factory returning a complete agent from bytes and restore context
// Return Err to reject the snapshot
Agent::load_snapshot(Bytes, SnapshotRestoreContext) -> Result[Agent, String]

The restoration factory does not receive self and does not call Agent::new. Its context provides identity fields, the full agent ID, restored principal, and phantom ID. Fresh agent configuration remains available through the SDK’s config API.

Restoration Is Read-Only

load_snapshot is a specially supported SDK lifecycle operation, not an agent method. It must return the complete fresh agent value; the SDK installs that value only after the factory succeeds.

Snapshot loading runs in read-only mode and writes nothing to the oplog. Decoding, local computation, config reads, and other permitted reads can be used to construct the value. Mutating host operations and outgoing HTTP or agent RPC calls are rejected before they take effect.

If the factory returns Err, partial state is discarded. A manual update remains on the previous component version. During automatic recovery, Golem recreates the component without the failed automatic snapshot. It then tries the previous usable automatic snapshot. After that, it uses the authoritative baseline of the last successful update or a full replay. During an automatic update, the update fails, and the agent stays on its source revision: with UPDATE_SNAPSHOT_INCOMPATIBLE when the update selected an automatic snapshot, else with UPDATE_REPLAY_FAILED. Without a pending update, when the snapshot of the last successful update does not load, the start of the agent fails.

How the SDK Wires Snapshots

The code generation tool (golem_sdk_tools agents) produces a ConstructedAgent struct for each agent. When snapshotting is enabled:

1. If the agent has ToJson + @json.FromJson derives, generated code provides JSON saving and a restoration factory.
2. If the agent has a manual impl Snapshottable, the static Agent::load_snapshot factory is required and the custom binary implementation is used instead.
3. The ConstructedAgent records the snapshottable interface reference and snapshot_format (Json or Binary).
4. Registration keeps normal construction and snapshot restoration as distinct factories.
5. The SDK’s save-snapshot and load-snapshot WIT exports delegate to these operations.

Best Practices

1. Prefer automatic (JSON) snapshotting — derive ToJson and @json.FromJson on the agent struct for zero-effort persistence.
2. Keep snapshots small — large snapshots impact recovery and update time.
3. Version your snapshot format — include a version byte so load_snapshot can handle snapshots from older versions.
4. Test round-trips — verify that save_snapshot → load_snapshot produces equivalent state without calling new.
5. Handle migration — when the state schema changes between versions, load_snapshot in the new version should be able to parse snapshots from the old version.
6. Return Err to reject incompatible snapshots — load_snapshot returning Err causes the update to fail gracefully, reverting the agent to the old version.