task

type Controller interface {
	// UpdateProgress stores a human-readable progress string on the task.
	UpdateProgress(ctx context.Context, text string) error
	// IsCancelled reports whether the task's context has been cancelled.
	IsCancelled(ctx context.Context) bool
}

type Handler interface {
	// Type returns the task type string this handler handles.
	Type() string
	// Run executes the task. Returning a non-nil error causes the task to be
	// failed or retried depending on whether the error is retryable and
	// whether attempts remain. A context.Canceled error marks the task cancelled.
	Run(ctx context.Context, t *Task, ctl Controller) (*TaskResult, error)
}

type ListFilter struct {
	OwnerType string
	OwnerID   string
	Type      string
	Status    []TaskStatus
	Limit     int
	Offset    int
}

type Manager interface {
	// Register adds a handler for a task type. May be called before Start.
	Register(handler Handler) error

	// Submit creates a new task and persists it. The scheduler picks it up
	// within one poll interval (5s by default). Submit is durable: if the
	// process crashes after Submit returns, the task survives in the DB.
	Submit(ctx context.Context, req SubmitRequest) (*Task, error)

	// Cancel transitions a task to cancelled. For running tasks it signals
	// the handler's context; the handler is responsible for returning promptly.
	Cancel(ctx context.Context, taskID string, reason string) error

	// Get returns the current state of a task. Returns ErrNotFound if absent.
	Get(ctx context.Context, taskID string) (*Task, error)

	// List returns tasks matching the filter, ordered by created_at DESC.
	List(ctx context.Context, filter ListFilter) ([]Task, error)

	// Wait polls until taskID reaches a terminal status or ctx is cancelled.
	// Useful for callers (e.g. HTTP handlers) that need a synchronous result.
	Wait(ctx context.Context, taskID string) (*Task, error)

	// Start runs restart recovery and launches the scheduler goroutine.
	Start(ctx context.Context) error

	// Stop signals the scheduler to stop. Running tasks are not interrupted.
	Stop(ctx context.Context) error
}

type ManagerOption func(*taskManager)

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

type RetryableError struct {
	Cause   error
	Backoff time.Duration // 0 = use default exponential backoff
}

type Store interface {
	// Create persists a new task. The task must have a non-empty ID.
	Create(ctx context.Context, t *Task) error

	// Get retrieves a task by its ID. Returns ErrNotFound if absent.
	Get(ctx context.Context, taskID string) (*Task, error)

	// Update overwrites all fields of an existing task record.
	Update(ctx context.Context, t *Task) error

	// List returns tasks matching filter, ordered by created_at DESC.
	List(ctx context.Context, filter ListFilter) ([]Task, error)

	// MarkInterruptedOnStartup transitions stale in-progress rows atomically:
	//   running → interrupted
	//   queued  → pending (so the scheduler rebuilds order from DB)
	// Called once during Manager.Start before the scheduler loop begins.
	MarkInterruptedOnStartup(ctx context.Context) error

	// FindDueTasks returns up to limit pending tasks whose scheduled_at is
	// NULL or <= now, ordered by created_at ASC (oldest first).
	FindDueTasks(ctx context.Context, now time.Time, limit int) ([]Task, error)

	// FindQueuedForKey returns the oldest queued task for a serialization key,
	// or nil if none exist.
	FindQueuedForKey(ctx context.Context, key string) (*Task, error)

	// UpdateStatus applies a partial update to the named task using the
	// provided column→value map. Only the listed columns are written;
	// other columns are left unchanged. This prevents concurrent goroutines
	// from stomping each other's fields.
	UpdateStatus(ctx context.Context, taskID string, fields map[string]interface{}) error
}

type SubmitRequest struct {
	Type             string
	OwnerType        string
	OwnerID          string
	Source           string
	SerializationKey string
	Payload          json.RawMessage
	MaxAttempts      int        // defaults to 1 if zero or negative
	ScheduledAt      *time.Time // nil = run as soon as possible
}

type Task struct {
	ID               string
	Type             string
	Status           TaskStatus
	OwnerType        string
	OwnerID          string
	Source           string
	SerializationKey string

	Payload json.RawMessage
	Result  json.RawMessage

	Progress string
	Error    string

	Attempt     int
	MaxAttempts int

	ScheduledAt *time.Time
	StartedAt   *time.Time
	FinishedAt  *time.Time
	CancelledAt *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time

	// Recurrence holds cron spec JSON. Reserved for Phase 4; nil in Phase 1.
	Recurrence json.RawMessage
	// ParentTaskID links a recurring child instance to its recurrence parent.
	ParentTaskID string
}

type TaskResult struct {
	Result json.RawMessage
}

type TaskStatus string