history

type Clearer ¶

type Clearer interface {
	// Clear removes the complete conversation and is idempotent when it is
	// already absent. Implementations must honor ctx.
	Clear(ctx context.Context, conversationID ConversationID) error
}

Clearer removes every message for one conversation.

type CommitError ¶ added in v0.20.0

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

CommitError means model generation completed but history persistence failed. It owns the exact batch submitted to Write, so recovery need not call the model again. Outcome governs whether a suffix is safe to submit: uncertain writes require reconciliation, and Accepted messages must not be appended again. During streaming this error can follow the terminal model delta.

func (c *CommitError) ConversationID() ConversationID

func (c *CommitError) Error() string

func (c *CommitError) Messages() []chat.Message

func (c *CommitError) Outcome() WriteOutcome

func (c *CommitError) Unwrap() error

type ConversationID ¶

type ConversationID string

ConversationID identifies one history partition. Its zero value is invalid. Use NewConversationID when converting runtime input; string constants may be converted directly when the value is known at compile time.

func ConversationIDFromContext(ctx context.Context) (ConversationID, bool)

func NewConversationID(value string) (ConversationID, error)

func (c ConversationID) String() string

func (c ConversationID) Validate() error

type Lister ¶

type Lister interface {
	// Conversations returns detached, unique identifiers in lexical order. An
	// empty store yields a non-nil empty slice; concurrent writes may appear or
	// not according to the backend's snapshot boundary.
	Conversations(ctx context.Context) ([]ConversationID, error)
}

Lister enumerates unique conversation IDs in lexical order. Implementations return a non-nil empty slice when no conversations exist. Concurrent mutations may affect the result.

type Middleware ¶

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

Middleware replays and persists history around synchronous and streaming chat capabilities. It is immutable after construction and safe for concurrent use when its Store is safe for concurrent use. This does not serialize complete Read/model/Write turns for the same conversation. The Host must serialize those turns across all instances if ordering is required; different conversations may proceed concurrently.

func NewMiddleware(store ReadWriter) (Middleware, error)

func (m Middleware) Call(next chat.Model) chat.Model

func (m Middleware) Stream(next chat.Streamer) chat.Streamer

type ReadWriter ¶

type ReadWriter interface {
	Reader
	Writer
}

ReadWriter combines the capabilities required by components that replay and append history without owning retention or deletion policy.

type Reader ¶

type Reader interface {
	// Read returns a detached snapshot in stored order. Unknown conversations
	// yield a non-nil empty slice; implementations honor ctx and never expose
	// mutable backing storage.
	Read(ctx context.Context, conversationID ConversationID) ([]chat.Message, error)
}

Reader returns the messages to replay for one conversation. Implementations return a non-nil empty slice for an unknown conversation and transfer ownership of returned protocol values to the caller.

type Sequence ¶ added in v0.16.0

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

Sequence assigns the positions a store writes alongside its messages.

Writer promises that one Write reads back in argument order, and a store that derives positions from the wall clock cannot keep that promise by itself: a clock that steps backward — an NTP correction, a suspended host — would place a later batch before an earlier one, and messages inside a single batch can land on the same instant however fine the clock's resolution. A Sequence hands out a contiguous, strictly increasing run per call and never reissues a position it has already given out, which is what makes the ordering the contract advertises hold.

A Sequence orders the writes made through one value. Ordering across separate Store instances stays implementation-defined, as Writer says.

func NewSequence(stride time.Duration) (*Sequence, error)

func (s *Sequence) Reserve(count int) int64

type Store ¶

type Store interface {
	ReadWriter
	Clearer
}

Store is the ordinary per-conversation read/write/clear contract. Optional cross-conversation or retention capabilities remain separate interfaces.

type WindowStore ¶

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

WindowStore projects reads to at most limit messages while preserving a merged system message followed by a suffix of complete conversation turns. A user message starts a turn; every following assistant and tool message remains in that turn until the next user message. Writes and clears pass through to the authoritative Store. Read returns ErrWindowTooSmall rather than splitting the newest complete turn, and the merged system message counts toward the configured limit.

func NewWindowStore(store Store, limit int) (WindowStore, error)

func (w WindowStore) Clear(ctx context.Context, conversationID ConversationID) error

func (w WindowStore) Read(ctx context.Context, conversationID ConversationID) ([]chat.Message, error)

func (w WindowStore) Write(ctx context.Context, conversationID ConversationID, messages ...chat.Message) (WriteOutcome, error)

type WriteOutcome ¶ added in v0.20.0

type WriteOutcome struct {
	Accepted  int
	Uncertain bool
}

WriteOutcome describes the acknowledged facts of one Write attempt. It never implies idempotency or rollback. The zero value confirms that nothing was written. Accepted counts the confirmed prefix in argument order. Uncertain means additional messages after that prefix may have been stored; the caller must reconcile them before retrying. Otherwise all remaining messages are confirmed unwritten. All messages may be accepted even if ancillary work fails.

func (w WriteOutcome) Validate(count int, err error) error

type Writer ¶

type Writer interface {
	// Write validates and snapshots the full argument batch before appending it
	// in argument order. The outcome must account for every acknowledged or
	// uncertain effect even on error; validation failures return the zero outcome.
	// A nil error acknowledges the complete batch.
	Write(ctx context.Context, conversationID ConversationID, messages ...chat.Message) (WriteOutcome, error)
}

Writer appends messages to one conversation. Implementations preserve the order of messages within each call, validate and snapshot them before returning, and prevent later caller mutation from altering stored history. The relative order of concurrent calls and writes issued through distinct Store instances is implementation-defined.