Reference

For the guided path, read getting started first. This page is for looking things up.

It has two halves. Part one is what an application recording and reading changes touches — the data model, the kit, Recorder, Service, verification, errors, the shipped adapters, and the HTTP layer. Part two is the contract a storage backend must satisfy: the Log port, the optional capabilities, and the conformance suite that decides whether you got it right. If you are using one of the shipped adapters, part two is not for you.

Conventions. Must and never describe guarantees the library upholds and a caller may rely on; may describes something optional. “The suite” means core/conformance, which is the executable form of the Log contract in part two — a backend that passes it satisfies this page.

Stability. v0, experimental. Modules are versioned independently (core/vX.Y.Z, adapters/sql/vX.Y.Z, …) and the API may change before v1. The Log port plus the conformance suite is the most stable surface; capability interfaces and adapters are the least.

Naming. The core module’s package is changelog. Kit packages are chroniclekit, chronicleschema, chroniclediff, chronicleview, chronicleexplain; adapters are changelogmemory, changelogsql, changelogclickhouse.

Part one — what a caller uses

Everything in this half is what an application recording and reading changes touches. If you are picking a backend off the shelf, you never need part two.

Data model

Change

One recorded edit — a line in a commit’s diff.

type Change struct {
    At    time.Time `json:"at"`
    Actor string    `json:"actor"`
    Path  string    `json:"path"`
    Kind  string    `json:"kind"`
    From  string    `json:"from,omitempty"`
    To    string    `json:"to,omitempty"`
}

Commit

An immutable, content-addressed bundle of changes chained to its parent.

type Commit struct {
    ID      string    `json:"id"`
    Parent  string    `json:"parent"`
    At      time.Time `json:"at"`
    Authors []string  `json:"authors"`
    Message string    `json:"message,omitempty"`
    Changes []Change  `json:"changes"`
}

What content-addressing does and does not give you. Equal (Parent, Message, Changes) always yields an equal ID. It does not give you exactly-once: each Change carries its own At, stamped at staging time and covered by the hash, so re-staging the same logical edit later produces a different id. Use idempotency keys for delivery deduplication.

DocCommit and Snapshot

type DocCommit struct { DocID string; Commit Commit }        // cross-document results self-identify
type Snapshot struct  { DocID, CommitID string; State []byte } // opaque to core

core never interprets Snapshot.State; the layer that wrote it does (the kit writes JSON document state).

The kit

chroniclekit is the facade; chronicleschema owns the shared document model; chroniclediff, chronicleview, and chronicleexplain are the three sides of the flow. Each imports chronicleschema and nothing else of the kit’s, so any one can be used without the others. The whole flow is walked through on the kit, end to end.

Kit

func New(log changelog.Log) *Kit
func NewWithService(svc changelog.Service) *Kit

func (k *Kit) RecordUpdate(ctx, docID string, before, after any, opts ...RecordOption) (changelog.Commit, error)
func (k *Kit) RecordChanges(ctx, docID string, changes []changelog.Change, opts ...RecordOption) (changelog.Commit, error)
func (k *Kit) RecordPatch(ctx, docID string, ops []Operation, opts ...RecordOption) (changelog.Commit, error)
func (k *Kit) State(ctx, docID string) (map[string]any, error)
func (k *Kit) StateAt(ctx, docID, commitID string) (map[string]any, error)
func (k *Kit) CommitSnapshot(ctx, docID, commitID string) (any, error)
func (k *Kit) Service() changelog.Service

func WithMessage(m string) RecordOption
func WithActor(actor string) RecordOption
func WithIdempotencyKey(key string) RecordOption
func WithDiffOptions(opts ...chronicleschema.Option) RecordOption

Either constructor detects the backend’s Snapshotter and TailReader once, through the Service’s Unwrap() chain. A Service exposing no Unwrap gets full-replay reads.

chroniclediff.Diff

func Diff(before, after any, opts ...chronicleschema.Option) ([]changelog.Change, error)

Array pairing walks a chain, per array, stopping at the first hop that holds:

Scalar and mixed arrays always reach hop 3, so a mid-array insertion reads as a run of puts plus a tail create. Two consequences are contract, not incidental:

chronicleview

func Reconstruct(commits []changelog.Commit) (map[string]any, error)
func New(svc changelog.Service) *Reader

chronicleexplain.Explain

func Explain(commits []changelog.Commit, opts ...chronicleschema.Option) ([][]Explained, error)

chronicleschema options

One vocabulary, two consumers. Which side an option affects is the thing to get right:

Write-side options are load-bearing at record time and cannot be changed retroactively. Read-side options are free to change at any time and re-render all history.

JSON Patch interop

func FromChanges(cs []changelog.Change) []Operation  // changes → RFC 6902 patch
func ToChanges(ops []Operation) []changelog.Change   // RFC 6902 patch → changes

To seal a patch use RecordPatch, not RecordChanges(ToChanges(ops)) — it recovers From, re-pairs arrays by declared identity, and rejects the ops ToChanges skips. Both are pure functions of their argument, which is why neither can fill From; sealing patches is the full path.

Recorder

The staging area plus git commit, bound to one document. Safe for concurrent use.

func NewRecorder(docID string, log Log) *Recorder
func (r *Recorder) WithClock(now func() time.Time) *Recorder
func (r *Recorder) Append(c Change)
func (r *Recorder) Pending() []Change
func (r *Recorder) Commit(ctx context.Context, opts ...CommitOption) (Commit, error)

func WithMessage(s string) CommitOption

When to assert: pass WithParent (or Seal’s WithSealParent, which forwards to it) whenever the writer knows which snapshot it built against — typically the head a state read returned; the kit’s RecordPatch does this automatically via StateWithHead. Omitting it chains onto whatever Head is current at commit time, which is only honest for blind appends that never read state at all.

Service

The in-process facade. No transport, no net/http dependency.

func NewService(log Log) Service

type Service interface {
    Seal(ctx context.Context, docID string, changes []Change, message string, opts ...SealOption) (Commit, error)
    Commits(ctx context.Context, docID string, limit int) ([]Commit, error)
    AllCommits(ctx context.Context, limit int) ([]DocCommit, error)
    Get(ctx context.Context, commitID string) (dc DocCommit, ok bool, err error)
}

func WithIdempotencyKey(key string) SealOption

NewService detects the backend’s Indexer and Deduper once, at construction, following any Unwrap() Log chain. Construct it once and reuse it.

Seal runs these steps in order:

Two asymmetries with Recorder: Seal takes message as a positional argument rather than an option, and reports an empty batch as ErrEmptyChanges where Recorder.Commit reports ErrNothingToCommit.

Verification

func Verify(ctx context.Context, log Log, docID string) error
func VerifyAfter(ctx context.Context, log Log, docID, anchorID string) (head string, err error)

The anchor trust contract. Because Parent is inside every hash, a verified anchor transitively attests everything behind it. The flip side: tampering at or before the anchor is invisible to VerifyAfter. Run the full Verify when the anchor’s own provenance is in doubt.

Errors wrap the offending commit’s position and id — match with errors.Is. What “tamper-free” means precisely, and the two []Commit forms these are built on, are in part two.

Errors

Adapters

changelogmemory.New() *Log
changelogsql.Open(ctx, dsn string, opts ...Option) (*Log, error)
changelogsql.New(db *sql.DB, opts ...Option) *Log
changelogclickhouse.Open(ctx, dsn string, opts ...Option) (*Log, error)
changelogclickhouse.New(db *sql.DB) *Log

kit/httpapi

Optional. The core ships no HTTP; this is one worked transport over a Service, and you can equally write your own.

func Handler(svc changelog.Service) http.Handler

POST /commits takes one of three write shapes, tried in this order — the first one present wins, so a body naming two is not an error:

Schema over the wire. Each side carries the half of the vocabulary that survives JSON. Both skip empty fields, since name_fields and identity_fields replace rather than merge and an empty list would wipe the default.

Two properties of POST /explain are contract:

The handler ships no authentication, authorization, rate limiting, or per-caller quotas. Mount it behind your own middleware, and validate changes from untrusted producers yourself.

Part two — what a backend implements

This half is the contract a storage backend must satisfy. Skip it unless you are writing a Log — the three shipped adapters already satisfy all of it, and getting started never mentions any of it.

The Log port

The mandatory storage contract. Three methods, no more.

type Log interface {
    AppendCommit(ctx context.Context, docID string, c Commit) error
    Commits(ctx context.Context, docID string, limit int) ([]Commit, error)
    Head(ctx context.Context, docID string) (string, error)
}

Beyond the per-method table, every implementation must:

The port is deliberately per-document. Cross-document reads, dedup, cursors, and snapshots are all optional capabilities below — none is required for a backend to be correct.

Optional capabilities

A backend may implement any of these. The Service and the kit’s reader detect them with a type assertion, walking any Unwrap() chain. A backend that implements none is still correct — it simply loses the corresponding feature, and the layers above keep no fallback of their own.

type Indexer interface {
    AllCommits(ctx context.Context, limit int) ([]DocCommit, error)
    FindByID(ctx context.Context, commitID string) (dc DocCommit, ok bool, err error)
}
type Deduper interface {
    Seen(ctx context.Context, docID, key string) (c Commit, ok bool, err error)
    MarkSeen(ctx context.Context, docID, key string, c Commit) error
}
type TailReader interface {
    CommitsAfter(ctx context.Context, docID, afterID string, limit int) ([]Commit, error)
}
type Snapshotter interface {
    SaveSnapshot(ctx context.Context, s Snapshot) error
    LoadSnapshot(ctx context.Context, docID string) (s Snapshot, ok bool, err error)
}

All three shipped adapters implement all four: adapters/sql and adapters/clickhouse durably across a restart, adapters/memory in process only.

Chain verification on fetched commits

The two forms that take commits you already hold, rather than a Log. An adapter’s tests use them; Verify and VerifyAfter are built on them.

func VerifyChain(commits []Commit) error
func VerifyCommits(commits []Commit) error

VerifyCommits never checks that a parent exists — a fork’s parent legitimately lies outside the batch it was given, so that is an ancestry question only VerifyChain (over the full history) can answer.

“Tamper-free” means all three hold — forks and multiple roots are legal ancestry, not violations:

Conformance

The executable half of this page. A backend is correct when it passes the mandatory suite.

type NewLog func(t *testing.T) (changelog.Log, func())

func RunLogConformance(t *testing.T, newLog NewLog)          // mandatory
func RunDeduperConformance(t *testing.T, newLog NewLog)      // if you implement Deduper
func RunTailReaderConformance(t *testing.T, newLog NewLog)   // if you implement TailReader
func RunSnapshotterConformance(t *testing.T, newLog NewLog)  // if you implement Snapshotter

The package imports only changelog and the standard library, so depending on it from your _test.go adds nothing to your build.

What this library does not do

Stated plainly, because the git framing invites the assumption. Why each is absent is on design decisions.

Provided as-is, without warranty. Review it against your own threat model before exposing it to untrusted input.