Accrue.Events.UpcasterRegistry (accrue v0.2.0)

Chain composition for event schema-version upcasting (EVT-05 / D4 Discretion).

When Accrue.Events.state_as_of/3 or timeline_for/3 reads historical rows, each row may have an outdated schema_version for its type. This registry returns the ordered list of upcaster modules required to migrate a payload from the row's recorded version up to the current in-app version.

Failure mode (Pitfall 9)

If the requested target version is unknown for a type, this module returns {:error, {:unknown_schema_version, v}}. It NEVER silently drops the row. The read path surfaces the error to the caller and emits [:accrue, :ops, :events_upcast_failed] telemetry.

Registration shape

@chains %{
  "event.type" => %{
    target_version => [Module1, Module2, ...]
  }
}

Most types are unregistered and resolve via the identity branch (no upcasters). Only when a payload shape changes do we add an entry.

Summary

Functions

chain(type, from, to)

Returns the upcaster module chain to migrate from from → to.

Functions

chain(type, from, to)

@spec chain(String.t(), pos_integer(), pos_integer()) ::
  {:ok, [module()]} | {:error, {:unknown_schema_version, pos_integer()}}

Returns the upcaster module chain to migrate from from → to.

{:ok, []} when from == to (identity)
{:ok, []} when the type has no registered chains
{:ok, [mod1, mod2, ...]} when a chain is registered
{:error, {:unknown_schema_version, v}} when the target version is unknown for a registered type