cratis-chronicle-event-type-migration

Chronicle event type migrations

Chronicle stores events forever. When an event's schema must change, you add a generation and write a migration rather than editing the original record. Chronicle discovers migrations by convention and applies them when reading older events.

You need this only once events of the prior shape exist somewhere you cannot regenerate. Before that — greenfield development with disposable data — rename event types and change schemas freely. A migration written too early is dead code that hides the real schema in the history.

Verified product sources

This skill is verified against these exact sources:

Package	Version	Purpose
Cratis.Chronicle	16.45.2	Cratis.Chronicle.Events and Cratis.Chronicle.Events.Migrations
Cratis.Chronicle.CodeAnalysis	16.45.2	CHR0012, CHR0037, CHR0049, CHR0050

Reverify product sources before claiming support for another version.

Generations

Cratis.Chronicle.Events.EventTypeAttribute carries the identity and the generation:

public sealed class EventTypeAttribute(string id = "", uint generation = 1) : Attribute

id defaults to the CLR type name and generation starts at 1. The attribute is not repeatable, so two generations are always two distinct CLR types. Chronicle routes a stored event through the migration chain before delivering it to observers:

Generation 1 (stored) -> Migration 1->2 -> Migration 2->3 -> Current (Generation 3)

Step 1 — Keep the prior record and bump the generation

Keep the old shape available to the migration as TPrevious. Bump the current record's generation, and mark the prior record with [EventTypeGenerationFor<TCurrent>(N-1)] rather than giving it its own [EventType]:

using Cratis.Chronicle.Events;

[EventType(generation: 2)]
public record <EventName>(<IdType> <IdProperty>, <NewType> <NewProperty>);

[EventTypeGenerationFor<<EventName>>(1)]
public record <EventName>V1(<IdType> <IdProperty>);