compat

package
v0.32.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 1 Imported by: 0

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

View Source
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

func Apply(eventType string, from, to int, payload map[string]any) (map[string]any, error)

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

type Key struct {
	EventType string // e.g. "llm.request"
	From, To  int
}

Key uniquely identifies one migration step: take a payload of the named event type from version From to version To.

type Migrator

type Migrator func(payload map[string]any) (map[string]any, error)

Migrator transforms a payload (always a map[string]any after JSON round-trip via the journal) from one version to the next. Returning (payload, nil) is fine for additive changes — drop a sensible zero value into the new field and pass through.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL