pi-mega-compact 0.7.9 → 0.8.1

package/src/store/sqlite/game-achievements.ts

@@ -0,0 +1,147 @@
+/**
+ * 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";
+
+/** A game_achievements row. */
+export interface AchievementRow {
+	id: string;
+	title: string;
+	description: string;
+	hidden: number;
+	icon: string | null;
+	unlocked_at: number | null;
+}
+
+/** The fixed set of valid achievement ids (mirrors ACHIEVEMENT_DEFS). */
+const VALID_IDS = new Set(ACHIEVEMENT_DEFS.map((d) => d.id));
+
+/** Intermediate row shape returned by node:sqlite (a Record<string,SQLOutputValue>);
+ *  coerced to AchievementRow via toAchievementRow. */
+type DbAchRow = {
+	id: string;
+	title: string;
+	description: string;
+	hidden: number;
+	icon: string | null;
+	unlocked_at: number | null;
+};
+
+/** Coerce a raw DB row into the typed AchievementRow shape. */
+function toAchievementRow(r: DbAchRow): AchievementRow {
+	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: string = getStateDir()): AchievementRow[] {
+	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() as DbAchRow[];
+	return rows.map(toAchievementRow);
+}
+
+/** Get a single achievement row by id (parameterized). Returns null if absent. */
+export function getAchievement(stateDir: string = getStateDir(), id: string): AchievementRow | null {
+	const db = openStore(stateDir);
+	const r = db
+		.prepare(
+			`SELECT id, title, description, hidden, icon, unlocked_at
+				 FROM game_achievements WHERE id = ?`,
+		)
+		.get(id) as DbAchRow | undefined;
+	return r ? toAchievementRow(r) : null;
+}
+
+/** True if the achievement has been unlocked (unlocked_at IS NOT NULL). */
+export function isUnlocked(stateDir: string = getStateDir(), id: string): boolean {
+	const db = openStore(stateDir);
+	const row = db
+		.prepare(`SELECT unlocked_at FROM game_achievements WHERE id = ?`)
+		.get(id) as { unlocked_at: number | null } | undefined;
+	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: string = getStateDir(), id: string): boolean {
+	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: string = getStateDir()): string[] {
+	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: string[] = [];
+		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/src/store/sqlite/game-scores.test.ts

@@ -0,0 +1,132 @@
+/**
+ * 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,
+	type GameMetric,
+} from "./game-scores.js";
+
+describe("game-scores (S33)", () => {
+	let dir: string;
+	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" as unknown as GameMetric;
+		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/src/store/sqlite/game-scores.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 type { SQLInputValue } from "node:sqlite";
+import { GameMetric, 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(): number {
+	return Date.now() * 1000 + (scoreSeq++ % 1000);
+}
+
+export type { GameMetric } from "../../game/scoring.js";
+export { METRICS } from "../../game/scoring.js";
+
+/** A single recorded game-score event (as stored). */
+export interface ScoreRow {
+	repo_root: string;
+	metric: GameMetric;
+	ts: number;
+	value: number;
+	meta?: unknown;
+}
+
+/** A leaderboard row returned by leaderboard(). */
+export interface LeaderboardRow {
+	repo_root: string;
+	value: number;
+	ts: number;
+	meta: unknown;
+}
+
+/** Options for leaderboard(): optional repo filter + result limit. */
+export interface LeaderboardOpts {
+	repoRoot?: string;
+	limit?: number;
+}
+
+/**
+ * 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: string = getStateDir(),
+	args: { repo_root: string; metric: GameMetric; value: number; meta?: unknown },
+): void {
+	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: string = getStateDir(),
+	metric: GameMetric,
+	opts: LeaderboardOpts = {},
+): LeaderboardRow[] {
+	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: SQLInputValue[] = opts.repoRoot != null ? [opts.repoRoot] : [];
+
+	if (metric === "repos") {
+		const row = db
+			.prepare(`SELECT COUNT(DISTINCT repo_root) AS value FROM game_scores`)
+			.get() as { value: number };
+		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) as Array<{
+			repo_root: string;
+			value: number;
+			ts: number;
+			meta: string | null;
+		}>;
+		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) as Array<{
+		repo_root: string;
+		value: number;
+		ts: number;
+		meta: string | null;
+	}>;
+	return rows.map(toLeaderboardRow);
+}
+
+/** Helper: coerce a raw row (meta as JSON text) into a LeaderboardRow. */
+function toLeaderboardRow(r: {
+	repo_root: string;
+	value: number;
+	ts: number;
+	meta: string | null;
+}): LeaderboardRow {
+	return {
+		repo_root: r.repo_root,
+		value: r.value,
+		ts: r.ts,
+		meta: r.meta != null ? JSON.parse(r.meta) : null,
+	};
+}

package/src/store/sqlite/game-state.test.ts

@@ -0,0 +1,89 @@
+/**
+ * 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: string;
+  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" as string });
+    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
+  });
+});

package/src/store/sqlite/game-state.ts

@@ -0,0 +1,87 @@
+/**
+ * game-state.ts — `game_state` table: the global game-mode toggle state (S30).
+ *
+ * Single row (id=1) holding: game_mode_on (bool), theme (one of THEME_IDS),
+ * tui_display_mode ('full'|'minimal'). Global — one choice across all repos.
+ * Survives restarts; editable from /mega-game (TUI) or the dashboard panel
+ * (S32), both reading/writing this same row so they stay in sync.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (@param / ? placeholders, no concat).
+ * Pi-agnostic: no pi runtime types (mirrors meta.ts / session-state.ts).
+ */
+import { DatabaseSync } from "node:sqlite";
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+import { DEFAULT_THEME, isValidTheme } from "../../config/themes.js";
+
+/** The persisted game-mode state. `theme` is always a valid THEME_IDS member
+ *  (callers may assume the invariant; setGameState validates). */
+export interface GameState {
+  game_mode_on: boolean;
+  theme: string;
+  tui_display_mode: "full" | "minimal";
+}
+
+export const DEFAULT_GAME_STATE: GameState = {
+  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: string = getStateDir()): GameState {
+  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: DatabaseSync): GameState {
+  const row = db.prepare(
+    "SELECT game_mode_on, theme, tui_display_mode FROM game_state WHERE id = 1",
+  ).get() as { game_mode_on: number; theme: string; tui_display_mode: string } | undefined;
+  if (!row) return { ...DEFAULT_GAME_STATE };
+  const mode: "full" | "minimal" =
+    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,
+  };
+}
+
+/** A partial update to the game state (omit fields you don't want to change). */
+export type GameStatePatch = Partial<GameState>;
+
+/** 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: GameStatePatch, stateDir: string = getStateDir()): GameState {
+  const db = openStore(stateDir);
+  return setGameStateRow(db, patch);
+}
+
+/** Upsert on an already-open connection (for transactional callers). */
+export function setGameStateRow(db: DatabaseSync, patch: GameStatePatch): GameState {
+  const cur = getGameStateRow(db);
+  const next: GameState = {
+    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/src/store/sqlite/schema.ts

@@ -2,6 +2,7 @@
  * schema.ts — table creation, migrations, `ensureColumn`, PRAGMA setup.
  */
 import { DatabaseSync } from "node:sqlite";
+import { ACHIEVEMENT_DEFS } from "../../game/scoring.js";
 
 const SCHEMA_VERSION = 2;
 
@@ -231,6 +232,41 @@ export function initSchema(db: DatabaseSync): void {
       first_seen_seq  INTEGER NOT NULL,
       created_at      INTEGER NOT NULL
     );
+
+    -- S30 game mode: global toggle state (single row, id=1). Holds the
+    -- game-mode on/off switch, the active visual-effect theme id, and the TUI
+    -- widget display mode. Global across all repos; written by /mega-game and
+    -- the dashboard settings strip (S32). Local SQLite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS game_state (
+      id                 INTEGER PRIMARY KEY CHECK(id = 1),
+      game_mode_on       INTEGER NOT NULL DEFAULT 0,
+      theme              TEXT NOT NULL DEFAULT 'transparent',
+      tui_display_mode   TEXT NOT NULL DEFAULT 'full'
+                          CHECK(tui_display_mode IN ('full','minimal'))
+    );
+    -- S33 game mode: per-repo leaderboard metrics. One row per recorded event
+    -- (turn_end / session_compact); leaderboard() derives rankings. 'repos' is
+    -- derived (COUNT DISTINCT, never recorded). Local SQLite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS game_scores (
+      repo_root TEXT NOT NULL,
+      metric    TEXT NOT NULL CHECK(metric IN ('cache','dedupe','turns','repos','mega_cache')),
+      ts        INTEGER NOT NULL,
+      value     REAL NOT NULL,
+      meta      TEXT,
+      PRIMARY KEY(repo_root, metric, ts)
+    ) WITHOUT ROWID;
+    CREATE INDEX IF NOT EXISTS idx_game_scores_metric_ts ON game_scores(metric, ts);
+
+    -- S35 game mode: achievements (9 rows, seeded idempotently on first open).
+    -- hidden=1 AND unlocked_at IS NULL => render NOTHING (no teaser). Local SQLite.
+    CREATE TABLE IF NOT EXISTS game_achievements (
+      id          TEXT PRIMARY KEY,
+      title       TEXT NOT NULL,
+      description TEXT NOT NULL,
+      hidden      INTEGER NOT NULL DEFAULT 0 CHECK(hidden IN (0,1)),
+      icon        TEXT,
+      unlocked_at INTEGER NULL
+    ) WITHOUT ROWID;
   `);
   // Idempotent column migrations. `CREATE TABLE IF NOT EXISTS` is a no-op on a
   // pre-existing table, so new columns added to context_chunks after a store was
@@ -249,6 +285,17 @@ export function initSchema(db: DatabaseSync): void {
   // S25: RAPTOR freshness-guard timestamp. Additive; old DBs have NULL → 0 →
   // treated as stale → flat fallback (safe).
   ensureColumn(db, "raptor_nodes", "built_at", "INTEGER");
+  // S35: idempotent seed of the 9 achievement rows. ON CONFLICT(id) DO
+  // NOTHING so a re-open never clobbers an already-unlocked row's
+  // unlocked_at. No user input reaches this SQL (PREVENT-002 safe).
+  const seedAch = db.prepare(
+    `INSERT INTO game_achievements (id, title, description, hidden, icon)
+     VALUES (?, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING`,
+  );
+  for (const d of ACHIEVEMENT_DEFS) {
+    seedAch.run(d.id, d.title, d.description, d.hidden ? 1 : 0, d.icon);
+  }
+
   const v = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get() as
     | { value: string }
     | undefined;