Documentation
¶
Overview ¶
Package compat carries field-level migrations between event-payload schema versions.
The events package stamps every emitted payload with `_schema_version` (see ../doc.go for the convention). When the journal is later replayed — by `engine.ReplaySession`, the eval harness, or external tooling — the running code may have moved to a newer version than the recorded payload. The replay path consults this package to lift the on-disk payload up to the in-memory contract before delivering it to live subscribers.
Wiring ¶
`engine.replayPayloadConverter` (in pkg/engine/engine.go) calls `compat.Apply(eventType, recordedVersion, currentVersion, payload)` before re-typing the map[string]any back into a struct via `journal.PayloadAs[T]`. With the registry empty (today's state), Apply is a no-op and the converter returns the payload unchanged. When a future PR ships v2 of an event type, the migrator goes here and replay-time data flows through it without touching the engine.
Why it lives in its own package ¶
Migrations are scoped data, not engine logic — they accrete over time as types evolve, are cited in PR templates, and get exercised by targeted tests. Keeping them out of pkg/engine and out of pkg/events itself prevents an import cycle (engine imports events; events does not import engine; compat depends only on map[string]any).
The v0 == v1 rule ¶
When a payload arrives without `_schema_version`, JSON deserializes it to 0. Per the package-level rule documented in ../doc.go, consumers treat 0 as v1 — the running code's contract. The first migration that ever lands here will register a `{Type, From: 0, To: 1}` no-op so chained Apply calls stay symmetric across the synthetic boundary.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Migrations = map[Key]Migrator{}
Migrations is the active registry. Empty today — see package doc.
Authors registering new entries must also add a unit test in compat_test.go demonstrating the migrator on a representative payload.
Functions ¶
func Apply ¶
Apply lifts a payload from version `from` up to version `to` for the named event type by chaining one-step migrators registered in Migrations. When `from == to` (the common case) or no migrators are registered for a step, the payload is returned unchanged.
Returns an error when a step is missing in the middle of a chain — e.g., Migrations has 1->2 but not 2->3, and the caller asked for 1->3. This forces explicit, contiguous migration registration rather than silent drops.
Types ¶
type Key ¶
Key uniquely identifies one migration step: take a payload of the named event type from version From to version To.