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.
Route near misses
- An accepted
.playmodel under the model root covers the behavior, or the repository is opted in (pergeneral.md"Model first"; wherecratis-screenplay-modeling-lifecycleis installed, run itsscripts/model-first-status.mjs): change the model first withcratis-screenplay-event-modeling. If the Screenplay skills are not installed, say so and do not author.playfrom memory. Edit code here only for infrastructure, clients, adapters, Screenplay code attachments, or gap-fill scope (cratis-screenplay-render-and-gap-fill); never edit Stage-managed output.
Verified product sources
Sources:
| Package | Purpose |
|---|---|
Cratis.Chronicle |
Cratis.Chronicle.Events and Cratis.Chronicle.Events.Migrations |
Cratis.Chronicle.CodeAnalysis |
CHR0012, CHR0037, CHR0049, CHR0050 |
Reverify product sources before claiming support for another version.
Requires Chronicle 19.52.0 for marker-free migration nomination through
ExplicitArtifacts.RegisterMigration<T>(). Read references/explicit-migrations.md
when event endpoints are plain/aliased or a migration cannot reference Chronicle;
check the client package version, since older clients need migration markers.
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 chains adjacent migrations to produce another generation. This is a
possible upcast path, not a promise that every observer receives the latest
generation; delivery policy is described below:
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>);
EventTypeGenerationForAttribute<TEventType> takes exactly one argument, the
generation. There is no id argument, which is the point: the event type id is
resolved from the current record's [EventType], so the two generations cannot
end up with mismatched ids.
Persisted event type ids are immutable identity, and an explicit id is a house
exception (decision 152): new events use plain [EventType], and an id string is
written only to retain an already-persisted id after a rename (below) or to
resolve a cross-package short-name collision. Never change or "normalize" one.
The older style — giving the prior record its own
[EventType("<explicit-id>", generation: 1)] with an id string identical to the
current generation's — is still supported and still works, as a retained id.
Prefer [EventTypeGenerationFor<T>] for anything new: with the explicit-id style, an
omitted or mistyped id silently defaults to the CLR type name, Chronicle then
treats the two as unrelated event types, and the migration never applies.
Three diagnostics guard this:
- CHR0037 (warning) — the generations a migration references must resolve to the same event type and differ only by generation.
- CHR0049 (error) —
[EventTypeGenerationFor<T>]must reference a type marked with[EventType]. - CHR0050 (error) — a type cannot carry both
[EventType]and[EventTypeGenerationFor<T>].
At runtime the EventTypeMigration<,> constructor throws
MigrationGenerationsMustShareEventTypeId on an id mismatch, and
InvalidMigrationGenerationGap when the generations are not consecutive.
Step 2 — Write the migration
Derive from Cratis.Chronicle.Events.Migrations.EventTypeMigration<TUpgrade, TPrevious>. Upcast and Downcast are public abstract void, so both must be
implemented. You describe the change declaratively through builder.Properties;
you never construct the record by hand.
The two builders have flipped generic arguments. The builder is always
IEventMigrationBuilder<TTarget, TSource>, so upcasting takes
<TUpgrade, TPrevious> and downcasting takes <TPrevious, TUpgrade>:
using Cratis.Chronicle.Events.Migrations;
public class <EventName>V1To<EventName> : EventTypeMigration<<EventName>, <EventName>V1>
{
public override void Upcast(IEventMigrationBuilder<<EventName>, <EventName>V1> builder) =>
builder.Properties(properties => properties
.DefaultValue(target => target.<NewProperty>, <defaultValue>));
public override void Downcast(IEventMigrationBuilder<<EventName>V1, <EventName>> builder) =>
builder.Properties(properties => { });
}
Downcast may be an empty builder.Properties(properties => { }) when no
consumer needs the earlier shape, but it must still be declared.
The property builder
IEventMigrationPropertyBuilder<TTarget, TSource> has exactly five fluent
members:
| Member | Use |
|---|---|
DefaultValue(targetProperty, value) |
supply a value the old events never carried |
RenamedFrom(targetProperty, sourceProperty) |
the property moved name |
Split(targetProperty, sourceProperty, separator, part) |
one old value becomes several |
Combine(targetProperty, separator, params sourceProperties) |
several old values become one |
MapValues(targetProperty, sourceProperty, map) |
one direction's value translation |
Requires Chronicle 19.51.1 for DefaultValue and MapValues on concept
properties to write the underlying primitive rather than a { Value: ... }
object. Check the client package version; older definitions need an upgrade
before relying on concept-valued defaults/maps.
There is no Rename — the method is RenamedFrom. There is no Join —
concatenation is Combine.
PropertySeparator and SplitPartIndex convert implicitly from string and
int, and expose PropertySeparator.Space, SplitPartIndex.First, and
SplitPartIndex.Second. Property expressions may address nested paths.
public override void Upcast(IEventMigrationBuilder<<EventName>, <EventName>V1> builder) =>
builder.Properties(properties => properties
.Split(target => target.<FirstPart>, source => source.<Combined>, PropertySeparator.Space, SplitPartIndex.First)
.Split(target => target.<SecondPart>, source => source.<Combined>, PropertySeparator.Space, SplitPartIndex.Second));
public override void Downcast(IEventMigrationBuilder<<EventName>V1, <EventName>> builder) =>
builder.Properties(properties => properties
.Combine(target => target.<Combined>, PropertySeparator.Space,
source => source.<FirstPart>, source => source.<SecondPart>));
Nested paths and compatible schema metadata
Property expressions traverse nested CLR members:
DefaultValue(m => m.Price.Description, "x") and
RenamedFrom(m => m.Price.Amount, e => e.Amount) address the nested target.
JsonPropertyName wins over the client's naming policy; raw string paths are
already JSON paths and are not renamed. An undeclared DefaultValue target in
a nonempty target schema is rejected with InvalidMigrationPropertyForEventType
(Source/Kernel/Core/EventTypes/EventTypeRegistrar.cs, ValidatePropertyKeys);
an empty auto-generated target schema is the exception.
Adding/removing an optional property at any depth still needs a migration
class to complete the new generation chain, but no property operations: the
target schema supplies absence/drops undeclared properties. That is a migration
fact, not a reason to put nullable facts on newly authored events. Schema title
is ignored, so renaming a CLR record whose persisted id is retained with [EventType("id")] does not
raise EventTypeSchemaChanged. A property described only by default may gain
type/format without that error. Source:
Documentation/migrations/dotnet-client.mdx and the kernel event-type schema comparison.
Step 3 — When the values changed meaning, declare a value map
The operations above move values between properties. When a value itself means
something different in the new generation — an enum renumbered, a status code
set replaced — override MapValues on the migration. It is virtual with an
empty default, so override it only when you need it. It is declared once and
applied forward when upcasting and inverted when downcasting.
IEventValueMapBuilder<TUpgrade, TPrevious> has one member, For. Map lives
on the inner IValueMapBuilder<TFrom, TTo> that For hands you, and its
arguments read previous value first, current value second:
public override void MapValues(IEventValueMapBuilder<<EventName>, <EventName>V1> builder) =>
builder.For(
current => current.<Property>,
previous => previous.<Property>,
map => map
.Map(<PreviousEnum>.<OldMember>, <CurrentEnum>.<NewMember>)
.Map(<PreviousEnum>.<OtherOldMember>, <CurrentEnum>.<OtherNewMember>));
Values the map does not mention are carried across unchanged. When two values
collapse onto one, the inverse takes the first pair declared for that value.
MapValues runs before Upcast/Downcast, so a direction that states its own
transformation for the property keeps it — that is also how you express a
deliberately one-way translation, using the property builder's own MapValues.
Enums: what actually needs a migration
Chronicle compares stored and generated schemas by the enum's underlying values, not its member names. So:
- Adding a member — compatible, no migration.
- Renaming a member — compatible, no migration; the values are unchanged.
- Removing a member — incompatible; new generation plus a value map.
- Renumbering members — incompatible; new generation plus a value map.
An incompatible change without a new generation fails registration with
EventTypeSchemaChanged.
Step 4 — Chain across generations
For three generations, write two migrations (1->2 and 2->3). Each knows only
its adjacent pair; Chronicle chains them. Two migrations claiming the same
(from, to) pair for one event type throw
MultipleMigratorsForSameEventTypeGeneration.
Migrations are discovered by convention — nothing is registered. They are activated through the service provider, so a migration may take constructor dependencies.
Backfill scope and rollout
Per Documentation/migrations/index.md, registering a new
generation starts add-only backfill in the default namespace's event log
only. Other namespaces and sequences are not covered. Existing stored
representations remain unchanged; changing a migration alone does not launch
another backfill. Older backfills may already have overwritten originals:
upgrading cannot recover those. Register new generations only after every
kernel silo is upgraded; an old worker can still overwrite content mid-rollout.
Choose the generation an observer receives
Requires Chronicle 19.41.0 for reactors and reducers, and 19.48.0 for typed materialized projections.
Compatibility remains the default. With
ChronicleOptions.EventGenerationDelivery = EventGenerationDelivery.Pinned,
reactors and reducers receive the generation of their handler's CLR event type.
Typed materialized projection clauses receive the
generation they declare, including joins, children,
removals, and event-content keys on live, catch-up, and replay.
Read references/pinned-generations.md for
missing-generation migration, release and revision behavior, registration
rejections, persisted PDL pins, and testing limits. Configure the opt-in through
cratis-chronicle-client-dotnet; do not invent generation-qualified Screenplay
syntax. ReadModelScenario and ReactorScenario do not emulate the kernel's
pinned-generation migration and release; prove delivery with real-client
integration, not a scenario-only assertion.
Requires Chronicle 19.60.0 for webhook generation pinning with
WithGenerationDelivery(EventGenerationDelivery.Pinned) on the .NET builder
(or direct registration's GenerationDelivery). Live delivery, catch-up, replay
and partition retries use the subscribed generation; unknown or duplicate
same-id generations fail registration before recording it. Migration/release
failure sends no request and fails the batch for retry. Check client/kernel
versions; older webhooks retain compatibility delivery, not this guarantee.
Do not model absence with a nullable property
CHR0012 (warning) flags a nullable property on an [EventType] record.
Model an optional fact as a separate event, or supply a DefaultValue in the
migration. Note the diagnostic only inspects types carrying [EventType], so a
prior generation marked with [EventTypeGenerationFor<T>] is not checked — that
is expected, since the prior generation records history rather than new intent.
Common pitfalls
| Pitfall | Why it breaks |
|---|---|
Editing the stored record without bumping generation |
old events still carry the old schema; nothing migrates them |
Giving the prior record its own [EventType] with no id, or a mismatched id |
Chronicle treats the two as unrelated event types and the migration never applies |
Writing both builders as IEventMigrationBuilder<TUpgrade, TPrevious> |
Downcast takes the flipped pair and will not compile |
Reaching for Rename or Join |
neither exists; use RenamedFrom and Combine |
Calling Map on IEventValueMapBuilder |
Map is on the inner IValueMapBuilder reached through For |
| Adding a nullable property to represent "missing on old events" | CHR0012; supply a DefaultValue instead |
Splitting one event into two inside Upcast |
a migration produces one event; model a split as a reactor or a command |
| Adding a new generation for a renamed enum member | not needed; only removal or renumbering requires one |
| Deriving an operational identity from the event type id (outbox deduplication key, derived fact id, fence-log key, replay receipt) and then renaming | generations do not cover it; keep the old id value or migrate that store |
Verify
- The current record carries the bumped
[EventType(generation: N)]. - The prior record carries
[EventTypeGenerationFor<TCurrent>(N-1)], or an explicit id identical to the current generation's. - The migration derives from
EventTypeMigration<TUpgrade, TPrevious>and implements bothUpcastandDowncastwith the correct generic order. MapValuesis overridden only where a value's meaning changed.- No nullable property was added to an
[EventType]record. - Any explicit id retains a persisted id or resolves a collision, and no store keyed by an event type id (deduplication keys, receipts) was left behind.
- The build is clean with no
CHR0012,CHR0037,CHR0049, orCHR0050outstanding. - Old-generation events replay into the current shape through the read-model specifications for the affected observers.
- With
EventGenerationDelivery.Pinned, real-client integration also verifies old-generation events on live delivery, catch-up, and replay into each observer's pinned generation; in-process read-model/reactor scenarios alone do not prove kernel migration and release.