pi-mega-compact 0.11.1 → 0.11.3

package/extensions/dashboard-server/api-contracts/endpoints.ts

@@ -14,6 +14,7 @@ import type { SnapshotResponse } from "./snapshot.js";
 import type { IndexesIndexRow, IndexesSummaryResponse } from "./multi-repo.js";
 import type { GameStateResponse } from "./game.js";
 import type { SseEvent } from "./index.js";
+import type { ProviderCacheResponse } from "./provider-cache.js";
 import type {
 	TurnsResponse,
 	ConversationTurnsResponse,
@@ -26,6 +27,13 @@ import type {
 	TopicMemoriesResponse,
 } from "./turns.js";
 
+import type {
+	DbStatsResponse,
+	MaintenanceActionResult,
+	MaintenanceAction,
+	SchemaHealthResponse,
+} from "./maintenance.js";
+
 import type {
 	GameScoreRow,
 	GameScoresQuery,
@@ -240,6 +248,15 @@ export interface ServerEntry {
 	} | null;
 	/** ISO timestamp of the live snapshot, or null. Present when a live snapshot has updatedAt. */
 	readonly updatedAt?: string | null;
+	/** Provider prompt-cache lifetime aggregates for this repo, or null when unavailable. */
+	readonly providerCache?: {
+		readonly avgHitPct: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+		readonly totalInput: number;
+		readonly sampleCount: number;
+		readonly estimatedSaved: number | null;
+	} | null;
 }
 
 /**
@@ -345,6 +362,8 @@ export interface PerfResponse {
 	readonly diag: PerfDiag | null;
 }
 
+// ─── Provider Cache Lifetime (A.2) — see provider-cache.ts ─────────────────
+
 // ─── Game Score & Achievement Types ─────────────────────────────────────────
 // (moved to game-types.ts; re-exported for backwards compatibility)
 
@@ -360,7 +379,7 @@ export interface PerfResponse {
 // ─── ENDPOINTS Registry ─────────────────────────────────────────────────────
 
 /**
- * Central registry of all 13 dashboard API endpoints. Each entry is an
+ * Central registry of all 14 dashboard API endpoints. Each entry is an
  * `EndpointDef` or `SseEndpointDef` instance serving as the single source of
  * truth for route paths, methods, descriptions, and typed request/response
  * contracts.
@@ -553,4 +572,38 @@ export const ENDPOINTS = {
 		path: "/api/topics/:topicId/memories",
 		description: "Member memories assigned to a wiki topic (drill-down).",
 	} as const satisfies EndpointDef<"GET", undefined, TopicMemoriesResponse>,
+
+	// ─── S49B Maintenance Tab ─────────────────────────────────────────
+
+	/** GET /api/maintenance — DB stats (table row counts + storage). */
+	maintenanceStats: {
+		method: "GET",
+		path: "/api/maintenance",
+		description: "SQLite table row counts, storage stats, and DB file sizes.",
+	} as const satisfies EndpointDef<"GET", undefined, DbStatsResponse>,
+
+	/** GET /api/maintenance/schema-health — Schema version + integrity audit. */
+	schemaHealth: {
+		method: "GET",
+		path: "/api/maintenance/schema-health",
+		description: "SCHEMA_VERSION, PRAGMA integrity_check, FK check, and per-column audit.",
+	} as const satisfies EndpointDef<"GET", undefined, SchemaHealthResponse>,
+
+	/** POST /api/maintenance/action — Trigger a maintenance action. */
+	maintenanceAction: {
+		method: "POST",
+		path: "/api/maintenance/action",
+		description: "Run vacuum, checkpoint, reindex, fts5-rebuild, reconcile-dedup, prune, or integrity-check.",
+	} as const satisfies EndpointDef<"POST", MaintenanceAction, MaintenanceActionResult>,
+
+	// ─── Provider Cache (Sprint A.2) ─────────────────────────────────
+
+	/** GET /api/provider-cache — Lifetime provider prompt cache aggregates + $ savings. */
+	providerCache: {
+		method: "GET",
+		path: "/api/provider-cache",
+		description:
+			"Lifetime provider prompt cache hit-rate aggregates + dollar savings estimate.",
+	} as const satisfies EndpointDef<"GET", undefined, ProviderCacheResponse>,
+
 } as const;

package/extensions/dashboard-server/api-contracts/index.ts

@@ -144,6 +144,10 @@ export type {
 	TopicsResponse,
 	TopicDetailResponse,
 } from "./endpoints.js";
+export type {
+	ProviderCacheSavings,
+	ProviderCacheResponse,
+} from "./provider-cache.js";
 
 export { ENDPOINTS } from "./endpoints.js";
 
@@ -171,6 +175,18 @@ export type SseEvent =
 	| SseGameRender
 	| SseSessionSample;
 
+// S49B — maintenance tab API
+export type {
+	TableStats,
+	DbFiles,
+	DbStorageStats,
+	DbStatsResponse,
+	MaintenanceActionResult,
+	SchemaHealthRow,
+	SchemaHealthResponse,
+	MaintenanceAction,
+} from "./maintenance.js";
+
 // S52 — turn-by-turn memory tracking + recall + rewind
 export type {
 	TurnRow,

package/extensions/dashboard-server/api-contracts/maintenance.ts

@@ -0,0 +1,84 @@
+/**
+ * api-contracts/maintenance.ts — Maintenance tab API contract (S49B).
+ *
+ * Types for the /api/maintenance and /api/maintenance/action endpoints.
+ * All pi-agnostic, all PREVENT-PI-004 compliant (type definitions only).
+ */
+
+/** Row count + size stats per SQLite table. */
+export interface TableStats {
+	/** Table name. */
+	table: string;
+	/** Row count (or -1 if FTS virtual table). */
+	rowCount: number;
+}
+
+/** DB file sizes on disk in bytes. */
+export interface DbFiles {
+	/** Main sqlite.db size. */
+	dbBytes: number;
+	/** WAL sidecar size (0 if absent). */
+	walBytes: number;
+	/** SHM sidecar size (0 if absent). */
+	shmBytes: number;
+}
+
+/** SQLite storage-level stats. */
+export interface DbStorageStats {
+	files: DbFiles;
+	pageSize: number;
+	pageCount: number;
+	freelistPages: number;
+}
+
+/** Full table + storage overview (GET /api/maintenance result). */
+export interface DbStatsResponse {
+	type: "db-stats";
+	/** Per-table row counts. */
+	tables: TableStats[];
+	/** Storage stats. */
+	storage: DbStorageStats;
+}
+
+/** Result of a single maintenance action. */
+export interface MaintenanceActionResult {
+	operation: string;
+	success: boolean;
+	affected: number;
+	reclaimedBytes: number;
+	summary: string;
+	detail?: string[];
+}
+
+/** Schema health check — per-column audit result. */
+export interface SchemaHealthRow {
+	table: string;
+	column: string;
+	present: boolean;
+	expectedDecl: string;
+}
+
+/** Schema health audit (GET /api/maintenance/schema-health). */
+export interface SchemaHealthResponse {
+	type: "schema-health";
+	/** SCHEMA_VERSION constant compiled in. */
+	schemaVersion: number;
+	/** PRAGMA integrity_check result lines. */
+	integrity: string[];
+	/** PRAGMA foreign_key_check result lines. */
+	fkCheck: string[];
+	/** Per-column audit of every ensureColumn migration column. */
+	columns: SchemaHealthRow[];
+	/** All present = healthy. */
+	healthy: boolean;
+}
+
+/** Maintenance actions the client can trigger (POST /api/maintenance/action). */
+export type MaintenanceAction =
+	| { action: "vacuum" }
+	| { action: "checkpoint" }
+	| { action: "reindex" }
+	| { action: "fts5-rebuild" }
+	| { action: "reconcile-dedup" }
+	| { action: "prune"; daysOld: number }
+	| { action: "integrity-check" };

package/extensions/dashboard-server/api-contracts/multi-repo.ts

@@ -172,6 +172,12 @@ export interface IndexesIndexRow {
   maxTokens: number | null;
   /** Whether reasoning/extended-thinking mode is enabled, or `null` if not configured. */
   reasoning: boolean | null;
+  /** Lifetime provider prompt-cache hit percentage, or `null` if no samples. */
+  providerCachePct: number | null;
+  /** Lifetime provider prompt-cache read tokens, or `null` if no samples. */
+  providerCacheRead: number | null;
+  /** Lifetime provider prompt-cache write tokens, or `null` if no samples. */
+  providerCacheWrite: number | null;
 }
 
 /**

package/extensions/dashboard-server/api-contracts/provider-cache.ts

@@ -0,0 +1,30 @@
+/**
+ * api-contracts/provider-cache.ts — Provider prompt cache contract (A.2).
+ *
+ * Response shape for GET /api/provider-cache: lifetime cache hit-rate
+ * aggregates plus optional $ savings estimate priced from model snapshots.
+ */
+
+/** Savings estimate derived from model pricing snapshot. */
+export interface ProviderCacheSavings {
+	readonly cacheReadSaved: number;
+	readonly cacheWriteCost: number;
+	readonly netSaved: number;
+	readonly model: string;
+	readonly inputRate: number;
+}
+
+/** Response body for GET /api/provider-cache. */
+export interface ProviderCacheResponse {
+	readonly cache: {
+		readonly avgHitPct: number;
+		readonly turnCount: number;
+		readonly totalCacheRead: number;
+		readonly totalCacheWrite: number;
+		readonly totalInput: number;
+		readonly firstTurnAt: string | null;
+		readonly latestTurnAt: string | null;
+	};
+	readonly savings: ProviderCacheSavings | null;
+	readonly updatedAt: string;
+}

package/extensions/dashboard-server/api-contracts.test.ts

@@ -162,7 +162,7 @@ void _c_achievements;
 // (Sprint 39 added /api/sessions + /api/sessions/timeseries.)
 
 const ENDPOINT_KEYS = Object.keys(ENDPOINTS) as (keyof typeof ENDPOINTS)[];
-const EXPECTED_ENDPOINT_COUNT = 23;
+const EXPECTED_ENDPOINT_COUNT = 27; // 23 base + 3 S49B maintenance + 1 provider-cache
 
 /** All `/api/*` paths served by server.ts (extracted from the route handlers). */
 const SERVER_TS_PATHS: string[] = [
@@ -181,12 +181,13 @@ const SERVER_TS_PATHS: string[] = [
 	"/api/sessions",
 	"/api/sessions/timeseries",
 	"/api/topics",
+	"/api/provider-cache",
 ];
 
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 describe("ENDPOINTS registry", () => {
-	test("has exactly 16 endpoint entries", () => {
+	test("has exactly the expected endpoint count", () => {
 		assert.equal(
 			ENDPOINT_KEYS.length,
 			EXPECTED_ENDPOINT_COUNT,

package/extensions/dashboard-server/api-contracts.ts

@@ -66,6 +66,15 @@ export type {
   MinHashBandState,
   // Composite
   SseEvent,
+  // S49B — maintenance tab
+  TableStats,
+  DbFiles,
+  DbStorageStats,
+  DbStatsResponse,
+  MaintenanceActionResult,
+  SchemaHealthRow,
+  SchemaHealthResponse,
+  MaintenanceAction,
   // Endpoints registry (Sprint A1)
   VersionResponse,
   IndexSummary,

package/extensions/dashboard-server/index-reader.ts

@@ -58,6 +58,9 @@ export function readIndex(): IndexIndex | null {
       contextWindow: null,
       maxTokens: null,
       reasoning: null,
+      providerCachePct: null,
+      providerCacheRead: null,
+      providerCacheWrite: null,
     }));
     // Enrich each repo with per-store token + model detail read directly via
     // node:sqlite (same zero-dependency invariant as readIndex; no store graph
@@ -91,6 +94,26 @@ export function readIndex(): IndexIndex | null {
               repo.maxTokens = Number(mrow.max_tokens ?? 0) || null;
               repo.reasoning = Number(mrow.reasoning ?? 0) === 1;
             }
+            // Provider prompt-cache stats (E.3)
+            try {
+              const pRow = sdb
+                .prepare(
+                  `SELECT
+                    SUM(cache_read) AS totalRead,
+                    SUM(cache_write) AS totalWrite,
+                    SUM(cache_read + cache_write) * 1.0 / MAX(SUM(cache_read + cache_write + tokens_in), 1) AS hitPct
+                   FROM perf_samples
+                   WHERE cache_read > 0 OR cache_write > 0`,
+                )
+                .get() as { totalRead: number; totalWrite: number; hitPct: number } | undefined;
+              if (pRow && pRow.totalRead > 0) {
+                repo.providerCacheRead = Number(pRow.totalRead);
+                repo.providerCacheWrite = Number(pRow.totalWrite);
+                repo.providerCachePct = Number((pRow.hitPct * 100).toFixed(1));
+              }
+            } catch {
+              /* best-effort — perf_samples may not exist */
+            }
           } finally {
             sdb.close();
           }

package/extensions/dashboard-server/routes-cache.test.ts

@@ -0,0 +1,302 @@
+/**
+ * routes-cache.test.ts — Sprint A /api/provider-cache endpoint tests.
+ *
+ * Covers the A.4 spec:
+ * - GET 200 → shape matches ProviderCacheResponse
+ * - POST → 405
+ * - empty perf_samples → zeros/nulls
+ * - no model snapshot → savings: null
+ * - with model snapshot → priced savings fields
+ *
+ * Uses the same spawn-and-fetch harness as perf-server.test.ts.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import {
+	recordPerfSample,
+	recordModelSnapshot,
+} from "../../src/store/sqlite.js";
+
+const SERVER_ENTRY = new URL("./server.js", import.meta.url).pathname;
+
+function waitFor(
+	cond: () => boolean | Promise<boolean>,
+	timeoutMs = 6000,
+): Promise<void> {
+	const start = Date.now();
+	return new Promise((resolve, reject) => {
+		const tick = async () => {
+			if (await cond()) return resolve();
+			if (Date.now() - start > timeoutMs) return reject(new Error("timeout"));
+			setTimeout(tick, 50);
+		};
+		tick();
+	});
+}
+
+function freshDir(prefix: string): string {
+	return mkdtempSync(join(tmpdir(), prefix));
+}
+
+async function withServer<T>(
+	port: string,
+	dir: string,
+	fn: (port: number) => Promise<T>,
+): Promise<T> {
+	process.env.MEGACOMPACT_DASHBOARD_PORT = port;
+	const child = spawn(process.execPath, [SERVER_ENTRY, dir], {
+		stdio: "ignore",
+	});
+	try {
+		await waitFor(async () => {
+			try {
+				const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+				const res = await fetch(`http://localhost:${raw.port}/api/version`);
+				return res.ok;
+			} catch {
+				return false;
+			}
+		});
+		const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+		return await fn(raw.port);
+	} finally {
+		child.kill("SIGTERM");
+		delete process.env.MEGACOMPACT_DASHBOARD_PORT;
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+interface ProviderCacheResponse {
+	cache: {
+		avgHitPct: number;
+		turnCount: number;
+		totalCacheRead: number;
+		totalCacheWrite: number;
+		totalInput: number;
+		firstTurnAt: string | null;
+		latestTurnAt: string | null;
+	};
+	savings: {
+		cacheReadSaved: number;
+		cacheWriteCost: number;
+		netSaved: number;
+		model: string;
+		inputRate: number;
+	} | null;
+	updatedAt: string;
+}
+
+describe("/api/provider-cache", () => {
+	test("GET 200 — shape matches ProviderCacheResponse", async () => {
+		const dir = freshDir("dash-pcache-agg-");
+		// Seed one cache_hit_pct sample with full meta.
+		recordPerfSample(dir, "cache_hit_pct", 42, {
+			cacheRead: 100,
+			cacheWrite: 20,
+			input: 500,
+		});
+		await withServer("19450", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			// Shape assertions
+			assert.ok("cache" in body, "should have cache");
+			assert.ok("savings" in body, "should have savings");
+			assert.ok("updatedAt" in body, "should have updatedAt");
+			assert.equal(body.cache.turnCount, 1);
+			assert.equal(body.cache.totalCacheRead, 100);
+			assert.equal(body.cache.totalCacheWrite, 20);
+			assert.equal(body.cache.totalInput, 500);
+			assert.ok(typeof body.cache.firstTurnAt === "string");
+			assert.ok(typeof body.cache.latestTurnAt === "string");
+			assert.ok(typeof body.updatedAt === "string");
+		});
+	});
+
+	test("GET 200 — empty perf_samples returns zeros/nulls", async () => {
+		const dir = freshDir("dash-pcache-empty-");
+		await withServer("19451", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			assert.equal(body.cache.turnCount, 0);
+			assert.equal(body.cache.avgHitPct, 0);
+			assert.equal(body.cache.totalCacheRead, 0);
+			assert.equal(body.cache.totalCacheWrite, 0);
+			assert.equal(body.cache.totalInput, 0);
+			assert.equal(body.cache.firstTurnAt, null);
+			assert.equal(body.cache.latestTurnAt, null);
+			assert.equal(body.savings, null);
+		});
+	});
+
+	test("POST → 405", async () => {
+		const dir = freshDir("dash-pcache-meth-");
+		await withServer("19452", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`, {
+				method: "POST",
+			});
+			assert.equal(res.status, 405);
+			const body = (await res.json()) as { error: string };
+			assert.equal(body.error, "method_not_allowed");
+		});
+	});
+
+	test("no model snapshot → savings: null", async () => {
+		const dir = freshDir("dash-pcache-nosnap-");
+		recordPerfSample(dir, "cache_hit_pct", 50, {
+			cacheRead: 200,
+			cacheWrite: 30,
+			input: 1000,
+		});
+		await withServer("19453", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			assert.equal(body.savings, null);
+		});
+	});
+
+	test("with model snapshot → priced savings fields", async () => {
+		const dir = freshDir("dash-pcache-savings-");
+		recordPerfSample(dir, "cache_hit_pct", 50, {
+			cacheRead: 2000,
+			cacheWrite: 400,
+			input: 10000,
+		});
+		// Record a model snapshot with a known input rate.
+		recordModelSnapshot(
+			"/tmp/test-repo",
+			{
+				provider: "anthropic",
+				providerName: "Anthropic",
+				modelId: "claude-sonnet-4-20250514",
+				modelName: "Claude Sonnet 4",
+				inputRate: 3e-6, // $3 / 1M tokens
+				outputRate: 15e-6,
+				contextWindow: 200000,
+				maxTokens: 32000,
+				reasoning: false,
+			},
+			dir,
+		);
+		await withServer("19454", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			assert.ok(body.savings, "savings should not be null");
+			// cacheReadSaved = 2000 * 3e-6 * 0.9 = 0.0054
+			assert.ok(body.savings!.cacheReadSaved > 0, "cacheReadSaved > 0");
+			// cacheWriteCost = 400 * 3e-6 * 0.25 = 0.0003
+			assert.ok(body.savings!.cacheWriteCost > 0, "cacheWriteCost > 0");
+			assert.ok(
+				body.savings!.netSaved ===
+					body.savings!.cacheReadSaved - body.savings!.cacheWriteCost,
+				"netSaved = cacheReadSaved - cacheWriteCost",
+			);
+			assert.equal(body.savings!.model, "Claude Sonnet 4");
+			assert.equal(body.savings!.inputRate, 3e-6);
+		});
+	});
+
+	test("partial meta (missing fields) → treated as 0", async () => {
+		const dir = freshDir("dash-pcache-partial-");
+		// Only input in meta; cacheRead/cacheWrite missing → treated as 0.
+		recordPerfSample(dir, "cache_hit_pct", 30, { input: 800 });
+		// Only cacheRead in meta; input/cacheWrite missing → treated as 0.
+		recordPerfSample(dir, "cache_hit_pct", 60, { cacheRead: 150 });
+		await withServer("19455", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			// First sample: input=800, cacheRead=0, cacheWrite=0
+			// Second sample: cacheRead=150, input=0, cacheWrite=0
+			assert.equal(body.cache.turnCount, 2);
+			assert.equal(body.cache.totalCacheRead, 150);
+			assert.equal(body.cache.totalCacheWrite, 0);
+			assert.equal(body.cache.totalInput, 800);
+		});
+	});
+
+	test("NULL meta → counted in turnCount, contributes 0 tokens + 0 avg", async () => {
+		const dir = freshDir("dash-pcache-nullmeta-");
+		// avgHitPct is derived from (cacheRead / (cacheRead + input + cacheWrite)) * 100,
+		// NOT from the `value` column. NULL meta → no tokens → avg 0, not 25.
+		recordPerfSample(dir, "cache_hit_pct", 25, undefined);
+		await withServer("19456", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			assert.equal(body.cache.turnCount, 1);
+			assert.equal(body.cache.avgHitPct, 0);
+			assert.equal(body.cache.totalCacheRead, 0);
+			assert.equal(body.cache.totalCacheWrite, 0);
+			assert.equal(body.cache.totalInput, 0);
+		});
+	});
+
+	test("model snapshot with modelName=null → falls back to modelId", async () => {
+		const dir = freshDir("dash-pcache-modelid-");
+		recordPerfSample(dir, "cache_hit_pct", 10, {
+			cacheRead: 100,
+			cacheWrite: 10,
+			input: 1000,
+		});
+		recordModelSnapshot(
+			"/tmp/test-repo",
+			{
+				provider: "openai",
+				providerName: null,
+				modelId: "gpt-4o",
+				modelName: null,
+				inputRate: 2.5e-6,
+				outputRate: 10e-6,
+				contextWindow: 128000,
+				maxTokens: 16384,
+				reasoning: false,
+			},
+			dir,
+		);
+		await withServer("19457", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			assert.ok(body.savings);
+			assert.equal(body.savings!.model, "gpt-4o");
+		});
+	});
+
+	test("model snapshot with zero inputRate → savings: null", async () => {
+		const dir = freshDir("dash-pcache-zerorate-");
+		recordPerfSample(dir, "cache_hit_pct", 10, {
+			cacheRead: 100,
+			cacheWrite: 10,
+			input: 1000,
+		});
+		recordModelSnapshot(
+			"/tmp/test-repo",
+			{
+				provider: "local",
+				providerName: null,
+				modelId: "local-llm",
+				modelName: null,
+				inputRate: 0,
+				outputRate: 0,
+				contextWindow: 4096,
+				maxTokens: 2048,
+				reasoning: false,
+			},
+			dir,
+		);
+		await withServer("19458", dir, async (port) => {
+			const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+			assert.equal(res.status, 200);
+			const body = (await res.json()) as ProviderCacheResponse;
+			assert.equal(body.savings, null);
+		});
+	});
+});