interfaces

type ActionRepo interface {
	// Run operations
	GetRun(ctx context.Context, runID *common.RunIdentifier) (*models.Run, error)
	// AbortRun marks only the root action as ABORTED and sets abort_requested_at on it.
	// K8s cascades CRD deletion to child actions via OwnerReferences; the action service
	// informer handles marking them ABORTED in DB when their CRDs are deleted.
	AbortRun(ctx context.Context, runID *common.RunIdentifier, reason string, abortedBy *common.EnrichedIdentity) error

	// Action operations
	CreateAction(ctx context.Context, action *models.Action, updateTriggeredAt bool) (*models.Action, error)
	InsertEvents(ctx context.Context, events []*models.ActionEvent) error
	ListEvents(ctx context.Context, actionID *common.ActionIdentifier, limit int) ([]*models.ActionEvent, error)
	ListEventsSince(ctx context.Context, actionID *common.ActionIdentifier, attempt uint32, since time.Time, offset, limit int) ([]*models.ActionEvent, error)
	GetLatestEventByAttempt(ctx context.Context, actionID *common.ActionIdentifier, attempt uint32) (*models.ActionEvent, error)
	GetAction(ctx context.Context, actionID *common.ActionIdentifier) (*models.Action, error)
	ListActions(ctx context.Context, input ListResourceInput) ([]*models.Action, error)
	UpdateActionPhase(ctx context.Context, actionID *common.ActionIdentifier, phase common.ActionPhase, attempts uint32, cacheStatus core.CatalogCacheStatus, endTime *time.Time, startTime *time.Time) error
	// UpdateActionDetailedInfo replaces the serialized RunInfo (detailed_info column).
	UpdateActionDetailedInfo(ctx context.Context, actionID *common.ActionIdentifier, detailedInfo []byte) error
	// AbortAction marks only the targeted action as ABORTED and sets abort_requested_at.
	// K8s cascades CRD deletion to descendants via OwnerReferences.
	AbortAction(ctx context.Context, actionID *common.ActionIdentifier, reason string, abortedBy *common.EnrichedIdentity) error

	// Abort reconciliation — used by the background AbortReconciler.
	ListPendingAborts(ctx context.Context) ([]*models.Action, error)
	MarkAbortAttempt(ctx context.Context, actionID *common.ActionIdentifier) (attemptCount int, err error)
	ClearAbortRequest(ctx context.Context, actionID *common.ActionIdentifier) error

	// Watch operations (for streaming)
	WatchRunUpdates(ctx context.Context, runID *common.RunIdentifier, updates chan<- *models.Run, errs chan<- error)
	WatchAllRunUpdates(ctx context.Context, updates chan<- *models.Run, errs chan<- error)
	WatchAllActionUpdates(ctx context.Context, runID *common.RunIdentifier, updates chan<- *models.Action, errs chan<- error)
	WatchActionUpdates(ctx context.Context, actionID *common.ActionIdentifier, updates chan<- *models.Action, errs chan<- error)

	// State operations
	UpdateActionState(ctx context.Context, actionID *common.ActionIdentifier, state string) error
	GetActionState(ctx context.Context, actionID *common.ActionIdentifier) (string, error)

	// Event notification (for state updates)
	NotifyStateUpdate(ctx context.Context, actionID *common.ActionIdentifier) error
	WatchStateUpdates(ctx context.Context, updates chan<- *common.ActionIdentifier, errs chan<- error)

	// Aggregation operations
	ListRootActions(ctx context.Context, project, domain string, startDate, endDate *time.Time, limit int) ([]*models.Action, error)
}

type Filter interface {
	QueryExpression(table string) (QueryExpr, error)
	And(filter Filter) Filter
	Or(filter Filter) Filter
}

type FilterExpression = int

type ListResourceInput struct {
	Limit int

	// CursorToken is reserved for an opaque keyset-cursor pagination mode. It is currently
	// unused — the ListRuns/ListActions RPC paginates by Offset (see below) — and no repo
	// reads it. Kept as a placeholder so a future keyset cursor can be wired in without an
	// interface change.
	CursorToken string

	// Offset is an integer offset for offset-based pagination. actionRepo.ListActions
	// applies it as SQL OFFSET (mutually exclusive with KeysetAfter) and rejects a negative
	// value; the ListRuns/ListActions RPC encodes the running offset as the page token. The
	// other repos' List methods use it too.
	Offset int

	// KeysetAfterCreatedAt/KeysetAfterName do ascending composite keyset pagination:
	// when KeysetAfterCreatedAt is non-nil, the query returns rows ordered strictly
	// after (created_at, name) = (*KeysetAfterCreatedAt, KeysetAfterName). The caller
	// must sort by (created_at ASC, name ASC). Mutually exclusive with Offset.
	// Used by the WatchActions snapshot to page a run's actions in O(n).
	KeysetAfterCreatedAt *time.Time
	KeysetAfterName      string

	Filter Filter
	// The filter set by scopeBy in the query
	ScopeByFilter  Filter
	SortParameters []SortParameter
}

type ProjectRepo interface {
	CreateProject(ctx context.Context, project *models.Project) error
	GetProject(ctx context.Context, identifier string) (*models.Project, error)
	UpdateProject(ctx context.Context, project *models.Project) error
	ListProjects(ctx context.Context, input ListResourceInput) ([]*models.Project, error)
}

type QueryExpr struct {
	Query string
	Args  []interface{}
}

type Repository interface {
	ActionRepo() ActionRepo
	TaskRepo() TaskRepo
	TriggerRepo() TriggerRepo
}

type SortOrder int

type SortParameter interface {
	GetOrderExpr() string
}

type TaskRepo interface {
	// CreateTask upserts a task and its associated triggers in one transaction.
	// Trigger models are optional; pass nil or an empty slice if there are no triggers.
	CreateTask(ctx context.Context, task *models.Task, triggers []*models.Trigger) error
	GetTask(ctx context.Context, key models.TaskKey) (*models.Task, error)
	ListTasks(ctx context.Context, input ListResourceInput) (*models.TaskListResult, error)
	ListVersions(ctx context.Context, input ListResourceInput) ([]*models.TaskVersion, error)

	CreateTaskSpec(ctx context.Context, taskSpec *models.TaskSpec) error
	GetTaskSpec(ctx context.Context, digest string) (*models.TaskSpec, error)
}

type TriggerNameKey struct {
	Project  string
	Domain   string
	TaskName string
	Name     string
}

type TriggerRepo interface {
	// SaveTrigger inserts or updates the latest trigger state and appends a revision row.
	// expectedRevision is the caller's current LatestRevision for optimistic locking.
	// Pass 0 when creating a brand-new trigger.
	SaveTrigger(ctx context.Context, trigger *models.Trigger, expectedRevision uint64) (*models.Trigger, error)

	// GetTrigger returns the latest (non-deleted) trigger row by composite key.
	GetTrigger(ctx context.Context, key TriggerNameKey) (*models.Trigger, error)

	// GetTriggerRevision returns a specific immutable revision row.
	GetTriggerRevision(ctx context.Context, project, domain, taskName, name string, revision uint64) (*models.TriggerRevision, error)

	// ListTriggers returns the latest (non-deleted) trigger rows matching the input.
	ListTriggers(ctx context.Context, input ListResourceInput) ([]*models.Trigger, error)

	// ListTriggerRevisions returns revision history for a given trigger, ordered by revision DESC.
	ListTriggerRevisions(ctx context.Context, project, domain, taskName, name string, input ListResourceInput) ([]*models.TriggerRevision, error)

	// UpdateTriggers activates or deactivates the given triggers and appends revision rows.
	UpdateTriggers(ctx context.Context, keys []TriggerNameKey, active bool) error

	// DeleteTriggers soft-deletes the given triggers and appends revision rows.
	DeleteTriggers(ctx context.Context, keys []TriggerNameKey) error
}