checkpoint.hpp
1#pragma once2#include "itch/book/book.hpp"3#include "itch/common/digest.hpp"4#include "itch/common/file_utils.hpp"5#include <cstddef>6#include <cstdint>7#include <iosfwd>8#include <string>910namespace itch {11/** Versioned offline replay state; CSV journal binding is optional. */12struct Checkpoint {13 Fingerprint input{};14 std::string target;15 uint64_t next_frame = 1;16 uint64_t offset = 0;17 uint64_t selected = 0;18 uint64_t hash = fnv1a_offset_basis;19 size_t depth = 5;20 bool with_offset = false;21 bool allow_implicit_eof = false;22 bool last_end_messages = false;23 BookState book;24 // Optional v2 binding to a durable, complete CSV prefix.25 std::string csv_path;26 uint64_t csv_bytes = 0;27};2829/** Encode canonical checkpoint bytes with a SHA-256 trailer (v1, or v2 with CSV binding). */30std::string encode_checkpoint(const Checkpoint& checkpoint);31/** Validate checksum, schema and book invariants; throws std::runtime_error on corruption. */32Checkpoint decode_checkpoint(const std::string& bytes);33/** Read and validate a checkpoint file; throws on open/read or validation failure. */34Checkpoint load_checkpoint(const std::string& path);35/** Publish a checkpoint atomically beside its destination, refusing to overwrite the input. */36void save_checkpoint(const Checkpoint& checkpoint, const std::string& path,37 const std::string& input);38/** Check that the saved offset/frame/end-marker state is a valid boundary of this input. */39void validate_boundary(const Checkpoint& checkpoint, const std::string& input);40/** Copy only the saved CSV prefix, verifying header, row count and historical FNV-1a digest.41 * Uncheckpointed tail bytes are ignored. A failure may already have written to output;42 * callers must use staged output to prevent publication of an invalid prefix.43 */44void copy_checkpoint_csv(const Checkpoint& checkpoint, std::ostream& output);45} // namespace itch