Chronicler

Deterministic state transfer for .NET runtimes that own their objects and their schemas.

Chronicler lets a type declare its state once, then use that same explicit schema for JSON, MemoryPack, restore workflows, stable runtime links, and deterministic record hashes. Your host constructs the object graph; Chronicler transfers state into it without taking ownership of your runtime.

Why Chronicler?

• Schemas stay in your code. RecordData(...) makes names, defaults, order, and ownership visible and reviewable.
• Restore into live objects. Populate initialized runtime shells instead of asking a serializer to invent your graph.
• Keep references stable. Record external or runtime-owned objects by IDs through a session-scoped registry.
• Compare deterministic state. Compute replay and conformance signals from the recording schema without hashing a transport payload.
• Choose your dependency surface. Use JSON and MemoryPack together, or take the Lean package when the built-in MemoryPack transport is unnecessary.

Install

dotnet add package Chronicler.Core

Chronicler.Core targets netstandard2.1 and net8.0 and includes the JSON and MemoryPack transports.

Quick start

using Chronicler;

public sealed class PlayerSnapshot : IRecordable
{
    public int Health = 100;
    public WeaponSnapshot Weapon = new();

    public void RecordData(IChronicler chronicler)
    {
        RecordValues.Look(chronicler, ref Health, "health", 100);
        RecordDeep.Look(chronicler, ref Weapon, "weapon");
    }
}

public sealed class WeaponSnapshot : IRecordable
{
    public int Ammo = 30;

    public void RecordData(IChronicler chronicler)
    {
        RecordValues.Look(chronicler, ref Ammo, "ammo", 30);
    }
}

PlayerSnapshot source = new() { Health = 72 };
string json = JsonRecordSerializer.Serialize(source, writeIndented: true);

PlayerSnapshot restored = new(); // The host creates and initializes the shell.
JsonRecordSerializer.Populate(restored, json);

The same RecordData(...) implementation works with MemoryPackRecordSerializer in the standard package.

Choose a package

Package	Use it when
Chronicler.Core	You want the core recording model plus built-in JSON and MemoryPack transports.
Chronicler.Core.Lean	You want the core recording model and JSON without the MemoryPack dependency or built-in MemoryPack transport.
Chronicler.MemoryPackShim	A Lean library keeps MemoryPack annotations in its public metadata. This package supplies compatibility attributes; it is not a serializer.

Learn more

• Getting started
• Understand values, owned state, and links
• Use deterministic record hashes
• Browse the API reference
• View test coverage

Development

dotnet build Chronicler.slnx --configuration Release
dotnet test tests/Chronicler.Tests/Chronicler.Tests.csproj --configuration Release --no-build

See the contributor guide for the full workflow.

Community and license

Open an issue for bugs and feature requests, or join the LSF Discord community.

Chronicler is available under the MIT License. See the notice for the repository's branding and redistribution terms.