persis

type ArtifactFile struct {
	// Path is relative to the run's artifact directory and uses forward
	// slashes on every platform.
	Path string
	Size int64
}

type ArtifactPage struct {
	Items      []ArtifactRun
	NextCursor string
}

type ArtifactPruneRequest struct {
	// Root is the artifact tree to sweep; empty uses the store's configured
	// artifact root.
	Root string
	// ProtectedDirs are directories the sweep must never reach. A root that
	// equals or contains one of them, or the store's run history, is refused.
	ProtectedDirs []string
	// OlderThan bounds removal to entries created before it. Stores clamp it
	// to a minimum age, because a run's artifact directory exists before its
	// record does.
	OlderThan TimeInUTC
	// DryRun reports what would be removed without removing it.
	DryRun bool
}

type ArtifactPruneResult struct {
	// Dirs are run artifact directories.
	Dirs []string
	// Records are artifact index sidecars whose run is gone.
	Records []string
}

type ArtifactQuery struct {
	// Name matches DAG names containing it, case-insensitively.
	Name string

	// FileName selects which of a run's files are returned. A pattern holding
	// glob metacharacters is a glob; anything else is a case-insensitive
	// substring. A run with no matching file is omitted.
	FileName string

	// From and To bound CreatedAt, not StartedAt.
	From TimeInUTC
	To   TimeInUTC

	WorkspaceFilter *workspace.WorkspaceFilter

	Limit  int
	Cursor string
}

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

type ArtifactRun struct {
	Name     string
	DAGRunID string

	// CreatedAt is when the run's artifact directory was made, which is the
	// value the date range filters and the listing orders on.
	CreatedAt time.Time

	// StartedAt is when the run began, which for a run that waited in a queue
	// is later than CreatedAt.
	StartedAt time.Time

	// Files are sorted by path, and only those matching the query's FileName
	// when one is set.
	Files []ArtifactFile

	// FilesTruncated reports that the run holds more files than were returned.
	// Which of its files were returned is then not defined.
	FilesTruncated bool
}

type ArtifactStore interface {
	QueryArtifacts(ctx context.Context, query ArtifactQuery) (ArtifactPage, error)
}

type Backend interface {
	Collection(name string) Collection
}

type Collection interface {
	// Get returns the record identified by id.
	// Returns [ErrNotFound] if no record with that id exists.
	Get(ctx context.Context, id string) (*Record, error)

	// Put atomically creates or replaces a record.
	Put(ctx context.Context, rec *Record) error

	// Create atomically inserts rec. Returns [ErrConflict] when a record with
	// rec.ID already exists. Implementations must guarantee the check-and-insert
	// is atomic with respect to every concurrent mutation of the same record.
	Create(ctx context.Context, rec *Record) error

	// Delete removes the record with the given id.
	// Returns nil if the record does not exist.
	Delete(ctx context.Context, id string) error

	// CompareAndDelete atomically removes expected.ID only when the current
	// record still matches expected. Returns [ErrConflict] when it does not and
	// [ErrNotFound] when the record does not exist.
	CompareAndDelete(ctx context.Context, expected *Record) error

	// List returns a page of records matching q, ordered by CreatedAt and then ID,
	// both ascending.
	List(ctx context.Context, q ListQuery) (*Page, error)

	// CompareAndSwap atomically replaces record id only when its current Data
	// bytes equal expected. Returns [ErrConflict] when they do not match and
	// [ErrNotFound] when the record does not exist.
	CompareAndSwap(ctx context.Context, id string, expected, next []byte) error
}

type DAGCatalog struct {
	Items  []DAGListItem
	Issues []string
}

type DAGChangeEvent struct {
	DAGEntry
	Type DAGChangeType
}

type DAGChangeType int

type DAGDefinition struct {
	ID string
	// SourcePath is the optional path where the definition was authored.
	SourcePath string
	Source     []byte
}

type DAGDefinitionStore interface {
	Create(ctx context.Context, id string, source []byte) error
	Delete(ctx context.Context, id string) error
	Get(ctx context.Context, id string) (DAGDefinition, error)
	Update(ctx context.Context, id string, source []byte) error
	Rename(ctx context.Context, oldID, newID string) error
	GetMetadata(ctx context.Context, id string) (*ir.DAG, error)
	Catalog(ctx context.Context) (DAGCatalog, error)
	// CatalogIncludingSearchPaths is like Catalog but also includes DAG
	// definitions found under the store's additional search paths (for example
	// alt_dags_dir). Stores without additional search paths may return the same
	// result as Catalog.
	CatalogIncludingSearchPaths(ctx context.Context) (DAGCatalog, error)
	MigrateSuspensionState(ctx context.Context) error
	SetSuspended(ctx context.Context, id string, suspended bool) error
	IsSuspended(ctx context.Context, id string) (bool, error)
}

type DAGEntry struct {
	DefinitionID string
	DAG          *ir.DAG
}

type DAGGrepResult struct {
	Name    string
	DAG     *ir.DAG
	Matches []*textsearch.Match
}

type DAGListItem struct {
	ID string
	*ir.DAG
	Suspended bool
}

type DAGListOptions struct {
	Paginator         *pagination.Paginator
	Name              string
	Labels            []string
	ActiveOnly        bool
	Sort              string
	Order             string
	Time              *time.Time
	NextRunProjection func(*ir.DAG, time.Time) time.Time
	WorkspaceFilter   *workspace.WorkspaceFilter
	// PinnedIDs holds DAG IDs listed before all other DAGs. Sort and Order
	// apply within the pinned and unpinned parts. Nil disables pinning.
	PinnedIDs map[string]struct{}
}

type DAGLoadOptions struct {
	// AllowBuildErrors returns a partially built DAG with its build errors attached.
	AllowBuildErrors bool
}

type DAGMatchSearchOptions struct {
	Cursor          string
	Limit           int
	Query           string
	Labels          []string
	WorkspaceFilter *workspace.WorkspaceFilter
}

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

type DAGRepositoryOptions struct {
	BaseConfigPath         string
	WorkspaceBaseConfigDir string
}

type DAGRunCompareAndSwapOptions struct {
	// RootDAGRun identifies the root containing a child attempt.
	RootDAGRun ir.DAGRunRef
	// ExpectedAttemptKey rejects an update when the persisted key differs.
	ExpectedAttemptKey string
}

type DAGRunCompareAndSwapStatusRequest struct {
	DAGRun             ir.DAGRunRef
	RootDAGRun         ir.DAGRunRef
	ExpectedAttemptID  string
	ExpectedAttemptKey string
	ExpectedStatus     ir.Status
	Mutate             func(*ir.DAGRunStatus) error
}

type DAGRunCreateAttemptOptions struct {
	// RootDAGRun identifies the root when creating a child attempt.
	RootDAGRun ir.DAGRunRef
	// Retry indicates that the attempt retries an existing DAG run.
	Retry bool
	// AttemptID uses a caller-assigned attempt identifier when non-empty.
	AttemptID string
}

type DAGRunCreateAttemptRequest struct {
	DAG        *ir.DAG
	RootDAGRun ir.DAGRunRef
	Timestamp  time.Time
	DAGRunID   string
	AttemptID  string
	Retry      bool
}

type DAGRunLatestAttemptOptions struct {
	// AllHistory disables the repository's optional today-only lookup window.
	AllHistory bool
}

type DAGRunLatestAttemptQuery struct {
	Name      string
	NotBefore TimeInUTC
}

type DAGRunListOptions struct {
	DAGRunID        string
	Name            string
	ExactName       string
	From            TimeInUTC
	To              TimeInUTC
	Statuses        []ir.Status
	Limit           int
	Cursor          string
	Labels          []string
	WorkspaceFilter *workspace.WorkspaceFilter
	// AllHistory disables the implicit recent-time window when no range is set.
	AllHistory bool
	// Unbounded disables the repository's result limit.
	Unbounded bool
}

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

type DAGRunRemovalEnqueuer interface {
	EnqueueDAGRunRemoval(ctx context.Context, root ir.DAGRunRef, resources []ir.AgentSessionResource) error
}

type DAGRunRemoveOptions struct {
	// RejectActive refuses to remove an active DAG run.
	RejectActive bool
}

type DAGRunRemoveRequest struct {
	DAGRun       ir.DAGRunRef
	RejectActive bool
}

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

type DAGRunRepositoryOptions struct {
	LatestStatusToday bool
	Location          *time.Location
	Now               func() time.Time
	RemovalEnqueuer   DAGRunRemovalEnqueuer
}

type DAGRunRetentionOptions struct {
	DryRun bool
	// RetentionRuns takes precedence over OlderThan and retention days when set.
	RetentionRuns *int
	// OlderThan takes precedence over retention days when RetentionRuns is unset.
	OlderThan *time.Time
}

type DAGRunRetentionRequest struct {
	Name      string
	OlderThan TimeInUTC
	KeepRuns  int
	DryRun    bool
}

type DAGRunStatusPage struct {
	Items      []*ir.DAGRunStatus
	NextCursor string
}

type DAGRunStatusQuery struct {
	DAGRunID        string
	Name            string
	ExactName       string
	From            TimeInUTC
	To              TimeInUTC
	Statuses        []ir.Status
	Limit           int
	Cursor          string
	Labels          []string
	WorkspaceFilter *workspace.WorkspaceFilter
}

type DAGRunStore interface {
	// OpenLog reads a regular log file up to its size when opened. The caller must close it.
	OpenLog(ctx context.Context, path string) (io.ReadCloser, error)
	CreateAttempt(ctx context.Context, req DAGRunCreateAttemptRequest) (dagrun.Attempt, error)
	RecentStatuses(ctx context.Context, name string, limit int) ([]ir.DAGRunStatus, error)
	LatestAttempt(ctx context.Context, query DAGRunLatestAttemptQuery) (dagrun.Attempt, error)
	QueryStatuses(ctx context.Context, query DAGRunStatusQuery) (DAGRunStatusPage, error)
	CompareAndSwapLatestAttemptStatus(ctx context.Context, req DAGRunCompareAndSwapStatusRequest) (*ir.DAGRunStatus, bool, error)
	FindAttempt(ctx context.Context, ref ir.DAGRunRef) (dagrun.Attempt, error)
	FindSubAttempt(ctx context.Context, root ir.DAGRunRef, childRunID string) (dagrun.Attempt, error)
	RemoveOldDAGRuns(ctx context.Context, req DAGRunRetentionRequest) ([]ir.DAGRunRef, error)
	RemoveDAGRun(ctx context.Context, req DAGRunRemoveRequest) error
	// PruneArtifacts removes artifact directories and index records that no
	// surviving DAG run points to.
	PruneArtifacts(ctx context.Context, req ArtifactPruneRequest) (*ArtifactPruneResult, error)
}

type DAGSearchOptions struct {
	Cursor          string
	Limit           int
	Query           string
	MatchLimit      int
	Labels          []string
	WorkspaceFilter *workspace.WorkspaceFilter
}

type DAGSearchResult struct {
	Name              string
	FileName          string
	Workspace         string
	Matches           []*textsearch.Match
	HasMoreMatches    bool
	NextMatchesCursor string
}

type ListQuery struct {
	// Prefix filters records whose ID starts with this string.
	// An empty Prefix returns all records in the collection.
	Prefix string

	// Since is inclusive and Until is exclusive. Both bound results by
	// Record.CreatedAt.
	Since *time.Time
	Until *time.Time

	// Cursor resumes a previous [Page] iteration.
	// Pass [Page.NextCursor] from the prior call; empty starts from the beginning.
	Cursor string

	// Limit caps the number of records returned. 0 uses the implementation default.
	Limit int
}

type Page struct {
	Records    []*Record
	NextCursor string // empty when no further records exist
}

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

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

type ProcStore interface {
	Validate(ctx context.Context) error
	WithLock(ctx context.Context, groupName string, fn func() error) error
	Acquire(ctx context.Context, groupName string, meta proc.ProcMeta) (proc.ProcHandle, error)
	ListEntries(ctx context.Context, groupName string) ([]proc.ProcEntry, error)
	LatestHeartbeat(ctx context.Context, groupName string, dagRun ir.DAGRunRef) (*proc.ProcHeartbeat, error)
	ListAllEntries(ctx context.Context) ([]proc.ProcEntry, error)
	RemoveIfStale(ctx context.Context, entry proc.ProcEntry) error
}

type Record struct {
	ID        string
	Data      []byte
	CreatedAt time.Time
	UpdatedAt time.Time
}

type TimeInUTC struct{ time.Time }