pi-mega-compact 0.7.8 → 0.8.0

package/dist/src/config/themes.js

@@ -0,0 +1,84 @@
+/**
+ * themes.ts — SINGLE SOURCE OF TRUTH for game-mode visual-effect themes (S30).
+ *
+ * Each theme defines BOTH an HTML/CSS palette (dashboard) AND an ANSI accent
+ * mapping (TUI widget), since the TUI is ANSI and the dashboard is HTML.
+ *
+ * Theme scope (QA1 correction): themes restyle the mega-compact statusbar
+ * widget + the whole dashboard HTML page. We do NOT theme pi's chrome.
+ *
+ * `transparent` (default) semantics: no background fill, colored accents only —
+ * so game-mode stays visible against any terminal background.
+ *
+ * PREVENT-PI-004: pure config, no network. Pi-agnostic: no pi runtime types.
+ */
+export const DEFAULT_THEME = "transparent";
+export const THEMES = [
+    {
+        id: "transparent",
+        label: "Transparent (accents only)",
+        css: { bg: null, fg: "#c9d1d9", accent: "#3fb950", mega: "#f0883e" },
+        ansi: { bg: null, fg: "39", accent: "32", mega: "33" },
+    },
+    {
+        id: "retro",
+        label: "Retro 8-bit green",
+        css: { bg: "#003300", fg: "#33ff33", accent: "#00ff41", mega: "#39ff14" },
+        ansi: { bg: "40", fg: "92", accent: "92", mega: "1;92" },
+    },
+    {
+        id: "orange-bold",
+        label: "Orange bold",
+        css: { bg: "#1a0f00", fg: "#ff8c00", accent: "#ff6b00", mega: "#ff4500" },
+        ansi: { bg: "48;5;52", fg: "38;5;208", accent: "38;5;208", mega: "1;38;5;202" },
+    },
+    {
+        id: "cyan-neon",
+        label: "Cyan neon",
+        css: { bg: "#001a1a", fg: "#00ffff", accent: "#22d3ee", mega: "#7df9ff" },
+        ansi: { bg: "48;5;23", fg: "38;5;51", accent: "38;5;51", mega: "1;38;5;51" },
+    },
+    {
+        id: "amber-mono",
+        label: "Amber phosphor",
+        css: { bg: "#1a1200", fg: "#ffb000", accent: "#ff8c00", mega: "#ff5500" },
+        ansi: { bg: "48;5;58", fg: "38;5;214", accent: "38;5;214", mega: "1;38;5;208" },
+    },
+    {
+        id: "grayscale",
+        label: "Grayscale minimal",
+        css: { bg: "#161616", fg: "#b0b0b0", accent: "#8b949e", mega: "#e6edf3" },
+        ansi: { bg: "48;5;235", fg: "38;5;249", accent: "38;5;249", mega: "1;38;5;255" },
+    },
+];
+/** All valid theme ids, in definition order (used for `theme next` cycling). */
+export const THEME_IDS = THEMES.map((t) => t.id);
+/** Look up a theme by id; returns `undefined` for an unknown id (caller
+ *  validates + falls back to DEFAULT_THEME). */
+export function getTheme(id) {
+    return THEMES.find((t) => t.id === id);
+}
+/** True if `id` is a known theme id. */
+export function isValidTheme(id) {
+    return THEME_IDS.includes(id);
+}
+/** Cycle to the next theme id (wraps at the end). Falls back to DEFAULT_THEME
+ *  if `current` is unknown (defensive — the stored id should always be valid). */
+export function nextTheme(current) {
+    const i = THEME_IDS.indexOf(current);
+    if (i < 0)
+        return DEFAULT_THEME;
+    return THEME_IDS[(i + 1) % THEME_IDS.length];
+}
+/** CSS variable declarations for a theme's CSS palette. `bg` is `null` for the
+ *  transparent theme → `--bg: transparent` (no page fill, accents only). Pure,
+ *  no pi types. */
+export function themeCssVars(theme) {
+    const bg = theme.css.bg ?? "transparent";
+    return `--bg: ${bg}; --fg: ${theme.css.fg}; --accent: ${theme.css.accent}; --mega: ${theme.css.mega};`;
+}
+/** A `:root[data-theme="<id>"]` override block carrying the theme's CSS vars,
+ *  for client-side instant theme switching. Pure, no pi types. */
+export function themeDataBlock(theme) {
+    return `:root[data-theme="${theme.id}"]{ ${themeCssVars(theme)} }`;
+}

package/dist/src/config/themes.test.js

@@ -0,0 +1,94 @@
+/**
+ * themes.test.ts — S30 theme palette source-of-truth tests.
+ * Pi-agnostic: no pi runtime imports.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { THEMES, THEME_IDS, DEFAULT_THEME, getTheme, isValidTheme, nextTheme, themeCssVars, themeDataBlock, } from "./themes.js";
+describe("themes (S30)", () => {
+    it("defines exactly 6 themes", () => {
+        assert.equal(THEMES.length, 6);
+        assert.equal(THEME_IDS.length, 6);
+    });
+    it("has unique ids", () => {
+        assert.equal(new Set(THEME_IDS).size, 6);
+    });
+    it("default theme is transparent", () => {
+        assert.equal(DEFAULT_THEME, "transparent");
+        assert.ok(isValidTheme(DEFAULT_THEME));
+    });
+    it("includes retro, orange-bold, cyan-neon, amber-mono, grayscale", () => {
+        for (const id of ["retro", "orange-bold", "cyan-neon", "amber-mono", "grayscale"]) {
+            assert.ok(isValidTheme(id), `missing ${id}`);
+        }
+    });
+    it("transparent theme has null bg (CSS + ANSI)", () => {
+        const t = getTheme("transparent");
+        assert.ok(t);
+        assert.equal(t.css.bg, null);
+        assert.equal(t.ansi.bg, null);
+    });
+    it("every non-transparent theme has a non-null bg", () => {
+        for (const t of THEMES) {
+            if (t.id === "transparent")
+                continue;
+            assert.ok(t.css.bg, `${t.id} css.bg`);
+            assert.ok(t.ansi.bg, `${t.id} ansi.bg`);
+        }
+    });
+    it("every theme has css + ansi {fg,accent,mega} strings", () => {
+        for (const t of THEMES) {
+            assert.ok(typeof t.css.fg === "string" && t.css.fg.startsWith("#"));
+            assert.ok(typeof t.css.accent === "string");
+            assert.ok(typeof t.css.mega === "string");
+            assert.ok(typeof t.ansi.fg === "string");
+            assert.ok(typeof t.ansi.accent === "string");
+            assert.ok(typeof t.ansi.mega === "string");
+        }
+    });
+    it("getTheme returns undefined for unknown id", () => {
+        assert.equal(getTheme("nope"), undefined);
+    });
+    it("isValidTheme is false for unknown", () => {
+        assert.equal(isValidTheme("nope"), false);
+    });
+    it("nextTheme cycles through all themes and wraps", () => {
+        const seen = [];
+        let cur = DEFAULT_THEME;
+        for (let i = 0; i < THEME_IDS.length; i++) {
+            cur = nextTheme(cur);
+            seen.push(cur);
+        }
+        // after N steps we've visited every theme once
+        assert.equal(new Set(seen).size, THEME_IDS.length);
+        // wraps: one more step from the last returns to the first
+        const first = nextTheme(THEME_IDS[THEME_IDS.length - 1]);
+        assert.equal(first, THEME_IDS[0]);
+    });
+    it("nextTheme falls back to DEFAULT_THEME for unknown current", () => {
+        assert.equal(nextTheme("garbage"), DEFAULT_THEME);
+    });
+});
+describe("themeCssVars / themeDataBlock (S32)", () => {
+    it("themeCssVars emits --bg/--fg/--accent/--mega for a normal theme", () => {
+        const t = getTheme("retro");
+        const vars = themeCssVars(t);
+        assert.match(vars, /--bg: #003300;/);
+        assert.match(vars, /--fg: #33ff33;/);
+        assert.match(vars, /--accent: #00ff41;/);
+        assert.match(vars, /--mega: #39ff14;/);
+    });
+    it("themeCssVars maps null bg to 'transparent'", () => {
+        const t = getTheme("transparent");
+        const vars = themeCssVars(t);
+        assert.match(vars, /--bg: transparent;/);
+        assert.match(vars, /--fg: #c9d1d9;/);
+    });
+    it("themeDataBlock wraps vars in a :root[data-theme=\"<id\"] selector", () => {
+        const t = getTheme("cyan-neon");
+        const block = themeDataBlock(t);
+        assert.equal(block.startsWith(':root[data-theme="cyan-neon"]{ '), true);
+        assert.equal(block.endsWith(" }"), true);
+        assert.ok(block.includes("--accent: #22d3ee;"));
+    });
+});

package/dist/src/game/scoring.js

@@ -0,0 +1,105 @@
+/** Canonical allow-list of game metrics (mirrors the schema CHECK constraint). */
+export const METRICS = [
+    "cache",
+    "dedupe",
+    "turns",
+    "repos",
+    "mega_cache",
+];
+/**
+ * Player level as a function of completed turns.
+ * Sequence: n=0→1, 1→2, 2→2, 3→3, 4→3, 7→4, 15→5, ...
+ * i.e. floor(log2(n+1)) + 1 (one level per doubling of turns). Defensive: any
+ * non-finite / negative input collapses to level 1 (never throws, never NaN).
+ */
+export function turnLevel(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return 1;
+    return Math.floor(Math.log2(n + 1)) + 1;
+}
+/**
+ * MEGA CACHE trigger test: the cache hit-rate (real ratio, may exceed 100%)
+ * has crossed the 100% threshold. Used to award the mega_cache trophy + arm
+ * the widget flare (the oopsie gag).
+ */
+export function isMegaCache(pct) {
+    return Number.isFinite(pct) && pct >= 100;
+}
+/**
+ * Cache-hit percentage (0..100+). Returns 0 when there are no lookups so the
+ * ratio can never be NaN / Infinity (QA3). Safe against non-finite inputs.
+ */
+export function cacheScore(hits, lookups) {
+    if (!Number.isFinite(hits) || !Number.isFinite(lookups))
+        return 0;
+    return lookups > 0 ? (hits / lookups) * 100 : 0;
+}
+/**
+ * The 9 achievements (8 visible + 1 hidden easter egg = Opie's Wild Ride).
+ * Seeded idempotently into the `game_achievements` table on first open
+ * (schema.ts). Pure, pi-agnostic — no I/O.
+ */
+export const ACHIEVEMENT_DEFS = [
+    { id: "first_compact", title: "First Compact", description: "Compact a conversation once.", hidden: false, icon: "\u{1F476}" },
+    { id: "compact_streak", title: "Compact Streak", description: "Compact 5 times in one session.", hidden: false, icon: "\u{1F525}" },
+    { id: "turn_veteran", title: "Turn Veteran", description: "Reach 25 turns in a repo.", hidden: false, icon: "\u{1F3C3}" },
+    { id: "level_five", title: "Level 5", description: "Reach player level 5.", hidden: false, icon: "\u{2B50}" },
+    { id: "dedupe_master", title: "Dedupe Master", description: "Collapse 100 chunks total.", hidden: false, icon: "\u{1F5DC}\u{FE0F}" },
+    { id: "repo_explorer", title: "Repo Explorer", description: "Use game mode across 3 repos.", hidden: false, icon: "\u{1F30D}" },
+    { id: "night_owl", title: "Night Owl", description: "Record a score after midnight (00:00–05:00 local).", hidden: false, icon: "\u{1F989}" },
+    { id: "flawless", title: "Flawless", description: "Hit exactly 100% cache with no overshoot.", hidden: false, icon: "\u{1F4AF}" },
+    { id: "opie_wild_ride", title: "Opie's Wild Ride", description: "Push the cache past 100%.", hidden: true, icon: "\u{1F3C6}" },
+];
+/**
+ * Max `compactCount` carried in a dedupe row's `meta` (S33 records
+ * `{ compactCount }` on each session_compact). Returns 0 when absent.
+ */
+export function maxCompactCount(rows) {
+    return rows.reduce((m, r) => {
+        const meta = r.meta;
+        const cm = meta && typeof meta === "object" && "compactCount" in meta
+            ? Number(meta.compactCount) || 0
+            : 0;
+        return Math.max(m, cm);
+    }, 0);
+}
+/**
+ * Pure evaluation of the 9 achievements against the leaderboard aggregates.
+ * `alreadyUnlocked` is the set of ids already persisted (so `newlyUnlocked`
+ * excludes them). No I/O, no pi types. Mirrors the S35.9 condition table.
+ */
+export function evaluateAchievements(ctx, alreadyUnlocked) {
+    const sumBy = (rows) => rows.reduce((s, r) => s + (Number(r.value) || 0), 0);
+    const maxBy = (rows) => rows.reduce((m, r) => Math.max(m, Number(r.value) || 0), 0);
+    const dedupeSum = sumBy(ctx.dedupe);
+    const maxTurns = maxBy(ctx.turns);
+    const maxCache = maxBy(ctx.cache);
+    const maxCompact = maxCompactCount(ctx.dedupe);
+    // Night owl: any row (across all metrics) recorded between 00:00–05:00 local.
+    const allTs = [
+        ...ctx.dedupe,
+        ...ctx.turns,
+        ...ctx.cache,
+        ...ctx.megaCache,
+    ];
+    const nightOwl = allTs.some((r) => {
+        const h = new Date(Number(r.ts) || 0).getHours();
+        return h >= 0 && h < 5;
+    });
+    // Flawless: cache hit 100%+, but NO mega_cache overshoot (>100).
+    const megaOvershoot = ctx.megaCache.some((r) => Number(r.value) > 100);
+    const conditions = {
+        first_compact: ctx.dedupe.length >= 1,
+        compact_streak: maxCompact >= 5,
+        turn_veteran: maxTurns >= 25,
+        level_five: turnLevel(maxTurns) >= 5,
+        dedupe_master: dedupeSum >= 100,
+        repo_explorer: ctx.reposCount >= 3,
+        night_owl: nightOwl,
+        flawless: maxCache >= 100 && !megaOvershoot,
+        opie_wild_ride: ctx.megaCache.length >= 1,
+    };
+    const unlocked = Object.keys(conditions).filter((id) => conditions[id]);
+    const newlyUnlocked = unlocked.filter((id) => !alreadyUnlocked.includes(id));
+    return { unlocked, newlyUnlocked };
+}

package/dist/src/game/scoring.test.js

@@ -0,0 +1,98 @@
+/**
+ * scoring.test.ts — S33 pure scoring helpers. Pi-agnostic, no I/O.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { turnLevel, isMegaCache, cacheScore, evaluateAchievements, maxCompactCount, ACHIEVEMENT_DEFS } from "./scoring.js";
+describe("scoring (S33)", () => {
+    it("turnLevel: floor(log2(n+1))+1 sequence", () => {
+        assert.equal(turnLevel(0), 1);
+        assert.equal(turnLevel(1), 2);
+        assert.equal(turnLevel(2), 2);
+        assert.equal(turnLevel(3), 3);
+        assert.equal(turnLevel(4), 3);
+        assert.equal(turnLevel(7), 4);
+        assert.equal(turnLevel(15), 5);
+        // defensive: non-finite / negative inputs collapse to level 1
+        assert.equal(turnLevel(-1), 1);
+        assert.equal(turnLevel(NaN), 1);
+    });
+    it("isMegaCache: 100% is the boundary", () => {
+        assert.equal(isMegaCache(99.9), false);
+        assert.equal(isMegaCache(100), true);
+        assert.equal(isMegaCache(150), true);
+        assert.equal(isMegaCache(0), false);
+        assert.equal(isMegaCache(NaN), false);
+    });
+    it("cacheScore: 0 lookups -> 0 (not NaN), else hits/lookups*100", () => {
+        assert.equal(cacheScore(0, 0), 0);
+        assert.equal(cacheScore(7, 10), 70);
+        assert.equal(cacheScore(0, 5), 0);
+        assert.equal(cacheScore(10, 10), 100);
+        // non-finite inputs are guarded (no NaN leaks)
+        assert.equal(cacheScore(1, NaN), 0);
+        assert.equal(cacheScore(NaN, 5), 0);
+    });
+});
+function achRow(value, opts = {}) {
+    return { repo_root: "/repo/a", value, ts: opts.ts ?? 1_700_000_000_000, meta: opts.meta ?? null };
+}
+describe("evaluateAchievements (S35)", () => {
+    const empty = { dedupe: [], turns: [], cache: [], megaCache: [], reposCount: 0 };
+    it("ACHIEVEMENT_DEFS: 9 achievements, exactly 1 hidden", () => {
+        assert.equal(ACHIEVEMENT_DEFS.length, 9);
+        assert.equal(ACHIEVEMENT_DEFS.filter((d) => d.hidden).length, 1);
+    });
+    it("first_compact: >=1 dedupe row", () => {
+        const r = evaluateAchievements({ ...empty, dedupe: [achRow(1)] }, []);
+        assert.ok(r.unlocked.includes("first_compact"));
+        assert.ok(r.newlyUnlocked.includes("first_compact"));
+    });
+    it("compact_streak: max meta.compactCount >= 5", () => {
+        const r = evaluateAchievements({ ...empty, dedupe: [achRow(1, { meta: { compactCount: 5 } })] }, []);
+        assert.ok(r.unlocked.includes("compact_streak"));
+    });
+    it("turn_veteran: max turns >= 25", () => {
+        const r = evaluateAchievements({ ...empty, turns: [achRow(25)] }, []);
+        assert.ok(r.unlocked.includes("turn_veteran"));
+    });
+    it("level_five: turnLevel(maxTurns) >= 5 (15 turns)", () => {
+        const r = evaluateAchievements({ ...empty, turns: [achRow(15)] }, []);
+        assert.ok(r.unlocked.includes("level_five"));
+    });
+    it("dedupe_master: sum dedupe >= 100", () => {
+        const r = evaluateAchievements({ ...empty, dedupe: [achRow(60), achRow(40)] }, []);
+        assert.ok(r.unlocked.includes("dedupe_master"));
+    });
+    it("repo_explorer: reposCount >= 3", () => {
+        const r = evaluateAchievements({ ...empty, reposCount: 3 }, []);
+        assert.ok(r.unlocked.includes("repo_explorer"));
+    });
+    it("night_owl: a row whose local hour is in [0,5)", () => {
+        const d = new Date();
+        d.setHours(2, 0, 0, 0);
+        const r = evaluateAchievements({ ...empty, cache: [achRow(50, { ts: d.getTime() })] }, []);
+        assert.ok(r.unlocked.includes("night_owl"));
+    });
+    it("flawless: maxCache >= 100 AND no mega_cache overshoot", () => {
+        const r = evaluateAchievements({ ...empty, cache: [achRow(100)], megaCache: [] }, []);
+        assert.ok(r.unlocked.includes("flawless"));
+    });
+    it("flawless NOT when a mega_cache overshoot row (>100) exists", () => {
+        const r = evaluateAchievements({ ...empty, cache: [achRow(100)], megaCache: [achRow(101)] }, []);
+        assert.ok(!r.unlocked.includes("flawless"));
+    });
+    it("opie_wild_ride: any mega_cache trophy row exists", () => {
+        const r = evaluateAchievements({ ...empty, megaCache: [achRow(100)] }, []);
+        assert.ok(r.unlocked.includes("opie_wild_ride"));
+    });
+    it("newlyUnlocked excludes ids already unlocked", () => {
+        const r = evaluateAchievements({ ...empty, dedupe: [achRow(1)] }, ["first_compact"]);
+        assert.ok(r.unlocked.includes("first_compact"));
+        assert.ok(!r.newlyUnlocked.includes("first_compact"));
+    });
+    it("maxCompactCount: 0 when meta absent, else the max", () => {
+        assert.equal(maxCompactCount([achRow(1)]), 0);
+        assert.equal(maxCompactCount([achRow(1, { meta: { compactCount: 7 } })]), 7);
+    });
+});

package/dist/src/store/sqlite/checkpoints.js

@@ -0,0 +1,145 @@
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { openStore, withTx, jsonText, encodeEmbedding, rowToCheckpoint, } from "./utils.js";
+/** Insert or replace a checkpoint (idempotent by id). */
+export function upsertCheckpoint(cp, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(cp.sessionId);
+    withTx(db, () => {
+        db.prepare(`INSERT INTO context_chunks
+        (id, session_id, region_hash, content_hash, content_hash2, content_hash_version,
+         normalized_text, summary, topic_summary, summary_hash,
+         key_decisions, next_steps, files_modified, embedding_blob,
+         token_estimate, original_token_estimate, timestamp, dedup_status, compressed_original)
+       VALUES (@id, @sid, @region_hash, @content_hash, @content_hash2, @content_hash_version,
+               @normalized_text, @summary, @topic_summary, @summary_hash,
+               @key_decisions, @next_steps, @files_modified, @embedding_blob,
+               @token_estimate, @original_token_estimate, @timestamp, @dedup_status, @compressed_original)
+       ON CONFLICT(session_id, id) DO UPDATE SET
+         summary=excluded.summary,
+         topic_summary=excluded.topic_summary,
+         summary_hash=excluded.summary_hash,
+         key_decisions=excluded.key_decisions,
+         next_steps=excluded.next_steps,
+         files_modified=excluded.files_modified,
+         embedding_blob=excluded.embedding_blob,
+         token_estimate=excluded.token_estimate,
+         original_token_estimate=excluded.original_token_estimate,
+         timestamp=excluded.timestamp,
+         dedup_status=excluded.dedup_status,
+         compressed_original=excluded.compressed_original`).run({
+            "@id": cp.checkpointId,
+            "@sid": sid,
+            "@region_hash": cp.regionHash ?? null,
+            "@content_hash": cp.contentHash ?? null,
+            "@content_hash2": cp.contentHash2 ?? null,
+            "@content_hash_version": cp.contentHashVersion ?? null,
+            "@normalized_text": cp.normalizedText ?? null,
+            "@summary": cp.summary ?? "",
+            "@topic_summary": cp.topicSummary ?? null,
+            "@summary_hash": cp.summaryHash ?? null,
+            "@key_decisions": jsonText(cp.keyDecisions),
+            "@next_steps": jsonText(cp.nextSteps),
+            "@files_modified": jsonText(cp.filesModified),
+            "@embedding_blob": encodeEmbedding(cp.embedding ?? []),
+            "@token_estimate": cp.tokenEstimate ?? 0,
+            "@original_token_estimate": cp.originalTokenEstimate ?? null,
+            "@timestamp": cp.timestamp ?? 0,
+            "@dedup_status": "active",
+            "@compressed_original": cp.compressedOriginal ?? null,
+        });
+        // FTS5 virtual tables don't support UPSERT — delete any prior row, reinsert.
+        // Store normalized_text (the L1 verify key); fall back to summary for rows
+        // that predate normalized_text population.
+        db.prepare("DELETE FROM context_chunks_trgm WHERE id = ?").run(cp.checkpointId);
+        db.prepare("INSERT INTO context_chunks_trgm(id, normalized_text) VALUES(?, ?)").run(cp.checkpointId, cp.normalizedText ?? cp.summary ?? "");
+    });
+}
+// --- Sprint 11: MinHash signatures + LSH buckets --------------------------
+/** Persist a checkpoint's MinHash signature (idempotent by chunk_id + version). */
+export function upsertMinhashSignature(chunkId, sessionId, signatureVersion, signatures, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    db.prepare(`INSERT INTO minhash_signatures(chunk_id, session_id, signature_version, signatures)
+     VALUES(?, ?, ?, ?)
+     ON CONFLICT(chunk_id, signature_version) DO UPDATE SET
+       session_id=excluded.session_id, signatures=excluded.signatures`).run(chunkId, sid, signatureVersion, JSON.stringify(signatures));
+}
+/** Persist LSH bucket memberships for a chunk (one row per bucket key). */
+export function insertLshBuckets(chunkId, sessionId, signatureVersion, bucketKeys, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const del = db.prepare("DELETE FROM dedup_lsh_buckets WHERE chunk_id = ?");
+    const ins = db.prepare("INSERT OR IGNORE INTO dedup_lsh_buckets(bucket_key, chunk_id, session_id, signature_version) VALUES(?, ?, ?, ?)");
+    withTx(db, () => {
+        del.run(chunkId);
+        for (const key of bucketKeys)
+            ins.run(key, chunkId, sid, signatureVersion);
+    });
+}
+/**
+ * Candidate chunk_ids sharing any LSH bucket with `bucketKeys`, scoped to the
+ * session, capped at `limit`. Single query (no N loops) — QA #15 amplification
+ * guard. Returns DISTINCT chunk_ids excluding `excludeChunkId` (the new row).
+ */
+export function lshCandidateChunks(bucketKeys, sessionId, excludeChunkId, stateDir = getStateDir(), limit = 100) {
+    if (bucketKeys.length === 0)
+        return [];
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const placeholders = bucketKeys.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT DISTINCT chunk_id FROM dedup_lsh_buckets
+       WHERE bucket_key IN (${placeholders}) AND session_id = ? AND chunk_id != ?
+       LIMIT ?`)
+        .all(...bucketKeys, sid, excludeChunkId, limit);
+    return rows.map((r) => r.chunk_id);
+}
+/** All checkpoints for a session, sorted by id. */
+export function listCheckpoints(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const rows = db
+        .prepare("SELECT * FROM context_chunks WHERE session_id = ? ORDER BY id ASC")
+        .all(sid);
+    return rows.map(rowToCheckpoint);
+}
+/** S25: the newest checkpoint timestamp for a session, or 0 when none. Used by
+ *  the RAPTOR freshness guard to reject a tree older than the live checkpoints. */
+export function maxCheckpointTimestamp(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare("SELECT MAX(timestamp) AS mx FROM context_chunks WHERE session_id = ?")
+        .get(normalizeSessionId(sessionId));
+    return Number(row?.mx ?? 0);
+}
+/** Next sequential checkpoint id (chkpt_001 …) for a session. */
+export function nextCheckpointId(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const row = db
+        .prepare("SELECT MAX(CAST(SUBSTR(id, 7) AS INTEGER)) AS n FROM context_chunks WHERE session_id = ?")
+        .get(sid);
+    const next = (row.n ?? 0) + 1;
+    return `chkpt_${String(next).padStart(3, "0")}`;
+}
+/** True if a checkpoint id already exists for a session. */
+export function hasCheckpoint(sessionId, checkpointId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare("SELECT 1 FROM context_chunks WHERE session_id = ? AND id = ? LIMIT 1")
+        .get(normalizeSessionId(sessionId), checkpointId);
+    return row !== undefined;
+}
+/** Fetch a single checkpoint by (session, id), or undefined if absent. */
+export function getCheckpoint(sessionId, checkpointId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare("SELECT * FROM context_chunks WHERE session_id = ? AND id = ? LIMIT 1")
+        .get(normalizeSessionId(sessionId), checkpointId);
+    return row ? rowToCheckpoint(row) : undefined;
+}
+/** Mark a checkpoint's dedup_status (e.g. 'removed' by SemDeDup). */
+export function setDedupStatus(checkpointId, sessionId, status, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    db.prepare("UPDATE context_chunks SET dedup_status = ? WHERE id = ? AND session_id = ?").run(status, checkpointId, normalizeSessionId(sessionId));
+}

package/dist/src/store/sqlite/dedup-mirror.js

@@ -0,0 +1,64 @@
+/**
+ * Upsert a row into dedup_mirror. If the hash already exists, increment ref_count.
+ * Returns true if this was a NEW unique content (first insert), false if it was a duplicate.
+ */
+export function upsertDedupMirror(db, contentHash, contentBytes, seq) {
+    const now = Date.now();
+    const existing = db
+        .prepare(`SELECT content_hash FROM dedup_mirror WHERE content_hash = @hash`)
+        .get({ "@hash": contentHash });
+    if (existing) {
+        db.prepare(`UPDATE dedup_mirror SET ref_count = ref_count + 1 WHERE content_hash = @hash`).run({
+            "@hash": contentHash,
+        });
+        return false;
+    }
+    db.prepare(`INSERT INTO dedup_mirror (content_hash, content_bytes, ref_count, first_seen_seq, created_at)
+     VALUES (@hash, @bytes, 1, @seq, @now)`).run({
+        "@hash": contentHash,
+        "@bytes": contentBytes,
+        "@seq": seq,
+        "@now": now,
+    });
+    return true;
+}
+/**
+ * Get dedup ratio for a session: total bytes vs unique bytes.
+ */
+export function getDedupRatio(db, sessionId) {
+    const totalRow = db
+        .prepare(`SELECT COALESCE(SUM(LENGTH(content_bytes)), 0) AS total
+       FROM raw_transcript
+       WHERE session_id = @session_id`)
+        .get({ "@session_id": sessionId });
+    const uniqueRow = db
+        .prepare(`SELECT COALESCE(SUM(LENGTH(content_bytes)), 0) AS unique_bytes
+       FROM dedup_mirror`)
+        .get();
+    const totalBytes = totalRow.total;
+    const uniqueBytes = uniqueRow.unique_bytes;
+    const ratio = uniqueBytes > 0 ? totalBytes / uniqueBytes : 1;
+    return { totalBytes, uniqueBytes, ratio };
+}
+/**
+ * Get dedup mirror stats (diagnostic / test helper).
+ */
+export function getDedupMirrorStats(db) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS cnt,
+              COALESCE(SUM(LENGTH(content_bytes)), 0) AS total_bytes,
+              COALESCE(AVG(ref_count), 0) AS avg_ref
+       FROM dedup_mirror`)
+        .get();
+    return { rowCount: row.cnt, totalBytes: row.total_bytes, avgRefCount: row.avg_ref };
+}
+/**
+ * Update raw_transcript.content_ref to point to dedup_mirror.
+ */
+export function updateRawTranscriptRef(db, sessionId, seq, contentHash) {
+    db.prepare(`UPDATE raw_transcript SET content_ref = @ref WHERE session_id = @sid AND seq = @seq`).run({
+        "@ref": contentHash,
+        "@sid": sessionId,
+        "@seq": seq,
+    });
+}

package/dist/src/store/sqlite/foundation.js

@@ -0,0 +1,38 @@
+/**
+ * foundation.ts — future-feature foundation (resume sessions / daily log / lessons).
+ *
+ * Scaffolded tables + minimal helpers so all store data lives in SQLite from
+ * day one. Full UI/recall for these lands in later sprints.
+ */
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { openStore } from "./utils.js";
+/** Upsert a `sessions` row (resume + per-repo session history). */
+export function touchSession(sessionId, repo, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const existing = db
+        .prepare("SELECT started_at FROM sessions WHERE session_id = ?")
+        .get(sid);
+    const now = Math.floor(Date.now() / 1000);
+    if (!existing) {
+        db.prepare(`INSERT INTO sessions(session_id, repo, started_at, last_compacted_at, status)
+       VALUES(?, ?, ?, ?, 'active')`).run(sid, repo ?? null, now, now);
+    }
+    else {
+        db.prepare("UPDATE sessions SET last_compacted_at = ?, repo = COALESCE(?, repo), status = 'active' WHERE session_id = ?").run(now, repo ?? null, sid);
+    }
+}
+/** Append a `daily_log` entry (day = YYYY-MM-DD, local-naive from Date). */
+export function logDaily(sessionId, event, detail, tokensSaved, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const day = new Date().toISOString().slice(0, 10);
+    const now = Math.floor(Date.now() / 1000);
+    db.prepare(`INSERT INTO daily_log(day, session_id, event, detail, tokens_saved, ts)
+     VALUES(?, ?, ?, ?, ?, ?)`).run(day, normalizeSessionId(sessionId), event, detail ?? null, tokensSaved, now);
+}
+/** Append a `lessons` entry (future lessons-learned browse/recall). */
+export function addLesson(sessionId, repo, lesson, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const now = Math.floor(Date.now() / 1000);
+    db.prepare(`INSERT INTO lessons(session_id, repo, lesson, ts) VALUES(?, ?, ?, ?)`).run(normalizeSessionId(sessionId), repo ?? null, lesson, now);
+}