libero3 0.3.0

package/dist/mcp/src/repo/sqlite.js

@@ -0,0 +1,754 @@
+import { buildTimeRangeWhere } from "./sqlite-helpers.js";
+import { buildTimelineFromEvents, computeDefaultWindow, } from "../timeline/index.js";
+import { effectiveUserId } from "../profile-helpers.js";
+import { userIdIn } from "../identity/equivalent-ids.js";
+function profileExistsForUser(db, userId) {
+    const uid = userIdIn(db, "id", userId);
+    const row = db
+        .prepare(`SELECT id FROM user_profile WHERE ${uid.clause} AND deleted_at IS NULL`)
+        .get(...uid.params);
+    return !!row;
+}
+// ============================================================
+// SqliteCategoryRepo (R1-R3)
+// ============================================================
+export class SqliteCategoryRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getAll() {
+        return this.db
+            .prepare("SELECT id, name, emoji, color FROM categories WHERE deleted_at IS NULL ORDER BY id")
+            .all();
+    }
+    async getById(id) {
+        const row = this.db
+            .prepare("SELECT id, name, emoji, color FROM categories WHERE id = ? AND deleted_at IS NULL")
+            .get(id);
+        return row ?? null;
+    }
+}
+// ============================================================
+// SqliteTimeBlockRepo (R2)
+// ============================================================
+export class SqliteTimeBlockRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        const durationMinutes = input.duration_minutes ??
+            Math.round((new Date(input.end_time).getTime() -
+                new Date(input.start_time).getTime()) /
+                60000);
+        this.db
+            .prepare(`INSERT INTO time_blocks (id, user_id, title, category_id, start_time, end_time, duration_minutes, rating, rating_reason, notes, status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, input.user_id, input.title.trim(), input.category_id ?? null, input.start_time, input.end_time, durationMinutes, input.rating ?? null, input.rating_reason ?? null, input.notes ?? null, input.status ?? "completed", now, now);
+        return (await this.getById(id));
+    }
+    async getById(id) {
+        const row = this.db
+            .prepare("SELECT * FROM time_blocks WHERE id = ? AND deleted_at IS NULL")
+            .get(id);
+        return row ?? null;
+    }
+    async list(filters) {
+        const uid = userIdIn(this.db, "user_id", filters.user_id);
+        const conditions = [uid.clause];
+        const params = [...uid.params];
+        if (!filters.include_deleted) {
+            conditions.push("deleted_at IS NULL");
+        }
+        const range = buildTimeRangeWhere({
+            column: "start_time",
+            date: filters.date,
+            from: filters.from,
+            to: filters.to,
+        });
+        conditions.push(...range.clauses);
+        params.push(...range.params);
+        if (filters.category_id) {
+            conditions.push("category_id = ?");
+            params.push(filters.category_id);
+        }
+        if (filters.status) {
+            conditions.push("status = ?");
+            params.push(filters.status);
+        }
+        let limit = filters.limit ?? 50;
+        if (limit > 100)
+            limit = 100;
+        const offset = filters.offset ?? 0;
+        const sql = `SELECT * FROM time_blocks WHERE ${conditions.join(" AND ")} ORDER BY start_time DESC LIMIT ? OFFSET ?`;
+        params.push(limit, offset);
+        return this.db.prepare(sql).all(...params);
+    }
+    async update(id, input) {
+        const existing = this.db
+            .prepare("SELECT * FROM time_blocks WHERE id = ? AND deleted_at IS NULL")
+            .get(id);
+        if (!existing) {
+            throw new Error("时间块不存在");
+        }
+        const newStart = input.start_time ?? existing.start_time;
+        const newEnd = input.end_time ?? existing.end_time;
+        let newDuration;
+        if (input.duration_minutes !== undefined) {
+            newDuration = input.duration_minutes;
+        }
+        else if (input.start_time !== undefined ||
+            input.end_time !== undefined) {
+            newDuration = Math.round((new Date(newEnd).getTime() - new Date(newStart).getTime()) / 60000);
+        }
+        else {
+            newDuration = existing.duration_minutes;
+        }
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "") +
+            String(Math.floor(performance.now() * 100000) % 100000).padStart(5, "0");
+        this.db
+            .prepare(`UPDATE time_blocks SET
+           title = ?,
+           category_id = ?,
+           start_time = ?,
+           end_time = ?,
+           duration_minutes = ?,
+           rating = ?,
+           rating_reason = ?,
+           notes = ?,
+           status = ?,
+           updated_at = ?
+         WHERE id = ?`)
+            .run((input.title ?? existing.title).trim() || existing.title, input.category_id !== undefined
+            ? input.category_id
+            : existing.category_id, newStart, newEnd, newDuration, input.rating !== undefined ? input.rating : existing.rating, input.rating_reason !== undefined
+            ? input.rating_reason
+            : existing.rating_reason, input.notes !== undefined ? input.notes : existing.notes, input.status !== undefined ? input.status : existing.status, now, id);
+        return (await this.getById(id));
+    }
+    async remove(id) {
+        const exists = this.db
+            .prepare("SELECT id, deleted_at FROM time_blocks WHERE id = ?")
+            .get(id);
+        if (!exists) {
+            throw new Error("时间块不存在");
+        }
+        if (exists.deleted_at !== null) {
+            return; // already soft-deleted, idempotent
+        }
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        this.db
+            .prepare("UPDATE time_blocks SET deleted_at = ?, updated_at = ? WHERE id = ?")
+            .run(now, now, id);
+    }
+    async exists(id) {
+        const row = this.db
+            .prepare("SELECT id FROM time_blocks WHERE id = ?")
+            .get(id);
+        return !!row;
+    }
+    async userExists(userId) {
+        return profileExistsForUser(this.db, userId);
+    }
+    /** S48（2026-08-11）：标记扫描追问已发。幂等保护：每条只被 cron 主动问一次。返回受影响行数。 */
+    async markAsked(ids, askedAt) {
+        if (!ids || ids.length === 0)
+            return 0;
+        const ts = askedAt ?? new Date().toISOString();
+        const placeholders = ids.map(() => "?").join(", ");
+        const result = this.db
+            .prepare(`UPDATE time_blocks SET asked_at = ?, updated_at = ?
+         WHERE id IN (${placeholders}) AND deleted_at IS NULL`)
+            .run(ts, ts, ...ids);
+        return result.changes;
+    }
+    async restore(id) {
+        const row = this.db
+            .prepare("SELECT id, deleted_at FROM time_blocks WHERE id = ?")
+            .get(id);
+        if (!row || row.deleted_at === null) {
+            throw new Error("时间块不存在或未被删除");
+        }
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        this.db
+            .prepare(
+        // MV-COACH-3 Slice 4: restore 后状态 = unverified（不知道用户执行了没，等用户核实才升 completed）。
+        // 原 v0 是 'completed'（当时没状态机概念，恢复即默认已完成）。新模型下 completed 必须用户确认。
+        "UPDATE time_blocks SET deleted_at = NULL, status = 'unverified', updated_at = ? WHERE id = ?")
+            .run(now, id);
+        return (await this.getById(id));
+    }
+    async findOverlapping(input) {
+        // ⚠️ 时区安全：用 SQLite datetime() 规范化所有时间字段后再比较。
+        // datetime() 能解析多种 ISO 格式（含 +08:00 / Z），输出统一 'YYYY-MM-DD HH:MM:SS' UTC。
+        // 不能用裸字符串比较（'2026-08-07T09:00:00+08:00' vs '2026-08-07T01:00:00Z' 字符串比较会误判）。
+        const uid = userIdIn(this.db, "user_id", input.user_id);
+        return this.db
+            .prepare(`SELECT * FROM time_blocks
+         WHERE ${uid.clause} AND status = 'planned' AND deleted_at IS NULL
+           AND datetime(start_time) < datetime(?)
+           AND datetime(end_time) > datetime(?)
+         ORDER BY start_time`)
+            .all(...uid.params, input.end, input.start);
+    }
+    async findExactWindow(input) {
+        const uid = userIdIn(this.db, "user_id", input.user_id);
+        const row = this.db
+            .prepare(`SELECT * FROM time_blocks
+         WHERE ${uid.clause} AND deleted_at IS NULL
+           AND title = ? AND status = ?
+           AND datetime(start_time) = datetime(?)
+           AND datetime(end_time) = datetime(?)
+         LIMIT 1`)
+            .get(...uid.params, input.title.trim(), input.status, input.start, input.end);
+        return row ?? null;
+    }
+}
+// ============================================================
+// SqliteStatsRepo (R2 — stats + matrix)
+// ============================================================
+// -- pure helpers for renderMatrix (copied verbatim from matrix/index.ts) --
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 1) {
+        return sorted[mid];
+    }
+    return (sorted[mid - 1] + sorted[mid]) / 2;
+}
+const QUADRANT_ORDER = {
+    "能耗黑洞": 0,
+    "可放弃": 1,
+    "保持区": 2,
+    "亮点区": 3,
+};
+function assignQuadrant(highTime, highRating) {
+    if (highTime && highRating)
+        return "保持区";
+    if (highTime && !highRating)
+        return "能耗黑洞";
+    if (!highTime && highRating)
+        return "亮点区";
+    return "可放弃";
+}
+export class SqliteStatsRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async summarize(filters) {
+        const uid = userIdIn(this.db, "tb.user_id", filters.user_id);
+        const conditions = [
+            uid.clause,
+            "tb.deleted_at IS NULL",
+            // MV-COACH-3 Slice 4: 只统计实绩。planned/unverified 不算（用户主权模型：
+            // 只有用户确认执行过的才进 stats，避免"建了日程就虚增统计"）。
+            "tb.status = 'completed'",
+        ];
+        const params = [...uid.params];
+        const range = buildTimeRangeWhere({
+            column: "tb.start_time",
+            from: filters.from,
+            to: filters.to,
+        });
+        conditions.push(...range.clauses);
+        params.push(...range.params);
+        if (filters.category_id) {
+            conditions.push("tb.category_id = ?");
+            params.push(filters.category_id);
+        }
+        const rows = this.db
+            .prepare(`SELECT
+           COALESCE(tb.category_id, 'cat-other') as category_id,
+           COALESCE(c.name, '其他') as category_name,
+           COALESCE(c.emoji, '❓') as category_emoji,
+           SUM(tb.duration_minutes) as total_minutes,
+           COUNT(*) as record_count
+         FROM time_blocks tb
+         LEFT JOIN categories c ON tb.category_id = c.id
+         WHERE ${conditions.join(" AND ")}
+         GROUP BY COALESCE(tb.category_id, 'cat-other')
+         ORDER BY total_minutes DESC`)
+            .all(...params);
+        const grandTotal = rows.reduce((sum, r) => sum + r.total_minutes, 0);
+        return rows.map((r) => ({
+            category_id: r.category_id,
+            category_name: r.category_name,
+            category_emoji: r.category_emoji,
+            total_minutes: r.total_minutes,
+            percentage: grandTotal > 0
+                ? Math.round((r.total_minutes / grandTotal) * 1000) / 10
+                : 0,
+            record_count: r.record_count,
+        }));
+    }
+    async dailyBreakdown(filters) {
+        const uid = userIdIn(this.db, "tb.user_id", filters.user_id);
+        const conditions = [
+            uid.clause,
+            "tb.deleted_at IS NULL",
+            // MV-COACH-3 Slice 4: 只统计实绩。planned/unverified 不算（用户主权模型：
+            // 只有用户确认执行过的才进 stats，避免"建了日程就虚增统计"）。
+            "tb.status = 'completed'",
+        ];
+        const params = [...uid.params];
+        const range = buildTimeRangeWhere({
+            column: "tb.start_time",
+            from: filters.from,
+            to: filters.to,
+        });
+        conditions.push(...range.clauses);
+        params.push(...range.params);
+        if (filters.category_id) {
+            conditions.push("tb.category_id = ?");
+            params.push(filters.category_id);
+        }
+        const rows = this.db
+            .prepare(`SELECT
+           DATE(tb.start_time) as date,
+           COALESCE(tb.category_id, 'cat-other') as category_id,
+           COALESCE(c.name, '其他') as category_name,
+           COALESCE(c.emoji, '❓') as category_emoji,
+           SUM(tb.duration_minutes) as minutes
+         FROM time_blocks tb
+         LEFT JOIN categories c ON tb.category_id = c.id
+         WHERE ${conditions.join(" AND ")}
+         GROUP BY DATE(tb.start_time), COALESCE(tb.category_id, 'cat-other')
+         ORDER BY DATE(tb.start_time) ASC, minutes DESC`)
+            .all(...params);
+        // Aggregate into date-keyed map
+        const dayMap = new Map();
+        for (const row of rows) {
+            let day = dayMap.get(row.date);
+            if (!day) {
+                day = { date: row.date, total_minutes: 0, categories: [] };
+                dayMap.set(row.date, day);
+            }
+            day.categories.push({
+                category_id: row.category_id,
+                category_name: row.category_name,
+                category_emoji: row.category_emoji,
+                minutes: row.minutes,
+            });
+            day.total_minutes += row.minutes;
+        }
+        return [...dayMap.values()];
+    }
+    async renderMatrix(filters) {
+        const uid = userIdIn(this.db, "tb.user_id", filters.user_id);
+        const conditions = [
+            uid.clause,
+            "tb.deleted_at IS NULL",
+            // MV-COACH-3 Slice 4: 只统计实绩。planned/unverified 不算（用户主权模型：
+            // 只有用户确认执行过的才进 stats，避免"建了日程就虚增统计"）。
+            "tb.status = 'completed'",
+        ];
+        const params = [...uid.params];
+        const range = buildTimeRangeWhere({
+            column: "tb.start_time",
+            from: filters.from,
+            to: filters.to,
+        });
+        conditions.push(...range.clauses);
+        params.push(...range.params);
+        const rows = this.db
+            .prepare(`SELECT
+           COALESCE(tb.category_id, 'cat-other') as category_id,
+           COALESCE(c.name, '其他') as category_name,
+           COALESCE(c.emoji, '❓') as category_emoji,
+           SUM(tb.duration_minutes) as total_minutes,
+           AVG(tb.rating) as avg_rating,
+           COUNT(*) as record_count
+         FROM time_blocks tb
+         LEFT JOIN categories c ON tb.category_id = c.id
+         WHERE ${conditions.join(" AND ")}
+         GROUP BY COALESCE(tb.category_id, 'cat-other')
+         HAVING avg_rating IS NOT NULL`)
+            .all(...params);
+        if (rows.length === 0) {
+            return { median_minutes: 0, median_rating: 0, bubbles: [] };
+        }
+        const minutesValues = rows.map((r) => r.total_minutes);
+        const ratingValues = rows.map((r) => r.avg_rating);
+        const medianMinutes = median(minutesValues);
+        const medianRating = median(ratingValues);
+        const bubbles = rows
+            .map((r) => {
+            const highTime = r.total_minutes >= medianMinutes;
+            const highRating = r.avg_rating >= medianRating;
+            return {
+                category_id: r.category_id,
+                category_name: r.category_name,
+                category_emoji: r.category_emoji,
+                total_minutes: r.total_minutes,
+                avg_rating: Math.round(r.avg_rating * 10) / 10,
+                record_count: r.record_count,
+                quadrant: assignQuadrant(highTime, highRating),
+            };
+        })
+            .sort((a, b) => {
+            const orderDiff = QUADRANT_ORDER[a.quadrant] - QUADRANT_ORDER[b.quadrant];
+            if (orderDiff !== 0)
+                return orderDiff;
+            return b.total_minutes - a.total_minutes;
+        });
+        return {
+            median_minutes: medianMinutes,
+            median_rating: Math.round(medianRating * 10) / 10,
+            bubbles,
+        };
+    }
+}
+// ============================================================
+// SqliteTimelineRepo (schedule.timeline)
+// ============================================================
+export class SqliteTimelineRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async renderTimeline(filters) {
+        const userId = effectiveUserId(filters);
+        const blockUid = userIdIn(this.db, "tb.user_id", userId);
+        const timerUid = userIdIn(this.db, "user_id", userId);
+        const now = new Date();
+        let from;
+        let to;
+        if (filters.from !== undefined || filters.to !== undefined) {
+            const def = computeDefaultWindow(now);
+            from = filters.from !== undefined ? new Date(filters.from) : def.from;
+            to = filters.to !== undefined ? new Date(filters.to) : def.to;
+        }
+        else {
+            const def = computeDefaultWindow(now);
+            from = def.from;
+            to = def.to;
+        }
+        // Expand fetch to calendar-day bounds so details can include 窗口外
+        const fetchFrom = new Date(from);
+        fetchFrom.setHours(0, 0, 0, 0);
+        const fetchTo = new Date(to);
+        fetchTo.setHours(23, 59, 59, 999);
+        const blocks = this.db
+            .prepare(`SELECT
+           tb.start_time as start,
+           tb.end_time as end,
+           tb.status as status,
+           tb.title as title,
+           tb.category_id as category_id,
+           c.emoji as category_emoji,
+           c.name as category_name,
+           c.color as category_color
+         FROM time_blocks tb
+         LEFT JOIN categories c ON tb.category_id = c.id
+         WHERE ${blockUid.clause}
+           AND tb.deleted_at IS NULL
+           AND tb.status IN ('planned', 'unverified', 'completed')
+           AND datetime(tb.start_time) < datetime(?)
+           AND datetime(tb.end_time) > datetime(?)`)
+            .all(...blockUid.params, fetchTo.toISOString(), fetchFrom.toISOString());
+        const timers = this.db
+            .prepare(`SELECT started_at, accumulated_ms, status, event
+         FROM timer_sessions
+         WHERE ${timerUid.clause} AND status IN ('running', 'paused')`)
+            .all(...timerUid.params);
+        return buildTimelineFromEvents({
+            blocks,
+            timers,
+            from,
+            to,
+            now,
+            format: filters.format ?? "emoji",
+        });
+    }
+}
+// ============================================================
+// SqliteTimerRepo (R4 — timer persistence)
+// ============================================================
+export class SqliteTimerRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getActive(userId) {
+        const uid = userIdIn(this.db, "user_id", userId);
+        const row = this.db
+            .prepare(`SELECT * FROM timer_sessions WHERE ${uid.clause} AND status IN ('running', 'paused') LIMIT 1`)
+            .get(...uid.params);
+        return row ?? null;
+    }
+    async getAllActive() {
+        return this.db
+            .prepare("SELECT * FROM timer_sessions WHERE status IN ('running', 'paused')")
+            .all();
+    }
+    async create(input) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO timer_sessions (id, user_id, event, category_id, status, started_at, accumulated_ms, target_ms, task_id, created_at, updated_at)
+         VALUES (?, ?, ?, ?, 'running', ?, 0, ?, ?, ?, ?)`)
+            .run(id, input.user_id, input.event.trim(), input.category_id ?? null, input.started_at, input.target_ms ?? null, input.task_id ?? null, now, now);
+        return this.db
+            .prepare("SELECT * FROM timer_sessions WHERE id = ?")
+            .get(id);
+    }
+    async update(id, patch) {
+        const now = new Date().toISOString();
+        const sets = ["updated_at = ?"];
+        const params = [now];
+        if (patch.status !== undefined) {
+            sets.push("status = ?");
+            params.push(patch.status);
+        }
+        if (patch.started_at !== undefined) {
+            sets.push("started_at = ?");
+            params.push(patch.started_at);
+        }
+        if (patch.accumulated_ms !== undefined) {
+            sets.push("accumulated_ms = ?");
+            params.push(patch.accumulated_ms);
+        }
+        if (patch.ended_at !== undefined) {
+            sets.push("ended_at = ?");
+            params.push(patch.ended_at);
+        }
+        if (patch.target_ms !== undefined) {
+            sets.push("target_ms = ?");
+            params.push(patch.target_ms);
+        }
+        params.push(id);
+        this.db
+            .prepare(`UPDATE timer_sessions SET ${sets.join(", ")} WHERE id = ?`)
+            .run(...params);
+        return this.db
+            .prepare("SELECT * FROM timer_sessions WHERE id = ?")
+            .get(id);
+    }
+    async userExists(userId) {
+        return profileExistsForUser(this.db, userId);
+    }
+}
+// ============================================================
+// SqliteProfileRepo (S13 — profile with structured settings)
+// ============================================================
+export class SqliteProfileRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async markPortraitDirty(userId) {
+        this.db
+            .prepare("UPDATE user_profile SET portrait_dirty = 1 WHERE id = ?")
+            .run(userId);
+    }
+    async getById(userId) {
+        const row = this.db
+            .prepare("SELECT id, display_name, expectations, settings, created_at, updated_at FROM user_profile WHERE id = ? AND deleted_at IS NULL")
+            .get(userId);
+        if (!row)
+            return null;
+        return {
+            id: row.id,
+            display_name: row.display_name,
+            expectations: row.expectations,
+            settings: row.settings != null ? JSON.parse(row.settings) : null,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        };
+    }
+    async upsert(input) {
+        const existing = await this.getById(input.user_id);
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        if (existing) {
+            // Update: merge top-level fields, retain existing values for unset fields
+            const display_name = input.display_name !== undefined
+                ? input.display_name
+                : existing.display_name;
+            const expectations = input.expectations !== undefined
+                ? input.expectations
+                : existing.expectations;
+            // settings: whole-object replace (not deep merge), per S13 §4
+            const settings = input.settings !== undefined
+                ? JSON.stringify(input.settings)
+                : existing.settings != null
+                    ? JSON.stringify(existing.settings)
+                    : null;
+            this.db
+                .prepare(`UPDATE user_profile SET display_name = ?, expectations = ?, settings = ?, updated_at = ? WHERE id = ?`)
+                .run(display_name, expectations, settings, now, input.user_id);
+        }
+        else {
+            // Insert
+            const display_name = input.display_name ?? "";
+            const expectations = input.expectations ?? null;
+            const settings = input.settings !== undefined
+                ? JSON.stringify(input.settings)
+                : null;
+            this.db
+                .prepare(`INSERT INTO user_profile (id, display_name, expectations, settings, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?)`)
+                .run(input.user_id, display_name, expectations, settings, now, now);
+        }
+        return (await this.getById(input.user_id));
+    }
+    /**
+     * S40 slice 3：Atomic claim nudge。
+     *
+     * 用 better-sqlite3 的 `db.transaction()` 把「SELECT → 检查 window → UPDATE → 返回」
+     * 包成一个原子单元。better-sqlite3 是**同步**的——transaction 期间阻塞 event loop，
+     * 第二个调用根本没机会插入。
+     *
+     * 注意：transaction 返回的函数是同步的，必须在同步上下文调用（不能 await）。
+     * 这里包装成 async 只是为了匹配 ProfileRepo interface，内部完全同步执行。
+     */
+    async claimNudgeAtomic(input) {
+        const windowMs = input.window_minutes * 60 * 1000;
+        const now = new Date();
+        const nowIso = now.toISOString();
+        const nowDb = nowIso.replace("T", " ").replace("Z", "");
+        const rowToProfile = (r) => ({
+            id: r.id,
+            display_name: r.display_name,
+            expectations: r.expectations,
+            settings: r.settings != null ? JSON.parse(r.settings) : null,
+            created_at: r.created_at,
+            updated_at: r.updated_at,
+        });
+        const selectStmt = this.db.prepare("SELECT id, display_name, expectations, settings, created_at, updated_at FROM user_profile WHERE id = ? AND deleted_at IS NULL");
+        const updateStmt = this.db.prepare(`UPDATE user_profile SET settings = ?, updated_at = ? WHERE id = ?`);
+        const insertStmt = this.db.prepare(`INSERT INTO user_profile (id, display_name, expectations, settings, created_at, updated_at)
+       VALUES (?, '', NULL, ?, ?, ?)`);
+        // transaction 函数（同步）。better-sqlite3 在 transaction() 期间阻塞 event loop，
+        // 第二个并发调用必须等第一个 COMMIT 才能进入 BEGIN。
+        const txn = this.db.transaction(() => {
+            const row = selectStmt.get(input.user_id);
+            const existingSettings = row?.settings != null
+                ? JSON.parse(row.settings)
+                : {};
+            const lastNudgeAt = existingSettings.last_inactivity_nudge_at;
+            if (typeof lastNudgeAt === "string") {
+                const ageMs = now.getTime() - new Date(lastNudgeAt).getTime();
+                if (ageMs < windowMs) {
+                    return { won: false, profile: rowToProfile(row) };
+                }
+            }
+            const merged = {
+                ...existingSettings,
+                last_inactivity_nudge_at: nowIso,
+            };
+            const settingsJson = JSON.stringify(merged);
+            if (row) {
+                updateStmt.run(settingsJson, nowDb, input.user_id);
+            }
+            else {
+                insertStmt.run(input.user_id, settingsJson, nowDb, nowDb);
+            }
+            const updated = selectStmt.get(input.user_id);
+            return { won: true, profile: rowToProfile(updated) };
+        });
+        // BEGIN IMMEDIATE：立刻拿写锁，防止 deferred 模式下读-写升级冲突
+        // better-sqlite3 API：transaction 函数有 .immediate(args) 变种
+        return txn.immediate();
+    }
+}
+// ============================================================
+// SqliteReminderRepo (S11 — reminder persistence)
+// ============================================================
+export class SqliteReminderRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        // Normalize to UTC Z format — ensures getDueReminders string comparison
+        // works correctly even when caller passes +08:00 or other offsets.
+        const remindAt = new Date(input.remind_at).toISOString();
+        this.db
+            .prepare(`INSERT INTO reminders (id, user_id, timeblock_id, content, remind_at, channel, status, attempts, sent_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 'pending', 0, NULL, ?, ?)`)
+            .run(id, input.user_id, input.timeblock_id ?? null, input.content, remindAt, input.channel ?? "session", now, now);
+        return (await this.getById(id));
+    }
+    async getById(id) {
+        const row = this.db
+            .prepare("SELECT * FROM reminders WHERE id = ? AND deleted_at IS NULL")
+            .get(id);
+        return row ?? null;
+    }
+    async getDueReminders(input) {
+        if (input.user_id) {
+            const uid = userIdIn(this.db, "user_id", input.user_id);
+            return this.db
+                .prepare(`SELECT * FROM reminders WHERE status = 'pending' AND remind_at <= ? AND ${uid.clause} AND deleted_at IS NULL ORDER BY remind_at ASC`)
+                .all(input.until, ...uid.params);
+        }
+        return this.db
+            .prepare("SELECT * FROM reminders WHERE status = 'pending' AND remind_at <= ? AND deleted_at IS NULL ORDER BY remind_at ASC")
+            .all(input.until);
+    }
+    async getNextDue(input = {}) {
+        if (input.user_id) {
+            const uid = userIdIn(this.db, "user_id", input.user_id);
+            const row = this.db
+                .prepare(`SELECT remind_at FROM reminders WHERE status = 'pending' AND ${uid.clause} AND deleted_at IS NULL ORDER BY remind_at ASC LIMIT 1`)
+                .get(...uid.params);
+            return row ?? null;
+        }
+        const row = this.db
+            .prepare("SELECT remind_at FROM reminders WHERE status = 'pending' AND deleted_at IS NULL ORDER BY remind_at ASC LIMIT 1")
+            .get();
+        return row ?? null;
+    }
+    async getMissedReminders(input) {
+        const uid = userIdIn(this.db, "user_id", input.user_id);
+        return this.db
+            .prepare(`SELECT * FROM reminders WHERE status = 'pending' AND remind_at < ? AND ${uid.clause} AND deleted_at IS NULL ORDER BY remind_at ASC`)
+            .all(input.now, ...uid.params);
+    }
+    async markSent(id) {
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        this.db
+            .prepare("UPDATE reminders SET status = 'sent', sent_at = ?, updated_at = ? WHERE id = ? AND deleted_at IS NULL")
+            .run(now, now, id);
+    }
+    async cancelReminder(id) {
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        this.db
+            .prepare("UPDATE reminders SET status = 'cancelled', updated_at = ? WHERE id = ? AND deleted_at IS NULL")
+            .run(now, id);
+    }
+    async userExists(userId) {
+        return profileExistsForUser(this.db, userId);
+    }
+    async claim(id) {
+        const result = this.db
+            .prepare("UPDATE reminders SET status = 'sending', updated_at = datetime('now') WHERE id = ? AND status = 'pending'")
+            .run(id);
+        return result.changes > 0;
+    }
+    async releaseOrFail(id, maxAttempts) {
+        const now = new Date().toISOString().replace("T", " ").replace("Z", "");
+        // Increment attempts atomically
+        this.db
+            .prepare("UPDATE reminders SET attempts = attempts + 1, updated_at = ? WHERE id = ? AND deleted_at IS NULL")
+            .run(now, id);
+        // Check if we should retry
+        const row = this.db
+            .prepare("SELECT attempts FROM reminders WHERE id = ? AND deleted_at IS NULL")
+            .get(id);
+        if (row && row.attempts < maxAttempts) {
+            this.db
+                .prepare("UPDATE reminders SET status = 'pending', updated_at = ? WHERE id = ? AND deleted_at IS NULL")
+                .run(now, id);
+        }
+        // else: stays 'sending' — dead, won't be picked up again
+    }
+}