pi-mega-compact 0.7.9 → 0.8.0

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/game-achievements.js

@@ -0,0 +1,111 @@
+/**
+ * game-achievements.ts — `game_achievements` table accessors (S35).
+ *
+ * Per-achievement unlock state. One row per of the 9 seeded achievements
+ * (seeded idempotently in schema.ts on first open). `unlocked_at` is set
+ * once when the condition first holds; hidden achievements stay invisible
+ * (no tile, no teaser) until unlocked_at IS NOT NULL (the Opie invariant).
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (? placeholders, no concat of user data).
+ * Pi-agnostic: no pi runtime types (mirrors game-scores.ts / game-state.ts).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+import { ACHIEVEMENT_DEFS } from "../../game/scoring.js";
+/** The fixed set of valid achievement ids (mirrors ACHIEVEMENT_DEFS). */
+const VALID_IDS = new Set(ACHIEVEMENT_DEFS.map((d) => d.id));
+/** Coerce a raw DB row into the typed AchievementRow shape. */
+function toAchievementRow(r) {
+    return {
+        id: r.id,
+        title: r.title,
+        description: r.description,
+        hidden: r.hidden,
+        icon: r.icon,
+        unlocked_at: r.unlocked_at,
+    };
+}
+/**
+ * List all achievement rows, ordered so hidden+locked (the Opie easter egg
+ * before it triggers) sort LAST and visible rows sort by id ASC. Parameterized
+ * n/a (no user input reaches this SQL — PREVENT-002 safe).
+ */
+export function listAchievements(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db
+        .prepare(`SELECT id, title, description, hidden, icon, unlocked_at
+				 FROM game_achievements
+				 ORDER BY (hidden=1 AND unlocked_at IS NULL) DESC, id ASC`)
+        .all();
+    return rows.map(toAchievementRow);
+}
+/** Get a single achievement row by id (parameterized). Returns null if absent. */
+export function getAchievement(stateDir = getStateDir(), id) {
+    const db = openStore(stateDir);
+    const r = db
+        .prepare(`SELECT id, title, description, hidden, icon, unlocked_at
+				 FROM game_achievements WHERE id = ?`)
+        .get(id);
+    return r ? toAchievementRow(r) : null;
+}
+/** True if the achievement has been unlocked (unlocked_at IS NOT NULL). */
+export function isUnlocked(stateDir = getStateDir(), id) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare(`SELECT unlocked_at FROM game_achievements WHERE id = ?`)
+        .get(id);
+    return row?.unlocked_at != null;
+}
+/**
+ * Unlock an achievement (set unlocked_at = now) only if it is currently
+ * locked (unlocked_at IS NULL). Returns true if this call newly unlocked it,
+ * false if it was already unlocked or the id is unknown. Throws on an
+ * unknown id (mirrors recordScore's validation discipline).
+ */
+export function unlockAchievement(stateDir = getStateDir(), id) {
+    if (!VALID_IDS.has(id)) {
+        throw new Error(`unlockAchievement: unknown achievement id ${String(id)}`);
+    }
+    const db = openStore(stateDir);
+    const res = db
+        .prepare(`UPDATE game_achievements SET unlocked_at = ? WHERE id = ? AND unlocked_at IS NULL`)
+        .run(Date.now(), id);
+    return res.changes > 0;
+}
+/**
+ * Orchestrator: evaluate all achievements against the live leaderboards and
+ * persist any newly-unlocked ones. Non-pure (SQLite I/O) but best-effort +
+ * non-fatal (G6) — returns [] on any failure. Returns the TITLES (not ids)
+ * of the newly-unlocked achievements so callers can fire a one-time toast.
+ */
+export function evaluateAndUnlockAchievements(stateDir = getStateDir()) {
+    try {
+        const dedupe = leaderboard(stateDir, "dedupe");
+        const turns = leaderboard(stateDir, "turns");
+        const cache = leaderboard(stateDir, "cache");
+        const megaCache = leaderboard(stateDir, "mega_cache");
+        const reposCount = leaderboard(stateDir, "repos")[0]?.value ?? 0;
+        const alreadyUnlocked = listAchievements(stateDir)
+            .filter((r) => r.unlocked_at != null)
+            .map((r) => r.id);
+        const { newlyUnlocked } = evaluateAchievements({ dedupe, turns, cache, megaCache, reposCount }, alreadyUnlocked);
+        const titles = [];
+        for (const id of newlyUnlocked) {
+            const ok = unlockAchievement(stateDir, id);
+            if (ok) {
+                const def = ACHIEVEMENT_DEFS.find((d) => d.id === id);
+                if (def)
+                    titles.push(def.title);
+            }
+        }
+        return titles;
+    }
+    catch {
+        return [];
+    }
+}
+// leaderboard is imported lazily-style at top to avoid a circular init: it lives in
+// game-scores.ts (same submodule layer) and is parameterized (PREVENT-002).
+import { leaderboard } from "./game-scores.js";
+import { evaluateAchievements } from "../../game/scoring.js";

package/dist/src/store/sqlite/game-achievements.test.js

@@ -0,0 +1,67 @@
+/**
+ * game-achievements.test.ts — S35 game_achievements table + accessors.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import { listAchievements, getAchievement, isUnlocked, unlockAchievement, } from "./game-achievements.js";
+describe("game-achievements (S35)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-ach-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        closeStore(dir);
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("seeds exactly 9 rows on first open (idempotent)", () => {
+        const rows = listAchievements(dir);
+        assert.equal(rows.length, 9);
+        // re-open: seeding is idempotent, still 9, unlocked_at still null
+        const again = listAchievements(dir);
+        assert.equal(again.length, 9);
+        assert.ok(again.every((r) => r.unlocked_at == null));
+    });
+    it("ordering: visible rows sorted by id asc; opie hidden+locked present", () => {
+        const rows = listAchievements(dir);
+        const opie = rows.find((r) => r.id === "opie_wild_ride");
+        assert.ok(opie, "opie_wild_ride present");
+        assert.equal(opie.hidden, 1);
+        assert.equal(opie.unlocked_at, null);
+        const visible = rows.filter((r) => !(r.hidden === 1 && r.unlocked_at == null));
+        const ids = visible.map((r) => r.id);
+        const sorted = [...ids].sort();
+        assert.deepEqual(ids, sorted, "visible rows ordered by id asc");
+    });
+    it("getAchievement returns a row by id, null for unknown", () => {
+        const r = getAchievement(dir, "first_compact");
+        assert.ok(r);
+        assert.equal(r.title, "First Compact");
+        assert.equal(getAchievement(dir, "nope"), null);
+    });
+    it("isUnlocked false before unlock, true after", () => {
+        assert.equal(isUnlocked(dir, "first_compact"), false);
+        assert.equal(unlockAchievement(dir, "first_compact"), true);
+        assert.equal(isUnlocked(dir, "first_compact"), true);
+    });
+    it("unlock is idempotent (second call false, unlocked_at unchanged)", () => {
+        assert.equal(unlockAchievement(dir, "turn_veteran"), true);
+        const t0 = getAchievement(dir, "turn_veteran").unlocked_at;
+        assert.equal(unlockAchievement(dir, "turn_veteran"), false);
+        assert.equal(getAchievement(dir, "turn_veteran").unlocked_at, t0);
+    });
+    it("unlockAchievement throws on unknown id", () => {
+        assert.throws(() => unlockAchievement(dir, "bogus"));
+    });
+    it("parameterizes id (no SQL injection via crafted id)", () => {
+        // The accessors bind id as a param; a hostile id is a literal lookup, never executed.
+        assert.equal(getAchievement(dir, "x'); DROP TABLE game_achievements; --"), null);
+        assert.throws(() => unlockAchievement(dir, "x'); DROP TABLE game_achievements; --"));
+    });
+});

package/dist/src/store/sqlite/game-scores.js

@@ -0,0 +1,105 @@
+/**
+ * game-scores.ts — `game_scores` table accessors (S33).
+ *
+ * Per-repo leaderboard metrics for game mode. One row per recorded event
+ * (turn_end / session_compact); leaderboard() derives rankings (latest / max /
+ * SUM / COUNT DISTINCT) per repo_root. 'repos' is derived (never recorded).
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (? placeholders, no string concat of user
+ *   data). The metric is validated against a fixed allow-list before use; the
+ *   only interpolated fragments are code-controlled constants (the aggregate
+ *   selector + the optional repo_root filter clause), never external input.
+ * Pi-agnostic: no pi runtime types (mirrors game-state.ts / meta.ts).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+import { METRICS } from "../../game/scoring.js";
+// Process-local monotonic sequence appended into the low 3 digits of `ts` so
+// back-to-back inserts within the same millisecond get distinct PK values
+// (Date.now()*1000 + seq%1000). Production turns are >1ms apart, so seq is
+// almost always 0; this only disambiguates the burst case. Without it,
+// OR REPLACE would drop the earlier same-ms row and break the dedupe SUM.
+let scoreSeq = 0;
+function nextTs() {
+    return Date.now() * 1000 + (scoreSeq++ % 1000);
+}
+export { METRICS } from "../../game/scoring.js";
+/**
+ * Record one game-score event. `ts` is set to Date.now() by the store. SQL is
+ * fully parameterized (PREVENT-002); the metric is validated against the fixed
+ * allow-list. Pi-agnostic. Never throws except on a genuinely unknown metric.
+ */
+export function recordScore(stateDir = getStateDir(), args) {
+    if (!METRICS.includes(args.metric)) {
+        throw new Error(`recordScore: unknown game metric ${String(args.metric)}`);
+    }
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO game_scores (repo_root, metric, ts, value, meta)
+		 VALUES (?, ?, ?, ?, ?)`).run(args.repo_root, args.metric, nextTs(), args.value, args.meta != null ? JSON.stringify(args.meta) : null);
+}
+/**
+ * Read the leaderboard for a metric:
+ *   - cache/turns: latest value per repo_root, sorted desc by value.
+ *   - mega_cache: the max value (trophy) per repo_root, sorted desc.
+ *   - dedupe: SUM(value) per repo_root (cumulative collapses), sorted desc.
+ *   - repos: COUNT(DISTINCT repo_root) — derived; returns a single synthesized
+ *     row (repo_root '*') with the distinct-repo count as `value`.
+ * The metric is validated against the allow-list. Pi-agnostic.
+ */
+export function leaderboard(stateDir = getStateDir(), metric, opts = {}) {
+    if (!METRICS.includes(metric)) {
+        throw new Error(`leaderboard: unknown game metric ${String(metric)}`);
+    }
+    const db = openStore(stateDir);
+    const limit = Math.max(1, opts.limit ?? 10);
+    // Code-controlled filter clauses (never external input) — safe under PREVENT-002.
+    // Two variants: the dedupe query is single-table (unqualified repo_root);
+    // the cache/turns/mega_cache query self-JOINs (must qualify as g.repo_root).
+    const repoFilterDedupe = opts.repoRoot != null ? " AND repo_root = ?" : "";
+    const repoFilter = opts.repoRoot != null ? " AND g.repo_root = ?" : "";
+    const repoParam = opts.repoRoot != null ? [opts.repoRoot] : [];
+    if (metric === "repos") {
+        const row = db
+            .prepare(`SELECT COUNT(DISTINCT repo_root) AS value FROM game_scores`)
+            .get();
+        return [{ repo_root: "*", value: row.value, ts: 0, meta: null }];
+    }
+    if (metric === "dedupe") {
+        const sql = `SELECT repo_root, SUM(value) AS value, MAX(ts) AS ts, NULL AS meta
+					 FROM game_scores
+					 WHERE metric = ?${repoFilterDedupe}
+					 GROUP BY repo_root
+					 ORDER BY value DESC
+					 LIMIT ?`;
+        const rows = db.prepare(sql).all(metric, ...repoParam, limit);
+        return rows.map(toLeaderboardRow);
+    }
+    // cache / turns / mega_cache: pick the qualifying row per repo_root (latest
+    // ts, or max value for mega_cache), then rank by value desc. The interpolated
+    // `key`/`col` fragments are derived from the validated metric — code constants,
+    // not user data (PREVENT-002 safe).
+    const key = metric === "mega_cache" ? "MAX(value)" : "MAX(ts)";
+    const col = metric === "mega_cache" ? "value" : "ts";
+    const sql = `SELECT g.repo_root, g.value AS value, g.ts AS ts, g.meta AS meta
+					 FROM game_scores g
+					 JOIN (SELECT repo_root, ${key} AS k
+							 FROM game_scores WHERE metric = ? GROUP BY repo_root) m
+						ON m.repo_root = g.repo_root AND m.k = g.${col}
+					 WHERE g.metric = ?${repoFilter}
+					 ORDER BY g.value DESC
+					 LIMIT ?`;
+    const rows = db
+        .prepare(sql)
+        .all(metric, metric, ...repoParam, limit);
+    return rows.map(toLeaderboardRow);
+}
+/** Helper: coerce a raw row (meta as JSON text) into a LeaderboardRow. */
+function toLeaderboardRow(r) {
+    return {
+        repo_root: r.repo_root,
+        value: r.value,
+        ts: r.ts,
+        meta: r.meta != null ? JSON.parse(r.meta) : null,
+    };
+}

package/dist/src/store/sqlite/game-scores.test.js

@@ -0,0 +1,106 @@
+/**
+ * game-scores.test.ts — S33 game_scores table round-trip + leaderboard ordering.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import { recordScore, leaderboard, METRICS, } from "./game-scores.js";
+describe("game-scores (S33)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-gamescores-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        closeStore(dir);
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("records + reads back a cache score with parsed meta", () => {
+        recordScore(dir, {
+            repo_root: "/repo/a",
+            metric: "cache",
+            value: 42,
+            meta: { hits: 7, lookups: 10 },
+        });
+        const rows = leaderboard(dir, "cache", { repoRoot: "/repo/a" });
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].repo_root, "/repo/a");
+        assert.equal(rows[0].value, 42);
+        assert.deepEqual(rows[0].meta, { hits: 7, lookups: 10 });
+    });
+    it("cache leaderboard ranks by latest value per repo, descending", () => {
+        recordScore(dir, { repo_root: "/repo/a", metric: "cache", value: 10 });
+        recordScore(dir, { repo_root: "/repo/a", metric: "cache", value: 99 }); // latest wins
+        recordScore(dir, { repo_root: "/repo/b", metric: "cache", value: 50 });
+        recordScore(dir, { repo_root: "/repo/c", metric: "cache", value: 75 });
+        const rows = leaderboard(dir, "cache"); // all repos, default limit 10
+        assert.equal(rows.length, 3);
+        assert.deepEqual(rows.map((r) => [r.repo_root, r.value]), [["/repo/a", 99], ["/repo/c", 75], ["/repo/b", 50]]);
+        const a = rows.find((r) => r.repo_root === "/repo/a");
+        assert.equal(a.value, 99); // not the older 10
+    });
+    it("turns leaderboard uses the latest value per repo", () => {
+        recordScore(dir, { repo_root: "/repo/a", metric: "turns", value: 3 });
+        recordScore(dir, { repo_root: "/repo/a", metric: "turns", value: 8 });
+        const rows = leaderboard(dir, "turns", { repoRoot: "/repo/a" });
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].value, 8);
+    });
+    it("dedupe leaderboard sums collapses per repo, descending", () => {
+        recordScore(dir, { repo_root: "/repo/a", metric: "dedupe", value: 2 });
+        recordScore(dir, { repo_root: "/repo/a", metric: "dedupe", value: 3 });
+        recordScore(dir, { repo_root: "/repo/b", metric: "dedupe", value: 10 });
+        const rows = leaderboard(dir, "dedupe");
+        assert.equal(rows.length, 2);
+        assert.deepEqual(rows.map((r) => [r.repo_root, r.value]), [["/repo/b", 10], ["/repo/a", 5]]);
+    });
+    it("mega_cache leaderboard returns the max trophy per repo", () => {
+        recordScore(dir, {
+            repo_root: "/repo/a",
+            metric: "mega_cache",
+            value: 120,
+            meta: { peakPct: 120 },
+        });
+        recordScore(dir, {
+            repo_root: "/repo/a",
+            metric: "mega_cache",
+            value: 150,
+            meta: { peakPct: 150 },
+        });
+        const rows = leaderboard(dir, "mega_cache", { repoRoot: "/repo/a" });
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].value, 150);
+        assert.deepEqual(rows[0].meta, { peakPct: 150 });
+    });
+    it("repos leaderboard is the derived COUNT(DISTINCT repo_root)", () => {
+        recordScore(dir, { repo_root: "/repo/a", metric: "cache", value: 1 });
+        recordScore(dir, { repo_root: "/repo/b", metric: "cache", value: 1 });
+        recordScore(dir, { repo_root: "/repo/c", metric: "cache", value: 1 });
+        const rows = leaderboard(dir, "repos");
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].value, 3);
+    });
+    it("parameterizes repo_root (no SQL injection via repo path)", () => {
+        const evil = "x'); DROP TABLE game_scores; --";
+        recordScore(dir, { repo_root: evil, metric: "cache", value: 5 });
+        const rows = leaderboard(dir, "cache", { repoRoot: evil });
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].repo_root, evil);
+        // the table is intact: a normal insert still works
+        recordScore(dir, { repo_root: "/repo/z", metric: "cache", value: 1 });
+        assert.equal(leaderboard(dir, "cache", { repoRoot: "/repo/z" }).length, 1);
+    });
+    it("rejects an unknown metric", () => {
+        const bad = "bogus";
+        assert.throws(() => recordScore(dir, { repo_root: "/r", metric: bad, value: 1 }));
+        assert.throws(() => leaderboard(dir, bad));
+    });
+    it("METRICS allow-list matches the schema CHECK set", () => {
+        assert.deepEqual([...METRICS].sort(), ["cache", "dedupe", "mega_cache", "repos", "turns"]);
+    });
+});

package/dist/src/store/sqlite/game-state.js

@@ -0,0 +1,54 @@
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+import { DEFAULT_THEME, isValidTheme } from "../../config/themes.js";
+export const DEFAULT_GAME_STATE = {
+    game_mode_on: false,
+    theme: DEFAULT_THEME,
+    tui_display_mode: "full",
+};
+/** Read the global game-mode state. Returns DEFAULT_GAME_STATE if the row is
+ *  absent (fresh install) or any column is unexpectedly null/invalid — never
+ *  throws, so the widget / command can call it on every render safely. */
+export function getGameState(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    return getGameStateRow(db);
+}
+/** Read the game state from an already-open connection (used by callers that
+ *  hold a db handle, e.g. within a transaction). Same defensive fallback. */
+export function getGameStateRow(db) {
+    const row = db.prepare("SELECT game_mode_on, theme, tui_display_mode FROM game_state WHERE id = 1").get();
+    if (!row)
+        return { ...DEFAULT_GAME_STATE };
+    const mode = row.tui_display_mode === "minimal" ? "minimal" : "full";
+    return {
+        game_mode_on: row.game_mode_on === 1,
+        theme: isValidTheme(row.theme) ? row.theme : DEFAULT_THEME,
+        tui_display_mode: mode,
+    };
+}
+/** Upsert the game state row, applying `patch` on top of the current values.
+ *  Validates `theme` (keeps previous on an unknown id) and `tui_display_mode`
+ *  (coerces to 'full' on anything but 'minimal'). Parameterized (PREVENT-002).
+ *  Returns the post-write state. */
+export function setGameState(patch, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    return setGameStateRow(db, patch);
+}
+/** Upsert on an already-open connection (for transactional callers). */
+export function setGameStateRow(db, patch) {
+    const cur = getGameStateRow(db);
+    const next = {
+        game_mode_on: patch.game_mode_on ?? cur.game_mode_on,
+        theme: patch.theme != null && isValidTheme(patch.theme) ? patch.theme : cur.theme,
+        tui_display_mode: patch.tui_display_mode ?? cur.tui_display_mode,
+    };
+    // Single-row upsert (id=1). INSERT ... ON CONFLICT(id) DO UPDATE keeps it
+    // one row whether the table is fresh or already seeded.
+    db.prepare(`INSERT INTO game_state (id, game_mode_on, theme, tui_display_mode)
+     VALUES (1, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       game_mode_on = excluded.game_mode_on,
+       theme = excluded.theme,
+       tui_display_mode = excluded.tui_display_mode`).run(next.game_mode_on ? 1 : 0, next.theme, next.tui_display_mode);
+    return next;
+}

package/dist/src/store/sqlite/game-state.test.js

@@ -0,0 +1,76 @@
+/**
+ * game-state.test.ts — S30 game_state table round-trip + validation.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import { getGameState, setGameState, DEFAULT_GAME_STATE, } from "./game-state.js";
+describe("game-state (S30)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-gamestate-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        closeStore(dir);
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("returns DEFAULT_GAME_STATE on a fresh store", () => {
+        const s = getGameState();
+        assert.deepEqual(s, { ...DEFAULT_GAME_STATE });
+        assert.equal(s.game_mode_on, false);
+        assert.equal(s.theme, "transparent");
+        assert.equal(s.tui_display_mode, "full");
+    });
+    it("round-trips game_mode_on", () => {
+        setGameState({ game_mode_on: true });
+        assert.equal(getGameState().game_mode_on, true);
+        setGameState({ game_mode_on: false });
+        assert.equal(getGameState().game_mode_on, false);
+    });
+    it("round-trips a valid theme", () => {
+        setGameState({ theme: "retro" });
+        assert.equal(getGameState().theme, "retro");
+        setGameState({ theme: "cyan-neon" });
+        assert.equal(getGameState().theme, "cyan-neon");
+    });
+    it("rejects an unknown theme (keeps previous)", () => {
+        setGameState({ theme: "orange-bold" });
+        setGameState({ theme: "does-not-exist" });
+        assert.equal(getGameState().theme, "orange-bold");
+    });
+    it("round-trips tui_display_mode full|minimal", () => {
+        setGameState({ tui_display_mode: "minimal" });
+        assert.equal(getGameState().tui_display_mode, "minimal");
+        setGameState({ tui_display_mode: "full" });
+        assert.equal(getGameState().tui_display_mode, "full");
+    });
+    it("persists across a reopen (survives restart)", () => {
+        setGameState({ game_mode_on: true, theme: "amber-mono", tui_display_mode: "minimal" });
+        // evict + reopen the store to prove it hit disk
+        closeStore(dir);
+        const s = getGameState();
+        assert.equal(s.game_mode_on, true);
+        assert.equal(s.theme, "amber-mono");
+        assert.equal(s.tui_display_mode, "minimal");
+    });
+    it("setGameState is a partial merge (untouched fields preserved)", () => {
+        setGameState({ game_mode_on: true, theme: "grayscale", tui_display_mode: "minimal" });
+        const s = setGameState({ game_mode_on: false });
+        assert.equal(s.game_mode_on, false);
+        assert.equal(s.theme, "grayscale");
+        assert.equal(s.tui_display_mode, "minimal");
+    });
+    it("stays a single row (no duplicate id=1)", () => {
+        setGameState({ game_mode_on: true });
+        setGameState({ game_mode_on: false });
+        setGameState({ theme: "retro" });
+        const s = getGameState();
+        assert.ok(s); // single state, last-write-wins
+    });
+});