In an event-sourced system, why can't you just edit the shape of an already-stored event when your code's model changes, and what technique is normally used to let old and new event shapes coexist?

## Why the log outlives the code that wrote it Event sourcing stores every state change as an **immutable, append-only event** rather than storing only current row values. Current state — whether an aggregate in the write model or a projection in a read model — is produced by replaying the full (or snapshot-plus-tail) sequence of events for that stream. This gives a complete audit trail and lets you rebuild any past state, but it also means the event log has to outlive the code that first wrote it. A field that made sense in an `OrderPlaced` event two years ago — say a single `total` amount — may need to become `subtotal` and `tax` once the business adds tax reporting. The events already on disk still say `total`; you cannot go back and rewrite millions of historical payloads without destroying the very thing that makes the log trustworthy (its immutability), and without risking that some other service already consumed the old shape. ## How upcasting works **Upcasting solves this by moving the translation work to read time instead of write time.** 1. Every event is tagged with a **type name** and a **version** (e.g. `OrderPlaced.v1`, `OrderPlaced.v2`). 2. For each schema change, the team writes a small, pure transformation function — an **upcaster** — that takes the raw representation of the old version and produces the raw representation of the next version. 3. When an event is deserialized, a pipeline runs it through the chain of applicable upcasters (v1→v2, then v2→v3, and so on) until it reaches the version current code expects, and only the fully-upcast object is ever exposed to domain logic. For the `OrderPlaced` example, the v1→v2 upcaster might read the old `total` field and emit `subtotal = total` and `tax = 0`, encoding an explicit assumption directly in the transformation rather than leaving it implicit. ## Why not a one-off migration script The reason this pattern exists, rather than a one-off migration script, is that it preserves two properties event-sourced systems depend on: - **immutability** of the stored fact, and - **continuous deployability**. A migration script that rewrites events in place requires downtime or a careful backfill dance, and it destroys the literal historical record, which matters both for compliance and for debugging (a bug replayed years later should see exactly what was written then). Upcasting treats 'what happened' and 'how current code models it' as separate concerns: the log stays a faithful, unedited record, while the upcaster chain is just another piece of versioned application code that ships and rolls back like anything else. ## The trade-off **The trade-off is that this code never gets to die.** - **Every upcaster you've written has to stay correct** for as long as any event of that version might still exist in the log — often years or forever. - **Long-lived aggregates pay a real CPU cost:** replaying an aggregate with a deep history might mean running early events through five or six chained upcasters before domain logic even sees them, which shows up as slow rehydration or slow snapshot rebuilds. - **There's also a correctness risk baked into every upcaster:** because it decides how to interpret old data (like the `tax = 0` default above), a wrong assumption doesn't crash anything — it silently produces plausible-looking but incorrect derived state, and because the raw event never changes, that mistake is easy to miss and often surfaces much later. ## Failure modes - **In production, the most common failure is forgetting to version-tag events at write time,** making it structurally impossible to tell v1 payloads from v2 payloads on read. - **Another is an upcaster that assumes external context** (a currency rate, a since-changed tax rule) that isn't actually recoverable from the event itself — a sign upcasting is the wrong tool and a full copy-and-replace migration is needed instead. - **Snapshots complicate this further:** a snapshot is a materialized replay result, so changing an upcaster invalidates existing snapshots built under the old interpretation, or they'll silently disagree with a fresh replay. Frameworks like Axon Framework formalize this as an `UpcasterChain` applied during deserialization; stores like EventStoreDB leave it to the application layer, but the pattern is the same everywhere: **translate at the boundary, keep the log untouched.**