Checkpoint system for graph execution state persistence and time-travel. More...

#include <neograph/api.h>
#include <neograph/graph/configuration_failure.h>
#include <neograph/graph/types.h>
#include <asio/awaitable.hpp>
#include <cstdint>
#include <memory>
#include <optional>
#include <mutex>
#include <map>
#include <set>
#include <vector>
#include <unordered_set>
#include <unordered_map>
#include <string_view>
#include <chrono>
#include <functional>

Include dependency graph for checkpoint.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	neograph::graph::AsyncCheckpointStore
	Canonical coroutine contract for a native async backend. More...

struct	neograph::graph::Checkpoint
	Serialized snapshot of graph execution state at a single super-step. More...

class	neograph::graph::CheckpointStore
	Abstract interface for checkpoint persistence backends. More...

class	neograph::graph::CheckpointStoreCore
	Mandatory synchronous operations for a sync-only backend. More...

class	neograph::graph::InMemoryCheckpointStore
	In-memory checkpoint store for testing and single-process use. More...

class	neograph::graph::ManagedBudgetDeadlineClockUnavailable
	A managed model-token budget with a deadline binds the deadline to the clock it counts on, so that a restart can tell whether it is still the same clock. More...

class	neograph::graph::ManagedBudgetEffectReceipt
	Actual write-ahead claim, bound to one original generation and owned actor. More...

class	neograph::graph::OwnedManagedBudgetLease
	Store-issued ownership; JSON or an archived observation cannot create it. More...

struct	neograph::graph::PendingWrite
	Successful node writes recorded within an in-progress super-step. More...

class	neograph::graph::PendingWritesCheckpointStore
	Optional fine-grained pending-writes capability. More...

class	neograph::graph::SynchronousCheckpointStoreUnavailable
	A checkpoint store that is not asynchronous (it implements CheckpointStoreCore, or a CheckpointStore operation without an async form) runs each operation on a pool of worker threads and resumes the run on its executor. More...

Enumerations
enum class	neograph::graph::CheckpointPhase { Before , After , Completed , NodeInterrupt , Updated }
	Phase at which a Checkpoint was produced. More...

Functions
NEOGRAPH_API std::shared_ptr< CheckpointStore >	neograph::graph::adapt_async_checkpoint_store (std::shared_ptr< AsyncCheckpointStore > backend)
	Explicit sync facade for an async-native backend.

NEOGRAPH_API std::shared_ptr< CheckpointStore >	neograph::graph::adapt_checkpoint_store (std::shared_ptr< CheckpointStoreCore > core)
	Adapt split checkpoint capabilities to the legacy engine contract.

NEOGRAPH_API std::uint64_t	neograph::graph::detail::blocking_checkpoint_hops () noexcept
	How many operations of a synchronous checkpoint store have been handed to the pool of worker threads so far.

NEOGRAPH_API json	neograph::graph::checkpoint_storage_metadata (const Checkpoint &checkpoint)
	Preserve the complete durable provider-state envelope without changing store schemas.

NEOGRAPH_API CheckpointPhase	neograph::graph::parse_checkpoint_phase (std::string_view s)
	Parse a phase string back to the enum.

NEOGRAPH_API asio::awaitable< void >	neograph::graph::detail::run_on_blocking_pool (std::function< void()> work)
	Runs `work` on a thread of the bounded pool that serves the synchronous checkpoint stores, and resumes the awaiting coroutine on its own executor (#556).

NEOGRAPH_API const char *	neograph::graph::to_string (CheckpointPhase phase)
	Canonical wire / log string for a CheckpointPhase.

Variables
constexpr std::uint32_t	neograph::graph::CHECKPOINT_SCHEMA_VERSION = 4
	Current Checkpoint layout version.

Detailed Description

Checkpoint system for graph execution state persistence and time-travel.

Provides the Checkpoint data structure and the CheckpointStore interface for saving and loading execution state snapshots. Used for HITL (Human-in-the-Loop) interrupt/resume, time-travel debugging, and thread forking.

Definition in file checkpoint.h.

Enumeration Type Documentation

◆ CheckpointPhase

enum class neograph::graph::CheckpointPhase

strong

Phase at which a Checkpoint was produced.

Drives resume semantics — Before means "re-enter before the target node runs", After / Completed means "routing has already happened, advance from the stored next_nodes", NodeInterrupt means "a node threw NodeInterrupt mid-execution", Updated means "user patched state out-of-band via update_state()".

Enumerator
Before	Saved just before an interrupt_before node fires.
After	Saved just after an interrupt_after node completed.
Completed	Saved at end of super-step (normal cadence).
NodeInterrupt	Saved when a node threw NodeInterrupt.
Updated	Saved by update_state() injecting state externally.

Definition at line 143 of file checkpoint.h.

Function Documentation

◆ adapt_async_checkpoint_store()

NEOGRAPH_API std::shared_ptr< CheckpointStore > neograph::graph::adapt_async_checkpoint_store ( std::shared_ptr< AsyncCheckpointStore > backend )

Explicit sync facade for an async-native backend.

The adapter retains the backend and forwards engine async operations without a blocking worker; synchronous administration drives them via run_sync. Pending-write storage is optional via PendingWritesCheckpointStore.

References neograph::graph::adapt_async_checkpoint_store().

Referenced by neograph::graph::adapt_async_checkpoint_store().

◆ adapt_checkpoint_store()

NEOGRAPH_API std::shared_ptr< CheckpointStore > neograph::graph::adapt_checkpoint_store ( std::shared_ptr< CheckpointStoreCore > core )

Adapt split checkpoint capabilities to the legacy engine contract.

The returned object keeps core alive. If the same implementation also derives from AsyncCheckpointStore or PendingWritesCheckpointStore, the adapter detects and delegates those optional capabilities. If it already implements CheckpointStore, the original shared object is returned. Without AsyncCheckpointStore, async calls run the synchronous core operation on the shared bounded blocking pool and resume on the caller's executor; I/O-bound backends should implement the async capability.

Exceptions

std::invalid_argument If core is null.

References neograph::graph::adapt_checkpoint_store().

Referenced by neograph::graph::adapt_checkpoint_store().

◆ blocking_checkpoint_hops()

NEOGRAPH_API std::uint64_t neograph::graph::detail::blocking_checkpoint_hops ( )

noexcept

How many operations of a synchronous checkpoint store have been handed to the pool of worker threads so far.

A diagnostic for tests: an operation that runs on the calling thread does not count.

References neograph::graph::detail::blocking_checkpoint_hops().

Referenced by neograph::graph::detail::blocking_checkpoint_hops().

◆ parse_checkpoint_phase()

NEOGRAPH_API CheckpointPhase neograph::graph::parse_checkpoint_phase ( std::string_view s )

Parse a phase string back to the enum.

Useful for deserializing checkpoints from persistent stores. Unknown strings throw std::invalid_argument — deliberate, because silent fallback would mask wire-format drift.

References neograph::graph::parse_checkpoint_phase().

Referenced by neograph::graph::parse_checkpoint_phase().

◆ run_on_blocking_pool()

NEOGRAPH_API asio::awaitable< void > neograph::graph::detail::run_on_blocking_pool ( std::function< void()> work )

Runs work on a thread of the bounded pool that serves the synchronous checkpoint stores, and resumes the awaiting coroutine on its own executor (#556).

Throws SynchronousCheckpointStoreUnavailable in a build without threads.

◆ to_string()

NEOGRAPH_API const char * neograph::graph::to_string ( CheckpointPhase phase )

Canonical wire / log string for a CheckpointPhase.

The returned value is the same as the legacy stringly-typed phase so persistent stores serializing with to_string() produce identical blobs to pre-enum NeoGraph.

Variable Documentation

◆ CHECKPOINT_SCHEMA_VERSION

constexpr std::uint32_t neograph::graph::CHECKPOINT_SCHEMA_VERSION = 4

constexpr

Current Checkpoint layout version.

Bump whenever the on-wire schema changes in a way that would break a naive load of an older blob.

Version log: 1 — first versioned format. next_nodes is vector<string> (previously a single next_node string; the string form is unversioned and predates this constant). 2 — added barrier_state: per-barrier accumulator of upstream signals received so far. v1 blobs deserialize with an empty map, which is safe — a barrier that had partial signals under v1 would have lost them anyway (the pre-v2 contract), so the v2 engine simply resumes with zero accumulated signals and waits for the full set again.

Definition at line 135 of file checkpoint.h.

Classes

Enumerations

Functions

Variables