recorded

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package recorded defines captured execution evidence and durable evaluation work.

Index

Constants

View Source 
const (
	// Unknown includes historical accounting without provenance.
	Unknown = evalrun.Unknown
	// Known identifies measured accounting.
	Known = evalrun.Known
	// Estimated identifies inferred accounting.
	Estimated = evalrun.Estimated
)

Variables

View Source 
var (
	// ErrConflict means an idempotency key, revision or lease no longer matches.
	ErrConflict = errors.New("sentinel: recorded evaluation conflict")
	// ErrNotFound means the exact scope has no matching recorded job.
	ErrNotFound = errors.New("sentinel: recorded evaluation not found")
)

Functions

func CursorStorageKey 

func CursorStorageKey(ctx context.Context, binding string) string

CursorStorageKey encodes exact app, tenant and binding identity.

func Encode 

func Encode(ctx context.Context, j *Job) ([]byte, error)

Encode validates records before crossing backend boundaries.

func InputDigest 

func InputDigest(input string) string

InputDigest identifies the exact UTF-8 input supplied to an execution.

func ValidateChange 

func ValidateChange(ctx context.Context, old, next *Job, now time.Time) error

ValidateChange enforces immutable inputs, append-only results and lease fences. A backend must also compare the old revision atomically when writing.

Types

type Case 

type Case struct {
	CaseID         id.CaseID         `json:"case_id"`
	Repetition     int               `json:"repetition"`
	InputDigest    string            `json:"input_digest"`
	Outcome        Outcome           `json:"outcome"`
	Output         string            `json:"output"`
	ExecutionError string            `json:"execution_error,omitempty"`
	Duration       time.Duration     `json:"duration_ns"`
	Usage          Usage             `json:"usage"`
	Trace          *evalrun.RunTrace `json:"trace,omitempty"`
	ArtifactRefs   []string          `json:"artifact_refs,omitempty"`
	SourceRunID    string            `json:"source_run_id,omitempty"`
}

Case is one captured execution. No executable target is part of the request.

func (Case) Key 

func (c Case) Key() string

Key identifies a case and repetition within a frozen evaluation.

type CaseResult 

type CaseResult struct {
	Key             string          `json:"key"`
	Result          *evalrun.Result `json:"result"`
	ScoringDuration time.Duration   `json:"scoring_duration_ns"`
	JudgeUsage      Usage           `json:"judge_usage"`
	ExecutionError  string          `json:"execution_error,omitempty"`
	ScoringError    string          `json:"scoring_error,omitempty"`
}

CaseResult records scoring separately from original execution accounting.

type CursorAdvance 

type CursorAdvance struct {
	BindingID        string
	ExpectedRevision int64
	JobID            id.ID
}

CursorAdvance acknowledges a persisted job. Position comes from that job, never from an unchecked caller-supplied high-water mark.

type Job 

type Job struct {
	ID            id.ID        `json:"id"`
	AppID         string       `json:"app_id"`
	TenantID      string       `json:"tenant_id"`
	Request       Request      `json:"request"`
	RequestDigest string       `json:"request_digest"`
	RunID         id.EvalRunID `json:"run_id"`
	Revision      int64        `json:"revision"`
	State         State        `json:"state"`
	Owner         string       `json:"owner,omitempty"`
	Generation    int64        `json:"generation"`
	LeaseUntil    time.Time    `json:"lease_until"`
	Attempts      int          `json:"attempts"`
	MaxAttempts   int          `json:"max_attempts"`
	Results       []CaseResult `json:"results"`
	Error         string       `json:"error,omitempty"`
	CreatedAt     time.Time    `json:"created_at"`
	UpdatedAt     time.Time    `json:"updated_at"`
}

Job stores an immutable request and append-only result checkpoints.

func Decode 

func Decode(ctx context.Context, data []byte) (*Job, error)

Decode validates records and detaches all nested values from storage.

func NewJob 

func NewJob(ctx context.Context, req Request) (*Job, error)

NewJob constructs detached queued work in the authenticated app and tenant.

func (*Job) Claim 

func (j *Job) Claim(owner string, ttl time.Duration, now time.Time) (*Job, error)

Claim creates the next fenced lease, or a terminal failure after bounded retries.

func (*Job) Clone 

func (j *Job) Clone() (*Job, error)

Clone detaches nested request data and result maps.

func (*Job) StorageKey 

func (j *Job) StorageKey() string

StorageKey hashes an unambiguous scope and idempotency tuple.

func (*Job) Terminal 

func (j *Job) Terminal() bool

Terminal reports whether work can no longer be claimed or changed.

func (*Job) Validate 

func (j *Job) Validate(ctx context.Context) error

Validate checks scope, request identity and every persisted result identity.

func (*Job) ValidateNew 

func (j *Job) ValidateNew(ctx context.Context) error

ValidateNew restricts insertion to a fresh queued request.

type Outcome 

type Outcome string

Outcome records how execution ended independently of evaluation status. 

const (
	// Completed means the executor reported a complete output.
	Completed Outcome = "completed"
	// Incomplete includes exhausted or truncated execution.
	Incomplete Outcome = "incomplete"
	// Failed means execution returned an error.
	Failed Outcome = "failed"
	// Cancelled means execution was cancelled.
	Cancelled Outcome = "cancelled"
	// Suspended means execution still requires external input.
	Suspended Outcome = "suspended"
	// UnknownOutcome covers historical records without termination provenance.
	UnknownOutcome Outcome = "unknown"
)

type Quality 

type Quality = evalrun.Quality

Quality identifies measured, estimated or unknown accounting.

type Query 

type Query struct {
	After  string
	Limit  int
	Active bool
}

Query pages jobs in ascending ID order. Active limits results to claimable work.

func (Query) PageLimit 

func (q Query) PageLimit() (int, error)

PageLimit returns a bounded limit shared by all backends.

type Request 

type Request struct {
	PlanID             id.ID  `json:"plan_id"`
	PlanDigest         string `json:"plan_digest"`
	IdempotencyKey     string `json:"idempotency_key"`
	SourceExperimentID string `json:"source_experiment_id,omitempty"`
	SourceCandidateID  string `json:"source_candidate_id,omitempty"`
	SourceBindingID    string `json:"source_binding_id,omitempty"`
	SourceCursor       string `json:"source_cursor,omitempty"`
	Cases              []Case `json:"cases"`
}

Request pins a plan and captured executions for idempotent ingestion.

func (Request) Digest 

func (r Request) Digest() (string, error)

Digest hashes the entire immutable request, including metric provenance.

func (Request) Validate 

func (r Request) Validate() error

Validate refuses missing identities, duplicate repetitions and invalid metrics.

type SourceCursor 

type SourceCursor struct {
	AppID     string    `json:"app_id"`
	TenantID  string    `json:"tenant_id"`
	BindingID string    `json:"binding_id"`
	Position  string    `json:"position"`
	JobID     id.ID     `json:"job_id"`
	Revision  int64     `json:"revision"`
	UpdatedAt time.Time `json:"updated_at"`
}

SourceCursor marks the latest acknowledged source event for one binding. Position uses a host-defined, lexically ordered completion-time/run-ID key.

func DecodeCursor 

func DecodeCursor(ctx context.Context, data []byte) (*SourceCursor, error)

DecodeCursor validates a stored cursor and returns a detached value.

func NextCursor 

func NextCursor(ctx context.Context, current *SourceCursor, j *Job, req CursorAdvance, now time.Time) (*SourceCursor, error)

NextCursor validates the durable acknowledgment and computes a monotonic CAS. An overlapping older event returns the current cursor without a write.

func (*SourceCursor) Validate 

func (c *SourceCursor) Validate(ctx context.Context) error

Validate checks scope and acknowledgment identity.

type State 

type State string

State is the durable recorded-evaluation lifecycle. 

const (
	// JobQueued is waiting for a worker.
	JobQueued State = "queued"
	// JobRunning has a lease, which may need recovery after expiry.
	JobRunning State = "running"
	// JobCompleted has a scored result for every captured case.
	JobCompleted State = "completed"
	// JobFailed stopped because of infrastructure failure or exhausted retries.
	JobFailed State = "failed"
	// JobCancelled retains partial results after explicit cancellation.
	JobCancelled State = "cancelled"
)

type Store 

type Store interface {
	GetRecordedCursor(context.Context, string) (*SourceCursor, error)
	AdvanceRecordedCursor(context.Context, CursorAdvance) (*SourceCursor, error)
	CreateRecordedJob(context.Context, *Job) (*Job, error)
	GetRecordedJob(context.Context, id.ID) (*Job, error)
	ListRecordedJobs(context.Context, Query) ([]*Job, error)
	UpdateRecordedJob(context.Context, int64, *Job) error
}

Store owns exactly scoped recorded jobs and atomic revision changes.

type Usage 

type Usage = evalrun.Usage

Usage keeps original accounting provenance.

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.