events

type Bus ¶

type Bus struct {
	// contains filtered or unexported fields
}

Bus is an in-process publish/subscribe spine. Publish is non-blocking with respect to every subscriber regardless of delivery mode.

Durability here means guaranteed in-process, in-order delivery to durable subscribers. Cross-restart persistence (an events table with replay) is a later layer behind this same interface — see design §8 open decision #1.

func NewBus() *Bus

func (b *Bus) Close()

func (b *Bus) Publish(e Event) Event

func (b *Bus) Subscribe(mode DeliveryMode, filter func(Event) bool) *Subscription

type DeliveryMode ¶

type DeliveryMode int

DeliveryMode controls how a subscriber tolerates backpressure.

const (
	// Lossy drops events when the subscriber's buffer is full rather than
	// blocking the publisher. Correct for a UI that can miss a frame.
	Lossy DeliveryMode = iota
	// Durable never drops: events queue without bound until delivered, in
	// order. Correct for reactive triggers, which must not miss a creak.
	Durable
)

type Event ¶

type Event struct {
	ID     string
	Type   string
	Data   map[string]any
	Origin *Origin
	Time   time.Time
}

Event is a single occurrence on the spine. Type is a dotted noun.verb string (e.g. "agent.completed"). Data carries the event-specific payload. ID and Time are stamped by the bus at Publish if left zero.

type Origin ¶

type Origin struct {
	EventID   string // the event that triggered the run that emitted this one
	AgentName string // the agent whose reactive run emitted it
	Depth     int    // reactive-chain depth
}

Origin carries typed causation — what caused this event. It is nil for external/root events (a human message, a cron fire, a sensor). When a reactive run emits events, they inherit the triggering event's Origin with Depth incremented, which is what the loop guard uses to cap reactive chains (design D2 / §5.3).

func OriginFromContext(ctx context.Context) *Origin

type Subscription ¶

type Subscription struct {
	C <-chan Event
	// contains filtered or unexported fields
}

Subscription is a handle to a stream of events. Read from C.

func (s *Subscription) Close()