ledger

package
v0.3.128 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package ledger stores cr review runs in SQLite.

Index

Constants

View Source 
const (
	// SchemaVersion is the current ledger schema version.
	SchemaVersion = 2
	// DefaultBusyTimeout is the SQLite busy timeout configured at open.
	DefaultBusyTimeout = 5 * time.Second
)
View Source 
const (
	PlannedActionFailureClassTerminal = "terminal"
	PlannedActionFailureClassAuth     = "auth"
)

PlannedActionFailureClass values stored for terminal post-phase failures.

Variables

View Source 
var (
	// ErrClosed means a mutating operation was attempted after Store.Close.
	ErrClosed = errors.New("ledger: store closed")
	// ErrNotFound means a requested ledger row does not exist.
	ErrNotFound = errors.New("ledger: not found")
	// ErrInvalidInput means a caller supplied an invalid storage value.
	ErrInvalidInput = errors.New("ledger: invalid input")
	// ErrRunExists means AllocateRun recovery mode received an existing run id.
	ErrRunExists = errors.New("ledger: run already exists")
)

Functions

This section is empty.

Types

type AllocateRunParams 

type AllocateRunParams struct {
	PRKey           string
	PRURL           string
	RunID           string
	SHA             string
	BaseSHA         string
	Profile         string
	PostingIdentity string
	PostMode        PostMode
	StartedAt       time.Time
	ArtifactPath    string
}

AllocateRunParams contains the inputs needed to create a run row.

type Finding 

type Finding struct {
	FindingID    review.FindingID
	RunID        string
	SessionRowID string
	Severity     review.Severity
	FilePath     string
	Side         *review.DiffSide
	Line         *int64
	DiffPosition *int64
	Anchoring    review.Anchoring
	Body         string
}

Finding records one harness-assigned review finding.

type ListRunsForHeadScopeParams 

type ListRunsForHeadScopeParams struct {
	PRKey           string
	SHA             string
	Profile         string
	PostingIdentity string
}

ListRunsForHeadScopeParams identifies local rows for one PR/head/profile/identity scope.

type NamedSession 

type NamedSession struct {
	Name              string
	Profile           string
	Provider          string
	Adapter           string
	Model             string
	Host              string
	ProviderSessionID string
	CreatedAt         time.Time
	LastUsedAt        time.Time
}

NamedSession records cross-run provider session reuse metadata.

type Outcome 

type Outcome string

Outcome records a finalized run outcome. 

const (
	OutcomeIncomplete      Outcome = "incomplete"
	OutcomeApproved        Outcome = "approved"
	OutcomeRequestChanges  Outcome = "request_changes"
	OutcomeComment         Outcome = "comment"
	OutcomeNothingToReview Outcome = "nothing_to_review"
	OutcomeDryRun          Outcome = "dry_run"
	OutcomeAborted         Outcome = "aborted"
	OutcomeFailed          Outcome = "failed"
)

Outcome values.

func ParseOutcome 

func ParseOutcome(value string) (Outcome, error)

ParseOutcome parses a storage outcome.

func (Outcome) String 

func (o Outcome) String() string

func (Outcome) Valid 

func (o Outcome) Valid() bool

Valid reports whether o is a known run outcome.

type PR 

type PR struct {
	PRKey       string
	PRURL       string
	FirstSeenAt time.Time
}

PR is the stable pull-request identity row.

type PlannedAction 

type PlannedAction struct {
	ActionID     string
	RunID        string
	Kind         PlannedActionKind
	FindingID    *string
	ThreadID     *string
	PlannedAt    time.Time
	PayloadJSON  string
	Status       PlannedActionStatus
	Required     bool
	Attempts     int
	AttemptedAt  *time.Time
	PostedAt     *time.Time
	UpstreamID   *string
	Error        *string
	FailureClass *string
}

PlannedAction records one outbox action planned for a run.

type PlannedActionKind 

type PlannedActionKind string

PlannedActionKind identifies the host-side action to execute later. 

const (
	PlannedActionInlineComment PlannedActionKind = "inline_comment"
	PlannedActionThreadReply   PlannedActionKind = "thread_reply"
	PlannedActionResolveThread PlannedActionKind = "resolve_thread"
	PlannedActionRollupComment PlannedActionKind = "rollup_comment"
	PlannedActionSubmitReview  PlannedActionKind = "submit_review"
)

PlannedActionKind values.

func ParsePlannedActionKind 

func ParsePlannedActionKind(value string) (PlannedActionKind, error)

ParsePlannedActionKind parses a storage planned action kind.

func (PlannedActionKind) String 

func (k PlannedActionKind) String() string

func (PlannedActionKind) Valid 

func (k PlannedActionKind) Valid() bool

Valid reports whether k is a known planned action kind.

type PlannedActionStatus 

type PlannedActionStatus string

PlannedActionStatus records the durable outbox status for a planned action. 

const (
	PlannedActionPending        PlannedActionStatus = "pending"
	PlannedActionPosted         PlannedActionStatus = "posted"
	PlannedActionFailedTerminal PlannedActionStatus = "failed_terminal"
	PlannedActionSuperseded     PlannedActionStatus = "superseded"
	PlannedActionPlannedOnly    PlannedActionStatus = "planned_only"
)

PlannedActionStatus values.

func ParsePlannedActionStatus 

func ParsePlannedActionStatus(value string) (PlannedActionStatus, error)

ParsePlannedActionStatus parses a storage planned action status.

func (PlannedActionStatus) String 

func (s PlannedActionStatus) String() string

func (PlannedActionStatus) Valid 

func (s PlannedActionStatus) Valid() bool

Valid reports whether s is a known planned action status.

type PostMode 

type PostMode string

PostMode records whether a run is live or dry-run. 

const (
	PostModeLive   PostMode = "live"
	PostModeDryRun PostMode = "dry_run"
)

PostMode values.

func ParsePostMode 

func ParsePostMode(value string) (PostMode, error)

ParsePostMode parses a storage post mode.

func (PostMode) String 

func (m PostMode) String() string

func (PostMode) Valid 

func (m PostMode) Valid() bool

Valid reports whether m is a known post mode.

type Run 

type Run struct {
	RunID           string
	PRKey           string
	SHA             string
	BaseSHA         string
	Attempt         int
	Profile         string
	PostingIdentity string
	PostMode        PostMode
	StartedAt       time.Time
	HeartbeatAt     *time.Time
	CompletedAt     *time.Time
	Outcome         *Outcome
	ArtifactPath    string
	BlockingCount   int
	MajorCount      int
	MinorCount      int
	NitsCount       int
}

Run is one cr review invocation recorded in the ledger.

type Session 

type Session struct {
	SessionRowID      string
	RunID             string
	ProviderSessionID string
	Role              SessionRole
	AgentID           *string
	Adapter           string
	Model             string
	Effort            *string
	StartedAt         time.Time
	CompletedAt       *time.Time
	DurationMS        *int64
	TokensIn          *int64
	TokensOut         *int64
	CacheRead         *int64
	CacheCreate       *int64
	CostUSD           *float64
}

Session records LLM session usage for a run.

type SessionRole 

type SessionRole string

SessionRole records the role attached to an LLM session row. 

const (
	SessionRoleOrchestrator SessionRole = "orchestrator"
	SessionRoleReviewer     SessionRole = "reviewer"
)

SessionRole values.

func ParseSessionRole 

func ParseSessionRole(value string) (SessionRole, error)

ParseSessionRole parses a storage session role.

func (SessionRole) String 

func (r SessionRole) String() string

func (SessionRole) Valid 

func (r SessionRole) Valid() bool

Valid reports whether r is a known session role.

type Store 

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

Store owns the SQLite connection and serializes mutating ledger writes.

func Open 

func Open(ctx context.Context, path string) (*Store, error)

Open opens or creates a ledger database at path and applies migrations.

func (*Store) AllocateRun 

func (s *Store) AllocateRun(ctx context.Context, params AllocateRunParams) (Run, error)

AllocateRun creates a run and allocates its attempt transactionally.

func (*Store) Close 

func (s *Store) Close() error

Close stops the writer goroutine and closes the database.

func (*Store) CompleteRun 

func (s *Store) CompleteRun(ctx context.Context, runID string, outcome Outcome, completedAt time.Time) error

CompleteRun records the terminal post-phase outcome for a run.

func (*Store) DeleteNamedSession 

func (s *Store) DeleteNamedSession(ctx context.Context, name string) error

DeleteNamedSession deletes a named provider session row.

func (*Store) DeleteRun 

func (s *Store) DeleteRun(ctx context.Context, runID string) error

DeleteRun deletes a run and lets SQLite cascade child rows.

func (*Store) GetNamedSession 

func (s *Store) GetNamedSession(ctx context.Context, name string) (NamedSession, error)

GetNamedSession returns a named provider session row.

func (*Store) GetPR 

func (s *Store) GetPR(ctx context.Context, prKey string) (PR, error)

GetPR returns a pull-request identity row by key.

func (*Store) GetRun 

func (s *Store) GetRun(ctx context.Context, runID string) (Run, error)

GetRun returns a run by id.

func (*Store) GetSession 

func (s *Store) GetSession(ctx context.Context, sessionRowID string) (Session, error)

GetSession returns a session by internal row id.

func (*Store) InsertFinding 

func (s *Store) InsertFinding(ctx context.Context, finding Finding) error

InsertFinding inserts a validated harness finding row.

func (*Store) InsertPlannedAction 

func (s *Store) InsertPlannedAction(ctx context.Context, action PlannedAction) error

InsertPlannedAction inserts an outbox planned-action row.

func (*Store) InsertSession 

func (s *Store) InsertSession(ctx context.Context, session Session) error

InsertSession inserts an LLM session row.

func (*Store) ListFindings 

func (s *Store) ListFindings(ctx context.Context, runID string) ([]Finding, error)

ListFindings lists findings for a run in stable order.

func (*Store) ListNamedSessions 

func (s *Store) ListNamedSessions(ctx context.Context) ([]NamedSession, error)

ListNamedSessions returns named provider sessions in stable name order.

func (*Store) ListPlannedActions 

func (s *Store) ListPlannedActions(ctx context.Context, runID string) ([]PlannedAction, error)

ListPlannedActions lists planned actions for a run in stable order.

func (*Store) ListRuns 

func (s *Store) ListRuns(ctx context.Context) ([]Run, error)

ListRuns lists all runs in newest-first stable order.

func (*Store) ListRunsForHeadScope 

func (s *Store) ListRunsForHeadScope(ctx context.Context, params ListRunsForHeadScopeParams) ([]Run, error)

ListRunsForHeadScope lists runs for one PR/head/profile/identity across bases.

func (*Store) ListSessionsForRun 

func (s *Store) ListSessionsForRun(ctx context.Context, runID string) ([]Session, error)

ListSessionsForRun lists sessions for a run in stable order.

func (*Store) UpdateHeartbeat 

func (s *Store) UpdateHeartbeat(ctx context.Context, runID string, heartbeatAt time.Time) error

UpdateHeartbeat records the latest liveness timestamp for a run.

func (*Store) UpdatePlannedAction 

func (s *Store) UpdatePlannedAction(ctx context.Context, action PlannedAction) error

UpdatePlannedAction updates the mutable outbox state for an existing action.

func (*Store) UpsertNamedSession 

func (s *Store) UpsertNamedSession(ctx context.Context, session NamedSession) error

UpsertNamedSession inserts or updates a named provider session row.

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.