Concepts

Events (Type System + Schema)

Events are typed messages that flow through the system. Each event has a name, a payload schema (validated at runtime via Effect Schema), and automatically-attached metadata (run ID, timestamps, correlation IDs).

Defining Events

Use AgentNetworkEvent.of() to define an event with a name and a payload schema:

TypeScript

import { AgentNetworkEvent, S } from '@m4trix/core/matrix';

const userMessage = AgentNetworkEvent.of(
  'user-message',
  S.Struct({
    text: S.String,
    userId: S.optional(S.String),
  }),
);

The resulting event definition is a constant you reference throughout your code — in agent factories, network setup, and expose configuration.

Event Envelope

Every event flowing through the system is wrapped in an envelope:

TypeScript

{
  name: 'user-message',        // Event name (literal type)
  meta: {
    runId: 'uuid-...',         // Unique run identifier
    contextId: '...',          // Optional context grouping
    eventId: '...',            // Unique event id (set on publish)
    correlationId: '...',      // Shared by an emitAndAwait request and its replies
    causationId: '...',        // eventId of the event whose handling emitted this one
    ts: 1700000000000,         // Publish time, epoch ms (set on publish)
    depth: 1,                  // Hops from the run's start event (start event: 0)
  },
  payload: {
    text: 'Hello!',            // Validated against the schema
    userId: 'user-123',
  },
}

The meta fields are automatically managed by the runtime. You only need to provide the name and payload when emitting events from agents.

API Summary

Method	Description
`AgentNetworkEvent.of(name, schema)`	Creates an event definition
`.make(payload)`	Creates an unbound event for `emit`; meta injected at runtime
`.makeBound(meta, payload)`	Creates full envelope for tests or manual triggers
`.makeEffect(payload)`	Effect version of `make`
`.makeBoundEffect(meta, payload)`	Effect version of `makeBound`
`.decode(unknown)`	Decodes unknown value into validated envelope
`.is(value)`	Type guard for event shape

See AgentNetworkEvent API for full details.