Core type class for versioned events.

This is the main constraint you'll use when working with events. It automatically includes all necessary constraints via EventConstraints.

To define an event, create instances of MaxVersion, Versions, Event, and MigrateVersion:

type instance MaxVersion "user_created" = 0
type instance Versions "user_created" = '[UserCreated]

instance Event "user_created"
instance MigrateVersion 0 "user_created"  -- Automatic migration (identity for v0)

Complete set of constraints required for an event type.

This type alias bundles all the low-level constraints needed for event processing:

• AssertVersionCountMatches - Validate MaxVersion matches Versions list length
• KnownSymbol - Access event name as runtime value
• Typeable - Runtime type information
• ToJSON - Serialize current version payloads
• FullVersionRange - Compile-time evidence for all version constraints
• ReifiablePeanoNat - Convert type-level version numbers to runtime values

You don't typically need to use this directly; just use the Event constraint. This is exported for documentation purposes so you can see what constraints are actually required.

Existential wrapper for an event at its latest version.

This packages up an event name (as a Proxy) with its current payload, hiding the specific event type. Useful for heterogeneous collections of events.

Create values using mkEvent.

Smart constructor for creating events using RequiredTypeArguments.

This provides a convenient syntax for creating events:

event = mkEvent "user_created" (UserCreated userId name)

This is equivalent to:

event = SomeLatestEvent (Proxy @"user_created") (UserCreated userId name)

Get the event name as Text from a Symbol.

This converts a type-level event name to a runtime value, useful for logging, debugging, and serialization.

getEventName (Proxy @"user_created") = "user_created"

Declare the maximum version number for an event.

Version numbers start at 0. For a single-version event, use MaxVersion = 0. For multi-version events, increment this as you add versions.

type instance MaxVersion "user_created" = 0  -- Single version
type instance MaxVersion "order_placed" = 2  -- Three versions (0, 1, 2)

Declare the payload types for each version of an event.

Use a type-level list to specify all payload versions in order:

-- Single version:
type instance Versions "user_created" = '[UserCreated]

-- Multiple versions:
type instance Versions "order_placed" = '[OrderPlacedV0, OrderPlacedV1, OrderPlacedV2]

The list length must match MaxVersion + 1. This constraint is enforced at compile time through the version evidence system.

Get the current (latest) payload type for an event.

This extracts the final type from the version vector:

CurrentPayloadType "user_created" = UserCreated
CurrentPayloadType "order_placed"  = OrderPlacedV2  -- if MaxVersion = 2

The number of versions for an event (as a Peano number).

This is MaxVersion + 1 in Peano encoding. For an event with MaxVersion = 2, this expands to PeanoSucc (PeanoSucc (PeanoSucc PeanoZero)).

This alias makes type signatures more readable when working with version indices and constraints.

The full version vector type for an event.

This type family represents the complete EventVersions structure from version 0 to MaxVersion. This is computed from the Versions list using FromList.

Example expansion:

EventVersionVector "user_created"
  = FromList (Versions "user_created")
  = FromList '[UserCreated]
  = EventVersions 'PeanoZero ('PeanoSucc 'PeanoZero)

Note: This is an internal type family. Users should work with Versions which uses the simpler list syntax.

Evidence that all version payloads satisfy the required constraints.

This is the main "proof obligation" checked by EventConstraints. It ensures that every payload version can be serialized, deserialized, and upgraded to the latest version.

Using this alias makes EventConstraints much more readable:

type EventConstraints event =
  ( ...
  , FullVersionRange event  -- instead of massive HasEvidenceList expression
  , ...
  )

Type-level vector of versioned payload types.

This GADT represents a non-empty list of types, indexed by Peano numbers. The indices track the "start" and "end" positions in the version sequence.

• startsAt - The version number where this vector begins
• finalCount - One past the last version (i.e., length when startsAt = 0)

Constructors:

• Final - A single-element vector (the last/only version)
• Then - Prepend a type to an existing vector (earlier versions)

Example: A vector of 3 versions (0, 1, 2):

Then PayloadV0 (Then PayloadV1 (Final PayloadV2))
  :: EventVersions PeanoZero (PeanoSucc (PeanoSucc (PeanoSucc PeanoZero)))

Convert a type-level list to an EventVersions GADT

This has a polymorphic kind to allow recursive usage at different indices. The result kind is constrained at usage sites via EventVersionVector.

Extract the final (most recent) type from a version vector.

This traverses the vector structure to find the Final constructor.

Get the payload type at a specific version number.

This allows you to reference older payload versions in upgrade logic:

instance Upcast 0 "order_placed" where
  upcast :: PayloadVersion "order_placed" 0 -> PayloadVersion "order_placed" 1
  upcast v0 = ... -- upgrade OrderPlacedV0 to OrderPlacedV1

Extract the type at a specific version index.

Returns a compile error if the index is out of bounds.

Upgrade a payload from version ver to version ver + 1.

This class represents a single consecutive upgrade step. You define one instance for each version transition:

-- Upgrade from V0 to V1
instance Upcast 0 MyEvent where
  upcast v0 = V1 { newField = defaultValue, ... }

-- Upgrade from V1 to V2
instance Upcast 1 MyEvent where
  upcast v1 = V2 { anotherField = defaultValue, ... }

These consecutive upgrades are automatically composed to provide migrations from any old version to the latest via MigrateVersion.

Migrate a payload from any version to the latest version.

You must declare an instance for each version, but the method body is optional (uses automatic consecutive composition by default):

-- Automatic consecutive composition (V0 → V1 → V2)
instance MigrateVersion 0 MyEvent

-- Also automatic (V1 → V2)
instance MigrateVersion 1 MyEvent

-- Latest version (identity)
instance MigrateVersion 2 MyEvent

-- Override for direct upgrade (if needed)
instance MigrateVersion 0 MyEvent where
  migrateVersion v0 = V2 { ... }  -- Skip V1 if it loses information

Convert MaxVersion to Peano representation for type-level computation.

This is used internally by the consecutive upcast machinery to determine when a version is the latest.

Basic type constraints required for event payloads.

All payload types must be serializable to JSON for storage and transmission.

Build a version-aware parser map for an event.

Creates a map from version numbers to parsers that can deserialize event payloads at any version and automatically upgrade them to the latest.

This is used internally by store implementations when reading events from storage.

parseMap @"order_placed"
  = Map.fromList
      [ (0, parser that reads OrderPlacedV0 and upgrades to V2)
      , (1, parser that reads OrderPlacedV1 and upgrades to V2)
      , (2, parser that reads OrderPlacedV2 directly)
      ]

Convenience wrapper around parseMap that accepts a proxy argument.

Some contexts require explicit type application or proxy arguments. This function provides compatibility with such APIs.

Get the maximum version number for an event as a runtime integer.

Useful for debugging, logging, or runtime version checks:

getMaxVersion (Proxy @"order_placed") = 2  -- if MaxVersion "order_placed" = 2

Type-level Peano natural numbers.

These provide an alternative representation to GHC's Nat that's more suitable for structural recursion and pattern matching at the type level.

0 = PeanoZero
1 = PeanoSucc PeanoZero
2 = PeanoSucc (PeanoSucc PeanoZero)
...

Convert type-level Peano numbers to runtime integers.

This class allows us to "reify" type-level numbers into runtime values, which is necessary for parsing version numbers from JSON and other runtime operations.

Convert GHC's Nat to Peano representation.

This is needed because type families and data families use Nat, but we need PeanoNat for structural pattern matching.

Convert Peano representation back to GHC's Nat.

This is the inverse of ToPeanoNat and is needed for some constraint manipulations where GHC requires Nat.

Dictionary carrying constraint evidence.

This allows us to package up constraints and manipulate them at runtime. It's particularly useful for passing around evidence that certain type-level properties hold.

Example use: storing evidence that a payload satisfies serialization constraints so we can retrieve it later when needed.

Evidence that each version in a vector satisfies some constraint.

This GADT packages up constraint evidence for all elements in an EventVersions vector. It's structurally similar to the vector itself:

• VersionConstraintsLast - Evidence for a single-element vector
• VersionConstraintsCons - Evidence for the head, plus recursive evidence

The constraint c is indexed by version number and payload type:

c :: PeanoNat -> Type -> Constraint

Example: Prove all versions are serializable:

class (ToJSON payload, FromJSON payload) => Serializable (idx :: PeanoNat) payload
...
evidence :: VersionConstraints myVersions Serializable

Evidence that a type is a valid payload for a version.

This class packages up VersionPayloadRequirements into a Dict that can be passed around at runtime. Used internally by the parsing machinery.

Build constraint evidence for all elements in a version vector.

This class provides a way to automatically derive VersionConstraints evidence given:

1. Evidence that each individual version satisfies the constraint c
2. The structure of the version vector

The instances mirror the structure of EventVersions:

• Base case: single-element vector (Final)
• Inductive case: multi-element vector (Then)

Usage:

getEvidenceList :: VersionConstraints myVersions MyConstraint

Convenience alias for full version range evidence.

This is used in EventConstraints via the FullVersionRange alias.

Extract constraint evidence for all versions of an event.

Used internally by parsing and serialization machinery.

Core constraints required for event payloads at a specific version.

This bundles together all the requirements for a payload type at a given version index. You typically won't use this directly.

Type-level equality check with conditional results.

Returns thenResult if a and b are equal, elseResult otherwise.

This is used for version number matching.

PeanoEqual PeanoZero PeanoZero "yes" "no" = "yes"
PeanoEqual (PeanoSucc PeanoZero) PeanoZero "yes" "no" = "no"