pi-mega-compact 0.7.9 → 0.8.0

package/src/game/scoring.test.ts

@@ -0,0 +1,103 @@
+/**
+ * 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";
+import type { LeaderboardRow } from "../store/sqlite/game-scores.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: number, opts: { ts?: number; meta?: unknown } = {}): LeaderboardRow {
+	return { repo_root: "/repo/a", value, ts: opts.ts ?? 1_700_000_000_000, meta: opts.meta ?? null };
+}
+
+describe("evaluateAchievements (S35)", () => {
+	const empty = { dedupe: [] as LeaderboardRow[], turns: [] as LeaderboardRow[], cache: [] as LeaderboardRow[], megaCache: [] as LeaderboardRow[], 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/src/game/scoring.ts

@@ -0,0 +1,158 @@
+/**
+ * scoring.ts — pure game-mode scoring helpers (S33) + achievements eval (S35).
+ *
+ * Pi-agnostic: no pi runtime types, no I/O, no dependencies. Every helper is a
+ * pure function so it can be unit-tested in isolation and reused by the
+ * extension event handlers (src/store stays free of pi types too).
+ */
+import type { LeaderboardRow } from "../store/sqlite/game-scores.js";
+
+/** The set of leaderboard metrics tracked in the `game_scores` table. */
+export type GameMetric = "cache" | "dedupe" | "turns" | "repos" | "mega_cache";
+
+/** Canonical allow-list of game metrics (mirrors the schema CHECK constraint). */
+export const METRICS: readonly GameMetric[] = [
+	"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: number): number {
+	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: number): boolean {
+	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: number, lookups: number): number {
+	if (!Number.isFinite(hits) || !Number.isFinite(lookups)) return 0;
+	return lookups > 0 ? (hits / lookups) * 100 : 0;
+}
+
+// ── S35: achievement definitions + evaluation ─────────────────────────────
+
+/** A single achievement definition (the seed row shape, minus unlocked_at). */
+export interface AchievementDef {
+	id: string;
+	title: string;
+	description: string;
+	hidden: boolean;
+	icon: string;
+}
+
+/**
+ * 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: readonly AchievementDef[] = [
+	{ 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}" },
+];
+
+/** Inputs to evaluateAchievements — the S33 leaderboard aggregates. */
+export interface AchievementContext {
+	dedupe: LeaderboardRow[];
+	turns: LeaderboardRow[];
+	cache: LeaderboardRow[];
+	megaCache: LeaderboardRow[];
+	reposCount: number;
+}
+
+/** Result of evaluateAchievements. */
+export interface AchievementEvalResult {
+	unlocked: string[];
+	newlyUnlocked: string[];
+}
+
+/**
+ * Max `compactCount` carried in a dedupe row's `meta` (S33 records
+ * `{ compactCount }` on each session_compact). Returns 0 when absent.
+ */
+export function maxCompactCount(rows: LeaderboardRow[]): number {
+	return rows.reduce((m, r) => {
+		const meta = r.meta;
+		const cm =
+			meta && typeof meta === "object" && "compactCount" in meta
+				? Number((meta as Record<string, unknown>).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: AchievementContext,
+	alreadyUnlocked: readonly string[],
+): AchievementEvalResult {
+	const sumBy = (rows: LeaderboardRow[]) =>
+		rows.reduce((s, r) => s + (Number(r.value) || 0), 0);
+	const maxBy = (rows: LeaderboardRow[]) =>
+		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: Record<string, boolean> = {
+		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/src/store/sqlite/game-achievements.test.ts

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