checkpoint

type Checkpoint struct {
	cortex.Entity
	ID        id.CheckpointID `json:"id"`
	RunID     id.AgentRunID   `json:"run_id"`
	AgentID   id.AgentID      `json:"agent_id"`
	Scope     cortex.Scope    `json:"scope"`
	Reason    string          `json:"reason"`
	StepIndex int             `json:"step_index"`
	State     string          `json:"state"`
	Decision  *Decision       `json:"decision,omitempty"`
	Metadata  map[string]any  `json:"metadata,omitempty"`
}

type Decision struct {
	Approved  bool      `json:"approved"`
	DecidedBy string    `json:"decided_by,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	DecidedAt time.Time `json:"decided_at"`
	// DecidedByPrincipal is the decider's principal, as the engine's
	// cortex.PrincipalCodec encoded it. ResolveCheckpoint fills it from
	// the context and overwrites whatever the caller supplied. It records
	// who decided; the run itself continues under its own principal.
	//
	// It is serialized because the SQL stores persist a decision as JSON.
	// Anything that serves a checkpoint to a reader goes through
	// Checkpoint.Public, which drops it.
	DecidedByPrincipal []byte `json:"decided_by_principal,omitempty"`
}

type ListFilter struct {
	RunID  string
	Limit  int
	Offset int
}

type Store interface {
	CreateCheckpoint(ctx context.Context, cp *Checkpoint) error
	GetCheckpoint(ctx context.Context, cpID id.CheckpointID) (*Checkpoint, error)
	// Resolve records decision on a pending checkpoint at the caller's
	// exact scope. A checkpoint that is no longer pending keeps its first
	// decision and Resolve returns an error wrapping cortex.ErrInvalidState;
	// one that does not exist there is cortex.ErrCheckpointNotFound.
	Resolve(ctx context.Context, cpID id.CheckpointID, decision Decision) error
	ListPending(ctx context.Context, filter *ListFilter) ([]*Checkpoint, error)
	CountPending(ctx context.Context, filter *ListFilter) (int64, error)
}

type SweepStore interface {
	// ListPendingAcrossScopes lists pending checkpoints whose id sorts
	// after the given one, in id order, at most limit. A nil id starts
	// from the first. It deliberately bypasses scope, for the sweeper
	// only, which acts on each checkpoint under that checkpoint's own
	// scope.
	ListPendingAcrossScopes(ctx context.Context, after id.CheckpointID, limit int) ([]*Checkpoint, error)
}