executionledger

Documentation

Overview

Package executionledger provides a bounded, branch-aware record of turn execution. It is deliberately separate from transcript/session streaming: MemoryLayer (or another HistoryStore) owns what was said, while this ledger records operational boundaries and stable references needed to explain how a turn ran. Distributed hosts may persist the same contract in Aether KV.

Index

• Constants
• Variables
• type AppendRequest
• type AppendResult
• type AuditAuthorizer
• type CASStore
  • func NewCASStore(config CASStoreConfig) (*CASStore, error)
  • func (s *CASStore) Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)
  • func (s *CASStore) PinnedModel(ctx context.Context, ref Ref) (string, error)
  • func (s *CASStore) Query(ctx context.Context, ref Ref, query Query) (Page, error)
• type CASStoreConfig
• type Event
• type EventType
• type FileStore
  • func NewFileStore(config FileStoreConfig) (*FileStore, error)
  • func (s *FileStore) Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)
  • func (s *FileStore) PinnedModel(ctx context.Context, ref Ref) (string, error)
  • func (s *FileStore) Query(ctx context.Context, ref Ref, query Query) (Page, error)
• type FileStoreConfig
• type MemoryStore
  • func NewMemoryStore(config MemoryStoreConfig) *MemoryStore
  • func (s *MemoryStore) Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)
  • func (s *MemoryStore) PinnedModel(ctx context.Context, ref Ref) (string, error)
  • func (s *MemoryStore) Query(ctx context.Context, ref Ref, query Query) (Page, error)
• type MemoryStoreConfig
• type Page
• type Query
• type Ref
• type Reference
• type Service
  • func (s *Service) ObserveTurn(ctx context.Context, observed hooks.TurnEvent)
  • func (s *Service) PinModel(ctx context.Context, addr protocol.MessageAddress, model string) error
  • func (s *Service) PinnedModel(ctx context.Context, addr protocol.MessageAddress) (string, error)
  • func (s *Service) RunExecutionLedgerCommand(ctx context.Context, addr protocol.MessageAddress, user protocol.ChatMessage, ...) (string, error)
  • func (s *Service) String() string
• type Store

Constants

const (
	SchemaVersion     = 1
	DefaultMaxEvents  = 512
	DefaultQueryLimit = 20
	MaxQueryLimit     = 100
	MaxCursorBytes    = 8 << 10
)

Variables

var (
	ErrInvalid  = errors.New("executionledger: invalid input")
	ErrConflict = errors.New("executionledger: conflict")
	ErrCorrupt  = errors.New("executionledger: corrupt store")
)

var ErrCASRetryLimit = errors.New("executionledger: distributed update retry limit exceeded")

Types

type AppendRequest

type AppendRequest struct {
	Type      EventType  `json:"type"`
	BranchID  string     `json:"branch_id"`
	ParentID  string     `json:"parent_id,omitempty"`
	TaskID    string     `json:"task_id,omitempty"`
	MessageID string     `json:"message_id,omitempty"`
	Iteration int        `json:"iteration,omitempty"`
	Model     string     `json:"model,omitempty"`
	Outcome   string     `json:"outcome,omitempty"`
	Error     string     `json:"error,omitempty"`
	Reference *Reference `json:"reference,omitempty"`
}

type AppendResult

type AppendResult struct {
	Event    Event
	Replayed bool
}

type AuditAuthorizer

type AuditAuthorizer interface {
	AuthorizeExecutionLedger(context.Context, protocol.MessageAddress, protocol.ChatMessage) error
}

AuditAuthorizer is the enterprise policy seam in front of operator reads. The OSS composition leaves it nil under its single-user trust model.

type CASStore

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

func NewCASStore

func NewCASStore(config CASStoreConfig) (*CASStore, error)

func (*CASStore) Append

func (s *CASStore) Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)

func (*CASStore) PinnedModel

func (s *CASStore) PinnedModel(ctx context.Context, ref Ref) (string, error)

func (*CASStore) Query

func (s *CASStore) Query(ctx context.Context, ref Ref, query Query) (Page, error)

type CASStoreConfig

type CASStoreConfig struct {
	Blobs      casblob.Store
	Prefix     string
	MaxEvents  int
	MaxRetries int
	Now        func() time.Time
	NewID      func() (string, error)
}

type Event

type Event struct {
	SchemaVersion int    `json:"schema_version"`
	ID            string `json:"id"`
	Sequence      uint64 `json:"sequence"`
	WorkspaceID   string `json:"workspace_id"`
	SessionID     string `json:"session_id"`
	AppendRequest
	CreatedAt string `json:"created_at"`
}

type EventType

type EventType string

const (
	EventTurnStarted          EventType = "turn_started"
	EventUserPromptSubmitted  EventType = "user_prompt_submitted"
	EventModelCallStarted     EventType = "model_call_started"
	EventModelCallFinished    EventType = "model_call_finished"
	EventContextCompacted     EventType = "context_compacted"
	EventModelPinned          EventType = "model_pinned"
	EventGoalReferenced       EventType = "goal_referenced"
	EventRefinementReferenced EventType = "refinement_referenced"
	EventSkillReferenced      EventType = "skill_referenced"
	EventRecoveryMarker       EventType = "recovery_marker"
	EventTurnFinished         EventType = "turn_finished"
)

type FileStore

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

func NewFileStore

func NewFileStore(config FileStoreConfig) (*FileStore, error)

func (*FileStore) Append

func (s *FileStore) Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)

func (*FileStore) PinnedModel

func (s *FileStore) PinnedModel(ctx context.Context, ref Ref) (string, error)

func (*FileStore) Query

func (s *FileStore) Query(ctx context.Context, ref Ref, query Query) (Page, error)

type FileStoreConfig

type FileStoreConfig struct {
	StateDir  string
	MaxEvents int
	Now       func() time.Time
	NewID     func() (string, error)
}

type MemoryStore

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

func NewMemoryStore

func NewMemoryStore(config MemoryStoreConfig) *MemoryStore

func (*MemoryStore) Append

func (s *MemoryStore) Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)

func (*MemoryStore) PinnedModel

func (s *MemoryStore) PinnedModel(ctx context.Context, ref Ref) (string, error)

func (*MemoryStore) Query

func (s *MemoryStore) Query(ctx context.Context, ref Ref, query Query) (Page, error)

type MemoryStoreConfig

type MemoryStoreConfig struct {
	MaxEvents int
	Now       func() time.Time
	NewID     func() (string, error)
}

type Page

type Page struct {
	Events        []Event `json:"events"`
	NextPageToken string  `json:"next_page_token,omitempty"`
	ScannedCount  int     `json:"scanned_count"`
}

type Query

type Query struct {
	Types       []EventType `json:"types,omitempty"`
	BranchID    string      `json:"branch_id,omitempty"`
	TaskID      string      `json:"task_id,omitempty"`
	ReferenceID string      `json:"reference_id,omitempty"`
	Limit       int         `json:"limit,omitempty"`
	PageToken   string      `json:"page_token,omitempty"`
}

type Ref

type Ref struct {
	WorkspaceID string `json:"workspace_id"`
	SessionID   string `json:"session_id"`
}

type Reference

type Reference struct {
	System string `json:"system"`
	Kind   string `json:"kind"`
	ID     string `json:"id"`
}

Reference points at an authoritative record without copying it into the execution plane. System names the authority (for example goal-store, refinement-store, or turnjournal); Kind is its record type/phase.

type Service

type Service struct {
	Store           Store
	Authority       string
	AuditAuthorizer AuditAuthorizer
}

func (*Service) ObserveTurn

func (s *Service) ObserveTurn(ctx context.Context, observed hooks.TurnEvent)

func (*Service) PinModel

func (s *Service) PinModel(ctx context.Context, addr protocol.MessageAddress, model string) error

PinModel durably records a thread-local model selection. Persistence happens before the runner updates its in-memory cache, so a failed write cannot make the current process claim a pin that will disappear on restart.

func (*Service) PinnedModel

func (s *Service) PinnedModel(ctx context.Context, addr protocol.MessageAddress) (string, error)

func (*Service) RunExecutionLedgerCommand

func (s *Service) RunExecutionLedgerCommand(ctx context.Context, addr protocol.MessageAddress, user protocol.ChatMessage, args string) (string, error)

func (*Service) String

func (s *Service) String() string

type Store

type Store interface {
	Append(ctx context.Context, ref Ref, operationID string, request AppendRequest) (AppendResult, error)
	Query(ctx context.Context, ref Ref, query Query) (Page, error)
	PinnedModel(ctx context.Context, ref Ref) (string, error)
}