Document event schema evolution design#9
Conversation
Render
Destroyed
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0b52b658bb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - the current runtime event representation; | ||
| - schemas for persisted historical versions; | ||
| - one centralized decoder from each supported historical representation into | ||
| the canonical runtime event; |
There was a problem hiding this comment.
If the canonical runtime representation or a legacy decoder changes after a projection has processed old events, its checkpointed state retains the previous decoded values while a clean rebuild uses the new decoder. The design neither freezes decoder semantics nor requires such changes to create new projection versions, so the same event log and projection version can produce different results across incremental processing and replay; make the decoder artifact part of projection versioning or otherwise require its output to remain immutable.
AGENTS.md reference: AGENTS.md:L51-L51
Useful? React with 👍 / 👎.
| An upgrade is not compatible if it can write new events but can no longer read | ||
| events produced by a supported earlier release. |
There was a problem hiding this comment.
When an upgraded deployment commits an event using a new schema version and then must be rolled back, the earlier release encounters that version as unsupported and cannot replay the log. The compatibility rule here only requires the new release to read events from older releases, so the design can reach Stable without specifying whether rollback is prohibited after the first new write, gated by a deployment transition, or supported through another mechanism; document and test that recovery contract explicitly.
AGENTS.md reference: AGENTS.md:L134-L140
Useful? React with 👍 / 👎.
| - an immutable event table; | ||
| - current and historical payload validation; | ||
| - centralized legacy decoding; | ||
| - historical fixtures for every persisted version; |
There was a problem hiding this comment.
Because compatible additions may retain a schema version, one version can cover both older payloads that omit a field and newer payloads that include it. Requiring fixtures only for every persisted version allows a single newer fixture to satisfy this gate while the missing-field interpretation for older rows remains untested, so a defaulting regression can make those historical events unreadable; require fixtures for every persisted representation or compatibility boundary within a version.
AGENTS.md reference: AGENTS.md:L52-L52
Useful? React with 👍 / 👎.
1 participant
Summary
Why
The README and AGENTS guidance define event immutability and long-lived compatibility, but they do not preserve the alternatives, tradeoffs, maturity, and evidence behind a specific schema-evolution design.
This record proposes explicit integer schema versions, centralized legacy decoding, and new event types for semantic changes while keeping stored event rows immutable.
Impact
This PR changes documentation only. It does not claim that the event store, schema-version reader, or replay compatibility mechanisms are implemented.
Validation
mainmain