state

package
v1.10.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 4, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package state shares optimization storage invariants across persistence adapters.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Backend 

type Backend interface {
	Load(context.Context, string) ([]Record, error)
	LoadRecord(context.Context, string, RecordKey) ([]Record, error)
	Update(context.Context, string, func([]Record) ([]Mutation, error)) error
	Migrate(context.Context) error
	Ping(context.Context) error
	Close() error
}

Backend provides coherent exact-scope reads and serialized database updates. LoadRecord queries one indexed compound identity and returns at most one row. Update must acquire its database fence before reading, invoke the callback once, and atomically persist its mutations or none. It must never retry a callback or use a process-local lock as its only concurrency control.

type Mutation 

type Mutation struct {
	Record         Record
	ExpectedDigest string
}

Mutation updates one row. An empty ExpectedDigest requires an absent row. Database adapters must apply every mutation in the enclosing transaction.

type Option 

type Option func(*Store) error

Option configures shared storage behavior.

func WithClock 

func WithClock(now func() time.Time) Option

WithClock supplies trusted timestamps for transactions and lease tests.

type Record 

type Record struct {
	Schema int
	Scope  string
	Kind   string
	Parent string
	Key    string
	ID     string
	Digest string
	Body   []byte
}

Record is one versioned, exact-scope database row. ID hashes the compound key; the original components remain available for equality checks and indexes.

type RecordKey 

type RecordKey struct {
	Kind, Parent, Key string
}

RecordKey identifies one record without conflating parent and item keys.

func (RecordKey) ID 

func (k RecordKey) ID() string

ID returns the bounded primary lookup key used by durable backends.

type Store 

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

Store applies storage invariants and detaches caller-owned values at each boundary.

func New 

func New(options ...Option) (*Store, error)

New returns an empty, non-durable backend.

func NewBackend 

func NewBackend(backend Backend) *Store

NewBackend binds the shared invariants to a database adapter.

func (*Store) Close 

func (s *Store) Close() error

Close stops access and closes the adapter connection when present.

func (*Store) GetActivation 

func (s *Store) GetActivation(ctx context.Context, agentID id.AgentID, channel string) (optimization.Activation, error)

GetActivation returns the current generation for the exact scope and channel.

func (*Store) GetActivationForKind 

func (s *Store) GetActivationForKind(ctx context.Context, agentID id.AgentID, channel string, kind optimization.HarnessKind) (optimization.Activation, error)

GetActivationForKind resolves a controller or execution route independently.

func (*Store) GetActivationGeneration 

func (s *Store) GetActivationGeneration(ctx context.Context, activationID id.ID) (optimization.Activation, error)

GetActivationGeneration reads an immutable historical activation by ID.

func (*Store) GetArtifact 

func (s *Store) GetArtifact(ctx context.Context, ref optimization.ArtifactRef) (optimization.ArtifactRetention, error)

GetArtifact reads retention metadata without asserting current availability.

func (*Store) GetCandidate 

func (s *Store) GetCandidate(ctx context.Context, candidateID id.ID) (optimization.Candidate, error)

GetCandidate reads an immutable accepted or rejected proposal in exact scope.

func (*Store) GetCreationReceipt 

func (s *Store) GetCreationReceipt(ctx context.Context, commandKey string) (optimization.CreationReceipt, error)

GetCreationReceipt retrieves one exact-scope receipt without loading a catalog.

func (*Store) GetDecision 

func (s *Store) GetDecision(ctx context.Context, decisionID id.ID) (optimization.Decision, error)

GetDecision returns immutable selection evidence in the exact context scope.

func (*Store) GetDiscoveryLessons 

func (s *Store) GetDiscoveryLessons(ctx context.Context, experimentID id.ID) (optimization.DiscoveryLessons, error)

GetDiscoveryLessons returns one immutable comparison-local reflection.

func (*Store) GetEvaluation 

func (s *Store) GetEvaluation(ctx context.Context, evaluationID string) (optimization.Evaluation, error)

GetEvaluation reads immutable captured scoring evidence in exact scope.

func (*Store) GetExperiment 

func (s *Store) GetExperiment(ctx context.Context, entityID id.ID) (optimization.Experiment, error)

GetExperiment reads only the context's exact scope and returns detached content.

func (*Store) GetLesson 

func (s *Store) GetLesson(ctx context.Context, lessonID id.ID) (optimization.Lesson, error)

GetLesson reads local eligibility independently of remote publication progress.

func (*Store) GetPublication 

func (s *Store) GetPublication(ctx context.Context, lessonID id.ID, revision int64) (optimization.Publication, error)

GetPublication reads one immutable payload and its delivery metadata.

func (*Store) GetReservation 

func (s *Store) GetReservation(ctx context.Context, experimentID id.ID, callKey string) (optimization.Reservation, error)

GetReservation reads a call's conservative debit and complete receipt history.

func (*Store) GetTrial 

func (s *Store) GetTrial(ctx context.Context, trialID id.ID) (optimization.Trial, error)

GetTrial returns the immutable trial identity and every persisted attempt.

func (*Store) GetValidationAllocation 

func (s *Store) GetValidationAllocation(ctx context.Context, allocationID id.ID) (optimization.ValidationAllocation, error)

GetValidationAllocation returns the frozen roster and its exposure history.

func (*Store) GetVersion 

func (s *Store) GetVersion(ctx context.Context, entityID id.ID) (optimization.HarnessVersion, error)

GetVersion reads immutable prepared content without consulting live sources.

func (*Store) ListActivationHistory 

func (s *Store) ListActivationHistory(ctx context.Context, agentID id.AgentID, channel string, query optimization.PageQuery) (optimization.Page[optimization.Activation], error)

ListActivationHistory returns immutable generations even when the head is stale.

func (*Store) ListActivationHistoryForKind 

func (s *Store) ListActivationHistoryForKind(ctx context.Context, agentID id.AgentID, channel string, kind optimization.HarnessKind, query optimization.PageQuery) (optimization.Page[optimization.Activation], error)

ListActivationHistoryForKind keeps controller and execution history separate.

func (*Store) ListArtifactWork 

func (s *Store) ListArtifactWork(ctx context.Context, cutoff time.Time, query optimization.PageQuery) (optimization.Page[optimization.ArtifactRetention], error)

ListArtifactWork returns pending deletions and artifacts expired at cutoff, ordered by immutable registration time and binding digest. Keep cutoff fixed across pages. New work behind a cursor is discovered by the next full sweep. The output is bounded; durable backends currently hydrate the whole scope.

func (*Store) ListCandidates 

func (s *Store) ListCandidates(ctx context.Context, experimentID id.ID, query optimization.PageQuery) (optimization.Page[optimization.Candidate], error)

ListCandidates includes accepted and rejected proposals for one experiment.

func (*Store) ListDecisions 

func (s *Store) ListDecisions(ctx context.Context, experimentID id.ID, query optimization.PageQuery) (optimization.Page[optimization.Decision], error)

ListDecisions returns immutable selection evidence for an experiment.

func (*Store) ListEvaluations 

func (s *Store) ListEvaluations(ctx context.Context, experimentID id.ID, query optimization.PageQuery) (optimization.Page[optimization.Evaluation], error)

ListEvaluations orders captured jobs by their trusted local recording time.

func (*Store) ListEvents 

func (s *Store) ListEvents(ctx context.Context, experimentID id.ID, after int64, limit int) (optimization.Page[optimization.Event], error)

ListEvents returns monotonic audit entries after the supplied sequence.

func (*Store) ListExperiments 

func (s *Store) ListExperiments(ctx context.Context, query optimization.ListQuery) (optimization.Page[optimization.Experiment], error)

ListExperiments pages exact-scope records by creation time and ID.

func (*Store) ListLessons 

func (s *Store) ListLessons(ctx context.Context, query optimization.LessonQuery) (optimization.Page[optimization.Lesson], error)

ListLessons returns local records, optionally rechecking current eligibility.

func (*Store) ListPublications 

func (s *Store) ListPublications(ctx context.Context, query optimization.PublicationQuery) (optimization.Page[optimization.Publication], error)

ListPublications exposes pending, failed, completed and superseded local records.

func (*Store) ListReservations 

func (s *Store) ListReservations(ctx context.Context, experimentID id.ID, query optimization.PageQuery) (optimization.Page[optimization.Reservation], error)

ListReservations returns conservative debits and reconciliation history.

func (*Store) ListTrials 

func (s *Store) ListTrials(ctx context.Context, experimentID id.ID, query optimization.TrialQuery) (optimization.Page[optimization.Trial], error)

ListTrials returns the filtered original trials, including failed attempts.

func (*Store) ListValidationAllocations 

func (s *Store) ListValidationAllocations(ctx context.Context, experimentID id.ID, query optimization.PageQuery) (optimization.Page[optimization.ValidationAllocation], error)

ListValidationAllocations includes allocations owned or consumed by an experiment.

func (*Store) ListVersions 

func (s *Store) ListVersions(ctx context.Context, query optimization.VersionQuery) (optimization.Page[optimization.HarnessVersion], error)

ListVersions returns immutable versions in creation-time and ID order.

func (*Store) Migrate 

func (s *Store) Migrate(ctx context.Context) error

Migrate creates the adapter schema or checks process-local availability.

func (*Store) Ping 

func (s *Store) Ping(ctx context.Context) error

Ping reports cancellation or a closed store without requiring resource scope.

func (*Store) ResolveActivation 

func (s *Store) ResolveActivation(ctx context.Context, activationID id.ID) (optimization.Activation, error)

ResolveActivation checks retained evidence and lesson eligibility for a pinned generation without resolving the current head again.

func (*Store) ResolveDiscoveryLessons 

func (s *Store) ResolveDiscoveryLessons(ctx context.Context, consumerID id.ID, ref optimization.DiscoveryRef) (optimization.DiscoveryLessons, error)

ResolveDiscoveryLessons validates a frozen earlier-task reference for its consumer.

func (*Store) ResolveLesson 

func (s *Store) ResolveLesson(ctx context.Context, ref optimization.LessonRef) (optimization.Lesson, error)

ResolveLesson rechecks a frozen reference and its transitive source eligibility.

func (*Store) Transact 

func (s *Store) Transact(ctx context.Context, fn func(store.Tx) error) error

Transact commits a detached scope snapshot only after a successful callback.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.