state

Documentation

Overview

Package state defines the State interface and supporting types for ore's conversation history model.

State is a mutable interface: Append() mutates in place. Turns() returns a defensive copy of the internal slice so providers can safely iterate without synchronization. The in-memory implementation (Buffer) is intentionally not goroutine-safe; concurrency control is a future middleware concern.

Package state defines the State interface and supporting types for ore's conversation history model.

Index

• func WithClock(c Clock) func(*Buffer)
• type Buffer
  • func NewBuffer(opts ...func(*Buffer)) *Buffer
  • func (m *Buffer) Append(role Role, artifacts ...artifact.Artifact)
  • func (m *Buffer) LoadTurns(turns []Turn)
  • func (m *Buffer) Meta() Meta
  • func (m *Buffer) Turns() []Turn
• type Clock
• type Meta
• type Role
• type State
  • func NewView(base State, turns []Turn) State
  • func Prepend(base State, virtual []Turn) State
• type Turn
  • func (t Turn) MarshalJSON() ([]byte, error)
• type View
  • func (v *View) Append(role Role, artifacts ...artifact.Artifact)
  • func (v *View) Meta() Meta
  • func (v *View) Turns() []Turn

Functions

func WithClock

func WithClock(c Clock) func(*Buffer)

WithClock configures Buffer to use a custom Clock for turn timestamps. If not used, Buffer defaults to the real wall-clock time.

Types

type Buffer

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

Buffer is a simple in-memory implementation of State. It is not safe for concurrent use.

func NewBuffer

func NewBuffer(opts ...func(*Buffer)) *Buffer

NewBuffer creates a Buffer with optional functional options.

func (*Buffer) Append

func (m *Buffer) Append(role Role, artifacts ...artifact.Artifact)

Append adds a new turn to the in-memory state, recording the current time from its configured Clock.

func (*Buffer) LoadTurns

func (m *Buffer) LoadTurns(turns []Turn)

LoadTurns replaces the internal turn slice with the provided turns. It is intended for deserialization paths that must preserve timestamps rather than re-Append them (which would overwrite timestamps).

func (*Buffer) Meta

func (m *Buffer) Meta() Meta

Meta returns the metadata handle for this buffer. The handle is live: reads and writes operate on the buffer's internal map. Multiple calls return handles that share the same backing storage, so writes through one are visible through any other.

As with the rest of Buffer's API, the Meta handle is not safe for concurrent use; the same serial-call contract applies.

func (*Buffer) Turns

func (m *Buffer) Turns() []Turn

Turns returns a defensive copy of the internal turn slice. Note: this is a shallow copy of the slice itself; the Artifacts slices within each Turn are not deep-copied.

type Clock

type Clock interface {
	Now() time.Time
}

Clock provides the current time for Buffer to set turn timestamps. Implementations can be swapped for deterministic testing.

type Meta

type Meta interface {
	// Get returns the value stored for key and a boolean indicating
	// whether the key was present.
	Get(key string) (string, bool)

	// Set stores value under key, replacing any prior value.
	Set(key, value string)

	// All returns a defensive copy of the metadata map. Mutating
	// the returned map does not affect the underlying state.
	All() map[string]string
}

Meta is the metadata context carried by a State. It mirrors the shape of context.Context but is keyed on string identifiers and is mutable: a conversation's metadata grows over time as turns are appended and processors add facts about the conversation as a whole (e.g. compaction boundaries, future checkpoint markers).

Meta values are produced by State.Meta; they are not constructed directly. Each call to State.Meta returns a handle backed by the same underlying storage, so writes made through one handle are visible through any other handle for the same State.

Concurrency: like State itself (and its in-memory implementation Buffer), Meta is not safe for concurrent use. The framework's serial pipeline — the loop worker goroutine, the Transform chain, the session's worker — is the only contract; concurrent access from outside that pipeline is a future middleware concern.

type Role

type Role string

Role represents the role of a participant in a conversation turn.

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type State

type State interface {
	// Turns returns a defensive copy of the turn history.
	Turns() []Turn

	// Append adds a new turn to the state. It mutates in place.
	Append(role Role, artifacts ...artifact.Artifact)

	// Meta returns the metadata context for this state. The handle
	// is live — writes propagate to the underlying state and are
	// visible to subsequent reads. See the [Meta] contract for
	// the serialization format and concurrency expectations.
	Meta() Meta
}

State is a mutable conversation state that the core loop appends to.

func NewView

func NewView(base State, turns []Turn) State

NewView creates a state wrapper that returns the given turns from Turns() and delegates Append() to the base state. If turns is empty or nil, it returns the base state directly as an identity optimization.

func Prepend

func Prepend(base State, virtual []Turn) State

Prepend returns a State view that projects virtual turns before the base state's current turns on every call to Turns(). Append() delegates to the base state. If virtual is empty, it returns the base state directly as an identity optimization.

type Turn

type Turn struct {
	Role      Role                `json:"role"`
	Artifacts []artifact.Artifact `json:"artifacts"`
	Timestamp time.Time           `json:"timestamp,omitempty"`
}

Turn represents a single turn in the conversation history.

func (Turn) MarshalJSON

func (t Turn) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, omitting the zero timestamp.

type View

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

View is a general State wrapper that returns a caller-provided slice of turns from Turns() while delegating Append() to a base State. This enables arbitrary state projections (compaction, filtering, reordering) without mutating the persistent conversation buffer.

func (*View) Append

func (v *View) Append(role Role, artifacts ...artifact.Artifact)

Append delegates to the underlying base state.

func (*View) Meta

func (v *View) Meta() Meta

Meta delegates to the base state. Views do not own metadata; they are projections of turns. Writes through a View's Meta are visible on the base state.

func (*View) Turns

func (v *View) Turns() []Turn

Turns returns a defensive copy of the projected turns.