Information Systems in Kotlin

Information systems as composable algebraic structures. Unifies state-stored (🏛️ store current state) and event-sourced (🌀 store past events) architectures under a single model.

typealias StateStoredSystem<Command, State> = (Command, State?) -> State
typealias EventSourcedSystem<Command, InEvent, OutEvent> = (Command, List<InEvent>) -> List<OutEvent>

The Journey: From General to Specific

The library is structured as a progression from the most general abstraction to practical implementations. Each file builds upon the previous one through specialization:

interface IGeneralSystem<in Command, in InState, out OutState, in InEvent, out OutEvent> {
    val decide: (Command, InState) -> List<OutEvent>
    val evolve: (InState, InEvent) -> OutState
    val initialState: () -> OutState

    //    We CAN NOT convert general system into EventSourcedSystem !!!
    //    fun asEventSourcedSystem(): EventSourcedSystem<Command, InEvent, OutEvent> =
    //        { command, events ->
    //           decide(command, events.fold(initialState()) { acc, event -> evolve(acc, event) })
    //         }

    //    We CAN NOT convert general system into StateStoredSystem !!!
    //    fun asStateStoredSystem(): StateStoredSystem<Command, State> =
    //        { command, state ->
    //            val current = state ?: initialState()
    //            decide(command, current).fold(current) { acc, event -> evolve(acc, event) }
    //        }
}

interface IDynamicSystem<in Command, State, in InEvent, out OutEvent> :
    IGeneralSystem<Command, State, State, InEvent, OutEvent> {

    fun asEventSourcedSystem(): EventSourcedSystem<Command, InEvent, OutEvent> =
        { command, events ->
            decide(command, events.fold(initialState()) { acc, event -> evolve(acc, event) })
        }
    //    We CAN NOT convert dynamic system into StateStoredSystem !!!
    //    fun asStateStoredSystem(): StateStoredSystem<Command, State> =
    //        { command, state ->
    //            val current = state ?: initialState()
    //            decide(command, current).fold(current) { acc, event -> evolve(acc, event) }
    //        }
}

interface ISystem<in Command, State, Event> : IDynamicSystem<Command, State, Event, Event> {

    fun asStateStoredSystem(): StateStoredSystem<Command, State> =
        { command, state ->
            val current = state ?: initialState()
            decide(command, current).fold(current) { acc, event -> evolve(acc, event) }
        }
}

Why conversions require type unification

Each level unlocks a new conversion, and the reason is purely type-level. The key operations are two folds:

Fold 1 — reconstruct state from events (needed by EventSourcedSystem):

events.fold(initialState()) { acc, event -> evolve(acc, event) }

initialState() returns OutState. evolve expects InState. If InState ≠ OutState, feeding the accumulator back in is a type error. This is why IGeneralSystem cannot produce an EventSourcedSystem — the loop can't close.

Fold 2 — fold output events back into state (needed by StateStoredSystem):

decide(command, current).fold(current) { acc, event -> evolve(acc, event) }

decide returns List<OutEvent>. evolve expects InEvent. If InEvent ≠ OutEvent, you can't pass output events into evolve. This is why IDynamicSystem (which already unifies state but not events) cannot produce a StateStoredSystem.

Only ISystem, which unifies both (InState == OutState == State and InEvent == OutEvent == Event), can close both folds and support both conversions.

System	InState == OutState	InEvent == OutEvent	→ EventSourcedSystem	→ StateStoredSystem
IGeneralSystem	✗	✗	✗ (Fold 1 breaks)	✗
IDynamicSystem	✓	✗	✓ full (InEvent ≠ OutEvent)	✗ (Fold 2 breaks)
ISystem	✓	✓	✓ limited (InEvent == OutEvent)	✓

The tradeoff at ISystem: constraining InEvent == OutEvent to unlock StateStoredSystem also weakens event sourcing. IDynamicSystem supports heterogeneous event types — you can read a InEvent and produce OutEvent. ISystem collapses these to a single Event type, so the events you read must be exactly the events you write.

┌─────────────────────────────────────────────────────────────────┐
│ IGeneralSystem<Command, InState, OutState, InEvent, OutEvent>  │
│ (5 type parameters - most general)                              │
│ • decide: (Command, InState) -> List<OutEvent>                  │
│ • evolve: (InState, InEvent) -> OutState                        │
│ • initialState: () -> OutState                                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ InState == OutState == State
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ IDynamicSystem<Command, State, InEvent, OutEvent>               │
│ extends IGeneralSystem<Command, State, State, InEvent, OutEvent>│
│ (4 type parameters)                                              │
│ • State types unified                                            │
│ • Can convert to EventSourcedSystem                              │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ InEvent == OutEvent == Event
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ ISystem<Command, State, Event>                                  │
│ extends IDynamicSystem<Command, State, Event, Event>            │
│ (3 type parameters - most common)                               │
│ • Event types unified                                            │
│ • Can convert to StateStoredSystem                               │
│ • Can convert to EventSourcedSystem (limited)                    │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Given-When-Then DSL
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ SystemSpecification (Testing DSL)                               │
│ • givenEvents / thenEvents (event-sourced, IDynamicSystem)      │
│ • givenState / thenState (state-stored, ISystem)                │
│ • whenCommand (identity for readability)                         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Add persistence + metadata + transactions
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ IStateRepository / IEventRepository                             │
│ (Infrastructure layer - metadata + transaction support)          │
│ • Metadata never leaks into domain                               │
│ • Explicit transaction handle (Txn), supplied via context param  │
│ • executeInTransaction (shared via ITransactional) / handle()    │
└─────────────────────────────────────────────────────────────────┘

1. GeneralSystem (5 type parameters)

src/1_GeneralSystem.kt — The foundation

The most general form that captures all possible information systems:

interface IGeneralSystem<Command, InState, OutState, InEvent, OutEvent> {
    val decide: (Command, InState) -> List<OutEvent>
    val evolve: (InState, InEvent) -> OutState
    val initialState: () -> OutState
}

This abstraction allows:

• Different input/output state types (InState ≠ OutState)
• Different input/output event types (InEvent ≠ OutEvent)
• Full functorial and profunctor transformations
• Monoidal composition via combine

2. DynamicSystem (4 type parameters)

src/2_DynamicSystem.kt — First specialization

Constrains state types to be equal: InState == OutState == State

interface IDynamicSystem<Command, State, InEvent, OutEvent> :
    IGeneralSystem<Command, State, State, InEvent, OutEvent>

This enables:

• Event-sourced systems (events can differ: InEvent ≠ OutEvent)
• State reconstruction from event sequences
• Conversion to EventSourcedSystem type alias

3. System (3 type parameters)

src/3_System.kt — Second specialization

Further constrains event types to be equal: InEvent == OutEvent == Event

interface ISystem<Command, State, Event> :
    IDynamicSystem<Command, State, Event, Event>

This is the most common form, enabling:

• Both state-stored and event-sourced architectures
• Conversion to StateStoredSystem type alias
• Conversion to EventSourcedSystem type alias (limited to InEvent == OutEvent)
• Full bidirectional system representation

Note: The constraint InEvent == OutEvent means this system can only handle event-sourced scenarios where the events you read are the same type as the events you produce. For more flexible event transformations (InEvent ≠ OutEvent), use DynamicSystem instead.

4. SystemSpecification (Testing DSL)

src/4_SystemSpecification.kt — Given-When-Then specification DSL

A lightweight DSL for specifying and verifying system behavior in both event-sourced and state-stored styles:

Event-sourced — given past events, when a command is issued, then expect new events:

counterSystem.givenEvents(emptyList()) {
    whenCommand(IncrementCounterCommand.Increment(5))
} thenEvents listOf(IncrementCounterEvent.Incremented(5, 5))

State-stored — given a current state, when a command is issued, then expect a new state:

counterSystem.givenState(CounterState(0, 0)) {
    whenCommand(IncrementCounterCommand.Increment(5))
} thenState CounterState(incValue = 5, decValue = 0)

Function	Role	Works with
givenEvents	Given	IDynamicSystem (InEvent ≠ OutEvent)
givenState	Given	ISystem (state-stored)
whenCommand	When	Any command type
thenEvents	Then	Asserts produced events match expected
thenState	Then	Asserts resulting state matches expected

5. StatefulSystem (Persistence layer)

src/5_StatefulSystem.kt — Practical implementation

Adds repository interfaces for persistence with metadata and explicit transaction support:

interface ITransactional<Txn> {
    suspend fun <T> executeInTransaction(block: suspend (Txn) -> T): T
}

interface IStateRepository<Command, CommandMetadata, State, StateMetadata, Txn> : ITransactional<Txn> {
    context(txn: Txn)
    suspend fun fetchState(command: Pair<Command, CommandMetadata>): Pair<State, StateMetadata>?

    context(txn: Txn)
    suspend fun save(state: Pair<State, CommandMetadata>): Pair<State, StateMetadata>

    context(system: StateStoredSystem<Command, State>)
    suspend fun handle(command: Pair<Command, CommandMetadata>): Pair<State, StateMetadata>
}

interface IEventRepository<Command, CommandMetadata, InEvent, InEventMetadata, OutEvent, OutEventMetadata, Txn> :
    ITransactional<Txn> {
    context(txn: Txn)
    suspend fun fetchEvents(command: Pair<Command, CommandMetadata>): List<Pair<InEvent, InEventMetadata>>

    context(txn: Txn)
    suspend fun save(
        events: List<OutEvent>,
        commandMetadata: CommandMetadata
    ): List<Pair<OutEvent, OutEventMetadata>>

    context(system: EventSourcedSystem<Command, InEvent, OutEvent>)
    suspend fun handle(command: Pair<Command, CommandMetadata>): List<Pair<OutEvent, OutEventMetadata>>
}

This provides:

• Separation of domain logic from persistence
• Explicit transaction handle (Txn) for atomicity — the fetch → compute → save sequence runs within a single transaction, with Txn threaded to fetchState/fetchEvents and save as a context parameter instead of an explicit argument
• Flexible locking strategy: pessimistic (e.g., SELECT ... FOR UPDATE) or optimistic (e.g., UPDATE ... WHERE version = ?)
• executeInTransaction factored into a shared ITransactional<Txn> interface, since the transaction lifecycle is identical for both repositories — only the persisted shape (state vs. events) differs
• Metadata support at infrastructure/application level

Metadata: Infrastructure Concern, Not Domain Concern

A key design principle: metadata exists only at the infrastructure/application boundaries and never leaks into the domain layer.

Domain systems (IGeneralSystem, IDynamicSystem, ISystem) remain pure and focused on business logic:

decide: (Command, State) -> List<Event>  // No metadata here

Metadata is introduced at the repository level for infrastructure concerns:

• Versioning and optimistic locking
• Audit trails (who, when, from where)
• Correlation IDs for distributed tracing
• Event sequence numbers and timestamps
• Tenant/user context for multi-tenancy

The handle method orchestrates the flow:

1. Fetch data with metadata from storage
2. Extract pure domain data and pass to domain system (metadata-free)
3. Domain system produces new data (pure business logic)
4. Attach metadata and persist

This separation keeps domain logic testable, composable, and free from infrastructure concerns.

Composition Through Context Parameters

handle takes the domain system as a context parameter rather than an explicit argument, so a caller supplies it by opening a context(...) block around the call:

context(orderRepository.asEventSourcedSystem()) {
    orderRepository.handle(placeOrderCommand to userContext)
}

This composition pattern:

• Explicit context, not hidden derivation: The domain system is derived once via asEventSourcedSystem() / asStateStoredSystem() (available on any IDynamicSystem/ISystem) and passed into scope explicitly at the call site
• Separation of concerns: Repository provides persistence (fetchEvents/fetchState, save, executeInTransaction), System provides domain logic
• No inheritance required: Composition through interfaces, not class hierarchies
• Metadata isolation: The domain system extracted via asEventSourcedSystem()/asStateStoredSystem() remains metadata-free

Example implementation:

class OrderSystem :
    ISystem<OrderCommand, OrderState, OrderEvent>,
    IEventRepository<OrderCommand, UserContext, OrderEvent, EventMetadata, OrderEvent, EventMetadata, Connection> {

    // Domain logic (pure)
    override val decide = { command: OrderCommand, state: OrderState -> emptyList<OrderEvent>() }
    override val evolve = { state: OrderState, event: OrderEvent -> state }
    override val initialState = { OrderState.empty() }

    // Infrastructure (with metadata and transactions)
    context(txn: Connection)
    override suspend fun fetchEvents(command: Pair<OrderCommand, UserContext>) =
        emptyList<Pair<OrderEvent, EventMetadata>>()

    context(txn: Connection)
    override suspend fun save(events: List<OrderEvent>, commandMetadata: UserContext) =
        emptyList<Pair<OrderEvent, EventMetadata>>()

    override suspend fun <T> executeInTransaction(block: suspend (Connection) -> T): T = block(connection)
}

// system is supplied explicitly via context - not derived automatically
context(orderSystem.asEventSourcedSystem()) {
    val result = orderSystem.handle(placeOrderCommand to userContext)
}

Algebraic View

Concept	Mathematical Structure	Notes
mapCommand	Contravariant Functor	Maps input command types
mapEvent	Profunctor (dimap)	Contravariant in input events, covariant in output
mapState	Profunctor (dimap)	Contravariant in input state, covariant in output
combine	Monoidal Product	Combines two systems into a product system
emptySystem	Monoidal Identity	Represents the "no-op" system (GeneralSystem<Nothing?, Unit, Nothing?>)

Why Systems Thinking Matters in the AI Era

As software engineering continues to raise the level of abstraction through AI, systems thinking becomes even more essential. While AI tools grow increasingly powerful at generating code, the real value lies in understanding how components interact, how decisions ripple through ecosystems, and how to design resilient, adaptable systems.

This library embodies that philosophy: composable algebraic structures that let you reason about system behavior at a higher level. When AI assists in implementation, your focus shifts to architecture, composition, and the invariants that matter—exactly where human insight creates the most value.

Data & Behaviour = Information (Algebra of the Business)

• Data (examples/api.kt): Commands, Events, State
• Behaviour (examples/domain.kt): Exhaustive pattern matching on data

📚 Learn More - fmodel.fraktalio.com