// Package checkpoint is the durable-resume battery: it persists a run's
// resumable progress so a run interrupted by a shutdown can be recovered and
// continued on the next boot, rather than silently lost. It plugs into
// run.Ports.Checkpointer.
//
// Mort backs CheckpointStore with its durable-job table; Memory() is the
// zero-dependency default; contrib/store can add a SQLite one. The executor calls
// run.Ports.Checkpointer (a CheckpointerFactory) during the run loop; NewFactory
// wires this battery into that seam.
package checkpoint

import (
	"context"
	"time"

	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"

	"gitea.stevedudenhoeffer.com/steve/executus/run"
)

// RunCheckpointMeta is the run attribution needed to resume a run from scratch
// (mirrors mort's agentexec.RunCheckpointMeta).
type RunCheckpointMeta struct {
	RunID       string
	AgentID     string
	AgentName   string
	CallerID    string
	ChannelID   string
	GuildID     string
	Prompt      string
	ModelTier   string
	ParentRunID string
}

// RunCheckpoint is one persisted snapshot of a run's resumable progress.
type RunCheckpoint struct {
	Meta            RunCheckpointMeta
	Messages        []llm.Message     // conversation so far (single-loop runs)
	Iteration       int               // completed agent-loop iterations
	CompletedPhases []run.PhaseOutput // finished phases, in order (multi-phase agents)
	UpdatedAt       time.Time
}

// CheckpointStore persists run checkpoints keyed by run id. A live checkpoint
// means "this run was in flight and not cleanly finished"; Complete/Fail delete
// it. ListInterrupted returns every surviving checkpoint at boot for recovery.
type CheckpointStore interface {
	Save(ctx context.Context, cp RunCheckpoint) error
	Load(ctx context.Context, runID string) (*RunCheckpoint, error)
	Delete(ctx context.Context, runID string) error
	ListInterrupted(ctx context.Context) ([]RunCheckpoint, error)
}