Persistence and schema

Durable journals, canonical serialization, schemas, and migrations. More...

Namespaces
namespace	pulp::timeline::detail

Classes
struct	pulp::timeline::FileJournalError
	File-journal failure with the offending byte and nested JSON error. More...
struct	pulp::timeline::FileJournalLimits
	File size, record size, and nested decode ceilings. More...
struct	pulp::timeline::FileJournalOpenResult
	Result of opening or recovering a native Timeline journal. More...
class	pulp::timeline::FileJournal
	Native, crash-consistent Timeline persistence sink. More...
struct	pulp::timeline::JournalLimits
	In-memory command-journal quotas. More...
struct	pulp::timeline::JournalEntry
	One contiguous revision transition retained by the command journal. More...
class	pulp::timeline::JournalSink
	Synchronous durability boundary used by DocumentSession. More...
class	pulp::timeline::CommandJournal
	Bounded, replayable in-memory log of contiguous document revisions. More...
struct	pulp::timeline::PersistenceError
	Structured persistence failure. More...
struct	pulp::timeline::DecodeLimits
	Parser, migration, opaque-payload, and Timeline structure quotas. More...
struct	pulp::timeline::JsonValue
	Owning JSON DOM node with source byte bounds. More...
struct	pulp::timeline::JsonObjectMember
	Pair-like owning member of a JSON object. More...
class	pulp::timeline::ParsedJson
	Parsed JSON tree that owns the source bytes referenced by node offsets. More...
struct	pulp::timeline::StructuralPreflightSuccess
	Empty success value returned by structural preflight. More...
struct	pulp::timeline::SchemaWriteSuccess
	Empty success value returned by bounded schema writers. More...
class	pulp::timeline::BoundedJsonSink
	Append-only JSON output sink with an enforced byte ceiling. More...
struct	pulp::timeline::FieldSchema
	Public field metadata for one registered schema type. More...
struct	pulp::timeline::SchemaCodec
	Immutable callback bundle and shared context for a registered type. More...
struct	pulp::timeline::MigrationStep
	One adjacent version transition for a schema type. More...
struct	pulp::timeline::TypeSchema
	Complete registration contract for one domain-qualified schema type. More...
struct	pulp::timeline::SchemaError
	Schema-registration failure with the affected type and version. More...
struct	pulp::timeline::SchemaRegistration
	Empty success value returned after registering a schema. More...
class	pulp::timeline::SchemaRegistry
	Immutable, shareable registry of Timeline schema contracts. More...
class	pulp::timeline::SchemaRegistryBuilder
	Mutable, single-owner accumulator for constructing a SchemaRegistry. More...
struct	pulp::timeline::SchemaVersionTarget
	Target version for one schema identity in a release projection. More...
struct	pulp::timeline::SchemaReleaseMap
	Immutable set of schema-version targets identified by a release label. More...
struct	pulp::timeline::SerializeOptions
	Output quota for project serialization. More...
struct	pulp::timeline::SerializedSnapshot
	Canonical serialized project plus extension-preservation status. More...
struct	pulp::timeline::ProjectSnapshotCounts
	Structural item counts extracted from a serialized project. More...
struct	pulp::timeline::ProjectSnapshotSummary
	Allocation-light metadata view for project browsers and admission checks. More...

Typedefs
using	pulp::timeline::SchemaDecodeFn
	Decodes schema data into an immutable type-erased value.
using	pulp::timeline::SchemaEncodeFn
	Encodes a type-erased value into a quota-enforcing JSON sink.
using	pulp::timeline::SchemaRetainedSizeFn
	Estimates bytes retained by a decoded type-erased value.
using	pulp::timeline::SchemaMigrationFn
	Rewrites one exact schema envelope into a quota-enforcing sink.

Enumerations
enum class	pulp::timeline::FileJournalErrorCode : std::uint8_t {   pulp::timeline::FileJournalErrorCode::IoError , pulp::timeline::FileJournalErrorCode::InvalidFormat , pulp::timeline::FileJournalErrorCode::UnsupportedVersion , pulp::timeline::FileJournalErrorCode::CorruptRecord ,   pulp::timeline::FileJournalErrorCode::RevisionMismatch , pulp::timeline::FileJournalErrorCode::LimitExceeded , pulp::timeline::FileJournalErrorCode::PersistenceError , pulp::timeline::FileJournalErrorCode::AlreadyOpen ,   pulp::timeline::FileJournalErrorCode::AliasedPath , pulp::timeline::FileJournalErrorCode::DurabilityUncertain }
	File-journal open or recovery failure category. More...
enum class	pulp::timeline::JournalEntryKind : std::uint8_t { pulp::timeline::JournalEntryKind::Ordinary , pulp::timeline::JournalEntryKind::History }
	Distinguishes user submissions from generated undo/redo transactions. More...
enum class	pulp::timeline::JournalSinkError : std::uint8_t { pulp::timeline::JournalSinkError::Closed , pulp::timeline::JournalSinkError::IoError , pulp::timeline::JournalSinkError::InvalidState , pulp::timeline::JournalSinkError::DurabilityUncertain }
	Failure category returned by a durable JournalSink. More...
enum class	pulp::timeline::PersistenceErrorCode : std::uint8_t {   pulp::timeline::PersistenceErrorCode::InvalidJson , pulp::timeline::PersistenceErrorCode::InvalidUtf8 , pulp::timeline::PersistenceErrorCode::DuplicateKey , pulp::timeline::PersistenceErrorCode::LimitExceeded ,   pulp::timeline::PersistenceErrorCode::MissingField , pulp::timeline::PersistenceErrorCode::UnexpectedType , pulp::timeline::PersistenceErrorCode::InvalidNumber , pulp::timeline::PersistenceErrorCode::InvalidSchema ,   pulp::timeline::PersistenceErrorCode::UnsupportedStructuralType , pulp::timeline::PersistenceErrorCode::UnsupportedSchemaVersion , pulp::timeline::PersistenceErrorCode::MigrationPathMissing , pulp::timeline::PersistenceErrorCode::MigrationFailed ,   pulp::timeline::PersistenceErrorCode::ModelRejected , pulp::timeline::PersistenceErrorCode::OutputLimitExceeded }
	Stable category for a JSON, schema, quota, migration, or model rejection. More...
enum class	pulp::timeline::SchemaDomain : std::uint8_t {   pulp::timeline::SchemaDomain::Document , pulp::timeline::SchemaDomain::Content , pulp::timeline::SchemaDomain::AssetRepresentation , pulp::timeline::SchemaDomain::Command ,   pulp::timeline::SchemaDomain::Diagnostic }
	Namespace in which a schema type name is unique. More...
enum class	pulp::timeline::SchemaValueKind : std::uint8_t {   pulp::timeline::SchemaValueKind::Boolean , pulp::timeline::SchemaValueKind::U32 , pulp::timeline::SchemaValueKind::I64String , pulp::timeline::SchemaValueKind::U64String ,   pulp::timeline::SchemaValueKind::String , pulp::timeline::SchemaValueKind::Object , pulp::timeline::SchemaValueKind::Array }
	JSON representation declared for a registered field. More...
enum class	pulp::timeline::SchemaErrorCode : std::uint8_t {   pulp::timeline::SchemaErrorCode::InvalidIdentity , pulp::timeline::SchemaErrorCode::DuplicateType , pulp::timeline::SchemaErrorCode::DuplicateField , pulp::timeline::SchemaErrorCode::InvalidCodec ,   pulp::timeline::SchemaErrorCode::InvalidMigration , pulp::timeline::SchemaErrorCode::DuplicateMigration }
	Reason a TypeSchema cannot be registered. More...

Functions
std::size_t	pulp::timeline::retained_size (const JournalEntry &entry) noexcept
	Returns a saturated retained-memory estimate for one journal entry.
runtime::Result< std::string, PersistenceError >	pulp::timeline::emit_schema_manifest (const SchemaRegistry &registry, std::size_t maximum_bytes=8ull *1024ull *1024ull)
	Emits a deterministic JSON-Schema projection of a SchemaRegistry.
runtime::Result< std::shared_ptr< const ParsedJson >, PersistenceError >	pulp::timeline::parse_json (std::string_view json, const DecodeLimits &limits={})
	Parses one complete UTF-8 JSON value into an owning immutable document.
runtime::Result< const JsonValue *, PersistenceError >	pulp::timeline::validate_exact_envelope (const JsonValue &value, std::string_view expected_type, std::uint32_t expected_version, std::string path={}, PersistenceErrorCode failure_code=PersistenceErrorCode::InvalidSchema)
	Validates an exact extension or migration envelope.
runtime::Result< StructuralPreflightSuccess, PersistenceError >	pulp::timeline::preflight_timeline_structure (std::string_view json, const DecodeLimits &limits)
	Performs an allocation-light, schema-aware Timeline quota scan.
runtime::Result< std::string, PersistenceError >	pulp::timeline::canonicalize_json (const JsonValue &value)
	Serializes a DOM value as deterministic JSON with sorted object keys.
std::string	pulp::timeline::quote_json_string (std::string_view value)
	Quotes and escapes a byte sequence as a JSON string token.
runtime::Result< std::uint64_t, PersistenceError >	pulp::timeline::parse_canonical_u64_string (const JsonValue &value, std::string path={})
	Parses a canonical decimal unsigned integer stored as a JSON string.
runtime::Result< std::int64_t, PersistenceError >	pulp::timeline::parse_canonical_i64_string (const JsonValue &value, std::string path={})
	Parses a canonical decimal signed integer stored as a JSON string.
runtime::Result< std::uint32_t, PersistenceError >	pulp::timeline::parse_u32_number (const JsonValue &value, std::string path={})
	Parses an integral JSON number representable as uint32_t.
runtime::Result< SchemaRegistration, SchemaError >	pulp::timeline::register_builtin_timeline_schemas (SchemaRegistryBuilder &builder)
	Registers the built-in document, content, command, and diagnostic schemas.
runtime::Result< SchemaRegistry, SchemaError >	pulp::timeline::make_builtin_timeline_registry ()
	Constructs a registry containing exactly the built-in Timeline schemas.
std::span< const SchemaReleaseMap >	pulp::timeline::builtin_timeline_schema_releases () noexcept
	Returns every built-in release projection in stable static storage.
const SchemaReleaseMap *	pulp::timeline::find_builtin_timeline_schema_release (std::string_view release_label) noexcept
	Finds a built-in release projection by exact label.
runtime::Result< SerializedSnapshot, PersistenceError >	pulp::timeline::serialize_project (const Project &project, const SchemaRegistry &registry, const SerializeOptions &options={})
	Serializes a model-valid project as canonical UTF-8 JSON.
runtime::Result< SerializedSnapshot, PersistenceError >	pulp::timeline::serialize_project_for_release (const Project &project, const SchemaRegistry &registry, const SchemaReleaseMap &release, const SerializeOptions &options={})
	Serializes a project using the schema versions pinned by a release map.
runtime::Result< ProjectSnapshotSummary, PersistenceError >	pulp::timeline::peek_project_summary (std::string_view json, const SchemaRegistry &registry, const DecodeLimits &limits={})
	Scans project metadata and structural counts without constructing Project.
runtime::Result< Project, PersistenceError >	pulp::timeline::deserialize_project (std::string_view json, const SchemaRegistry &registry, const DecodeLimits &limits={})
	Decodes canonical Timeline JSON into a validated Project.
runtime::Result< std::vector< Command >, PersistenceError >	pulp::timeline::deserialize_commands (std::string_view json, const SchemaRegistry &registry, const DecodeLimits &limits={})
	Decodes a JSON command array through the supplied schema registry.

Variables
constexpr std::uint32_t	pulp::timeline::schema_manifest_version = 1
	Manifest-shape version consumed by Timeline surface generators.

Detailed Description

Durable journals, canonical serialization, schemas, and migrations.

Typedef Documentation

SchemaDecodeFn

using pulp::timeline::SchemaDecodeFn

Initial value:

 runtime::Result<std::shared_ptr<const void>, PersistenceError> (*)(
    const JsonValue& data, const void* context) noexcept

Decodes schema data into an immutable type-erased value.

The returned shared object owns its value independently of the parsed JSON.

SchemaEncodeFn

using pulp::timeline::SchemaEncodeFn

Initial value:

 runtime::Result<SchemaWriteSuccess, PersistenceError> (*)(
    const std::shared_ptr<const void>& value, BoundedJsonSink& output,
    const void* context) noexcept

Encodes a type-erased value into a quota-enforcing JSON sink.

SchemaMigrationFn

using pulp::timeline::SchemaMigrationFn

Initial value:

 runtime::Result<SchemaWriteSuccess, PersistenceError> (*)(
    std::string_view source_envelope, BoundedJsonSink& output, const void* context) noexcept

Rewrites one exact schema envelope into a quota-enforcing sink.

SchemaRetainedSizeFn

using pulp::timeline::SchemaRetainedSizeFn

Initial value:

 std::size_t (*)(const std::shared_ptr<const void>& value,
                                             const void* context) noexcept

Estimates bytes retained by a decoded type-erased value.

Enumeration Type Documentation

FileJournalErrorCode

enum class pulp::timeline::FileJournalErrorCode : std::uint8_t

strong

File-journal open or recovery failure category.

Enumerator
IoError
InvalidFormat
UnsupportedVersion
CorruptRecord
RevisionMismatch
LimitExceeded
PersistenceError
AlreadyOpen
AliasedPath
DurabilityUncertain

JournalEntryKind

enum class pulp::timeline::JournalEntryKind : std::uint8_t

strong

Distinguishes user submissions from generated undo/redo transactions.

Enumerator
Ordinary
History

JournalSinkError

enum class pulp::timeline::JournalSinkError : std::uint8_t

strong

Failure category returned by a durable JournalSink.

Enumerator
Closed
IoError
InvalidState
DurabilityUncertain

PersistenceErrorCode

enum class pulp::timeline::PersistenceErrorCode : std::uint8_t

strong

Stable category for a JSON, schema, quota, migration, or model rejection.

Enumerator
InvalidJson	JSON syntax or document shape is invalid.
InvalidUtf8	A required string is not valid UTF-8.
DuplicateKey	An object repeats a member name.
LimitExceeded	An input, structure, or migration quota was exceeded.
MissingField	A required schema field is absent.
UnexpectedType	A JSON value has the wrong kind.
InvalidNumber	A numeric value is malformed or out of range.
InvalidSchema	A schema identity, envelope, or codec contract is invalid.
UnsupportedStructuralType	Structural preflight encountered an unknown typed envelope.
UnsupportedSchemaVersion	No supported decoder version accepts the envelope.
MigrationPathMissing	Registered migrations do not connect source to target.
MigrationFailed	A migration returned or produced invalid output.
ModelRejected	The decoded value violates a Timeline model invariant.
OutputLimitExceeded	Generated JSON exceeded its output ceiling.

SchemaDomain

enum class pulp::timeline::SchemaDomain : std::uint8_t

strong

Namespace in which a schema type name is unique.

Enumerator
Document
Content
AssetRepresentation
Command
Diagnostic

SchemaErrorCode

enum class pulp::timeline::SchemaErrorCode : std::uint8_t

strong

Reason a TypeSchema cannot be registered.

Enumerator
InvalidIdentity
DuplicateType
DuplicateField
InvalidCodec
InvalidMigration
DuplicateMigration

SchemaValueKind

enum class pulp::timeline::SchemaValueKind : std::uint8_t

strong

JSON representation declared for a registered field.

Enumerator
Boolean
U32
I64String
U64String
String
Object
Array

Function Documentation

builtin_timeline_schema_releases()

std::span< const SchemaReleaseMap > pulp::timeline::builtin_timeline_schema_releases ( )

noexcept

Returns every built-in release projection in stable static storage.

canonicalize_json()

runtime::Result< std::string, PersistenceError > pulp::timeline::canonicalize_json

(

const JsonValue &

value

)

Serializes a DOM value as deterministic JSON with sorted object keys.

Strings are escaped as needed and numbers must already use an accepted JSON lexical form.

Parameters

value

Complete DOM subtree.

Returns

Canonical JSON or InvalidJson for an invalid DOM value.

deserialize_commands()

runtime::Result< std::vector< Command >, PersistenceError > pulp::timeline::deserialize_commands	(	std::string_view	json,
		const SchemaRegistry &	registry,
		const DecodeLimits &	limits = {} )

Decodes a JSON command array through the supplied schema registry.

The complete array and all nested values are subject to DecodeLimits.

Parameters

json	Complete command-envelope array JSON, borrowed for the call.
registry	Command schema contracts and migrations.
limits	Parser, migration, and value quotas.

Returns

Ordered commands or a structured persistence error.

deserialize_project()

runtime::Result< Project, PersistenceError > pulp::timeline::deserialize_project	(	std::string_view	json,
		const SchemaRegistry &	registry,
		const DecodeLimits &	limits = {} )

Decodes canonical Timeline JSON into a validated Project.

The input is copied as needed and need not outlive the call. Parsing, migrations, structural quotas, registered content, and model invariants are validated before a Project is returned.

Parameters

json	Complete project JSON, borrowed for the call.
registry	Structural and extension schema contracts.
limits	Parser, migration, opaque-content, and structural quotas.

Returns

A validated immutable Project or a structured persistence error.

emit_schema_manifest()

runtime::Result< std::string, PersistenceError > pulp::timeline::emit_schema_manifest	(	const SchemaRegistry &	registry,
		std::size_t	maximum_bytes = 8ull *1024ull *1024ull )

Emits a deterministic JSON-Schema projection of a SchemaRegistry.

Every TypeSchema becomes a $defs entry containing its domain, current version, fields, required set, and migration edges. The result is canonical JSON, so equivalent registries produce byte-identical output independent of registration order.

This manifest is the authoritative input for the Timeline JavaScript, TypeScript, MCP, and CLI projections; those surfaces derive from the schema contract instead of maintaining independent type descriptions.

Parameters

registry	Immutable source registry.
maximum_bytes	Hard ceiling for the generated document.

Returns

The canonical manifest, or OutputLimitExceeded when the projection cannot fit within maximum_bytes.

find_builtin_timeline_schema_release()

const SchemaReleaseMap * pulp::timeline::find_builtin_timeline_schema_release ( std::string_view release_label )

noexcept

Finds a built-in release projection by exact label.

Returns

A pointer with static lifetime, or nullptr when the label is unknown.

make_builtin_timeline_registry()

runtime::Result< SchemaRegistry, SchemaError > pulp::timeline::make_builtin_timeline_registry

(

)

Constructs a registry containing exactly the built-in Timeline schemas.

parse_canonical_i64_string()

runtime::Result< std::int64_t, PersistenceError > pulp::timeline::parse_canonical_i64_string	(	const JsonValue &	value,
		std::string	path = {} )

Parses a canonical decimal signed integer stored as a JSON string.

Redundant leading zeroes, a leading plus, negative zero, non-digits, and overflow are rejected.

Parameters

value	JSON string node to parse.
path	Diagnostic path for a rejection.

Returns

The parsed integer or a typed numeric error.

parse_canonical_u64_string()

runtime::Result< std::uint64_t, PersistenceError > pulp::timeline::parse_canonical_u64_string	(	const JsonValue &	value,
		std::string	path = {} )

Parses a canonical decimal unsigned integer stored as a JSON string.

Leading zeroes, signs, non-digits, and overflow are rejected.

Parameters

value	JSON string node to parse.
path	Diagnostic path for a rejection.

Returns

The parsed integer or a typed numeric error.

parse_json()

runtime::Result< std::shared_ptr< const ParsedJson >, PersistenceError > pulp::timeline::parse_json	(	std::string_view	json,
		const DecodeLimits &	limits = {} )

Parses one complete UTF-8 JSON value into an owning immutable document.

Duplicate object keys are rejected. Input bytes are copied, and all parser depth, value, container, and string ceilings are enforced before success.

Parameters

json	Complete JSON text, borrowed for the call.
limits	Parser resource ceilings.

Returns

An owning immutable parse tree or a structured parse error.

parse_u32_number()

runtime::Result< std::uint32_t, PersistenceError > pulp::timeline::parse_u32_number	(	const JsonValue &	value,
		std::string	path = {} )

Parses an integral JSON number representable as uint32_t.

Fractions, exponents, signs, noncanonical leading zeroes, and overflow are rejected.

Parameters

value	JSON number node to parse.
path	Diagnostic path for a rejection.

Returns

The parsed integer or a typed numeric error.

peek_project_summary()

runtime::Result< ProjectSnapshotSummary, PersistenceError > pulp::timeline::peek_project_summary	(	std::string_view	json,
		const SchemaRegistry &	registry,
		const DecodeLimits &	limits = {} )

Scans project metadata and structural counts without constructing Project.

The input is borrowed only for the call. Structural quotas, exact envelopes, schema versions, UTF-8, and numeric forms are validated; cross-item model references are not resolved.

Parameters

json	Complete project JSON, borrowed for the call.
registry	Structural schema contracts and migrations.
limits	Parser, migration, and structural quotas.

Returns

Validated metadata and counts, or a structured persistence error.

preflight_timeline_structure()

runtime::Result< StructuralPreflightSuccess, PersistenceError > pulp::timeline::preflight_timeline_structure	(	std::string_view	json,
		const DecodeLimits &	limits )

Performs an allocation-light, schema-aware Timeline quota scan.

Only arrays reached through supported structural envelopes contribute to the named Timeline item ceilings. This pass does not replace full JSON parsing or model validation.

Parameters

json	Complete Timeline JSON, borrowed for the call.
limits	Input and Timeline structure ceilings.

Returns

Success or the first syntax, structure, or quota failure.

quote_json_string()

std::string pulp::timeline::quote_json_string

(

std::string_view

value

)

Quotes and escapes a byte sequence as a JSON string token.

The function escapes JSON syntax and control bytes but does not validate Unicode. Callers producing a JSON document must validate UTF-8 first.

Parameters

value

Unquoted bytes to escape.

Returns

A quoted JSON string token.

register_builtin_timeline_schemas()

runtime::Result< SchemaRegistration, SchemaError > pulp::timeline::register_builtin_timeline_schemas

(

SchemaRegistryBuilder &

builder

)

Registers the built-in document, content, command, and diagnostic schemas.

Registration stops at and returns the first builder error.

retained_size()

std::size_t pulp::timeline::retained_size ( const JournalEntry & entry )

noexcept

Returns a saturated retained-memory estimate for one journal entry.

serialize_project()

runtime::Result< SerializedSnapshot, PersistenceError > pulp::timeline::serialize_project	(	const Project &	project,
		const SchemaRegistry &	registry,
		const SerializeOptions &	options = {} )

Serializes a model-valid project as canonical UTF-8 JSON.

Registered codecs are resolved through registry. Output is deterministic and bounded by options.max_output_bytes.

Parameters

project	Immutable source project.
registry	Schema contracts and extension codecs used by the project.
options	Output quota.

Returns

Canonical JSON, or a path-bearing error for invalid UTF-8, registry incompatibility, codec failure, or output quota exhaustion.

serialize_project_for_release()

runtime::Result< SerializedSnapshot, PersistenceError > pulp::timeline::serialize_project_for_release	(	const Project &	project,
		const SchemaRegistry &	registry,
		const SchemaReleaseMap &	release,
		const SerializeOptions &	options = {} )

Serializes a project using the schema versions pinned by a release map.

The current canonical snapshot is rewritten through registered downgrade migrations. The release map must cover compatible registered structural types; unsupported content or missing migration paths fail closed.

Parameters

project	Immutable source project.
registry	Schema contracts and migrations.
release	Target versions for the release projection.
options	Output quota applied to current and rewritten documents.

Returns

Canonical release JSON or a structured persistence error.

validate_exact_envelope()

runtime::Result< const JsonValue *, PersistenceError > pulp::timeline::validate_exact_envelope	(	const JsonValue &	value,
		std::string_view	expected_type,
		std::uint32_t	expected_version,
		std::string	path = {},
		PersistenceErrorCode	failure_code = PersistenceErrorCode::InvalidSchema )

Validates an exact extension or migration envelope.

value must contain only data, type_name, and version; data must be an object, and identity fields must equal the expected values.

Parameters

value	Candidate envelope.
expected_type	Required type_name value.
expected_version	Required version value.
path	Diagnostic path for the envelope.
failure_code	Error category returned for envelope mismatch.

Returns

A pointer to data owned by value, or failure_code at path.

Variable Documentation

schema_manifest_version

std::uint32_t pulp::timeline::schema_manifest_version = 1

inlineconstexpr

Manifest-shape version consumed by Timeline surface generators.