pi-mega-compact 0.20.78 → 0.20.80

package/src/store/analytics/schema.ts

@@ -0,0 +1,132 @@
+/**
+ * schema.ts — PMA-1 DDL for analytics.db.
+ *
+ * Idempotent (CREATE IF NOT EXISTS). One statement per exec so a failure names
+ * the exact table. Matches the schema defined in
+ * docs/specs/provider-model-analytics-program.md §6.
+ *
+ * PREVENT-PI-004: no network. PREVENT-002: no interpolated identifiers.
+ */
+import type { DatabaseSync } from "node:sqlite";
+
+const SCHEMA_VERSION = 1;
+
+/**
+ * Initialize the analytics.db schema. Safe to call on every open — every
+ * statement is CREATE IF NOT EXISTS.
+ */
+export function initAnalyticsSchema(db: DatabaseSync): void {
+	// ── Lifecycle tables ──────────────────────────────────────────────
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS analytics_meta (
+			key   TEXT PRIMARY KEY,
+			value TEXT NOT NULL
+		)
+	`);
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS analytics_schema (
+			version    INTEGER PRIMARY KEY,
+			applied_at INTEGER NOT NULL,
+			digest     TEXT NOT NULL
+		)
+	`);
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS analytics_migrations (
+			id                TEXT PRIMARY KEY,
+			started_at        INTEGER NOT NULL,
+			completed_at      INTEGER,
+			source_fingerprint TEXT,
+			rows_copied       INTEGER,
+			status            TEXT NOT NULL,
+			detail            TEXT
+		)
+	`);
+
+	// ── Append-only fact tables ───────────────────────────────────────
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS request_events (
+			id                 TEXT PRIMARY KEY,
+			correlation_id     TEXT,
+			session_id         TEXT,
+			repo_id            TEXT,
+			turn_id            TEXT,
+			event_kind         TEXT NOT NULL CHECK(event_kind IN (
+				'request_started',
+				'provider_selected',
+				'first_token',
+				'request_completed',
+				'request_failed'
+			)),
+			observed_at        INTEGER NOT NULL,
+			provider           TEXT,
+			model              TEXT,
+			status             TEXT,
+			input_tokens       INTEGER,
+			output_tokens      INTEGER,
+			cache_read_tokens  INTEGER,
+			cache_write_tokens INTEGER,
+			duration_ms        REAL,
+			ttft_ms            REAL,
+			source             TEXT NOT NULL,
+			quality_json       TEXT NOT NULL
+		)
+	`);
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS measurement_samples (
+			id              INTEGER PRIMARY KEY AUTOINCREMENT,
+			observed_at     INTEGER NOT NULL,
+			sample_kind     TEXT NOT NULL,
+			provider        TEXT,
+			model           TEXT,
+			value           REAL NOT NULL,
+			unit            TEXT NOT NULL,
+			correlation_id  TEXT,
+			source          TEXT NOT NULL,
+			quality_json    TEXT NOT NULL
+		)
+	`);
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS identity_observations (
+			id             INTEGER PRIMARY KEY AUTOINCREMENT,
+			observed_at    INTEGER NOT NULL,
+			provider       TEXT,
+			model          TEXT,
+			source         TEXT NOT NULL,
+			metadata_json  TEXT NOT NULL
+		)
+	`);
+
+	// ── Indexes (spec §6) ─────────────────────────────────────────────
+
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_request_events_observed_at ON request_events(observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_request_events_provider_observed ON request_events(provider, observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_request_events_model_observed ON request_events(model, observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_request_events_kind_observed ON request_events(event_kind, observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_request_events_correlation ON request_events(correlation_id, observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_measurement_samples_kind_observed ON measurement_samples(sample_kind, observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_measurement_samples_provider_model ON measurement_samples(provider, model, observed_at)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS idx_identity_obs_provider_model ON identity_observations(provider, model, observed_at)`);
+
+	// ── Schema version stamp (insert-only, never overwrites) ─────────
+
+	const existing = db
+		.prepare("SELECT value FROM analytics_meta WHERE key = 'schema_version'")
+		.get() as { value: string } | undefined;
+	if (!existing) {
+		db.prepare("INSERT INTO analytics_meta (key, value) VALUES ('schema_version', ?)")
+			.run(String(SCHEMA_VERSION));
+		db.prepare("INSERT INTO analytics_schema (version, applied_at, digest) VALUES (?, ?, ?)")
+			.run(SCHEMA_VERSION, Date.now(), "pma-1-initial");
+	}
+}
+
+/** The current analytics schema version. */
+export function getAnalyticsSchemaVersion(): number {
+	return SCHEMA_VERSION;
+}

package/src/store/analytics/sqlite-store/admin.ts

@@ -0,0 +1,96 @@
+/**
+ * admin.ts — AnalyticsAdmin delegate bodies for the SQLite backend.
+ * Destructive/maintenance operations: prune, vacuum, integrityCheck, backup, clear, close.
+ */
+import { copyFileSync, existsSync } from "node:fs";
+import type {
+	RetentionPolicy,
+	PruneReport,
+	IntegrityReport,
+	MaintenanceReport,
+	BackupReport,
+} from "../types.js";
+import type { AnalyticsStoreCtx } from "./ctx.js";
+import { withTx } from "../connection.js";
+import { analyticsDbPath } from "../connection.js";
+
+export function prune(ctx: AnalyticsStoreCtx, policy: RetentionPolicy): PruneReport {
+	const now = Date.now();
+	const eventCutoff = now - policy.maxEventAgeMs;
+	const measCutoff = now - policy.maxMeasurementAgeMs;
+
+	const delEvents = ctx.db
+		.prepare("DELETE FROM request_events WHERE observed_at < ?")
+		.run(eventCutoff) as { changes?: number };
+	const delMeas = ctx.db
+		.prepare("DELETE FROM measurement_samples WHERE observed_at < ?")
+		.run(measCutoff) as { changes?: number };
+	// Identity observations are not age-pruned (they're low-volume snapshots).
+
+	if (policy.vacuumAfterPrune) {
+		try {
+			ctx.db.exec("VACUUM");
+		} catch {
+			/* non-fatal */
+		}
+	}
+
+	return {
+		eventsRemoved: delEvents.changes ?? 0,
+		measurementsRemoved: delMeas.changes ?? 0,
+		identitiesRemoved: 0,
+		freedBytes: 0,
+	};
+}
+
+export function vacuum(ctx: AnalyticsStoreCtx): MaintenanceReport {
+	try {
+		ctx.db.exec("VACUUM");
+		return { ok: true, detail: "VACUUM completed" };
+	} catch (e) {
+		return { ok: false, detail: String(e) };
+	}
+}
+
+export function integrityCheck(ctx: AnalyticsStoreCtx): IntegrityReport {
+	try {
+		const row = ctx.db.prepare("PRAGMA integrity_check").get() as
+			| { integrity_check: string }
+			| undefined;
+		const result = row?.integrity_check ?? "ok";
+		return { ok: result === "ok", detail: result };
+	} catch (e) {
+		return { ok: false, detail: String(e) };
+	}
+}
+
+export function backup(ctx: AnalyticsStoreCtx): BackupReport {
+	if (ctx.opts.inMemory) {
+		return { ok: false, detail: "Cannot backup an in-memory database" };
+	}
+	try {
+		// WAL-safe checkpoint before copy.
+		ctx.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+		const src = analyticsDbPath(ctx.stateDir);
+		if (!existsSync(src)) return { ok: false, detail: "analytics.db not found" };
+		const dest = `${src}.bak-${Date.now()}`;
+		copyFileSync(src, dest);
+		return { ok: true, path: dest, detail: `Backup written to ${dest}` };
+	} catch (e) {
+		return { ok: false, detail: String(e) };
+	}
+}
+
+export function clear(ctx: AnalyticsStoreCtx): void {
+	withTx(ctx.db, () => {
+		ctx.db.exec("DELETE FROM request_events");
+		ctx.db.exec("DELETE FROM measurement_samples");
+		ctx.db.exec("DELETE FROM identity_observations");
+		// Reset AUTOINCREMENT sequences for measurement_samples + identity_observations.
+		try {
+			ctx.db.exec("DELETE FROM sqlite_sequence WHERE name IN ('measurement_samples', 'identity_observations')");
+		} catch {
+			/* non-fatal: sqlite_sequence may not exist yet */
+		}
+	});
+}

package/src/store/analytics/sqlite-store/ctx.ts

@@ -0,0 +1,9 @@
+/** The shared context passed to every SQLite delegate function. */
+import type { DatabaseSync } from "node:sqlite";
+import type { AnalyticsStoreOptions } from "../types.js";
+
+export interface AnalyticsStoreCtx {
+	db: DatabaseSync;
+	stateDir: string;
+	opts: AnalyticsStoreOptions;
+}

package/src/store/analytics/sqlite-store/read.ts

@@ -0,0 +1,46 @@
+/**
+ * read.ts — AnalyticsReader delegate bodies for the SQLite backend.
+ * PMA-1: minimal (status only). Full queries (providers/models/live/detailed)
+ * arrive in PMA-3.
+ */
+import type { AnalyticsStatus } from "../types.js";
+import type { AnalyticsStoreCtx } from "./ctx.js";
+import { getAnalyticsSchemaVersion } from "../schema.js";
+
+export function status(ctx: AnalyticsStoreCtx): AnalyticsStatus {
+	const eventCount = (
+		ctx.db.prepare("SELECT COUNT(*) AS c FROM request_events").get() as { c: number }
+	).c;
+	const measurementCount = (
+		ctx.db.prepare("SELECT COUNT(*) AS c FROM measurement_samples").get() as { c: number }
+	).c;
+	const identityCount = (
+		ctx.db.prepare("SELECT COUNT(*) AS c FROM identity_observations").get() as { c: number }
+	).c;
+	// Freshness: the most recent observed_at across all three fact tables.
+	const lastEvent = (
+		ctx.db
+			.prepare("SELECT MAX(observed_at) AS mx FROM request_events")
+			.get() as { mx: number | null }
+	).mx;
+	const lastMeas = (
+		ctx.db
+			.prepare("SELECT MAX(observed_at) AS mx FROM measurement_samples")
+			.get() as { mx: number | null }
+	).mx;
+	const lastId = (
+		ctx.db
+			.prepare("SELECT MAX(observed_at) AS mx FROM identity_observations")
+			.get() as { mx: number | null }
+	).mx;
+	const freshThrough = Math.max(lastEvent ?? 0, lastMeas ?? 0, lastId ?? 0) || null;
+
+	return {
+		enabled: true,
+		schemaVersion: getAnalyticsSchemaVersion(),
+		requestEventCount: eventCount,
+		measurementCount,
+		identityCount,
+		freshThrough,
+	};
+}

package/src/store/analytics/sqlite-store/rows.ts

@@ -0,0 +1,58 @@
+/**
+ * rows.ts — row ↔ fact mappers for the SQLite analytics store.
+ * Maps snake_case DB columns to camelCase contract fields.
+ */
+import type {
+	RequestEventFact,
+	MeasurementFact,
+	IdentityObservation,
+	RequestEventKind,
+	QualityNote,
+} from "../types.js";
+
+export function rowToRequestEvent(r: Record<string, unknown>): RequestEventFact {
+	return {
+		id: r.id as string,
+		correlationId: (r.correlation_id as string) ?? undefined,
+		sessionId: (r.session_id as string) ?? undefined,
+		repoId: (r.repo_id as string) ?? undefined,
+		turnId: (r.turn_id as string) ?? undefined,
+		eventKind: r.event_kind as RequestEventKind,
+		observedAt: r.observed_at as number,
+		provider: (r.provider as string) ?? undefined,
+		model: (r.model as string) ?? undefined,
+		status: (r.status as string) ?? undefined,
+		inputTokens: (r.input_tokens as number) ?? undefined,
+		outputTokens: (r.output_tokens as number) ?? undefined,
+		cacheReadTokens: (r.cache_read_tokens as number) ?? undefined,
+		cacheWriteTokens: (r.cache_write_tokens as number) ?? undefined,
+		durationMs: (r.duration_ms as number) ?? undefined,
+		ttftMs: (r.ttft_ms as number) ?? undefined,
+		source: r.source as RequestEventFact["source"],
+		quality: JSON.parse((r.quality_json as string) ?? "{}") as QualityNote,
+	};
+}
+
+export function rowToMeasurement(r: Record<string, unknown>): MeasurementFact {
+	return {
+		observedAt: r.observed_at as number,
+		sampleKind: r.sample_kind as string,
+		provider: (r.provider as string) ?? undefined,
+		model: (r.model as string) ?? undefined,
+		value: r.value as number,
+		unit: r.unit as string,
+		correlationId: (r.correlation_id as string) ?? undefined,
+		source: r.source as MeasurementFact["source"],
+		quality: JSON.parse((r.quality_json as string) ?? "{}") as QualityNote,
+	};
+}
+
+export function rowToIdentity(r: Record<string, unknown>): IdentityObservation {
+	return {
+		observedAt: r.observed_at as number,
+		provider: (r.provider as string) ?? undefined,
+		model: (r.model as string) ?? undefined,
+		source: r.source as IdentityObservation["source"],
+		metadata: JSON.parse((r.metadata_json as string) ?? "{}") as Record<string, unknown>,
+	};
+}

package/src/store/analytics/sqlite-store/write.ts

@@ -0,0 +1,111 @@
+/**
+ * write.ts — AnalyticsWriter delegate bodies for the SQLite backend.
+ *
+ * All methods are append-only (INSERT only, never UPDATE). They return
+ * AppendResult — never throw into the host. INSERT OR IGNORE handles duplicate
+ * ids gracefully (PMA spec §5: "AppendResult identifies accepted/duplicate/
+ * failed without throwing").
+ */
+import type {
+	RequestEventFact,
+	MeasurementFact,
+	IdentityObservation,
+	AppendResult,
+} from "../types.js";
+import type { AnalyticsStoreCtx } from "./ctx.js";
+
+export function appendRequestEvent(ctx: AnalyticsStoreCtx, fact: RequestEventFact): AppendResult {
+	try {
+		const res = ctx.db
+			.prepare(
+				`INSERT OR IGNORE INTO request_events (
+					id, correlation_id, session_id, repo_id, turn_id, event_kind,
+					observed_at, provider, model, status,
+					input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+					duration_ms, ttft_ms, source, quality_json
+				) VALUES (
+					@id, @correlation_id, @session_id, @repo_id, @turn_id, @event_kind,
+					@observed_at, @provider, @model, @status,
+					@input_tokens, @output_tokens, @cache_read_tokens, @cache_write_tokens,
+					@duration_ms, @ttft_ms, @source, @quality_json
+				)`,
+			)
+			.run({
+				"@id": fact.id,
+				"@correlation_id": fact.correlationId ?? null,
+				"@session_id": fact.sessionId ?? null,
+				"@repo_id": fact.repoId ?? null,
+				"@turn_id": fact.turnId ?? null,
+				"@event_kind": fact.eventKind,
+				"@observed_at": fact.observedAt,
+				"@provider": fact.provider ?? null,
+				"@model": fact.model ?? null,
+				"@status": fact.status ?? null,
+				"@input_tokens": fact.inputTokens ?? null,
+				"@output_tokens": fact.outputTokens ?? null,
+				"@cache_read_tokens": fact.cacheReadTokens ?? null,
+				"@cache_write_tokens": fact.cacheWriteTokens ?? null,
+				"@duration_ms": fact.durationMs ?? null,
+				"@ttft_ms": fact.ttftMs ?? null,
+				"@source": fact.source,
+				"@quality_json": JSON.stringify(fact.quality ?? {}),
+			}) as { changes?: number };
+		return (res.changes ?? 0) > 0
+			? { status: "accepted", id: fact.id }
+			: { status: "duplicate", id: fact.id };
+	} catch (e) {
+		return { status: "failed", error: String(e) };
+	}
+}
+
+export function appendMeasurement(ctx: AnalyticsStoreCtx, fact: MeasurementFact): AppendResult {
+	try {
+		const res = ctx.db
+			.prepare(
+				`INSERT INTO measurement_samples (
+					observed_at, sample_kind, provider, model, value, unit,
+					correlation_id, source, quality_json
+				) VALUES (
+					@observed_at, @sample_kind, @provider, @model, @value, @unit,
+					@correlation_id, @source, @quality_json
+				)`,
+			)
+			.run({
+				"@observed_at": fact.observedAt,
+				"@sample_kind": fact.sampleKind,
+				"@provider": fact.provider ?? null,
+				"@model": fact.model ?? null,
+				"@value": fact.value,
+				"@unit": fact.unit,
+				"@correlation_id": fact.correlationId ?? null,
+				"@source": fact.source,
+				"@quality_json": JSON.stringify(fact.quality ?? {}),
+			}) as { lastInsertRowid?: number | bigint };
+		return { status: "accepted", id: Number(res.lastInsertRowid ?? 0) };
+	} catch (e) {
+		return { status: "failed", error: String(e) };
+	}
+}
+
+export function appendIdentity(ctx: AnalyticsStoreCtx, obs: IdentityObservation): AppendResult {
+	try {
+		const res = ctx.db
+			.prepare(
+				`INSERT INTO identity_observations (
+					observed_at, provider, model, source, metadata_json
+				) VALUES (
+					@observed_at, @provider, @model, @source, @metadata_json
+				)`,
+			)
+			.run({
+				"@observed_at": obs.observedAt,
+				"@provider": obs.provider ?? null,
+				"@model": obs.model ?? null,
+				"@source": obs.source,
+				"@metadata_json": JSON.stringify(obs.metadata ?? {}),
+			}) as { lastInsertRowid?: number | bigint };
+		return { status: "accepted", id: Number(res.lastInsertRowid ?? 0) };
+	} catch (e) {
+		return { status: "failed", error: String(e) };
+	}
+}

package/src/store/analytics/sqlite-store.ts

@@ -0,0 +1,119 @@
+/**
+ * sqlite-store.ts — SqliteAnalyticsStore: thin delegate shell for the SQLite
+ * analytics backend. Mirrors the turns store pattern (src/store/turns/sqlite-store.ts).
+ *
+ * Every method delegates to a function in sqlite-store/{read,write,admin}.ts.
+ * Capability gating: asReader/asWriter/asAdmin return fresh object literals
+ * exposing ONLY that interface's methods — never `this`.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type {
+	AnalyticsStore,
+	AnalyticsReader,
+	AnalyticsWriter,
+	AnalyticsAdmin,
+	AnalyticsStoreOptions,
+	RequestEventFact,
+	MeasurementFact,
+	IdentityObservation,
+	AppendResult,
+	AnalyticsStatus,
+	RetentionPolicy,
+	PruneReport,
+	IntegrityReport,
+	MaintenanceReport,
+	BackupReport,
+} from "./types.js";
+import { openAnalyticsDb, closeAnalyticsDb } from "./connection.js";
+import type { AnalyticsStoreCtx } from "./sqlite-store/ctx.js";
+import * as read from "./sqlite-store/read.js";
+import * as write from "./sqlite-store/write.js";
+import * as admin from "./sqlite-store/admin.js";
+
+export class SqliteAnalyticsStore implements AnalyticsStore {
+	private db: DatabaseSync;
+	private readonly stateDir: string;
+	private readonly opts: AnalyticsStoreOptions;
+
+	constructor(options: AnalyticsStoreOptions) {
+		this.opts = options;
+		this.stateDir = options.stateDir;
+		this.db = openAnalyticsDb(options.stateDir, {
+			dbPath: options.dbPath,
+			inMemory: options.inMemory,
+		});
+	}
+
+	private ctx(): AnalyticsStoreCtx {
+		return { db: this.db, stateDir: this.stateDir, opts: this.opts };
+	}
+
+	// ── AnalyticsReader ───────────────────────────────────────────────
+
+	status(): AnalyticsStatus {
+		return read.status(this.ctx());
+	}
+
+	// ── AnalyticsWriter ───────────────────────────────────────────────
+
+	appendRequestEvent(fact: RequestEventFact): AppendResult {
+		return write.appendRequestEvent(this.ctx(), fact);
+	}
+	appendMeasurement(sample: MeasurementFact): AppendResult {
+		return write.appendMeasurement(this.ctx(), sample);
+	}
+	appendIdentity(observation: IdentityObservation): AppendResult {
+		return write.appendIdentity(this.ctx(), observation);
+	}
+
+	// ── AnalyticsAdmin ────────────────────────────────────────────────
+
+	prune(policy: RetentionPolicy): PruneReport {
+		return admin.prune(this.ctx(), policy);
+	}
+	vacuum(): MaintenanceReport {
+		return admin.vacuum(this.ctx());
+	}
+	integrityCheck(): IntegrityReport {
+		return admin.integrityCheck(this.ctx());
+	}
+	backup(): BackupReport {
+		return admin.backup(this.ctx());
+	}
+	clear(): void {
+		admin.clear(this.ctx());
+	}
+	close(): void {
+		closeAnalyticsDb(this.stateDir, {
+			dbPath: this.opts.dbPath,
+			inMemory: this.opts.inMemory,
+		});
+	}
+
+	// ── Capability views ──────────────────────────────────────────────
+
+	asReader(): AnalyticsReader {
+		return {
+			status: () => this.status(),
+		};
+	}
+
+	asWriter(): AnalyticsWriter {
+		return {
+			appendRequestEvent: (f) => this.appendRequestEvent(f),
+			appendMeasurement: (s) => this.appendMeasurement(s),
+			appendIdentity: (o) => this.appendIdentity(o),
+		};
+	}
+
+	asAdmin(): AnalyticsAdmin {
+		return {
+			prune: (p) => this.prune(p),
+			vacuum: () => this.vacuum(),
+			integrityCheck: () => this.integrityCheck(),
+			backup: () => this.backup(),
+			clear: () => this.clear(),
+			close: () => this.close(),
+		};
+	}
+}