runlog

type AppendResult struct {
	// ID is the store-assigned opaque identifier for the canonical event.
	ID string
	// Inserted reports whether the event was newly inserted.
	Inserted bool
}

type Event struct {
	// ID is the store-assigned opaque identifier for this event.
	ID string
	// EventKey is the stable logical identity for this event within the run.
	// Append deduplicates on (run_id, event_key) while leaving ID as the
	// ordered cursor for pagination.
	EventKey string
	// RunID is the identifier of the run this event belongs to.
	RunID string
	// AgentID is the identifier of the agent that emitted the event.
	AgentID agent.Ident
	// SessionID groups related runs into a conversation thread.
	SessionID string
	// TurnID identifies the conversational turn within the session.
	TurnID string
	// Type is the hook event type.
	Type hooks.EventType
	// Payload is the canonical JSON-encoded payload for the event.
	Payload rawjson.Message
	// Timestamp is the event time.
	Timestamp time.Time
}

type Page struct {
	// Events are ordered oldest-first.
	Events []*Event
	// NextCursor is the cursor to use to fetch the next page.
	// It is empty when there are no further events.
	NextCursor string
}

type Store interface {
	// Append stores the event in the run log.
	//
	// Store implementations assign the event ID and persist the payload
	// verbatim. Append must be durable and idempotent on (run_id, event_key):
	// exact duplicates return the existing event ID with Inserted=false, while
	// conflicting bodies for the same key must fail loudly.
	Append(ctx context.Context, e *Event) (AppendResult, error)

	// List returns the next forward page of events for the given run ID.
	//
	// Cursor is an opaque value returned by a previous call to List (or empty
	// to start from the beginning). Limit must be greater than zero.
	List(ctx context.Context, runID string, cursor string, limit int) (Page, error)
}