coachapi

type APIError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type ClaimLease struct {
	JobID     string
	WorkerID  string
	Attempt   int
	StartedAt time.Time
}

type Completion struct {
	Attempt     int
	CommitSHA   string
	Findings    []JobFinding
	Diagnostics []JobDiagnostic
	Versions    ReportVersions
	FinishedAt  time.Time
	GeneratedAt time.Time
}

type CreateJobRequest struct {
	Kind   JobKind         `json:"kind"`
	Params json.RawMessage `json:"params"`
}

type CreateJobResponse struct {
	ID string `json:"id"`
}

type Diagnostic struct {
	Scope   string `json:"scope"`
	Message string `json:"message"`
}

type ErrorEnvelope struct {
	Error APIError `json:"error"`
}

type Finding struct {
	Source        FindingSource   `json:"source"`
	RubricID      *string         `json:"rubric_id"`
	RubricVersion *string         `json:"rubric_version"`
	ModelIdentity *string         `json:"model_identity"`
	Payload       json.RawMessage `json:"payload"`
}

type FindingSource string

type Job struct {
	ID                string          `json:"id"`
	Kind              JobKind         `json:"kind"`
	Params            json.RawMessage `json:"params"`
	Status            JobStatus       `json:"status"`
	Error             *string         `json:"error"`
	CreatedAt         time.Time       `json:"created_at"`
	StartedAt         *time.Time      `json:"started_at,omitempty"`
	FinishedAt        *time.Time      `json:"finished_at,omitempty"`
	ClaimedBy         *string         `json:"claimed_by,omitempty"`
	HeartbeatAt       *time.Time      `json:"heartbeat_at,omitempty"`
	Attempt           int             `json:"attempt"`
	CreatedByProvider string          `json:"created_by_provider"`
	CreatedBySubject  string          `json:"created_by_subject"`
	CreatedByLogin    string          `json:"created_by_login"`
}

type JobDiagnostic struct {
	ID        string    `json:"id"`
	JobID     string    `json:"job_id"`
	Attempt   int       `json:"attempt"`
	Scope     string    `json:"scope"`
	Message   string    `json:"message"`
	CreatedAt time.Time `json:"created_at"`
}

type JobFinding struct {
	ID            string          `json:"id"`
	JobID         string          `json:"job_id"`
	Attempt       int             `json:"attempt"`
	Source        FindingSource   `json:"source"`
	RubricID      *string         `json:"rubric_id"`
	RubricVersion *string         `json:"rubric_version"`
	ModelIdentity *string         `json:"model_identity"`
	Payload       json.RawMessage `json:"payload"`
	PayloadHash   string          `json:"payload_hash"`
	CreatedAt     time.Time       `json:"created_at"`
}

type JobKind string

type JobStatus string

type JobStatusResponse struct {
	ID        string    `json:"id"`
	Kind      JobKind   `json:"kind"`
	Status    JobStatus `json:"status"`
	Attempt   int       `json:"attempt"`
	Error     *string   `json:"error"`
	ReportURL string    `json:"report_url,omitempty"`
}

type JobStore interface {
	// CreateJob persists a new job row. Callers set ID, Kind, Params,
	// Status (must be JobStatusQueued), CreatedAt, Attempt (must be 0), and
	// CreatedByProvider/Subject/Login before calling; CreateJob does not
	// default or mutate them. Returns an error (never ErrJobNotFound) on
	// store failure, including a duplicate ID. Does not enqueue on any
	// TaskQueue — that is the HTTP handler's job, per the submit-durability
	// rule (persist, then enqueue, then 202).
	CreateJob(ctx context.Context, job Job) error

	// GetJob returns the current row for id, or an error wrapping
	// ErrJobNotFound.
	GetJob(ctx context.Context, id string) (Job, error)

	// GetReport assembles and returns the Report for a completed job.
	// Callers (the HTTP handler) are responsible for checking
	// Job.Status == JobStatusCompleted first (via GetJob) and returning 409
	// job_not_completed themselves. Calling GetReport for a job id that
	// does not exist, or that has never had a successful RecordCompletion,
	// both return an error wrapping ErrJobNotFound; normal callers won't
	// hit the latter case because they check Job.Status first.
	GetReport(ctx context.Context, id string) (Report, error)

	// RecordCompletion finalizes one attempt of a job as successful: sets
	// status=completed, attempt=completion.Attempt,
	// finished_at=completion.FinishedAt, and durably records
	// completion.Findings/completion.Diagnostics (each already stamped
	// with completion.Attempt by the caller) plus the report-level
	// CommitSHA/Versions/GeneratedAt needed to assemble the Report later.
	// Returns an error wrapping ErrJobNotFound if the job id does not
	// exist.
	RecordCompletion(ctx context.Context, jobID string, completion Completion) error

	// RecordFailure finalizes a job attempt as failed: sets status=failed,
	// finished_at=finishedAt, error=errMsg. Returns an error wrapping
	// ErrJobNotFound if the job id does not exist.
	RecordFailure(ctx context.Context, jobID string, errMsg string, finishedAt time.Time) error
}

type Principal struct {
	Provider string `json:"provider"`
	Subject  string `json:"subject"`
	Login    string `json:"login"`
}

type RepoBaselineScanParams struct {
	RepoOwner string `json:"repo_owner"`
	RepoName  string `json:"repo_name"`
	Ref       string `json:"ref,omitempty"`
}

type Report struct {
	ReportVersion string          `json:"report_version"`
	JobID         string          `json:"job_id"`
	Kind          JobKind         `json:"kind"`
	Params        json.RawMessage `json:"params"`
	CommitSHA     string          `json:"commit_sha"`
	Summary       ReportSummary   `json:"summary"`
	Findings      []Finding       `json:"findings"`
	Diagnostics   []Diagnostic    `json:"diagnostics"`
	Error         *string         `json:"error"`
	Versions      ReportVersions  `json:"versions"`
	GeneratedAt   time.Time       `json:"generated_at"`
}

type ReportSummary struct {
	FindingCounts map[string]map[string]int `json:"finding_counts"`
	PRCount       *int                      `json:"pr_count,omitempty"`
	PRFailedCount *int                      `json:"pr_failed_count,omitempty"`
}

type ReportVersions struct {
	Analyzer string            `json:"analyzer"`
	Rubrics  map[string]string `json:"rubrics,omitempty"`
}

type WorkerJobStore interface {
	JobStore

	// ClaimJob claims a queued job, or reclaims a running job whose
	// heartbeat is older than staleAfter (relative to now). On success it
	// increments attempt, deletes prior job_findings/job_diagnostics for the
	// job, sets status=running, claimed_by, heartbeat_at, and started_at, and
	// returns the new lease. Returns ErrJobNotFound or ErrNotClaimable.
	ClaimJob(ctx context.Context, jobID, workerID string, now time.Time, staleAfter time.Duration) (ClaimLease, error)

	// Heartbeat updates heartbeat_at when (claimed_by, attempt) match.
	// Returns ErrClaimLost on fence mismatch.
	Heartbeat(ctx context.Context, jobID, workerID string, attempt int, now time.Time) error

	// InsertFindings appends findings when (claimed_by, attempt) match.
	// Implementations stamp each finding's JobID and Attempt from the lease
	// args (caller-supplied values are ignored). Returns ErrClaimLost on
	// fence mismatch.
	InsertFindings(ctx context.Context, jobID, workerID string, attempt int, findings []JobFinding) error

	// InsertDiagnostics appends diagnostics when (claimed_by, attempt) match.
	// Implementations stamp each diagnostic's JobID and Attempt from the
	// lease args (caller-supplied values are ignored). Returns ErrClaimLost
	// on fence mismatch.
	InsertDiagnostics(ctx context.Context, jobID, workerID string, attempt int, diagnostics []JobDiagnostic) error

	// CompleteJob fenced-terminal-transitions the job to completed and
	// records report assembly fields. Findings already inserted for this
	// attempt (via InsertFindings) are kept; completion.Findings are also
	// inserted when non-empty. Returns ErrClaimLost on fence mismatch.
	CompleteJob(ctx context.Context, jobID, workerID string, attempt int, completion Completion) error

	// FailJob fenced-terminal-transitions the job to failed.
	// Returns ErrClaimLost on fence mismatch.
	FailJob(ctx context.Context, jobID, workerID string, attempt int, errMsg string, finishedAt time.Time) error

	// ReleaseClaim fenced-transitions a running job back to queued and clears
	// claim fields so a retryable handler failure can Nack(false) and the next
	// ClaimJob can take ownership. It does not increment attempt (ClaimJob
	// does that on the next successful claim). Returns ErrClaimLost on fence
	// mismatch.
	ReleaseClaim(ctx context.Context, jobID, workerID string, attempt int) error

	// ListQueuedOlderThan returns queued jobs with created_at strictly before
	// olderThan, for the requeue reconciler.
	ListQueuedOlderThan(ctx context.Context, olderThan time.Time) ([]Job, error)

	// ReleaseStaleRunning sets running jobs whose heartbeat is older than
	// staleAfter (relative to now) back to queued and clears claim fields so
	// the requeue reconciler can re-enqueue them. It does not increment
	// attempt (ClaimJob does that on the next successful claim).
	ReleaseStaleRunning(ctx context.Context, now time.Time, staleAfter time.Duration) (released int, err error)
}