// Package session 为 Orca 框架提供对话会话管理功能。
package session

// Store 定义会话消息存储的持久化接口。
//
// 实现必须支持并发使用。默认实现使用 JSONL 文件
//（每个会话一个文件），支持 O(1) 追加写入。
type Store interface {
	// Save 将单条消息追加到会话历史中。
	// 如果会话文件不存在，则创建它。
	Save(sessionID string, msg SessionMessage) error

	// Load 按时间顺序检索会话的所有消息。
	// 如果会话不存在，则返回错误。
	Load(sessionID string) ([]SessionMessage, error)

	// List 返回所有已知的会话 ID。
	List() ([]string, error)

	// Exists 检查会话是否存在于存储中。
	Exists(sessionID string) (bool, error)

	// Archive 将会话标记为已归档（只读）。
	// 这是一个保留数据的软删除操作。
	Archive(sessionID string) error

	// Delete 从存储中永久移除会话。
	Delete(sessionID string) error
}