Cyrene_v2/internal/runtime/history/store.go

// Package history implements the persistent chat-history session model described in
// DevDocs/design/16-会话持久化与主次级会话.md.
//
// It is the storage layer, not the orchestration/context layer: it persists the raw
// message stream (chat_messages) and the persistent session records (chat_sessions)
// so the Web frontend can request + display history, and secondary (sub) sessions can
// be created, listed and deleted. It intentionally does not touch memory (design/16
// §3.2: memory is persona-scoped and lives in runtime/memory), does not build context
// (runtime/loop) and does not schedule turns (gateway/session_orchestrator).
//
// Session model (design/16 §2.1): there is exactly one fixed main session (id "web") and
// any number of sub sessions (id "web:<uuid>"). Main + sub share the same persona and
// therefore the same memory; this package only models sessions + messages.
package history

import (
	"context"
	"crypto/rand"
	"database/sql"
	"encoding/hex"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"time"

	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
)

// Session roles and types. These are the values persisted in the role / type columns.
const (
	// RoleUser, RoleAssistant, RoleSystem classify a message's author.
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleSystem    = "system"

	// SessionMain and SessionSub classify a persistent session.
	SessionMain = "main"
	SessionSub  = "sub"
)

// MainSessionID is the fixed id of the one main session (design/16 §2.1). Sub session
// ids are MainSessionID + ":" + uuid.
const MainSessionID = "web"

// defaultPageLimit is the page size used when the caller does not pass one.
const defaultPageLimit = 50

// maxPageLimit bounds a client-supplied limit so a single request cannot drain memory.
const maxPageLimit = 200

// Sentinels distinguishing history package failures. Callers wrap them with %w so
// errors.Is works through the chain.
var (
	// ErrNilDB is returned when NewStore receives a nil *sql.DB.
	ErrNilDB = errors.New("history: nil db")

	// ErrImmutableMain is returned when a caller tries to delete the fixed main session.
	ErrImmutableMain = errors.New("history: the main session cannot be deleted")
)

// Message is one persisted chat message. CreatedAt is a Unix millisecond timestamp and
// doubles as the pagination cursor (design/16 §3.1): pages are ordered newest-first and
// "before" is the created_at of the oldest message on the previous page.
type Message struct {
	ID        string
	SessionID string
	Role      string
	Content   string
	Mode      string
	Mood      string
	Image     string
	Thinking  string
	CreatedAt int64
}

// SessionMeta is the wire-facing metadata of one persistent session.
type SessionMeta struct {
	ID        string
	Type      string // "main" | "sub"
	Title     string
	CreatedAt int64
}

// HistoryStore abstracts the chat-history store so callers (the gateway) and tests can
// hold an interface rather than a concrete *Store.
type HistoryStore interface {
	// Append persists msg, assigning an id and timestamp when the caller omitted them.
	Append(ctx context.Context, msg Message) error
	// AppendFull persists msg like Append but returns the complete stored message
	// (with the assigned id/timestamp) so a caller can broadcast it for cross-end sync.
	AppendFull(ctx context.Context, msg Message) (Message, error)
	// List returns up to limit messages for sessionID, newest first. before is a
	// millisecond timestamp cursor: when nonzero, only messages older than before are
	// returned (inclusive-free, matching the "before" bound on the frontend).
	List(ctx context.Context, sessionID string, before int64, limit int) ([]Message, error)
	// Recent returns the most recent n messages for sessionID in oldest-first order,
	// for WS replay / context tail usage.
	Recent(ctx context.Context, sessionID string, n int) ([]Message, error)
	// DeleteSession removes a sub session and all its messages. The main session is
	// immutable and returns ErrImmutableMain.
	DeleteSession(ctx context.Context, sessionID string) error
	// NewSubSession creates a new sub session and returns its id (MainSessionID:uuid).
	NewSubSession(ctx context.Context, ownerID string) (string, error)
	// ListSessions returns the main session first then every sub session, oldest first.
	ListSessions(ctx context.Context) ([]SessionMeta, error)
}

// Store is the SQLite-backed chat-history store. It owns the chat_sessions and
// chat_messages tables. Concurrency is delegated to *sql.DB (safe for concurrent use),
// so Store holds no further lock. Every query is parameterized and reads list columns
// explicitly (no SELECT *); reads take a context.
type Store struct {
	db  *sql.DB
	log *slog.Logger
}

// rowScanner is satisfied by both *sql.Row and *sql.Rows, so a single scanMessage
// helper serves List and Recent.
type rowScanner interface {
	Scan(dest ...any) error
}

// NewStore builds a Store on db, ensuring the chat_sessions/chat_messages schema exists
// and that the fixed main session row is present. The DDL mirrors the 0003 migration;
// it is idempotent so the store is self-contained and usable from any *sql.DB, matching
// the memory and session packages. db must be live; nil returns ErrNilDB. log may be nil.
func NewStore(ctx context.Context, db *sql.DB, log *slog.Logger) (*Store, error) {
	if db == nil {
		return nil, ErrNilDB
	}
	log = logger.WithSource(discardLogger(log), "history")
	for _, ddl := range []string{
		createSessionsTable,
		createMessagesTable,
		createMessagesIndex,
	} {
		if _, err := db.ExecContext(ctx, ddl); err != nil {
			return nil, fmt.Errorf("history: apply schema: %w", err)
		}
	}
	s := &Store{db: db, log: log}
	if err := s.ensureMainSession(ctx); err != nil {
		return nil, err
	}
	return s, nil
}

// Append persists msg, assigning a fresh id and a now-ms CreatedAt when the caller left
// either empty/zero. It returns the error wrapped with the operation name. Callers that
// need the generated id/timestamp back should use AppendFull instead.
func (s *Store) Append(ctx context.Context, msg Message) error {
	_, err := s.insert(ctx, msg)
	return err
}

// AppendFull persists msg like Append but returns the complete stored message — the id
// and CreatedAt the store assigned when the caller left them empty/zero — so a caller can
// broadcast it for cross-end realtime sync (design/16 §4.2) without a second read.
func (s *Store) AppendFull(ctx context.Context, msg Message) (Message, error) {
	return s.insert(ctx, msg)
}

// insert is the shared Append/AppendFull body. It assigns a fresh id and a now-ms
// CreatedAt when the caller left either empty/zero, then inserts the row and returns the
// resulting message.
func (s *Store) insert(ctx context.Context, msg Message) (Message, error) {
	if msg.ID == "" {
		id, err := newID()
		if err != nil {
			return Message{}, fmt.Errorf("history: append id: %w", err)
		}
		msg.ID = id
	}
	if msg.CreatedAt == 0 {
		msg.CreatedAt = time.Now().UnixMilli()
	}
	_, err := s.db.ExecContext(ctx, `INSERT INTO chat_messages
		(id, session_id, role, content, mode, mood, image, thinking, created_at)
		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
		msg.ID, msg.SessionID, msg.Role, msg.Content, msg.Mode, msg.Mood,
		msg.Image, msg.Thinking, msg.CreatedAt)
	if err != nil {
		return Message{}, fmt.Errorf("history: append %s to %s: %w", msg.Role, msg.SessionID, err)
	}
	return msg, nil
}

// List returns up to limit messages for sessionID, newest first. When before is nonzero
// it bounds the query to messages strictly older than before, so a client can page upward
// by passing the oldest message's created_at from the previous page. The returned slice
// is non-nil. limit is clamped to [1, maxPageLimit].
func (s *Store) List(ctx context.Context, sessionID string, before int64, limit int) ([]Message, error) {
	limit = clampLimit(limit)
	query := `SELECT id, session_id, role, content, mode, mood, image, thinking, created_at
		FROM chat_messages WHERE session_id = ?`
	args := []any{sessionID}
	if before > 0 {
		query += ` AND created_at < ?`
		args = append(args, before)
	}
	query += ` ORDER BY created_at DESC LIMIT ?`
	args = append(args, limit)

	rows, err := s.db.QueryContext(ctx, query, args...)
	if err != nil {
		return nil, fmt.Errorf("history: list %s: %w", sessionID, err)
	}
	defer func() { _ = rows.Close() }()

	msgs := make([]Message, 0)
	for rows.Next() {
		m, err := scanMessage(rows)
		if err != nil {
			return nil, fmt.Errorf("history: scan list %s: %w", sessionID, err)
		}
		msgs = append(msgs, m)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("history: iterate list %s: %w", sessionID, err)
	}
	return msgs, nil
}

// Recent returns the most recent n messages for sessionID in oldest-first order (the
// tail-most window), for WS replay / context tail. The returned slice is non-nil.
func (s *Store) Recent(ctx context.Context, sessionID string, n int) ([]Message, error) {
	if n < 1 {
		n = defaultPageLimit
	}
	rows, err := s.db.QueryContext(ctx, `SELECT id, session_id, role, content, mode, mood, image, thinking, created_at
		FROM chat_messages WHERE session_id = ? ORDER BY created_at DESC LIMIT ?`, sessionID, n)
	if err != nil {
		return nil, fmt.Errorf("history: recent %s: %w", sessionID, err)
	}
	defer func() { _ = rows.Close() }()

	// Recent returns newest-last so the window is in chronological order; build it and
	// reverse in place.
	msgs := make([]Message, 0)
	for rows.Next() {
		m, err := scanMessage(rows)
		if err != nil {
			return nil, fmt.Errorf("history: scan recent %s: %w", sessionID, err)
		}
		msgs = append(msgs, m)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("history: iterate recent %s: %w", sessionID, err)
	}
	for i, j := 0, len(msgs)-1; i < j; i, j = i+1, j-1 {
		msgs[i], msgs[j] = msgs[j], msgs[i]
	}
	return msgs, nil
}

// DeleteSession removes a sub session and all its messages in one transaction. The fixed
// main session is immutable and returns ErrImmutableMain (design/16 §6).
func (s *Store) DeleteSession(ctx context.Context, sessionID string) error {
	if sessionID == MainSessionID {
		return ErrImmutableMain
	}
	tx, err := s.db.BeginTx(ctx, nil)
	if err != nil {
		return fmt.Errorf("history: begin delete %s: %w", sessionID, err)
	}
	defer func() { _ = tx.Rollback() }()

	if _, err := tx.ExecContext(ctx, `DELETE FROM chat_messages WHERE session_id = ?`, sessionID); err != nil {
		return fmt.Errorf("history: delete messages %s: %w", sessionID, err)
	}
	if _, err := tx.ExecContext(ctx, `DELETE FROM chat_sessions WHERE id = ? AND type = ?`, sessionID, SessionSub); err != nil {
		return fmt.Errorf("history: delete session %s: %w", sessionID, err)
	}
	if err := tx.Commit(); err != nil {
		return fmt.Errorf("history: commit delete %s: %w", sessionID, err)
	}
	return nil
}

// NewSubSession creates a sub session and returns its id (MainSessionID:uuid). ownerID is
// accepted for interface completeness (the Web owner is identified by JWT, not stored per
// session); it is logged at debug and not persisted.
func (s *Store) NewSubSession(ctx context.Context, ownerID string) (string, error) {
	id, err := newID()
	if err != nil {
		return "", fmt.Errorf("history: new sub id: %w", err)
	}
	sessionID := MainSessionID + ":" + id
	now := time.Now().UnixMilli()
	if _, err := s.db.ExecContext(ctx, `INSERT INTO chat_sessions (id, type, title, created_at)
		VALUES (?, ?, ?, ?)`, sessionID, SessionSub, "", now); err != nil {
		return "", fmt.Errorf("history: insert sub session: %w", err)
	}
	if s.log != nil {
		s.log.Debug("sub session created", "session_id", sessionID, "owner_id", ownerID)
	}
	return sessionID, nil
}

// ListSessions returns the main session first, then every sub session, oldest first. The
// returned slice is non-nil.
func (s *Store) ListSessions(ctx context.Context) ([]SessionMeta, error) {
	rows, err := s.db.QueryContext(ctx, `SELECT id, type, title, created_at FROM chat_sessions
		ORDER BY (type = ?) DESC, created_at ASC`, SessionMain)
	if err != nil {
		return nil, fmt.Errorf("history: list sessions: %w", err)
	}
	defer func() { _ = rows.Close() }()

	sessions := make([]SessionMeta, 0)
	for rows.Next() {
		var (
			meta      SessionMeta
			typeStr   string
			createdAt int64
		)
		if err := rows.Scan(&meta.ID, &typeStr, &meta.Title, &createdAt); err != nil {
			return nil, fmt.Errorf("history: scan session: %w", err)
		}
		meta.Type = typeStr
		meta.CreatedAt = createdAt
		sessions = append(sessions, meta)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("history: iterate sessions: %w", err)
	}
	return sessions, nil
}

// ensureMainSession inserts the fixed main session row when it is absent, so ListSessions
// always reports the main session even before any message is written.
func (s *Store) ensureMainSession(ctx context.Context) error {
	_, err := s.db.ExecContext(ctx, `INSERT OR IGNORE INTO chat_sessions (id, type, title, created_at)
		VALUES (?, ?, ?, ?)`, MainSessionID, SessionMain, "", time.Now().UnixMilli())
	if err != nil {
		return fmt.Errorf("history: ensure main session: %w", err)
	}
	return nil
}

// scanMessage reads one chat_messages row. message columns are scanned positionally.
func scanMessage(sc rowScanner) (Message, error) {
	var m Message
	var mode, mood, image, thinking string
	if err := sc.Scan(&m.ID, &m.SessionID, &m.Role, &m.Content, &mode, &mood, &image, &thinking, &m.CreatedAt); err != nil {
		return Message{}, err
	}
	m.Mode, m.Mood, m.Image, m.Thinking = mode, mood, image, thinking
	return m, nil
}

// clampLimit bounds limit to [1, maxPageLimit]; a caller-supplied 0 or negative falls back
// to defaultPageLimit.
func clampLimit(limit int) int {
	if limit < 1 {
		return defaultPageLimit
	}
	if limit > maxPageLimit {
		return maxPageLimit
	}
	return limit
}

// newID returns a 128-bit cryptographically random id, hex-encoded. It avoids a UUID
// dependency so the package stays self-contained.
func newID() (string, error) {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		return "", fmt.Errorf("history: generate id: %w", err)
	}
	return hex.EncodeToString(b), nil
}

// discardLogger returns log if non-nil, otherwise a logger that writes nowhere.
func discardLogger(log *slog.Logger) *slog.Logger {
	if log != nil {
		return log
	}
	return slog.New(slog.NewTextHandler(io.Discard, nil))
}

// Schema DDL. The 0003 migration in internal/db is the authoritative mechanism for
// domain tables, but it is intentionally also re-issued here idempotently so the store is
// self-contained and usable from any *sql.DB (matching the memory and session packages).
const createSessionsTable = `
CREATE TABLE IF NOT EXISTS chat_sessions (
    id         TEXT PRIMARY KEY,
    type       TEXT NOT NULL,
    title      TEXT NOT NULL DEFAULT '',
    created_at INTEGER NOT NULL
)`

const createMessagesTable = `
CREATE TABLE IF NOT EXISTS chat_messages (
    id         TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    role       TEXT NOT NULL,
    content    TEXT NOT NULL,
    mode       TEXT,
    mood       TEXT,
    image      TEXT,
    thinking   TEXT,
    created_at INTEGER NOT NULL
)`

const createMessagesIndex = `
CREATE INDEX IF NOT EXISTS idx_chat_msgs_session_created
    ON chat_messages (session_id, created_at DESC)`