Event Versioning

Executive Summary

Event Versioning defines how Algosure event contracts evolve. Every event has an event version, and publishers are responsible for compatibility with consumers.

Why This Exists

Events become contracts between Domains, AIOS, notifications, analytics, integrations, and future external consumers. Unmanaged changes can break workflows, projections, and audit interpretation.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Versioning allows Algosure to evolve event contracts without destabilizing cross-domain processes.

Versioning Model

flowchart LR
    V1[Event v1]
    Compatible[Backward-Compatible Change]
    V1b[Event v1 compatible]
    Breaking[Breaking Change]
    V2[Event v2]
    Consumers[Consumers]

    V1 --> Compatible
    Compatible --> V1b
    V1 --> Breaking
    Breaking --> V2
    V1b --> Consumers
    V2 --> Consumers

Versioning Rules

Rule	Requirement
Event version is mandatory	Consumers must know which contract version they received.
Publisher owns compatibility	The source module owns versioning and migration impact.
Backward-compatible changes are preferred	Additive changes should not break existing consumers.
Breaking changes require new version	Removed fields, changed meaning, changed identity, or changed semantics require a new version.
Consumers declare support	Consumers should state which versions they understand.
Old versions need retirement policy	Deprecated event versions require review before removal.

Compatibility Guidance

Change	Compatibility
Add optional business field	Usually compatible.
Add metadata field	Usually compatible if consumers ignore unknown metadata.
Rename event	Breaking.
Change event meaning	Breaking.
Remove field used by consumers	Breaking.
Change identifier semantics	Breaking.
Split one event into multiple facts	Potentially breaking; requires architecture review.
Merge multiple facts into one event	Potentially breaking; usually discouraged.

Consumer Version Handling

Consumer Situation	Required Behavior
Supported version received	Process normally and idempotently.
Older supported version received	Process with compatibility logic.
Unknown newer version received	Reject, park, or route according to compatibility policy.
Deprecated version received	Process if still supported and emit operational visibility where useful.

Non-Implementation Boundary

This document does not define schema registry tooling, serialization format, compatibility test tooling, or version number syntax beyond the logical requirement for an event version.