DeluxeOwl/chronicle

Chronicle is a Go library that provides a comprehensive framework for implementing event-sourced aggregates, supporting multiple storage backends including memory, SQLite, PostgreSQL, and NATS. It offers core infrastructure for managing event logs, projections, and snapshots, along with utilities for optimistic concurrency control and durable workflow execution. The system also includes examples demonstrating common patterns such as encryption transformers, outbox processing, and unique constraint enforcement.

The examples/internal/accountv2 directory now contains a complete example of an event-sourced aggregate (Account) that tracks balance, holder name, and opening time. The implementation includes domain events (account opened, money deposited/withdrawn), an outbox processor that writes committed events to a database table, and a projection processor that maintains a denormalized 'accounts' table for quick lookups. A snapshotter is also provided to persist and restore aggregate state. Additionally, helper utilities (PubSubMemory, SQLPrinter) are added to support the example.

examples/internal/accountv2 · high confidence

A new example at examples/4\_transformers\_crypto/main.go demonstrates using a crypto transformer to encrypt sensitive fields (like holder names) during event storage and decrypt them on read. The example also shows how to handle data deletion by swapping the encryption key, rendering the encrypted data unreadable, which illustrates a GDPR-style right-to-be-forgotten workflow.

_examples/4\_transformers\crypto · medium confidence

A new example in the examples/5\_event\_metadata directory demonstrates event sourcing with snapshotting. The code shows how to configure an event-sourced repository with a memory-based snapshot store, using a mock time provider to simulate future timestamps for testing. The example includes depositing money, saving the aggregate, reloading it, and verifying the snapshot was stored.

_examples/5\_event\metadata · medium confidence

Added two new example applications: one demonstrating event projections using a SQL-based projection table, and another implementing an outbox pattern with a polling goroutine to publish events to a pub/sub channel. These examples illustrate how to integrate the Chronicle library with SQLite for event sourcing and reliable event delivery.

_examples/6\projections · high confidence

The codebase now includes a new \encoding\ package that defines a \Codec\ interface for encoding and decoding data. This package provides three concrete implementations: \Generic\ for custom function-based codecs, \JSONB\ for standard JSON serialization, and \Protobuf\ for Protocol Buffers serialization. This introduces a unified abstraction for data serialization across the application.

encoding · high confidence

A new example in examples/3\_snapshots/main.go shows how to use the chronicle library's snapshot store to optimize aggregate loading. The code creates a memory-based snapshot store, configures a snap policy to trigger every 3 events, and demonstrates saving an account with deposits, then reloading it via the snapshot at version 3.

_examples/3\snapshots · medium confidence

A new example in the codebase demonstrates how to implement synchronous transactional projections to enforce unique constraints on data. The code shows a \uniqueUsernameProjection\ that listens for account opening events and inserts usernames into a database table with a UNIQUE constraint, ensuring that duplicate usernames are rejected at the transactional level.

_examples/8\_unique\constraint · high confidence

Introduced two new implementations for the aggregate.SnapshotStore interface: a thread-safe, in-memory store (Memory) for testing and development, and a PostgreSQL-backed store (Postgres) that persists snapshots to a 'chronicle\_snapshots' table using an UPSERT strategy. Both stores utilize a configurable encoding codec to serialize snapshot data.

snapshotstore · high confidence

Added the internal example package examples/internal/account, which demonstrates an event-sourced Account aggregate. The example includes the core account logic (Open, DepositMoney, WithdrawMoney), a snapshotter for state persistence, and a CryptoTransformer that encrypts the holder's name using AES-GCM before writing events and decrypts it on read. This provides a concrete reference for implementing event sourcing with custom transformers and snapshotting.

examples/internal/account · high confidence

Added a new example demonstrating optimistic concurrency control using event sourcing. The example shows how to handle version conflicts when multiple users modify the same account, including a conflict error scenario and subsequent retry logic.

_examples/2\_optimistic\concurrency · high confidence

A new shared package for examples has been introduced, providing an EventMetadata struct and an associated generator. The metadata includes an event ID (using UUID v7, which embeds a timestamp) and an occurrence time. The generator creates new event metadata instances, allowing example code to produce consistent, timestamped event identifiers. Tests verify the generation of these metadata structures.

examples/internal/shared · high confidence

The internal testutils package now provides setup helpers for multiple event log backends, including memory, SQLite, Postgres, and NATS JetStream. Tests can now run against these diverse storage and messaging systems, enabling broader coverage of transactional and global event log behaviors across different infrastructure.

internal/testutils · high confidence

The workflow package now provides a durable, replay-based workflow engine built on Chronicle's event sourcing primitives. Users can define workflows as aggregates where each step becomes an event, allowing restarts to replay the event log and cache step results for deterministic execution. The engine supports multiple task queue backends: an in-memory queue for testing, a SQL-backed synchronous queue for transactional durability, and an asynchronous SQL-backed queue for eventual consistency scenarios. The system includes persistent event waiting via SQL tables, automatic lease extension for long-running steps, and retry strategies with backoff. Tests cover queue implementations, async projection handling, and workflow execution scenarios.

workflow · high confidence

Added the \aggregate\ package, which provides a generic, type-safe foundation for event-sourced aggregates. This includes the \Root\ and \Aggregate\ interfaces, a \Base\ struct for versioning and event tracking, and a \Repository\ interface with a default \ESRepo\ implementation. The package also introduces support for transactional processing via \TransactionalAggregateProcessor\ and \ProcessorChain\, optimistic concurrency retry logic via \ESRepoWithRetry\, and snapshotting capabilities through \ESRepoWithSnapshots\. Comprehensive tests cover event transformation (upcasting and batching), snapshot policies, and deletion scenarios.

aggregate · high confidence

The eventlog package now provides a unified interface for event sourcing across four distinct backends: an in-memory store, SQLite, PostgreSQL, and NATS JetStream. Each backend implements the \event.Log\ and \event.TransactionalEventLog\ interfaces, allowing users to swap storage mechanisms without changing application code. The in-memory store supports global tailing for real-time event streams, while the database-backed stores (SQLite, Postgres) use triggers or advisory locks to enforce optimistic concurrency control. Additionally, a driver-agnostic conflict parser is introduced to standardize error handling across all backends, and benchmark tests are added to measure performance across all implementations.

eventlog · high confidence

The version package now provides a complete optimistic concurrency control mechanism. A new \Check\ interface and \CheckExact\ implementation allow applications to validate that an aggregate's version matches an expected value before appending events, returning a \ConflictError\ if a concurrent modification is detected. Additionally, a \Selector\ struct and helper functions (\SelectFrom\, \SelectExact\, \SelectInterval\) enable querying event logs for specific ranges of versions, supporting both forward and backward reading of event history.

version · medium confidence

Adds the foundational types and interfaces for event sourcing, including the \Log\ interface for reading and appending events to an aggregate's stream, and the \GlobalLog\ interface for reading the global chronological event stream. The update introduces \AsyncProjection\ and \SyncProjection\ interfaces to handle event processing, with the \AsyncProjectionRunner\ providing a configurable runner that supports both polling and tailing modes with configurable checkpoint policies. A \Transformer\ interface and \TransformerChain\ are added to allow event transformation (e.g., encryption, upcasting) during read and write operations. Additionally, a \Registry\ system is introduced to map event names to concrete types, supporting both type-specific and global registries for decoding events from the store.

event · high confidence

The application now includes a new \pkg/migrations\ package that wraps the \goose\ library to handle database schema updates, allowing users to configure migration options such as skipping automatic execution or providing a custom logger. Additionally, a \pkg/timeutils\ package has been added to abstract the current time via a \TimeProvider\ interface, which facilitates testing by allowing the system time to be mocked.

pkg · high confidence

A new internal/assert package has been added, providing Thatf and Neverf functions that trigger a panic when an assertion fails, rather than using a fatal exit. This change introduces a type-safe mechanism for handling test failures via panic, allowing for more immediate and explicit failure reporting in internal test utilities.

internal/assert · high confidence

A new PostgreSQL migration file has been added to create the 'chronicle\_snapshots' table, which stores log IDs, versions, and binary data, along with the corresponding down-migration to drop the table.

snapshotstore/postgresmigrations · high confidence

A new quickstart example has been added to demonstrate how to use the account module. The example shows how to create a memory-based event log, initialize an account repository, and perform operations such as depositing and withdrawing money, followed by saving the state to the event log.

_examples/1\quickstart · high confidence

The project's Go module (go.mod) and dependency manifest (go.sum) have been updated. The module path was changed from 'github.com/DeluxeOwl/eventuallynow' to 'github.com/DeluxeOwl/chronicle', and the minimum Go version was raised from 1.24.2 to 1.25.0. New dependencies were added, including 'github.com/nats-io/nats.go' for event logging, 'github.com/pressly/goose/v3' for database migrations, and 'github.com/jackc/pgx/v5' for PostgreSQL support. Several other packages were also added or updated, such as 'github.com/avast/retry-go/v4' and 'github.com/stretchr/testify' for testing.

(dependencies) · high confidence

The development environment has been updated with new tools including \commitlint-rs\, \go-task\, \golines\, \lefthook\, \yek\, and \goose\. Additionally, the lockfile has been refreshed to use \go\ version 1.26.3 and \golangci-lint\ version 2.12.2, replacing the previous versions.

(repo-wide) · high confidence

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

• CAI 58 → 63 (+5.3)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 88 → 92 (+4.0)
• Architecture 100 → 100 (-0.2)
• Maturity 62 → 63 (+1.0)
• Readiness 37 → 47 (+9.3)
• Security 79 → 82 (+3.6)
• Domain Modelling 100 → 100 (+0.0)
• Event-Driven 100 → 100 (+0.0)

• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (10 lines × 2) (eventlog/memory.go)
• Duplicated block (10 lines × 2) (examples/6_projections/main.go)
• Duplicated block (10 lines × 2) (workflow/workflow.go)
• Duplicated block (10 lines × 3) (internal/testutils/eventlogs.go)
• Duplicated block (12 lines × 3) (eventlog/memory.go)
• Duplicated block (13 lines × 2) (examples/3_snapshots/main.go)
• Duplicated block (13 lines × 2) (examples/internal/account/account.go)
• Duplicated block (14 lines × 2) (aggregate/repository_transactional.go)
• Duplicated block (14 lines × 2) (eventlog/postgres.go)
• Duplicated block (15 lines × 2) (eventlog/memory.go)
• Duplicated block (15 lines × 2) (eventlog/postgres.go)
• Duplicated block (16 lines × 2) (eventlog/postgres.go)
• Duplicated block (16 lines × 2) (workflow/queue_async.go)
• Duplicated block (17 lines × 2) (eventlog/memory.go)
• Duplicated block (17 lines × 2) (eventlog/postgres.go)
• …and 19 more

• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Critical CVE: [GHSA redacted] (go.mod)
• Documentation: no installation or build instructions (README.md)
• Documentation: written for insiders (docs/todo.md)
• Duplicated block (10 lines × 2) (aggregate/repository.go)
• Duplicated block (11 lines × 2) (workflow/queue_async.go)
• Duplicated block (11–12 lines × 2) (eventlog/postgres.go)
• Duplicated block (12 lines × 2) (aggregate/repository.go)
• Duplicated block (12 lines × 2) (eventlog/memory.go)
• Duplicated block (12 lines × 2) (examples/3_snapshots/main.go)
• Duplicated block (12 lines × 2) (workflow/queue_async.go)
• Duplicated block (12 lines × 3) (eventlog/memory.go)
• Duplicated block (13 lines × 2) (eventlog/postgres.go)
• Duplicated block (13 lines × 2) (examples/6_projections/main.go)
• Duplicated block (14 lines × 2) (workflow/queue_async.go)
• Duplicated block (14 lines × 3) (internal/testutils/eventlogs.go)
• Duplicated block (14–15 lines × 2) (examples/6_projections/main.go)
• Duplicated block (15 lines × 2) (examples/internal/account/account.go)
• Duplicated block (15 lines × 2) (workflow/queue_async.go)
• …and 45 more

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

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.