Skip to content

Epic: named checkpoints & version branching #554

@ethe

Description

@ethe

Summary

Tonbo has full MVCC time travel via snapshot_at(timestamp), but users must track raw timestamps manually. This epic adds:

  1. Named checkpoints: Human-readable bookmarks for versions
  2. Version branching: Fork execution state for exploration and rollback

These features complete the "decision point" promise from the Tonbo manifesto, enabling agents and applications to checkpoint progress, explore alternatives, and backtrack when needed.

Motivation

Current State

// Today: raw timestamps only
let versions = db.list_versions(10).await?;
let snapshot = db.snapshot_at(versions[3].timestamp).await?;
// User must remember: "versions[3] was before the migration"

Pain Points

  • No semantic naming: Users track timestamps externally
  • No exploration: Can't fork state to try alternatives
  • No safe rollback: Can't easily revert to a known-good state
  • Agent workflows blocked: Agents need "save points" for backtracking

Desired State

// Named checkpoints
db.checkpoint("before-migration").await?;
db.checkpoint("episode-42-complete").await?;

// Query at checkpoint
let snapshot = db.snapshot_at_checkpoint("before-migration").await?;
let data = snapshot.scan(&db).collect().await?;

// Branch from checkpoint
let branch = db.branch_from("before-migration", "experimental").await?;
branch.ingest(experimental_data).await?;

// Compare branches
let diff = db.diff("main", "experimental").await?;

// Merge or discard
db.merge_branch("experimental").await?;  // or
db.delete_branch("experimental").await?;

Goals

  1. Named checkpoints: Tag any version with a human-readable name
  2. Checkpoint management: List, delete, and query checkpoints
  3. Branching: Fork state from any checkpoint for parallel exploration
  4. Branch operations: Query, merge, delete branches
  5. Diff: Compare state between checkpoints or branches
  6. Retention integration: Checkpoints protect versions from GC

Non-Goals

  • Cross-table checkpoints (each table independent)
  • Distributed branch coordination (single-writer model)
  • Automatic conflict resolution on merge (fail on conflict)
  • Nested branches (single level only for MVP)

Metadata

Metadata

Assignees

No one assigned

    Labels

    XL - Extra LargeSystem architecture overhaul, adding support for new platforms, large-scale dependency updates.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions