dagrun

type Attempt interface {
	// ID returns the identifier for the attempt that is unique within the dag-run.
	ID() string
	// Open prepares the attempt for writing status updates
	Open(ctx context.Context) error
	// Write updates the status of the attempt
	Write(ctx context.Context, status ir.DAGRunStatus) error
	// Close finalizes writing to the attempt
	Close(ctx context.Context) error
	// ReadStatus retrieves the current status of the attempt
	ReadStatus(ctx context.Context) (*ir.DAGRunStatus, error)
	// ReadStatusUncached retrieves the current status without retaining it in a shared cache.
	ReadStatusUncached(ctx context.Context) (*ir.DAGRunStatus, error)
	// ReadDAG reads the DAG associated with this run attempt
	ReadDAG(ctx context.Context) (*ir.DAG, error)
	// SetDAG sets the DAG for this attempt (must be called before Open for DAG to be persisted)
	SetDAG(dag *ir.DAG)
	// Abort requests aborting the attempt
	Abort(ctx context.Context) error
	// IsAborting checks if an abort has been requested for the attempt
	IsAborting(ctx context.Context) (bool, error)
	// Hide marks the attempt as hidden from normal operations.
	// This is useful for preserving previous state visibility when dequeuing.
	Hide(ctx context.Context) error
	// Hidden returns true if the attempt is hidden from normal operations.
	Hidden() bool
	// WriteOutputs writes the collected step outputs for the dag-run.
	// Does nothing if outputs is nil or has no output entries.
	WriteOutputs(ctx context.Context, outputs *ir.DAGRunOutputs) error
	// ReadOutputs reads the collected step outputs for the dag-run.
	// Returns nil when outputs are unavailable or use the legacy representation.
	ReadOutputs(ctx context.Context) (*ir.DAGRunOutputs, error)
	// WriteStepMessages writes LLM messages for a single step.
	WriteStepMessages(ctx context.Context, stepName string, messages []ir.LLMMessage) error
	// ReadStepMessages reads LLM messages for a single step.
	// Returns nil if no messages exist for the step.
	ReadStepMessages(ctx context.Context, stepName string) ([]ir.LLMMessage, error)
}

type FailedAutoRetryCancelEligibility int

type FailedAutoRetryCancelStateChangedError struct {
	CurrentStatus *ir.DAGRunStatus
}

type PushBack struct {
	// TargetName is the step that runs again first.
	TargetName string
	// AllowedInputs restricts which inputs are recorded. Empty keeps them all.
	AllowedInputs []string
	// Inputs holds the reviewer feedback.
	Inputs map[string]string
	// By, ByID, and At identify who pushed the step back and when.
	By   string
	ByID string
	At   string
}

type RetryHop struct {
	Step  string `json:"step"`
	RunID string `json:"runId"`
}

type RetryPath struct {
	Hops []RetryHop `json:"hops"`
	Step string     `json:"step"`
}

type StateEntry struct {
	StateRef
	Value     json.RawMessage    `json:"value"`
	Version   int64              `json:"version"`
	Hash      string             `json:"hash"`
	CreatedAt time.Time          `json:"created_at"`
	UpdatedAt time.Time          `json:"updated_at"`
	UpdatedBy *StateUpdateSource `json:"updated_by,omitempty"`
}

type StateListOptions struct {
	Scope     StateScope
	Namespace string
	KeyPrefix string
	Limit     int
}

type StatePutOptions struct {
	ExpectedVersion *int64
	CreateOnly      bool
	UpdatedBy       *StateUpdateSource
}

type StateRef struct {
	Scope     StateScope `json:"scope"`
	Namespace string     `json:"namespace"`
	Key       string     `json:"key"`
}

type StateScope string

type StateStore interface {
	Get(ctx context.Context, ref StateRef) (*StateEntry, error)
	Put(ctx context.Context, ref StateRef, value json.RawMessage, opts StatePutOptions) (*StateEntry, error)
	Delete(ctx context.Context, ref StateRef) (bool, error)
	List(ctx context.Context, opts StateListOptions) ([]*StateEntry, error)
}

type StateUpdateSource struct {
	DAGName   string `json:"dag_name,omitempty"`
	DAGRunID  string `json:"dag_run_id,omitempty"`
	AttemptID string `json:"attempt_id,omitempty"`
	StepName  string `json:"step_name,omitempty"`
}

type WorkDirRef struct {
	RootDAGRun ir.DAGRunRef
	DAGRun     ir.DAGRunRef
}

type WorkDirStore interface {
	Materialize(ctx context.Context, ref WorkDirRef) (string, error)
	Snapshot(ctx context.Context, ref WorkDirRef, localDir string) error
	Remove(ctx context.Context, ref WorkDirRef) error
}