db

package
v1.55.0 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	InvocationModeCold     = "cold"     // no durable session involved
	InvocationModeStarted  = "started"  // began a new durable session
	InvocationModeResumed  = "resumed"  // resumed an existing durable session
	InvocationModeFallback = "fallback" // fresh session after a failed resume
)

Agent invocation session modes recorded for local performance telemetry.

View Source 
const (
	FallbackReasonTransient   = "transient"   // retryable provider/transport error
	FallbackReasonParse       = "parse"       // could not parse the resumed output
	FallbackReasonExit        = "exit"        // resumed process exited non-zero
	FallbackReasonSpawn       = "spawn"       // resumed process failed to start
	FallbackReasonUnsupported = "unsupported" // adapter rejected a resume flag
	FallbackReasonQuota       = "quota"       // provider quota exhausted on the session's lane
	FallbackReasonOther       = "other"       // anything else
)

Fallback reasons classify why a resume failed and forced a fresh-session retry. They are low-cardinality and content-free (never the error text, which can embed agent output), so a silent-fallback regression is both countable and diagnosable from telemetry alone.

View Source 
const (
	RoundSelectionSourceUser    = "user"
	RoundSelectionSourceAutoFix = "auto_fix"
)
View Source 
const RunIntentSourceAgent = "agent"

RunIntentSourceAgent is the intent_source value stamped when the driving agent supplied the intent explicitly via `axi run --intent`. It marks an authoritative, author-stated goal (score 1) as opposed to a transcript inference (whose source is the matched agent name: "claude", "codex", ...). Prompt-construction code branches on this to frame an explicit intent as authoritative acceptance criteria rather than a low-confidence hint.

View Source 
const RunIntentSourceRerun = "rerun"

RunIntentSourceRerun marks an authoritative intent inherited from the run selected for a rerun. It remains authoritative, but the distinct value keeps inherited intent inspectable instead of confusing it with a new override.

Variables

This section is empty.

Functions

func IsAuthoritativeRunIntentSource 

func IsAuthoritativeRunIntentSource(source string) bool

IsAuthoritativeRunIntentSource reports whether a run's intent came from an explicit operator/agent contract, either directly or through rerun inheritance.

Types

type AgentInvocation 

type AgentInvocation struct {
	ID       string
	RunID    string
	StepName string
	Round    int
	// Purpose is the pipeline duty served: review, review-fix,
	// test-evidence, housekeeping, document, lint, pr, intent, or a
	// step-derived default.
	Purpose string
	// Agent is the configured adapter kind (for example claude or codex).
	Agent string
	// ResolvedExecutable is the absolute, symlink-resolved executable invoked.
	// Nil means it could not be resolved before the invocation.
	ResolvedExecutable *string
	// Model is the model reported by the adapter. Nil means the adapter did not
	// surface one; it is never inferred from the configured agent kind.
	Model *string
	// ModelArgs contains only argv entries that select a model/provider. A
	// non-nil empty slice means the invocation argv was inspected and contained
	// no selectors; nil means argv identity was unavailable (including old rows).
	ModelArgs []string
	// ModelProvider is the provider that served the model (openai, anthropic,
	// ...). Nil when the adapter cannot report it.
	ModelProvider *string
	// SessionMode is one of the InvocationMode constants.
	SessionMode string
	// SessionKey is a privacy-safe fingerprint (truncated SHA-256) of the
	// adapter-native session identity, so session reuse is auditable without
	// storing the raw resumable identity in a second place.
	SessionKey string
	// FallbackReason classifies why a fallback invocation happened (one of the
	// FallbackReason constants). Nil unless SessionMode is fallback.
	FallbackReason  *string
	StartedAt       int64
	CompletedAt     int64
	DurationMS      int64
	ExitStatus      string // ok | error | cancelled
	FailureCategory string // parse | exit | spawn | quota | cancelled | other ("" when ok)
	InputTokens     int
	OutputTokens    int
	CacheReadTokens int
	// CacheCreationTokens is the provider's cache-creation cost. Nil when the
	// provider does not surface it (codex), distinguishing "not reported" from a
	// genuine zero.
	CacheCreationTokens *int
	// FreshInputTokens is InputTokens minus CacheReadTokens: the non-cached
	// portion of this invocation's input. Nil when no usage was reported.
	FreshInputTokens *int
	// ReasoningTokens is the model's hidden-reasoning output tokens, when the
	// provider reports them. Nil when not reported.
	ReasoningTokens *int
	// SubprocessWaitMS is the wall-clock this invocation spent inside tool
	// subprocesses; DurationMS minus it is model/reasoning time. Nil when the
	// adapter reported no activity metrics.
	SubprocessWaitMS *int64
	// Delta* are the per-round token amounts for resumed durable sessions whose
	// raw counters are cumulative: current cumulative minus the same session's
	// prior cumulative. For cold/started/fallback rows they equal the raw
	// counters. Nil when no usage was reported.
	DeltaInputTokens     *int
	DeltaOutputTokens    *int
	DeltaCacheReadTokens *int
	// ModelRoundtrips is the count of model-authored items (messages + tool
	// calls) - a live-stream proxy for productive model round-trips. Nil when
	// the adapter reported no activity metrics.
	ModelRoundtrips *int
	// ToolCalls is the count of whole tool invocations. Nil when unknown.
	ToolCalls *int
	// Tool*Calls is the bounded per-category sub-command histogram. Because a
	// compound command counts once per sub-command, their sum can exceed
	// ToolCalls. Nil when the adapter reported no activity metrics.
	ToolWaitCalls     *int
	ToolTestLintCalls *int
	ToolEditCalls     *int
	ToolReadCalls     *int
	ToolGitCalls      *int
	ToolOtherCalls    *int
	// WorkloadFiles and WorkloadLines record the bounded size of the change this
	// invocation worked over. Nil for invocations with no meaningful workload
	// (or steps that do not supply it).
	WorkloadFiles *int
	WorkloadLines *int
	// FindingCount is the number of findings in this invocation's structured
	// output. Nil when the output is not findings-shaped.
	FindingCount *int
}

AgentInvocation is one agent process invocation's local performance evidence. It stores identity, timing, session mode, bounded activity counts, and token usage only - never prompts, model outputs, diffs, full command arguments, or credentials. The only argv retained is the allowlisted subset that selects a model/provider. The record stays local: no per-invocation identity is ever sent to remote telemetry.

Fields typed as pointers are nullable: a nil value means the datum was not reported for this invocation and is recorded as unknown, never a fabricated zero. Pre-existing rows created before these columns existed read back as nil, so they too report unknown honestly.

type AgentInvocationAggregate 

type AgentInvocationAggregate struct {
	Purpose          string
	Count            int
	TotalDurationMS  int64
	AvgDurationMS    int64
	SubprocessWaitMS *int64
	Cold             int
	Started          int
	Resumed          int
	Fallback         int
	Errors           int
	// Quota counts the invocations in Errors that failed on provider quota
	// exhaustion (failure_category = "quota"), so quota cost is answerable
	// per purpose without reading per-run detail.
	Quota               int
	InputTokens         int64
	OutputTokens        int64
	CacheReadTokens     int64
	CacheCreationTokens *int64
	FreshInputTokens    *int64
	ReasoningTokens     *int64
	ModelRoundtrips     *int64
	ToolCalls           *int64
	ToolWaitCalls       *int64
	ToolTestLintCalls   *int64
	ToolEditCalls       *int64
	ToolReadCalls       *int64
	ToolGitCalls        *int64
	ToolOtherCalls      *int64
	// MetricsRows counts invocations in the group whose adapter reported
	// activity metrics (model_roundtrips is non-NULL).
	MetricsRows int
}

AgentInvocationAggregate summarizes invocations for one purpose, powering the read-only performance report. Nullable sums preserve unknown when no row reported that metric. MetricsRows reports activity-metric coverage.

type DB 

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

DB wraps a SQLite database connection.

func Open 

func Open(path string) (*DB, error)

Open opens (or creates) the SQLite database at path and runs migrations.

func OpenReadOnly 

func OpenReadOnly(path string) (*DB, error)

OpenReadOnly opens an existing database without creating or migrating it. It is used by pre-mutation authorization, where even schema repair would be an unacceptable side effect before the caller is classified.

func (*DB) AddRunParkedDuration 

func (d *DB) AddRunParkedDuration(id string, ms int64) error

AddRunParkedDuration accumulates parked-at-gate wall time onto a run's total. Called by the executor when a gate wait ends.

func (*DB) AgentInvocationAggregates 

func (d *DB) AgentInvocationAggregates() ([]AgentInvocationAggregate, error)

AgentInvocationAggregates returns per-purpose aggregates across all runs, largest total duration first.

func (*DB) AgentInvocationSummaryForRun 

func (d *DB) AgentInvocationSummaryForRun(runID string) (RunInvocationSummary, error)

AgentInvocationSummaryForRun returns the run's invocation rollup.

func (*DB) CleanupOldIntentCache 

func (d *DB) CleanupOldIntentCache(maxAge time.Duration) (int64, error)

CleanupOldIntentCache deletes entries older than maxAge. Returns rows deleted.

func (*DB) ClearRunAwaitingAgent 

func (d *DB) ClearRunAwaitingAgent(id string) error

ClearRunAwaitingAgent clears the awaiting-agent marker on a run. Called by the executor the moment the agent responds (or the approval wait is cancelled) and the run resumes, so awaiting_agent_since is non-nil exactly while a gate is actually parked.

func (*DB) ClearStepFindings 

func (d *DB) ClearStepFindings(id string) error

ClearStepFindings removes any stored findings JSON from a step result.

func (*DB) Close 

func (d *DB) Close() error

Close closes the database connection.

func (*DB) CompleteReviewStep 

func (d *DB) CompleteReviewStep(id, runID, approvedHeadSHA string, exitCode int, durationMS int64, logPath string, certifiedRange *UncertifiedPipelineRange) error

CompleteReviewStep atomically completes a successful review, replaces the run's exact review-approved head, and retires the certified recovery range.

func (*DB) CompleteRunAwaitingAgent 

func (d *DB) CompleteRunAwaitingAgent(id string, ms int64) error

func (*DB) CompleteStep 

func (d *DB) CompleteStep(id string, exitCode int, durationMS int64, logPath string) error

CompleteStep marks a step as completed with timing and result info.

func (*DB) CompleteStepWithStatus 

func (d *DB) CompleteStepWithStatus(id string, status types.StepStatus, exitCode int, durationMS int64, logPath string) error

CompleteStepWithStatus marks a step as finished with timing and result info.

func (*DB) CompleteStepWithStatusAtHead 

func (d *DB) CompleteStepWithStatusAtHead(id string, status types.StepStatus, certifiedHeadSHA string, exitCode int, durationMS int64, logPath string) error

func (*DB) DeleteRepo 

func (d *DB) DeleteRepo(id string) error

DeleteRepo deletes a repo by ID (cascade deletes runs and steps).

func (*DB) DeleteRunAgentSession 

func (d *DB) DeleteRunAgentSession(runID, role string) error

DeleteRunAgentSession drops one role's session identity so the next turn starts a fresh same-role session (used after a failed resume).

func (*DB) DeleteUncertifiedPipelineRange 

func (d *DB) DeleteUncertifiedPipelineRange(repoID, branch string) error

DeleteUncertifiedPipelineRange removes the uncertified marker for a branch. It is a no-op when no row exists.

func (*DB) FailStep 

func (d *DB) FailStep(id string, errMsg string, durationMS int64) error

FailStep marks a step as failed with an error message and duration.

func (*DB) FixedFindingsByStep 

func (d *DB) FixedFindingsByStep(step *StepResult) (int, error)

FixedFindingsByStep returns how many findings were resolved for a single step.

func (*DB) GetActiveRun 

func (d *DB) GetActiveRun(repoID, branch string) (*Run, error)

GetActiveRun returns the currently active run (pending or running) for a repo, if any. When branch is non-empty, only a run on that exact branch is returned - the setup wizard relies on this to decide whether a new run is needed for the current branch. When branch is empty, returns the most recently created active run across any branch.

func (*DB) GetActiveRuns 

func (d *DB) GetActiveRuns() ([]*Run, error)

GetActiveRuns returns all pending or running runs across all repos, newest first.

func (*DB) GetAgentInvocationsByRun 

func (d *DB) GetAgentInvocationsByRun(runID string) ([]AgentInvocation, error)

GetAgentInvocationsByRun returns a run's invocations in execution order.

func (*DB) GetIntentCache 

func (d *DB) GetIntentCache(key string) (*IntentCacheEntry, error)

GetIntentCache returns the cached summary for a key, or nil if absent.

func (*DB) GetLatestStepRoundSelection 

func (d *DB) GetLatestStepRoundSelection(stepResultID string) (*string, error)

func (*DB) GetRepo 

func (d *DB) GetRepo(id string) (*Repo, error)

GetRepo returns a repo by ID.

func (*DB) GetRepoByPath 

func (d *DB) GetRepoByPath(workingPath string) (*Repo, error)

GetRepoByPath returns a repo by its working path.

func (*DB) GetRepos 

func (d *DB) GetRepos() ([]*Repo, error)

GetRepos returns every authoritative repository record ordered by ID.

func (*DB) GetReviewTiming added in v1.55.0 

func (d *DB) GetReviewTiming(runID string, nowUnix int64) (*ReviewTiming, error)

func (*DB) GetReviewTimingAt added in v1.55.0 

func (d *DB) GetReviewTimingAt(runID string, now time.Time) (*ReviewTiming, error)

func (*DB) GetRoundsByStep 

func (d *DB) GetRoundsByStep(stepResultID string) ([]*StepRound, error)

GetRoundsByStep returns all rounds for a step result, ordered by round number.

func (*DB) GetRun 

func (d *DB) GetRun(id string) (*Run, error)

GetRun returns a run by ID.

func (*DB) GetRunAgentSessions 

func (d *DB) GetRunAgentSessions(runID string) ([]RunAgentSession, error)

GetRunAgentSessions returns all stored session identities for a run.

func (*DB) GetRunCIAttestationState 

func (d *DB) GetRunCIAttestationState(id string) (string, error)

func (*DB) GetRunCIRerunState 

func (d *DB) GetRunCIRerunState(id string) (string, error)

GetRunCIRerunState returns the CI step's persisted rerun budget for a run, or the empty string when the run has never spent one. The payload is opaque here: pipeline CI state owns its shape, and the database only guarantees that what was written survives a restart.

func (*DB) GetRunsByRepo 

func (d *DB) GetRunsByRepo(repoID string) ([]*Run, error)

GetRunsByRepo returns all runs for a repo, newest first.

func (*DB) GetRunsByRepoHead 

func (d *DB) GetRunsByRepoHead(repoID, branch, headSHA string) ([]*Run, error)

GetRunsByRepoHead returns the runs for a repo matching an exact branch and head SHA, newest first. It lets a caller detect the run created by a specific push without scanning (and rebuilding step data for) the repo's entire run history, so the cost stays bounded to the handful of runs for one head.

func (*DB) GetStats 

func (d *DB) GetStats() (*Stats, error)

GetStats aggregates historical usage across all repositories.

func (*DB) GetStepResult 

func (d *DB) GetStepResult(id string) (*StepResult, error)

GetStepResult returns a step result by ID.

func (*DB) GetStepsByRun 

func (d *DB) GetStepsByRun(runID string) ([]*StepResult, error)

GetStepsByRun returns all step results for a run, in execution order.

func (*DB) GetUncertifiedPipelineRange 

func (d *DB) GetUncertifiedPipelineRange(repoID, branch string) (*UncertifiedPipelineRange, error)

GetUncertifiedPipelineRange returns the uncertified range for a branch, or nil when none is recorded.

func (*DB) InsertAgentInvocation 

func (d *DB) InsertAgentInvocation(inv AgentInvocation) (*AgentInvocation, error)

InsertAgentInvocation records one completed agent invocation. Nil pointer fields are stored as SQL NULL (database/sql dereferences non-nil pointers).

func (*DB) InsertEffectiveReviewStepRoundWithProvenance 

func (d *DB) InsertEffectiveReviewStepRoundWithProvenance(stepResultID string, round int, trigger string, findingsJSON *string, fixSummary *string, reviewedHeadSHA, startingHeadSHA, trustedConfigSHA string, globalConfigYAML, repoConfigYAML []byte, durationMS int64) (*StepRound, error)

func (*DB) InsertRepo 

func (d *DB) InsertRepo(workingPath, upstreamURL, defaultBranch string) (*Repo, error)

InsertRepo creates a new repo record and returns it with a generated ID.

func (*DB) InsertRepoWithFork 

func (d *DB) InsertRepoWithFork(workingPath, upstreamURL, forkURL, defaultBranch string) (*Repo, error)

InsertRepoWithFork creates a new repo record with an optional fork push URL.

func (*DB) InsertRepoWithID 

func (d *DB) InsertRepoWithID(id, workingPath, upstreamURL, defaultBranch string) (*Repo, error)

InsertRepoWithID creates a new repo record with a caller-provided ID.

func (*DB) InsertRepoWithIDAndFork 

func (d *DB) InsertRepoWithIDAndFork(id, workingPath, upstreamURL, forkURL, defaultBranch string) (*Repo, error)

InsertRepoWithIDAndFork creates a repo record with an optional fork push URL.

func (*DB) InsertReviewStepRound 

func (d *DB) InsertReviewStepRound(stepResultID string, round int, trigger string, findingsJSON *string, fixSummary *string, reviewedHeadSHA string, durationMS int64) (*StepRound, error)

InsertReviewStepRound persists a review round's examined commit as a non-authoritative candidate. A recovered parked gate can promote this exact candidate only after approval; merely storing it grants no push authority.

func (*DB) InsertReviewStepRoundWithProvenance 

func (d *DB) InsertReviewStepRoundWithProvenance(stepResultID string, round int, trigger string, findingsJSON *string, fixSummary *string, reviewedHeadSHA, startingHeadSHA, trustedConfigSHA string, globalConfigYAML, repoConfigYAML []byte, durationMS int64) (*StepRound, error)

func (*DB) InsertRun 

func (d *DB) InsertRun(repoID, branch, headSHA, baseSHA string) (*Run, error)

InsertRun creates a new run record.

func (*DB) InsertRunWithIntent 

func (d *DB) InsertRunWithIntent(repoID, branch, headSHA, baseSHA string, intent *RunIntent) (*Run, error)

func (*DB) InsertStepResult 

func (d *DB) InsertStepResult(runID string, stepName types.StepName) (*StepResult, error)

InsertStepResult creates a new step result record.

func (*DB) InsertStepRound 

func (d *DB) InsertStepRound(stepResultID string, round int, trigger string, findingsJSON *string, fixSummary *string, durationMS int64) (*StepRound, error)

InsertStepRound creates a new round record for a step result. fixSummary may be nil for non-fix rounds or when the agent produced no summary.

func (*DB) LatestSessionCumulative 

func (d *DB) LatestSessionCumulative(runID, sessionKey string) (input, output, cacheRead int, found bool)

LatestSessionCumulative returns the most recent prior invocation's cumulative token counters for the same run and non-empty session key. It is how the pipeline computes a resumed session's per-round delta (current cumulative minus this prior). found is false when the session has no prior invocation (cold, started, or a fresh fallback), in which case the current counters are already per-round.

func (*DB) ParkStepForApproval 

func (d *DB) ParkStepForApproval(runID, stepID string, status types.StepStatus, durationMS int64, findingsJSON *string) error

func (*DB) PersistReviewFixSelection 

func (d *DB) PersistReviewFixSelection(selection ReviewFixSelection) error

func (*DB) PutIntentCache 

func (d *DB) PutIntentCache(e IntentCacheEntry) error

PutIntentCache inserts or replaces an intent cache entry.

func (*DB) ReconcileTerminalPRRuns 

func (d *DB) ReconcileTerminalPRRuns() (int, error)

ReconcileTerminalPRRuns repairs active rows written by an older or interrupted daemon after terminal PR truth became durable but before the separate run completion write. It is called during exclusive daemon startup before parked-run planning and generic crash recovery.

func (*DB) RecoverStaleRuns 

func (d *DB) RecoverStaleRuns(errMsg string) (int, error)

RecoverStaleRuns marks any runs stuck in pending/running status as failed and fails any in-progress steps. This is called at daemon startup to clean up after a previous crash. Returns the number of recovered runs.

func (*DB) RecoverStaleRunsExcept 

func (d *DB) RecoverStaleRunsExcept(errMsg string, preserved map[string]struct{}) (int, error)

RecoverStaleRunsExcept marks active runs as failed unless their IDs appear in preserved. Callers use preserved only after independently proving a run can be reconstructed safely.

func (*DB) ReplaceRepoURLs 

func (d *DB) ReplaceRepoURLs(id, upstreamURL, forkURL string) (*Repo, error)

ReplaceRepoURLs atomically replaces both registered repository URLs and returns the committed record. A failure leaves the exact prior registration intact.

func (*DB) ResetStepsFrom 

func (d *DB) ResetStepsFrom(runID string, stepOrder int) error

ResetStepsFrom prepares completed or interrupted steps for revalidation. Explicitly skipped steps remain skipped across execution and recovery.

func (*DB) ResetStepsFromOrder 

func (d *DB) ResetStepsFromOrder(runID string, stepOrder int) error

func (*DB) RestoreUncertifiedPipelineRangeIfCurrent 

func (d *DB) RestoreUncertifiedPipelineRangeIfCurrent(current UncertifiedPipelineRange, previous *UncertifiedPipelineRange) (bool, error)

func (*DB) SetCIFixAttempts 

func (d *DB) SetCIFixAttempts(id string, attempts int) error

SetCIFixAttempts records the CI repair budget already consumed so recovery cannot silently grant another set of fix attempts.

func (*DB) SetRunAwaitingAgent 

func (d *DB) SetRunAwaitingAgent(id string) error

SetRunAwaitingAgent marks a run as parked awaiting the driving agent, stamping awaiting_agent_since with the current time. Called by the executor when a step enters a gate (awaiting_approval / fix_review). This is a pollable observability signal only; it does not change gate resolution.

func (*DB) SetRunCIAttestationState 

func (d *DB) SetRunCIAttestationState(id, state string) error

func (*DB) SetRunCIReady 

func (d *DB) SetRunCIReady(id string, ready bool) error

SetRunCIReady persists checks-passed readiness so fresh TUI and AXI attaches do not depend on receiving a historical log line.

func (*DB) SetRunCIReadyWithReason 

func (d *DB) SetRunCIReadyWithReason(id string, ready, declaredNoCI bool) error

func (*DB) SetRunCIRerunState 

func (d *DB) SetRunCIRerunState(id, state string) error

SetRunCIRerunState persists CI monitoring state before the corresponding provider mutation, so recovery cannot lose a consumed rerun or an expected attestation attempt.

func (*DB) SetRunCustodyReturned 

func (d *DB) SetRunCustodyReturned(id string) error

SetRunCustodyReturned stamps the moment a guarded recovery explicitly returned custody of this run's branch to the operator worktree. Stamping is idempotent: the first timestamp wins so the record keeps the original recovery moment.

func (*DB) SetRunPushActive 

func (d *DB) SetRunPushActive(id string, active bool) error

SetRunPushActive marks whether a pipeline phase currently owns a possible branch-head update. Sync refuses while this marker is set.

func (*DB) SetStepAgentActivity 

func (d *DB) SetStepAgentActivity(id string, text string, agentPID *int) error

SetStepAgentActivity records an agent lifecycle activity and replaces the active agent pid. Passing nil clears the pid after the process exits.

func (*DB) SetStepAutoFixLimit 

func (d *DB) SetStepAutoFixLimit(id string, autoFixLimit int) error

func (*DB) SetStepConvergence 

func (d *DB) SetStepConvergence(id string, reportJSON string) error

SetStepConvergence overwrites the review step's persisted convergence report (internal/convergence.Report JSON).

func (*DB) SetStepDuration 

func (d *DB) SetStepDuration(id string, durationMS int64) error

SetStepDuration sets the execution-only duration on a step result.

func (*DB) SetStepFindings 

func (d *DB) SetStepFindings(id string, findingsJSON string) error

SetStepFindings sets the findings JSON on a step result.

func (*DB) SetStepRoundSelectedFindingIDs 

func (d *DB) SetStepRoundSelectedFindingIDs(id string, selectedFindingIDs *string) error

SetStepRoundSelectedFindingIDs preserves the old API for callers that do not need to distinguish how the selection was made.

func (*DB) SetStepRoundSelection 

func (d *DB) SetStepRoundSelection(id string, selectedFindingIDs *string, source string) error

SetStepRoundSelection records which findings were selected for fix AFTER the given round produced its findings, along with whether that selection came from the user or auto-fix filtering. Passing a nil or empty JSON array clears both columns.

func (*DB) SetStepRoundUserDecision 

func (d *DB) SetStepRoundUserDecision(id string, selectedFindingIDs *string, source string, userFindingsJSON *string) error

func (*DB) SetStepRoundUserDecisionAndFindings 

func (d *DB) SetStepRoundUserDecisionAndFindings(id, stepResultID string, selectedFindingIDs *string, source string, userFindingsJSON *string, findingsJSON string) error

func (*DB) SetStepRoundUserFindings 

func (d *DB) SetStepRoundUserFindings(id string, userFindingsJSON *string) error

SetStepRoundUserFindings records the merged finding list (with user instructions attached and user-added findings appended) that was dispatched to the fix agent for the round. Passing nil clears the column.

func (*DB) StartStep 

func (d *DB) StartStep(id string) error

StartStep marks a step as running with a started_at timestamp.

func (*DB) StartStepWithAutoFixLimit 

func (d *DB) StartStepWithAutoFixLimit(id string, autoFixLimit int) error

StartStepWithAutoFixLimit marks a step as running and records the effective auto-fix limit that status surfaces use while the step is active.

func (*DB) StepFindingStats 

func (d *DB) StepFindingStats(step *StepResult) (StepStats, error)

StepFindingStats returns reported and fixed finding counts for a single step.

func (*DB) StepFixSummaries 

func (d *DB) StepFixSummaries(stepResultID string) ([]string, error)

StepFixSummaries returns one entry per fix round for a step, in round order: the agent's one-line fix summary, or "" when the round recorded none.

func (*DB) StepRoundStats 

func (d *DB) StepRoundStats(stepResultID string) (StepRoundStats, error)

StepRoundStats returns aggregate round information for a step result.

func (*DB) TouchStepActivity 

func (d *DB) TouchStepActivity(id string, text string) error

TouchStepActivity records the latest meaningful activity for an active step without changing its status or current agent pid.

func (*DB) UpdateRepoForkURL 

func (d *DB) UpdateRepoForkURL(id, forkURL string) (*Repo, error)

UpdateRepoForkURL sets or clears the optional fork push URL.

func (*DB) UpdateRepoMetadata 

func (d *DB) UpdateRepoMetadata(id, upstreamURL, defaultBranch string) (*Repo, error)

UpdateRepoMetadata refreshes mutable repository metadata while preserving the stable repo ID, created_at timestamp, and any existing fork push URL.

func (*DB) UpdateRepoMetadataWithFork 

func (d *DB) UpdateRepoMetadataWithFork(id, upstreamURL, forkURL, defaultBranch string) (*Repo, error)

UpdateRepoMetadataWithFork refreshes repo metadata and explicitly sets the optional fork push URL.

func (*DB) UpdateRepoWorkingPath 

func (d *DB) UpdateRepoWorkingPath(id, workingPath string) (*Repo, error)

UpdateRepoWorkingPath moves a repo record to a new working path, preserving the repo ID (and with it the gate and run history) when the working directory is renamed or moved on disk.

func (*DB) UpdateRunError 

func (d *DB) UpdateRunError(id, errMsg string) error

UpdateRunError sets the error message on a run.

func (*DB) UpdateRunErrorStatus 

func (d *DB) UpdateRunErrorStatus(id, errMsg string, status types.RunStatus) error

UpdateRunErrorStatus sets the error message and terminal status on a run.

func (*DB) UpdateRunErrorStatusWithVerifiedHead 

func (d *DB) UpdateRunErrorStatusWithVerifiedHead(id, errMsg string, status types.RunStatus, headSHA string) error

func (*DB) UpdateRunHeadSHA 

func (d *DB) UpdateRunHeadSHA(id, headSHA string) error

UpdateRunHeadSHA promotes a new run head through the single persistence writer. Every changed head revokes authority and findings from a completed Review in the same transaction, so callers cannot remember only part of the adjudication invalidation protocol.

func (*DB) UpdateRunHeadSHAForRevalidation 

func (d *DB) UpdateRunHeadSHAForRevalidation(id, headSHA string) error

UpdateRunHeadSHAForRevalidation records a late repair while revoking the previous review binding so the repaired head must pass review before push.

func (*DB) UpdateRunIntent 

func (d *DB) UpdateRunIntent(id string, intent RunIntent) error

UpdateRunIntent persists the inferred user intent for a run.

func (*DB) UpdateRunPRState 

func (d *DB) UpdateRunPRState(id, state string) error

UpdateRunPRState persists normalized lifecycle truth independently of logs. A merged or closed PR is also the terminal outcome of the final CI monitor step, so the PR observation and active-run finalization are committed in one transaction. This makes the database authoritative even if execution stops before the executor's ordinary follow-up completion write.

func (*DB) UpdateRunPRURL 

func (d *DB) UpdateRunPRURL(id, prURL string) error

UpdateRunPRURL sets the PR URL on a run. A delayed PR-step write must not regress terminal lifecycle truth already observed by the CI monitor.

func (*DB) UpdateRunPushBinding 

func (d *DB) UpdateRunPushBinding(id string, binding PushBinding) error

UpdateRunPushBinding advances a run's successful-push provenance and increments its generation. It is called for both a completed push and a freshly verified already-up-to-date push.

func (*DB) UpdateRunReviewApprovedHeadSHA 

func (d *DB) UpdateRunReviewApprovedHeadSHA(id, headSHA string) error

UpdateRunReviewApprovedHeadSHA replaces the run's review authority with the exact commit approved by the latest successfully completed full review.

func (*DB) UpdateRunStatus 

func (d *DB) UpdateRunStatus(id string, status types.RunStatus) error

UpdateRunStatus updates a run's status and updated_at timestamp.

func (*DB) UpdateRunStatusWithVerifiedHead 

func (d *DB) UpdateRunStatusWithVerifiedHead(id string, status types.RunStatus, headSHA string) error

func (*DB) UpdateStepStatus 

func (d *DB) UpdateStepStatus(id string, status types.StepStatus) error

UpdateStepStatus updates a step's status.

func (*DB) UpdateStepStatusWithDuration 

func (d *DB) UpdateStepStatusWithDuration(id string, status types.StepStatus, durationMS int64) error

UpdateStepStatusWithDuration updates a step's status and execution duration together.

func (*DB) UpsertRunAgentSession 

func (d *DB) UpsertRunAgentSession(runID, role, agent, sessionID string) error

UpsertRunAgentSession stores or replaces the session identity for a run+role. A run has at most one session per role.

func (*DB) UpsertUncertifiedPipelineRange 

func (d *DB) UpsertUncertifiedPipelineRange(repoID, branch, fromSHA, toSHA, sourceRunID string) error

UpsertUncertifiedPipelineRange records or replaces the uncertified recovery boundary for one repo+branch. A newer uncertified HEAD replaces an older one.

func (*DB) UpsertUncertifiedPipelineRangeRecovery added in v1.55.0 

func (d *DB) UpsertUncertifiedPipelineRangeRecovery(repoID, branch, fromSHA, toSHA, sourceRunID string, recoveryState ReviewRecoveryState) error

func (*DB) UpsertUncertifiedPipelineRangeState 

func (d *DB) UpsertUncertifiedPipelineRangeState(repoID, branch, fromSHA, toSHA, sourceRunID string, selectionApplied bool) error

type IntentCacheEntry 

type IntentCacheEntry struct {
	CacheKey  string
	Summary   string
	AgentName string
	SessionID string
	CreatedAt int64
}

IntentCacheEntry is a cached summarization for a known agent session.

type PushBinding 

type PushBinding struct {
	HeadSHA           string
	TargetKind        string
	TargetFingerprint string
	Ref               string
}

PushBinding records the exact target and commit proven by a successful pipeline-owned push. TargetFingerprint is a one-way digest and must never be a raw URL.

type Repo 

type Repo struct {
	ID            string
	WorkingPath   string
	UpstreamURL   string
	ForkURL       string
	DefaultBranch string
	CreatedAt     int64

	// URLsVerified is run-scoped, in-memory evidence that the URL fields were
	// just validated against the working clone. It is never persisted.
	URLsVerified bool `json:"-"`
}

Repo represents a registered repository.

func (*Repo) PushURL 

func (r *Repo) PushURL() string

PushURL returns the remote URL that should receive branch updates.

type RepoStats 

type RepoStats struct {
	RepoID           string
	WorkingPath      string
	Runs             int
	RescueRuns       int
	ReportedFindings int
	FixedFindings    int
}

RepoStats summarizes historical usage for one repository.

func (RepoStats) DisplayName 

func (r RepoStats) DisplayName() string

DisplayName returns a compact repository name for terminal reports.

type ReviewFixSelection 

type ReviewFixSelection struct {
	RoundID            string
	StepResultID       string
	RepoID             string
	Branch             string
	FromSHA            string
	HeadSHA            string
	SourceRunID        string
	RoundFindingsJSON  string
	StepFindingsJSON   string
	SelectedFindingIDs *string
	SelectionSource    string
	UserFindingsJSON   *string
}

type ReviewRecoveryState added in v1.55.0 

type ReviewRecoveryState string
const (
	ReviewRecoverySelectionRecoveredNoDelta   ReviewRecoveryState = "selection_recovered_no_delta"
	ReviewRecoverySelectionRecoveredWithDelta ReviewRecoveryState = "selection_recovered_with_delta"
	ReviewRecoverySelectionApplied            ReviewRecoveryState = "selection_applied"
)

func (ReviewRecoveryState) Valid added in v1.55.0 

func (s ReviewRecoveryState) Valid() bool

type ReviewTiming added in v1.55.0 

type ReviewTiming struct {
	StartedAtMS *int64             `json:"started_at_ms"`
	StartedAt   int64              `json:"started_at"`
	Status      types.StepStatus   `json:"status"`
	TotalMS     int64              `json:"total_ms"`
	Complete    bool               `json:"complete"`
	RoundCount  int                `json:"round_count"`
	ReviewMS    int64              `json:"review_ms"`
	FixMS       int64              `json:"fix_ms"`
	Turns       []ReviewTurnTiming `json:"turns"`
}

ReviewTiming projects the per-run timing record already persisted in step_results and agent_invocations. Keeping those normalized records as the source of truth avoids a second mutable summary that can drift after recovery. TotalMS includes queue and decision waits; ReviewMS/FixMS sum completed agent attempt latencies, including failures. Unreported model-only time stays nil.

type ReviewTurnTiming added in v1.55.0 

type ReviewTurnTiming struct {
	Round       int    `json:"round" toon:"round"`
	Purpose     string `json:"purpose" toon:"purpose"`
	LatencyMS   int64  `json:"latency_ms" toon:"latency_ms"`
	ModelMS     *int64 `json:"model_ms" toon:"model_ms"`
	StartedAt   int64  `json:"started_at" toon:"started_at"`
	CompletedAt int64  `json:"completed_at" toon:"completed_at"`
	ExitStatus  string `json:"exit_status" toon:"exit_status"`
}

type Run 

type Run struct {
	ID               string
	RepoID           string
	Branch           string
	HeadSHA          string
	BaseSHA          string
	SubmittedHeadSHA *string
	// NoMistakesVersion and NoMistakesBuildSHA identify the binary that created
	// this run. They remain nil only for runs recorded before these fields.
	NoMistakesVersion  *string
	NoMistakesBuildSHA *string
	// ReviewApprovedHeadSHA is the exact commit approved by the last
	// successfully completed full review. It is nil for legacy runs and until
	// review completes; mutable run/worktree heads never infer this authority.
	ReviewApprovedHeadSHA  *string
	Status                 types.RunStatus
	PRURL                  *string
	PRState                *string
	PRStateObservedAt      *int64
	CIReadyAt              *int64
	CIReadyNoCI            bool
	LastPushedSHA          *string
	PushTargetKind         *string
	PushTargetFingerprint  *string
	PushRef                *string
	LastPushedAt           *int64
	PushGeneration         *int64
	PushActive             bool
	TerminalHeadVerifiedAt *int64
	// TerminalAtMS freezes at the first terminal transition; returning to a
	// nonterminal state clears it. Later terminal diagnostics do not add wall time.
	TerminalAtMS *int64
	// CustodyReturnedAt is non-nil once a guarded branch-sync recovery
	// explicitly ended this run's ownership of an unpublished pipeline head
	// (terminal run whose head was never successfully pushed, or moved after
	// the last push). It never changes push provenance; it only records that
	// the operator worktree took the branch back.
	CustodyReturnedAt *int64
	Error             *string
	// AwaitingAgentSince is the unix-seconds timestamp at which the run parked
	// at a gate awaiting the driving agent's response (an awaiting_approval or
	// fix_review step). It is nil whenever the run is not parked: the executor
	// sets it on gate entry and clears it the moment the agent responds (or the
	// wait is cancelled). It is observability only and does not affect gate
	// resolution.
	AwaitingAgentSince *int64
	// ParkedMS accumulates the run's total parked-at-gate wall time in
	// milliseconds across every gate wait (local performance telemetry;
	// step duration_ms values exclude this time).
	ParkedMS        int64
	Intent          *string
	IntentSource    *string
	IntentSessionID *string
	IntentScore     *float64
	CreatedAt       int64
	UpdatedAt       int64
}

Run represents a pipeline run.

type RunAgentSession 

type RunAgentSession struct {
	RunID     string
	Role      string
	Agent     string
	SessionID string
	CreatedAt int64
	UpdatedAt int64
}

RunAgentSession is the minimum session-resume metadata for one durable per-run, per-role agent session. Production resumes only the review-fixer role; legacy reviewer rows remain readable for crash recovery but are never resumed. Only the adapter-native session identity is stored - never prompts, transcripts, or any conversation content - so the review loop can resume its fixer session across parking and daemon process boundaries.

type RunIntent 

type RunIntent struct {
	Summary   string
	Source    string
	SessionID string
	Score     float64
}

RunIntent carries the four intent-related columns persisted on a run.

type RunInvocationSummary 

type RunInvocationSummary struct {
	Count           int
	Resumed         int
	Fallback        int
	TotalDurationMS int64
}

RunInvocationSummary is the low-cardinality per-run rollup used for the bounded terminal remote summary (counts only - no ids, paths, or models).

type Stats 

type Stats struct {
	TotalRepos       int
	TotalRuns        int
	PullRequests     int
	RescueRuns       int
	ReportedFindings int
	FixedFindings    int
	StepStats        []StepStats
	RepoStats        []RepoStats
}

Stats summarizes historical no-slop usage across all repositories.

type StepResult 

type StepResult struct {
	ID               string
	RunID            string
	StepName         types.StepName
	StepOrder        int
	Status           types.StepStatus
	ExitCode         *int
	DurationMS       *int64
	LogPath          *string
	FindingsJSON     *string
	Error            *string
	StartedAt        *int64
	CompletedAt      *int64
	StartedAtMS      *int64
	CompletedAtMS    *int64
	FirstStartedAtMS *int64
	LastActivityAt   *int64
	LastActivity     *string
	AgentPID         *int
	AutoFixLimit     *int
	CertifiedHeadSHA *string
	CIFixAttempts    int
	// ConvergenceJSON is the review step's persisted convergence report
	// (internal/convergence.Report). The executor overwrites it once per
	// review round; nil means no report was ever computed (non-review steps,
	// legacy rows), never an empty report.
	ConvergenceJSON *string
}

StepResult represents the result of a pipeline step execution.

type StepRound 

type StepRound struct {
	ID           string
	StepResultID string
	Round        int
	Trigger      string // "initial", "auto_fix"; legacy "user_fix" is treated as "auto_fix"
	// FindingsJSON is the nullable finding set shown at this round's gate.
	// Review rounds persist the effective set, including unresolved carry.
	FindingsJSON     *string
	ReviewedHeadSHA  *string // non-authoritative commit candidate captured by a review round
	StartingHeadSHA  *string
	TrustedConfigSHA *string
	GlobalConfigYAML []byte
	RepoConfigYAML   []byte
	// UserFindingsJSON, when non-nil, is the merged finding list that was
	// dispatched to the fix agent after the user edited per-finding
	// instructions or added their own findings. It includes both the
	// selected agent-produced findings (with any attached user
	// instructions) and the user-authored findings.
	UserFindingsJSON *string
	// SelectedFindingIDs, when non-nil, is a JSON array of finding IDs that
	// were chosen (by the user or auto-fix filter) to be fixed AFTER this
	// round. It is populated on the round whose findings triggered the next
	// round, so that later rounds' prompts can tell which findings were
	// deliberately left unselected.
	SelectedFindingIDs *string
	SelectionSource    *string
	// FixSummary, when non-nil, is the agent's one-line commit summary for
	// the fix attempt performed during this round. It is only set when the
	// round itself was a fix round (trigger=="auto_fix").
	FixSummary *string
	DurationMS int64
	CreatedAt  int64
}

StepRound represents one execution round within a pipeline step.

func (*StepRound) IsFixRound 

func (r *StepRound) IsFixRound() bool

IsFixRound reports whether this round was a fix attempt. Legacy "user_fix" rounds count: they were fix rounds dispatched by an explicit user selection.

type StepRoundStats 

type StepRoundStats struct {
	TotalRounds        int
	FixRounds          int
	LatestRound        int
	LatestTrigger      string
	LatestSelection    string
	LatestRoundAt      int64
	LatestFixRound     int
	LatestFixRoundAt   int64
	SelectedForFix     bool
	AutoSelectedForFix bool
	PendingFixSource   string
}

StepRoundStats summarizes execution rounds for a step. It lets status surfaces show whether a running/fixing step is in an initial pass or a fix pass without reloading every round in callers.

type StepStats 

type StepStats struct {
	StepName         types.StepName
	ReportedFindings int
	FixedFindings    int
}

StepStats summarizes reported and fixed findings for one pipeline step.

type UncertifiedPipelineRange 

type UncertifiedPipelineRange struct {
	RepoID             string
	Branch             string
	FromSHA            string
	ToSHA              string
	SourceRunID        string
	RecoveryState      ReviewRecoveryState
	SelectionApplied   bool
	FindingsJSON       *string
	SelectedFindingIDs *string
	CreatedAt          int64
}

UncertifiedPipelineRange is the per-branch recovery boundary for review truth whose verification did not complete. RecoveryState records whether a selection was recovered before a fixer delta, recovered with that delta, or already applied by an ordinary promotion. The database boundary is authoritative. SelectionApplied is a compatibility view for older callers.

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.