Skip to content
CAI
Software that uses CAICheck a score

DeluxeOwl/chronicle

64.7

Adequate · 8 November 2026

13.9k

lines of production code

Go

primary language

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Chronicle is a type-safe event sourcing toolkit for Go that provides a comprehensive framework for building domain-driven applications with aggregates, event logs, and repositories. It supports multiple storage backends including Postgres, SQLite, and NATS, and includes features like snapshotting, optimistic concurrency control, and event transformation for encryption and upcasting. The system also offers a durable work queue and a distributed workflow engine for orchestrating multi-step processes with crash recovery and step replay capabilities.

How it got here

2025 — Chronicle initial release and core framework

23 changes.

This period marks the initial release of Chronicle, a type-safe event sourcing toolkit for Go, establishing the foundational abstractions for aggregates, event logs, and projections. The work involved building the core library with support for multiple storage backends, snapshotting, and optimistic concurrency, alongside comprehensive documentation and example applications.

2026 — durable workflow and queue engine

4 changes.

This period focused on implementing a durable, event-sourced workflow engine and persistent work queue backed by SQL storage. The work introduced task leasing, idempotent message handling, and snapshot-based replay optimizations to ensure reliability in distributed environments. Supporting examples demonstrated these capabilities through a persistent queue and a monitored workflow application with an embedded HTTP interface.

Features

Added Go quickstart example demonstrating event-sourced account usage

A new Go example at examples/1\_quickstart/main.go shows how to create an event-sourced account repository, open an account with a holder name, perform deposit and withdrawal operations, and save the resulting events to an in-memory event log.

_examples/1\quickstart · high confidence

Added crypto transformer example demonstrating event encryption and GDPR deletion

The new \examples/4\_transformers\_crypto/main.go\ file demonstrates how to use a crypto transformer to encrypt account holder names when writing events and decrypt them when reading. It also illustrates a GDPR compliance scenario where replacing the encryption key renders historical event data unreadable upon retrieval, alongside a logging transformer for debugging.

_examples/4\_transformers\crypto · high confidence

Added database migration for chronicle\_snapshots table

A new database migration has been added to create the \chronicle\_snapshots\ table, which stores snapshot data with columns for \log\_id\ (primary key), \version\, and \data\. This migration includes both an 'Up' operation to create the table and a 'Down' operation to drop it, ensuring proper schema management for the snapshot store.

snapshotstore/postgresmigrations · high confidence

Added example demonstrating a persistent, event-sourced work queue

The examples/9\_persistent\_queue directory now contains a Go application that showcases a durable work queue backed by SQLite. This example illustrates how to enqueue messages with stable IDs, claim them for processing, and acknowledge completion, ensuring that work is persisted and can survive restarts or crashes without duplication.

_examples/9\_persistent\queue · high confidence

Added example implementations for event transformation and snapshotting

The examples/internal/account directory now includes concrete implementations for data transformation and state persistence. A new CryptoTransformer demonstrates how to encrypt and decrypt the account holder's name using AES-GCM during event write and read operations. Additionally, a Snapshotter and CustomSnapshot function are provided to show how to capture and restore the aggregate's state (ID, balance, holder name, and version) based on specific conditions.

examples/internal/account · high confidence

Added in-memory and PostgreSQL snapshot stores

The snapshotstore package now provides two concrete implementations for persisting aggregate snapshots: an in-memory store (Memory) suitable for testing and development, and a PostgreSQL-backed store (Postgres) for production use. The PostgreSQL implementation automatically manages its schema via embedded goose migrations and uses an upsert strategy to maintain the latest snapshot per aggregate. Both stores are generic, thread-safe, and utilize the new global encoding codec for serializing snapshot data.

snapshotstore · high confidence

Added optimistic concurrency example with conflict handling

The examples/2\_optimistic\_concurrency/main.go file demonstrates how to use the event-sourced repository with optimistic concurrency control. It shows loading an account by two users, having one user save a change, and then handling the resulting version conflict when the other user attempts to save their outdated copy. The example illustrates catching the version.ConflictError and re-fetching the latest state to retry the operation.

_examples/2\_optimistic\concurrency · high confidence

Added shared event metadata generation utilities

Introduced a new \EventMetadata\ struct and \EventMetaGenerator\ in the shared package to standardize event identification and timestamping. The generator creates UUID v7-based event IDs that embed timestamps, alongside a separate \OccuredAt\ field, and provides a method to extract the timestamp directly from the ID. This allows example applications to consistently generate and parse event metadata.

examples/internal/shared · high confidence

Event sourcing core: new log, projection, and registry abstractions

The event package has been restructured to provide a comprehensive event-sourcing foundation. The core \event\_log.go\ defines \Log\, \GlobalLog\, and \DeleterLog\ interfaces for reading, writing, and managing event streams with optimistic concurrency and lazy iteration. A new \event\_processor.go\ introduces \TransactableLog\ to support synchronous projections within the same transaction as event appends. The \projection.go\ and \projection\_policies.go\ files add an \AsyncProjectionRunner\ with configurable checkpoint policies (time, count, or composite) for building eventually consistent read models. Event transformation is handled by \event\_transformer.go\, which provides a \Transformer\ interface and \TransformerChain\ for upcasting or encrypting events. Finally, \registry.go\ introduces a type-safe \EventRegistry\ with a global \Any\ registry to enforce unique event names across aggregates, replacing the previous generic \GenericEvent\ and \Metadata\ structures.

event · high confidence

Expanded versioning API with new selectors and concurrency checks

The version package now provides a richer API for managing event streams and optimistic concurrency. Users can retrieve specific ranges of events using the new Selector struct (with From/To fields) or convenience functions like SelectFrom, SelectExact, and SelectInterval, alongside the existing SelectFromBeginning. Optimistic concurrency is enforced via the Check interface, with a new CheckExact implementation that validates the aggregate's current version against an expected value, returning a ConflictError with detailed expected and actual version information if a mismatch occurs.

version · high confidence

Initial release of Chronicle, a type-safe event sourcing toolkit for Go

This change introduces the Chronicle library, providing a complete event sourcing framework for Go. It includes core abstractions for aggregates, event logs (with support for Postgres, SQLite, and Memory backends), and repositories with optional snapshotting and retry logic. The toolkit supports both synchronous and asynchronous projections, event transformers for encryption and upcasting, and a global event registry. Additionally, it provides a persistent work queue and distributed workflow workers with an embedded monitor. The release also includes comprehensive documentation, a quickstart guide, and developer tooling such as lefthook, devbox, and commitlint to enforce coding standards.

(repo-wide) · high confidence

Introduce event-sourced persistent work queue

The \queue\ package now provides an at-least-once persistent work queue backed by the \event.Log\. Users can enqueue messages with stable IDs for idempotency, claim work with time-bound leases, and acknowledge or negatively acknowledge deliveries. The queue supports scheduled delivery, lease extension, and snapshot-based replay optimization to reduce event history traversal. It is designed for distributed environments, ensuring that work survives process restarts and handling concurrent claims and duplicate enqueues safely.

queue · high confidence

Introduces core event-sourced aggregate framework with snapshotting, transactional processing, and event transformation

This change adds the \aggregate\ package, providing the foundational types and behaviors for event sourcing. It introduces the \Base\ struct for versioning and uncommitted event tracking, along with generic \Root\ and \Aggregate\ interfaces. Key features include \ReadAndLoadFromStore\ for hydrating aggregates from event logs, \ESRepoWithSnapshots\ for optimizing load performance via point-in-time snapshots, and \TransactionalRepository\ for atomically saving events alongside side-effects like projections or outbox messages via \TransactionalAggregateProcessor\. The framework also supports event transformation through \event.Transformer\ for upcasting and batching, and includes \ESRepoWithRetry\ for handling optimistic concurrency conflicts.

aggregate · high confidence

Introduces durable, replay-based workflow engine with SQL-backed task queues

Adds a new workflow package providing a durable, event-sourced workflow engine where steps are replayed from an event log for reliability. The package includes a \TaskQueue\ abstraction with three implementations: an in-memory queue for testing, a synchronous SQL-backed queue that atomically enqueues tasks within event transactions, and an asynchronous SQL-backed queue that uses an event projection to populate a ready-tasks table for eventual consistency. It also introduces task leasing to prevent concurrent execution, persistent event waiting via SQL tables to support distributed \WaitForEvent\/\PublishEvent\ patterns, and a worker loop with automatic lease extension.

workflow · high confidence

Introduces event-sourced work queue and durable workflow engine

Chronicle now includes a durable, event-sourced work queue and a workflow engine for orchestrating multi-step processes. The queue provides at-least-once delivery with lease management, idempotent enqueueing, and snapshot support to handle large pending sets. The workflow engine manages long-running instances with step tracking, retry strategies, cancellation policies, and the ability to wait for external events, all persisted to the event log for crash recovery.

github.com/DeluxeOwl/chronicle · high confidence

Introduction of a unified encoding package with JSON and Protobuf support

A new \encoding\ package has been added to provide a standardized way to serialize and deserialize data. It defines \Codec\, \Encoder\, and \Decoder\ interfaces, along with concrete implementations for JSON (\JSONB\) and Protocol Buffers (\Protobuf\). This allows users to easily switch between encoding formats for storage or transmission, with \JSONB\ serving as the default codec.

encoding · high confidence

New event metadata example with snapshot support

Added a new example demonstrating how to use event metadata and snapshots within the event sourcing framework. The example shows how to configure a memory-based event log and snapshot store, use a mock time provider for consistent testing, and save/reload an account entity with snapshotting enabled every 3 events.

_examples/5\_event\metadata · high confidence

New example demonstrating synchronous unique constraint enforcement

Added a new example in \examples/8\_unique\_constraint\ that demonstrates how to enforce unique constraints on domain data using a synchronous transactional projection. The example implements a \uniqueUsernameProjection\ that intercepts \AccountOpened\ events and attempts to insert usernames into a SQLite \unique\_usernames\ table; if a duplicate username is detected, the database constraint violation causes the transaction to fail, thereby preventing the duplicate account from being saved.

_examples/8\_unique\constraint · high confidence

New examples for projections and outbox patterns

Added two new example programs in the examples directory: one demonstrating how to build and query projections from event data using a transactional repository, and another illustrating the outbox pattern for reliably publishing events to a pub/sub system via a polling mechanism.

_examples/6\projections · high confidence

New v2 example with outbox, projections, and snapshots

The examples/internal/accountv2 directory now includes a complete v2 example implementation featuring an outbox processor for reliable event persistence, a projection processor to maintain a denormalized account view, and a snapshotter to optimize aggregate state reconstruction. Supporting utilities in examplehelper provide an in-memory pub/sub mechanism and an SQL query printer for demonstration purposes.

examples/internal/accountv2 · high confidence

New workflow monitoring example with embedded HTTP server

Added a new example application in examples/10\_workflow\_monitor that demonstrates a distributed workflow system with an embedded HTTP-based monitor. The application runs concurrent workers to process order fulfillment workflows (including payment charging, shipment preparation, and event waiting) while exposing a web interface at /workflows/ for monitoring workflow status. It uses SQLite for persistence and supports configuration via command-line flags for database path, listen address, worker count, and initial data seeding.

_examples/10\_workflow\monitor · high confidence

Snapshot example for event-sourced repositories

Added a Go example demonstrating how to use snapshotting with event-sourced repositories to optimize loading performance. The code shows configuring a memory-based snapshot store, defining a snapshot policy (triggering every 3 events), and saving/loading an account aggregate to illustrate how snapshots reduce the number of events replayed during retrieval.

_examples/3\snapshots · high confidence

Behavioural changes

Event log backend overhaul with driver-agnostic conflict handling and performance benchmarks

The event log implementation has been modernized to support multiple backends (Postgres, SQLite, Memory, and NATS) with a new driver-agnostic conflict parser that standardizes optimistic concurrency error handling across all stores. Postgres performance is improved by moving version checks from per-row database triggers to application-level advisory locks, while SQLite and Memory stores retain trigger-based or in-memory checks. The update also introduces global event tailing for the memory store, comprehensive benchmarking across all backends, and automated database migrations via Goose.

eventlog · high confidence

Harden database migration concurrency and locking

The migration subsystem now ensures safe concurrent execution and robust error handling. For SQLite, a new file-based locking mechanism (using platform-specific file locks on Unix/Windows) prevents race conditions during initialization, while a process-level gate serializes in-memory database access. For PostgreSQL, the system now uses a session locker with a bounded timeout to coordinate across processes. Additionally, a new concurrency test suite verifies that migrations handle simultaneous callers correctly and that database locks are properly released even when a migration fails.

pkg · high confidence

New internal assertion helpers using panic instead of fatal

Added internal/assert/assert.go, introducing Thatf and Neverf functions that trigger a panic when assertions fail, replacing previous fatal behavior.

internal/assert · high confidence

Test coverage

Test infrastructure now supports NATS JetStream and Postgres 16 via testcontainers

The internal test utilities have been updated to provision real infrastructure dependencies for integration testing. Event logs and snapshot stores can now be tested against a NATS JetStream server (using the nats:2.12 image) in addition to the existing in-memory, SQLite, and Postgres backends. The Postgres test container has been upgraded to version 16-alpine, and the test setup code now initializes and cleans up these containers automatically using testcontainers-go.

internal/testutils · high confidence

Dependencies

Updated Go module dependencies and runtime version

The project's Go runtime requirement has been bumped from 1.24.2 to 1.25.0, and the module path has been updated to github.com/DeluxeOwl/chronicle. A comprehensive set of dependencies has been added or updated, including NATS client libraries (nats.go, nkeys, nuid), database drivers (pgx, go-sqlite3), migration tools (goose), testing utilities (testcontainers-go, testify), and OpenTelemetry tracing components.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 54 → 65 (+10.2)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 88 → 88 (+0.0)
  • Architecture 92 → 90 (-1.2)
  • Maturity 40 → 65 (+25.3)
  • Readiness 51 → 51 (+0.0)
  • Security 79 → 90 (+11.7)
  • Event-Driven 100 → 100 (+0.0)
  • Accessibility 80 → 80 (+0.0)
  • Performance 77 → 89 (+11.5)

Findings

  • No change — the same findings as the prior survey.

Architecture

  • Unchanged — 0 containers · 1 contexts · 0 edges

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

DeluxeOwl/chronicle was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 8 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 53a28d8859f677eeb1fee08c08490d8a57c154f3 — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-45ab2cab63de.