session

type ArchiveBoundaryNotFoundError struct {
	EventID int64
}

type CreateSessionRequest struct {
	// SessionID is the application-provided session identifier. It must be unique
	// in the session store.
	SessionID string
	// AppID identifies the application or tenant that owns the session.
	AppID string
	// UserID identifies the end user that owns the session.
	UserID string
}

type ListSessionsRequest struct {
	// AppID restricts results to sessions owned by this application or tenant.
	AppID string
	// UserID restricts results to sessions owned by this end user.
	UserID string
	// Limit is the maximum number of sessions to return. Zero uses the default of 50.
	Limit int64
	// Offset is the number of ordered sessions to skip.
	Offset int64
	// SortBy is the primary sort field. Empty defaults to SessionSortByCreatedAt.
	SortBy SessionSortField
	// SortOrder is the sort direction. Empty defaults to SortDescending.
	SortOrder SortOrder
}

type RunLockKey struct {
	// AppID identifies the application or tenant that owns the session.
	AppID string
	// UserID identifies the end user that owns the session.
	UserID string
	// SessionID is the application-provided session identifier.
	SessionID string
}

type RunScopedLocker interface {
	LockRun(ctx context.Context, key RunLockKey) (unlock func(), err error)
}

type Session interface {
	// GetSessionID returns the application-provided session identifier.
	GetSessionID() string
	// GetAppID returns the application or tenant that owns the session.
	GetAppID() string
	// GetUserID returns the end user that owns the session.
	GetUserID() string
	// GetCreatedAt returns the Unix millisecond timestamp when the session was created.
	GetCreatedAt() int64
	CreateEvent(ctx context.Context, event *event.Event) error
	// GetEvents returns a paginated slice of active (non-archived, non-deleted) events
	// sorted by created_at ASC.
	GetEvents(ctx context.Context, limit, offset int64) ([]*event.Event, error)
	// ListEvents returns all active (non-archived, non-deleted) events sorted by
	// created_at ASC. Use this instead of GetEvents when the full history is needed.
	ListEvents(ctx context.Context) ([]*event.Event, error)
	DeleteEvent(ctx context.Context, eventID int64) error
	// ListArchivedEvents returns all archived, non-deleted events sorted by
	// created_at ASC with event_id as a stable tiebreaker.
	ListArchivedEvents(ctx context.Context) ([]*event.Event, error)
	// ArchiveEventsBefore archives all active events that precede eventID in
	// conversation order. eventID remains active. Zero archives all active
	// events. A non-zero eventID must identify an active event in this session.
	// Archiving is idempotent and never creates or deletes events.
	ArchiveEventsBefore(ctx context.Context, eventID int64) error
}

type SessionService interface {
	CreateSession(ctx context.Context, req CreateSessionRequest) (Session, error)
	DeleteSession(ctx context.Context, sessionID string) error
	GetSession(ctx context.Context, sessionID string) (Session, error)
	ListSessions(ctx context.Context, req ListSessionsRequest) ([]Session, error)
}

type SessionSortField string

type SortOrder string

type Turn struct {
	ID         string       `json:"turn_id" db:"turn_id"`
	SessionID  string       `json:"session_id" db:"session_id"`
	Status     TurnStatus   `json:"status" db:"status"`
	Reason     TurnReason   `json:"reason" db:"reason"`
	Failure    *TurnFailure `json:"failure,omitempty" db:"-"`
	StartedAt  int64        `json:"started_at" db:"started_at"`
	FinishedAt int64        `json:"finished_at" db:"finished_at"`
}

type TurnFailure struct {
	Code    string           `json:"code" db:"failure_code"`
	Message string           `json:"message" db:"failure_message"`
	Stage   TurnFailureStage `json:"stage" db:"failure_stage"`
}

type TurnFailureProvider interface {
	TurnFailure() TurnFailure
}

type TurnFailureStage string

type TurnNotFoundError struct {
	TurnID string
}

type TurnOutcome struct {
	// Status is the terminal state to record.
	Status TurnStatus
	// Reason is the stable terminal classification. It is empty for completed Turns.
	Reason TurnReason
	// Failure contains optional safe display metadata for a non-completed Turn.
	Failure *TurnFailure
}

type TurnReason string

type TurnStateConflictError struct {
	TurnID string
	Status TurnStatus
}

type TurnStatus string

type TurnStore interface {
	// BeginTurn durably creates a running Turn.
	BeginTurn(ctx context.Context, turn Turn) error
	// FinalizeTurn atomically transitions a running Turn to one terminal outcome.
	FinalizeTurn(ctx context.Context, turnID string, outcome TurnOutcome) error
	// GetTurn returns one Turn, or nil when it does not exist.
	GetTurn(ctx context.Context, turnID string) (*Turn, error)
	// ListTurns returns all Turns in timeline order.
	ListTurns(ctx context.Context) ([]*Turn, error)
	// InterruptRunningTurns marks every running Turn as interrupted with reason.
	InterruptRunningTurns(ctx context.Context, reason TurnReason) error
}