libero3 0.3.0

package/dist/mcp/src/repo/in-memory.js

@@ -0,0 +1,469 @@
+import { BOUNTY_QUESTS, REWARD_CONFIG, dayKey, periodKeyFor, rewardForNth } from "../ap/rewards.js";
+import { buildTimelineFromEvents, computeDefaultWindow, } from "../timeline/index.js";
+import { effectiveUserId } from "../profile-helpers.js";
+/** In-memory CategoryRepo for testing / contract verification.
+ *  Receives seed data via constructor — no global state, no getDb(). */
+export class InMemoryCategoryRepo {
+    categories;
+    constructor(seed) {
+        this.categories = [...seed];
+    }
+    async getAll() {
+        // Return defensive copy so callers can't mutate internal state
+        return [...this.categories];
+    }
+    async getById(id) {
+        return this.categories.find((c) => c.id === id) ?? null;
+    }
+}
+/** In-memory TimeBlockRepo for testing / contract verification. */
+export class InMemoryTimeBlockRepo {
+    blocks = [];
+    userIds;
+    constructor(userIds) {
+        this.userIds = new Set(userIds);
+    }
+    async create(input) {
+        const now = new Date().toISOString();
+        const durationMinutes = input.duration_minutes ??
+            Math.round((new Date(input.end_time).getTime() -
+                new Date(input.start_time).getTime()) /
+                60000);
+        const block = {
+            id: crypto.randomUUID(),
+            user_id: input.user_id,
+            title: input.title.trim(),
+            category_id: input.category_id ?? null,
+            start_time: input.start_time,
+            end_time: input.end_time,
+            duration_minutes: durationMinutes,
+            rating: input.rating ?? null,
+            rating_reason: input.rating_reason ?? null,
+            notes: input.notes ?? null,
+            status: input.status ?? "completed",
+            created_at: now,
+            updated_at: now,
+            deleted_at: null,
+        };
+        this.blocks.push(block);
+        return { ...block };
+    }
+    async getById(id) {
+        const b = this.blocks.find((b) => b.id === id && b.deleted_at === null);
+        return b ? { ...b } : null;
+    }
+    async list(filters) {
+        let results = this.blocks.filter((b) => b.user_id === filters.user_id);
+        if (!filters.include_deleted) {
+            results = results.filter((b) => b.deleted_at === null);
+        }
+        if (filters.status) {
+            results = results.filter((b) => b.status === filters.status);
+        }
+        if (filters.category_id) {
+            results = results.filter((b) => b.category_id === filters.category_id);
+        }
+        if (filters.date) {
+            const dayStart = `${filters.date}T00:00:00`;
+            const dayEnd = `${filters.date}T23:59:59`;
+            results = results.filter((b) => b.start_time >= dayStart && b.start_time < dayEnd);
+        }
+        else {
+            if (filters.from) {
+                results = results.filter((b) => b.start_time >= filters.from);
+            }
+            if (filters.to) {
+                results = results.filter((b) => b.start_time <= filters.to);
+            }
+        }
+        results.sort((a, b) => b.start_time.localeCompare(a.start_time));
+        const offset = filters.offset ?? 0;
+        let limit = filters.limit ?? 50;
+        if (limit > 100)
+            limit = 100;
+        return results.slice(offset, offset + limit).map((b) => ({ ...b }));
+    }
+    async update(id, input) {
+        const b = this.blocks.find((b) => b.id === id && b.deleted_at === null);
+        if (!b) {
+            throw new Error("时间块不存在");
+        }
+        const newStart = input.start_time ?? b.start_time;
+        const newEnd = input.end_time ?? b.end_time;
+        if (input.title !== undefined)
+            b.title = input.title.trim() || b.title;
+        if (input.category_id !== undefined)
+            b.category_id = input.category_id;
+        b.start_time = newStart;
+        b.end_time = newEnd;
+        if (input.duration_minutes !== undefined) {
+            b.duration_minutes = input.duration_minutes;
+        }
+        else if (input.start_time !== undefined || input.end_time !== undefined) {
+            b.duration_minutes = Math.round((new Date(newEnd).getTime() - new Date(newStart).getTime()) / 60000);
+        }
+        if (input.rating !== undefined)
+            b.rating = input.rating;
+        if (input.rating_reason !== undefined)
+            b.rating_reason = input.rating_reason;
+        if (input.notes !== undefined)
+            b.notes = input.notes;
+        if (input.status !== undefined)
+            b.status = input.status;
+        b.updated_at = new Date().toISOString();
+        return { ...b };
+    }
+    async remove(id) {
+        const b = this.blocks.find((b) => b.id === id);
+        if (!b) {
+            throw new Error("时间块不存在");
+        }
+        if (b.deleted_at !== null)
+            return; // idempotent
+        b.deleted_at = new Date().toISOString();
+        b.updated_at = b.deleted_at;
+    }
+    async restore(id) {
+        const b = this.blocks.find((b) => b.id === id);
+        if (!b || b.deleted_at === null) {
+            throw new Error("时间块不存在或未被删除");
+        }
+        b.deleted_at = null;
+        // MV-COACH-3 Slice 4: restore 后 = unverified（对齐 sqlite 实现，等用户核实才升 completed）
+        b.status = "unverified";
+        b.updated_at = new Date().toISOString();
+        return { ...b };
+    }
+    async exists(id) {
+        return this.blocks.some((b) => b.id === id);
+    }
+    async userExists(userId) {
+        return this.userIds.has(userId);
+    }
+    /** S48（2026-08-11）：标记扫描追问已发。幂等保护。 */
+    async markAsked(ids, askedAt) {
+        if (!ids || ids.length === 0)
+            return 0;
+        const ts = askedAt ?? new Date().toISOString();
+        let changed = 0;
+        for (const b of this.blocks) {
+            if (ids.includes(b.id) && !b.deleted_at) {
+                b.asked_at = ts;
+                b.updated_at = ts;
+                changed++;
+            }
+        }
+        return changed;
+    }
+    async findOverlapping(input) {
+        return this.blocks
+            .filter((b) => b.user_id === input.user_id &&
+            b.status === "planned" &&
+            b.deleted_at === null &&
+            b.start_time < input.end &&
+            b.end_time > input.start)
+            .sort((a, b) => a.start_time.localeCompare(b.start_time))
+            .map((b) => ({ ...b }));
+    }
+    async findExactWindow(input) {
+        const title = input.title.trim();
+        const startMs = new Date(input.start).getTime();
+        const endMs = new Date(input.end).getTime();
+        const b = this.blocks.find((row) => row.user_id === input.user_id &&
+            row.deleted_at === null &&
+            row.title === title &&
+            row.status === input.status &&
+            new Date(row.start_time).getTime() === startMs &&
+            new Date(row.end_time).getTime() === endMs);
+        return b ? { ...b } : null;
+    }
+}
+/** In-memory ReminderRepo for testing / tool-layer verification. */
+export class InMemoryReminderRepo {
+    reminders = [];
+    userIds;
+    constructor(userIds) {
+        this.userIds = new Set(userIds);
+    }
+    async create(input) {
+        const now = new Date().toISOString();
+        // 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();
+        const reminder = {
+            id: crypto.randomUUID(),
+            user_id: input.user_id,
+            timeblock_id: input.timeblock_id ?? null,
+            content: input.content,
+            remind_at: remindAt,
+            channel: input.channel ?? "session",
+            status: "pending",
+            attempts: 0,
+            sent_at: null,
+            created_at: now,
+            updated_at: now,
+            deleted_at: null,
+        };
+        this.reminders.push(reminder);
+        return { ...reminder };
+    }
+    async getById(id) {
+        const r = this.reminders.find((r) => r.id === id && r.deleted_at === null);
+        return r ? { ...r } : null;
+    }
+    async getDueReminders(input) {
+        return this.reminders
+            .filter((r) => r.status === "pending" &&
+            r.remind_at <= input.until &&
+            r.deleted_at === null &&
+            (input.user_id === undefined || r.user_id === input.user_id))
+            .sort((a, b) => a.remind_at.localeCompare(b.remind_at))
+            .map((r) => ({ ...r }));
+    }
+    async getNextDue(input = {}) {
+        const pending = this.reminders
+            .filter((r) => r.status === "pending" &&
+            r.deleted_at === null &&
+            (input.user_id === undefined || r.user_id === input.user_id))
+            .sort((a, b) => a.remind_at.localeCompare(b.remind_at));
+        return pending.length > 0 ? { remind_at: pending[0].remind_at } : null;
+    }
+    async getMissedReminders(input) {
+        return this.reminders
+            .filter((r) => r.status === "pending" &&
+            r.remind_at < input.now &&
+            r.user_id === input.user_id &&
+            r.deleted_at === null)
+            .sort((a, b) => a.remind_at.localeCompare(b.remind_at))
+            .map((r) => ({ ...r }));
+    }
+    async markSent(id) {
+        const r = this.reminders.find((r) => r.id === id && r.deleted_at === null);
+        if (!r)
+            return; // idempotent: no-op on missing
+        if (r.status === "sent")
+            return; // idempotent
+        const now = new Date().toISOString();
+        r.status = "sent";
+        r.sent_at = now;
+        r.updated_at = now;
+    }
+    async cancelReminder(id) {
+        const r = this.reminders.find((r) => r.id === id && r.deleted_at === null);
+        if (!r)
+            return; // idempotent
+        const now = new Date().toISOString();
+        r.status = "cancelled";
+        r.updated_at = now;
+    }
+    async userExists(userId) {
+        return this.userIds.has(userId);
+    }
+    async claim(id) {
+        const r = this.reminders.find((r) => r.id === id && r.deleted_at === null);
+        if (!r || r.status !== "pending")
+            return false;
+        r.status = "sending";
+        r.updated_at = new Date().toISOString();
+        return true;
+    }
+    async releaseOrFail(id, maxAttempts) {
+        const r = this.reminders.find((r) => r.id === id && r.deleted_at === null);
+        if (!r)
+            return;
+        r.attempts += 1;
+        r.updated_at = new Date().toISOString();
+        if (r.attempts < maxAttempts) {
+            r.status = "pending"; // retry
+        }
+        // else: stays 'sending' — dead, won't be picked up again
+    }
+}
+/** In-memory TimelineRepo — independent of other in-memory repos. */
+export class InMemoryTimelineRepo {
+    seed;
+    constructor(seed) {
+        this.seed = {
+            timeblocks: [...seed.timeblocks],
+            timer_sessions: [...seed.timer_sessions],
+            categories: [...seed.categories],
+        };
+    }
+    async renderTimeline(filters) {
+        const userId = effectiveUserId(filters);
+        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;
+        }
+        const fetchFrom = new Date(from);
+        fetchFrom.setHours(0, 0, 0, 0);
+        const fetchTo = new Date(to);
+        fetchTo.setHours(23, 59, 59, 999);
+        const fetchFromMs = fetchFrom.getTime();
+        const fetchToMs = fetchTo.getTime();
+        const catMap = new Map(this.seed.categories.map((c) => [c.id, c]));
+        const blocks = this.seed.timeblocks
+            .filter((b) => b.user_id === userId &&
+            !b.deleted_at &&
+            (b.status === "planned" ||
+                b.status === "unverified" ||
+                b.status === "completed") &&
+            new Date(b.start_time).getTime() < fetchToMs &&
+            new Date(b.end_time).getTime() > fetchFromMs)
+            .map((b) => {
+            const cat = b.category_id ? catMap.get(b.category_id) : undefined;
+            return {
+                start: b.start_time,
+                end: b.end_time,
+                status: b.status,
+                title: b.title,
+                category_id: b.category_id ?? null,
+                category_emoji: cat?.emoji ?? null,
+                category_name: cat?.name ?? null,
+                category_color: cat?.color ?? null,
+            };
+        });
+        const timers = this.seed.timer_sessions
+            .filter((t) => t.user_id === userId &&
+            (t.status === "running" || t.status === "paused"))
+            .map((t) => ({
+            started_at: t.started_at,
+            accumulated_ms: t.accumulated_ms,
+            status: t.status,
+            event: t.event,
+        }));
+        return buildTimelineFromEvents({
+            blocks,
+            timers,
+            from,
+            to,
+            now,
+            format: filters.format ?? "emoji",
+        });
+    }
+}
+/** In-memory ApRepo for contract tests. */
+export class InMemoryApRepo {
+    wallets = new Map();
+    creditLog = new Map();
+    spendLog = new Map();
+    rewardEvents = [];
+    rewardCounters = new Map(); // `${user_id}:${action_type}:${period_key}` → count
+    bountyClaims = new Set(); // `${user_id}:${date_key}:${quest_id}`
+    balanceViews = []; // S3 看余额埋点
+    async balance(userId) {
+        const bal = this.wallets.get(userId) ?? 0;
+        // S3（INT-mvp-100）：与 SqliteApRepo 同行为——每次读取追加一条快照。
+        this.balanceViews.push({ user_id: userId, balance: bal, created_at: new Date().toISOString() });
+        return bal;
+    }
+    async recordRewardEvent(input) {
+        const now = input.now ?? new Date();
+        if (this.rewardEvents.some((e) => e.user === input.user_id && e.id === input.event_id))
+            return null;
+        const pk = periodKeyFor(input.action_type, now);
+        const counterKey = `${input.user_id}:${input.action_type}:${pk}`;
+        const nth = (this.rewardCounters.get(counterKey) ?? 0) + 1;
+        const amount = rewardForNth(input.action_type, nth);
+        this.rewardCounters.set(counterKey, nth);
+        this.rewardEvents.push({ user: input.user_id, type: input.action_type, id: input.event_id, at: now });
+        if (amount > 0) {
+            this.wallets.set(input.user_id, (this.wallets.get(input.user_id) ?? 0) + amount);
+        }
+        // 悬赏奖金：当天该类型事件数达标且未领过
+        const dk = dayKey(now);
+        let bonus;
+        for (const q of BOUNTY_QUESTS) {
+            if (q.action_type !== input.action_type)
+                continue;
+            const claimKey = `${input.user_id}:${dk}:${q.id}`;
+            const start = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+            const end = start + 86400000;
+            const dayCount = this.rewardEvents.filter((e) => e.user === input.user_id && e.type === q.action_type && e.at.getTime() >= start && e.at.getTime() < end).length;
+            if (dayCount >= q.target && !this.bountyClaims.has(claimKey)) {
+                this.bountyClaims.add(claimKey);
+                this.wallets.set(input.user_id, (this.wallets.get(input.user_id) ?? 0) + q.bonus);
+                bonus = (bonus ?? 0) + q.bonus;
+            }
+        }
+        return bonus === undefined ? { nth, amount } : { nth, amount, bonus };
+    }
+    async rewardStatus(userId, now) {
+        const at = now ?? new Date();
+        const out = {};
+        for (const type of Object.keys(REWARD_CONFIG)) {
+            const count = this.rewardCounters.get(`${userId}:${type}:${periodKeyFor(type, at)}`) ?? 0;
+            out[type] = { count, next: rewardForNth(type, count + 1), period: REWARD_CONFIG[type].period };
+        }
+        return out;
+    }
+    async bountiesStatus(userId, now) {
+        const at = now ?? new Date();
+        const dk = dayKey(at);
+        const start = new Date(at.getFullYear(), at.getMonth(), at.getDate()).getTime();
+        const end = start + 86400000;
+        return {
+            date: dk,
+            quests: BOUNTY_QUESTS.map((q) => {
+                const count = Math.min(this.rewardEvents.filter((e) => e.user === userId && e.type === q.action_type && e.at.getTime() >= start && e.at.getTime() < end).length, q.target);
+                return {
+                    id: q.id,
+                    action_type: q.action_type,
+                    target: q.target,
+                    count,
+                    done: this.bountyClaims.has(`${userId}:${dk}:${q.id}`),
+                    bonus: q.bonus,
+                };
+            }),
+        };
+    }
+    async credit(input) {
+        if (input.idempotency_key) {
+            const key = `${input.user_id}:${input.idempotency_key}`;
+            const existing = this.creditLog.get(key);
+            if (existing) {
+                return {
+                    balance: this.wallets.get(input.user_id) ?? 0,
+                    credited: existing.amount,
+                    source: existing.source,
+                };
+            }
+            this.creditLog.set(key, { amount: input.amount, source: input.source });
+        }
+        const next = (this.wallets.get(input.user_id) ?? 0) + input.amount;
+        this.wallets.set(input.user_id, next);
+        return { balance: next, credited: input.amount, source: input.source };
+    }
+    async spend(input) {
+        if (input.idempotency_key) {
+            const key = `${input.user_id}:${input.idempotency_key}`;
+            const existing = this.spendLog.get(key);
+            if (existing !== undefined) {
+                return {
+                    ok: true,
+                    balance: this.wallets.get(input.user_id) ?? 0,
+                    spent: existing,
+                };
+            }
+        }
+        const current = this.wallets.get(input.user_id) ?? 0;
+        if (current < input.amount) {
+            return { ok: false, code: "insufficient", balance: current };
+        }
+        const next = current - input.amount;
+        this.wallets.set(input.user_id, next);
+        if (input.idempotency_key) {
+            this.spendLog.set(`${input.user_id}:${input.idempotency_key}`, input.amount);
+        }
+        return { ok: true, balance: next, spent: input.amount };
+    }
+}

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

@@ -0,0 +1,188 @@
+import { BOUNTY_QUESTS, REWARD_CONFIG, dayKey, periodKeyFor, rewardForNth } from "../ap/rewards.js";
+/**
+ * SqliteApRepo — AP 账真源（INT-AP-tools R2）。
+ * credit / spend 包在 transaction 里，幂等靠 UNIQUE(user_id, idempotency_key)。
+ */
+export class SqliteApRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** INT-ap-rewards：事件幂等 + 曲线计数 + 入账 + 悬赏奖金，单事务（计数与余额同进退） */
+    async recordRewardEvent(input) {
+        const now = input.now ?? new Date();
+        const nowISO = now.toISOString();
+        return this.db.transaction(() => {
+            const seen = this.db
+                .prepare("SELECT 1 FROM ap_reward_log WHERE user_id = ? AND event_id = ?")
+                .get(input.user_id, input.event_id);
+            if (seen)
+                return null; // 重放：不计数不入账
+            const pk = periodKeyFor(input.action_type, now);
+            const row = this.db
+                .prepare("SELECT count FROM ap_reward_counter WHERE user_id = ? AND action_type = ? AND period_key = ?")
+                .get(input.user_id, input.action_type, pk);
+            const nth = (row?.count ?? 0) + 1;
+            const amount = rewardForNth(input.action_type, nth);
+            this.db
+                .prepare(`INSERT INTO ap_reward_counter (user_id, action_type, period_key, count, updated_at)
+           VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(user_id, action_type, period_key) DO UPDATE SET count = excluded.count, updated_at = excluded.updated_at`)
+                .run(input.user_id, input.action_type, pk, nth, nowISO);
+            this.db
+                .prepare("INSERT INTO ap_reward_log (user_id, event_id, action_type, period_key, nth, amount, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)")
+                .run(input.user_id, input.event_id, input.action_type, pk, nth, amount, nowISO);
+            if (amount > 0) {
+                // 入账与计数同事务；幂等键兜底跨面重放
+                this.db
+                    .prepare("INSERT INTO ap_credit_log (user_id, idempotency_key, amount, source, created_at) VALUES (?, ?, ?, ?, ?)")
+                    .run(input.user_id, `reward:${input.event_id}`, amount, `libero:${input.action_type}`, nowISO);
+                this.addBalance(input.user_id, amount);
+            }
+            // 悬赏奖金（方案 A）：当天该类型事件数达标且未领过 → 同事务发放
+            const dk = dayKey(now);
+            let bonus;
+            for (const q of BOUNTY_QUESTS) {
+                if (q.action_type !== input.action_type)
+                    continue;
+                const dayCount = this.dayCountSync(input.user_id, q.action_type, now);
+                const claimed = this.db
+                    .prepare("SELECT 1 FROM ap_bounty_log WHERE user_id = ? AND date_key = ? AND quest_id = ?")
+                    .get(input.user_id, dk, q.id);
+                if (dayCount >= q.target && !claimed) {
+                    this.db
+                        .prepare("INSERT INTO ap_bounty_log (user_id, date_key, quest_id, bonus, created_at) VALUES (?, ?, ?, ?, ?)")
+                        .run(input.user_id, dk, q.id, q.bonus, nowISO);
+                    this.db
+                        .prepare("INSERT INTO ap_credit_log (user_id, idempotency_key, amount, source, created_at) VALUES (?, ?, ?, ?, ?)")
+                        .run(input.user_id, `bounty:${dk}:${q.id}`, q.bonus, `bounty:${q.id}`, nowISO);
+                    this.addBalance(input.user_id, q.bonus);
+                    bonus = (bonus ?? 0) + q.bonus;
+                }
+            }
+            return bonus === undefined ? { nth, amount } : { nth, amount, bonus };
+        })();
+    }
+    /** 当天（本地时区）该类型实绩事件数——悬赏进度与曲线周期无关，按天判 */
+    dayCountSync(userId, actionType, now) {
+        const start = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        const end = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
+        const row = this.db
+            .prepare("SELECT COUNT(*) AS c FROM ap_reward_log WHERE user_id = ? AND action_type = ? AND created_at >= ? AND created_at < ?")
+            .get(userId, actionType, start.toISOString(), end.toISOString());
+        return row.c;
+    }
+    async bountiesStatus(userId, now) {
+        const at = now ?? new Date();
+        const dk = dayKey(at);
+        return {
+            date: dk,
+            quests: BOUNTY_QUESTS.map((q) => {
+                const count = this.dayCountSync(userId, q.action_type, at);
+                const done = count >= q.target &&
+                    !!this.db
+                        .prepare("SELECT 1 FROM ap_bounty_log WHERE user_id = ? AND date_key = ? AND quest_id = ?")
+                        .get(userId, dk, q.id);
+                return { id: q.id, action_type: q.action_type, target: q.target, count: Math.min(count, q.target), done, bonus: q.bonus };
+            }),
+        };
+    }
+    async rewardStatus(userId, now) {
+        const at = now ?? new Date();
+        const out = {};
+        for (const type of Object.keys(REWARD_CONFIG)) {
+            const row = this.db
+                .prepare("SELECT count FROM ap_reward_counter WHERE user_id = ? AND action_type = ? AND period_key = ?")
+                .get(userId, type, periodKeyFor(type, at));
+            const count = row?.count ?? 0;
+            out[type] = { count, next: rewardForNth(type, count + 1), period: REWARD_CONFIG[type].period };
+        }
+        return out;
+    }
+    async balance(userId) {
+        const bal = this.balanceSync(userId);
+        // S3（INT-mvp-100）：看余额埋点。只追加，只记显式 balance 调用——
+        // credit/spend 内部经 balanceSync 取返回值不算「看」，故埋点放这里而非 balanceSync。
+        this.db
+            .prepare("INSERT INTO ap_balance_view_log (user_id, balance, created_at) VALUES (?, ?, ?)")
+            .run(userId, bal, new Date().toISOString());
+        return bal;
+    }
+    async credit(input) {
+        return this.db.transaction(() => {
+            if (input.idempotency_key) {
+                const existing = this.db
+                    .prepare("SELECT amount, source FROM ap_credit_log WHERE user_id = ? AND idempotency_key = ?")
+                    .get(input.user_id, input.idempotency_key);
+                if (existing) {
+                    return {
+                        balance: this.balanceSync(input.user_id),
+                        credited: existing.amount,
+                        source: existing.source,
+                    };
+                }
+                const now = new Date().toISOString();
+                this.db
+                    .prepare("INSERT INTO ap_credit_log (user_id, idempotency_key, amount, source, created_at) VALUES (?, ?, ?, ?, ?)")
+                    .run(input.user_id, input.idempotency_key, input.amount, input.source, now);
+            }
+            this.addBalance(input.user_id, input.amount);
+            return {
+                balance: this.balanceSync(input.user_id),
+                credited: input.amount,
+                source: input.source,
+            };
+        })();
+    }
+    async spend(input) {
+        return this.db.transaction(() => {
+            if (input.idempotency_key) {
+                const existing = this.db
+                    .prepare("SELECT amount FROM ap_spend_log WHERE user_id = ? AND idempotency_key = ?")
+                    .get(input.user_id, input.idempotency_key);
+                if (existing) {
+                    return {
+                        ok: true,
+                        balance: this.balanceSync(input.user_id),
+                        spent: existing.amount,
+                    };
+                }
+            }
+            const current = this.balanceSync(input.user_id);
+            if (current < input.amount) {
+                return {
+                    ok: false,
+                    code: "insufficient",
+                    balance: current,
+                };
+            }
+            const now = new Date().toISOString();
+            const next = current - input.amount;
+            this.db
+                .prepare(`INSERT INTO ap_wallet (user_id, balance, updated_at) VALUES (?, ?, ?)
+           ON CONFLICT(user_id) DO UPDATE SET balance = ?, updated_at = ?`)
+                .run(input.user_id, next, now, next, now);
+            if (input.idempotency_key) {
+                this.db
+                    .prepare("INSERT INTO ap_spend_log (user_id, idempotency_key, amount, created_at) VALUES (?, ?, ?, ?)")
+                    .run(input.user_id, input.idempotency_key, input.amount, now);
+            }
+            return { ok: true, balance: next, spent: input.amount };
+        })();
+    }
+    balanceSync(userId) {
+        const row = this.db
+            .prepare("SELECT balance FROM ap_wallet WHERE user_id = ?")
+            .get(userId);
+        return row?.balance ?? 0;
+    }
+    addBalance(userId, amount) {
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO ap_wallet (user_id, balance, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(user_id) DO UPDATE SET
+           balance = balance + excluded.balance,
+           updated_at = excluded.updated_at`)
+            .run(userId, amount, now);
+    }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * SQLite-specific WHERE-clause builder for time-range filtering.
+ *
+ * Eliminates duplicated time-filter logic previously inlined in:
+ *   timeblock.list / stats.summarize / stats.dailyBreakdown / matrix.renderMatrix
+ *
+ * ADR-0001: SQLite dialect helpers belong in this file, not in the generic repo interface.
+ */
+/**
+ * Build WHERE sub-clauses for time-range filtering.
+ *
+ * Date mode (date is set):
+ *   `column >= :dateT00:00:00 AND column < :dateT23:59:59`
+ * Range mode (date absent, from/to optional):
+ *   `column >= :from` / `column <= :to`
+ * Neither:
+ *   returns empty clauses.
+ */
+export function buildTimeRangeWhere(input) {
+    const clauses = [];
+    const params = [];
+    if (input.date) {
+        // Single-day mode — timeblock.list legacy contract:
+        // start_time >= dateT00:00:00 AND start_time < dateT23:59:59
+        clauses.push(`${input.column} >= ?`, `${input.column} < ?`);
+        params.push(`${input.date}T00:00:00`, `${input.date}T23:59:59`);
+    }
+    else {
+        if (input.from) {
+            clauses.push(`${input.column} >= ?`);
+            params.push(input.from);
+        }
+        if (input.to) {
+            clauses.push(`${input.column} <= ?`);
+            params.push(input.to);
+        }
+    }
+    return { clauses, params };
+}