Problem
Events are a public interface. Once an indexer, an export pipeline, or a partner
consumes them, changing a topic or reordering a data tuple silently breaks
downstream consumers — and unlike an entrypoint signature, there is no
compile-time error to catch it.
What to do
- Include a schema version in every event's topic tuple from the start.
- Document the full event catalogue: name, topics, data layout, and which
entrypoint emits it.
- Establish the compatibility rule — additive changes only within a version;
anything else increments it and both are emitted during a migration window.
- Add tests asserting exact event shape, so a change is a visible test failure
rather than a silent break.
- Generate the catalogue from code where possible.
Acceptance criteria
Notes
Cheap now, expensive later. Adding a version field before anyone consumes
events costs nothing; adding one afterwards is itself the breaking change.
Problem
Events are a public interface. Once an indexer, an export pipeline, or a partner
consumes them, changing a topic or reordering a data tuple silently breaks
downstream consumers — and unlike an entrypoint signature, there is no
compile-time error to catch it.
What to do
entrypoint emits it.
anything else increments it and both are emitted during a migration window.
rather than a silent break.
Acceptance criteria
Notes
Cheap now, expensive later. Adding a version field before anyone consumes
events costs nothing; adding one afterwards is itself the breaking change.