Old events never change
Events in the store are immutable, so when an event shape changes you cannot rewrite the history. Instead you keep multiple versions of an event and convert old ones into the current shape as they are read. That conversion step is called upcasting.
How upcasting works
- Each event carries a type and a version.
- On read, an upcaster chain transforms a version one event into version two, then into version three, until it matches the current shape.
- The application code then only ever sees the latest shape.
Guidelines
- Upcast on read, not by mutating stored events, so the audit trail stays intact.
- Keep upcasters pure and total, mapping every old field deterministically, perhaps filling new fields with sensible defaults.
- Chain small upcasters per version step rather than one big jump, which is easier to reason about and test.
When to add a new event type
If the meaning changes rather than the shape, prefer a new event type over an upcaster, and let consumers handle both.
Key idea
Upcasting transforms old stored events into the current shape at read time so immutable history stays intact while handlers only see the latest version.