@obsunified/collector 2.0.1

package/src/lib/sql-db.ts

@@ -0,0 +1,166 @@
+/**
+ * Storage seam for the collector — RFC 0008.
+ *
+ * Stores and plugins target this interface instead of `D1Database` directly,
+ * so a future Node / better-sqlite3 / ClickHouse runtime is one new adapter
+ * away rather than a fork-and-rewrite. The shape is deliberately D1's
+ * existing `prepare → bind → first|all|run` chain so the migration of
+ * existing stores is mechanical (search-and-replace the constructor type).
+ *
+ * Today there is one implementation, `D1Adapter`. A `MemSqlDb` test double
+ * lives next door under `test-utils/`; `BetterSqliteAdapter` and
+ * `ClickHouseAdapter` are deferred until they have a real runtime to serve.
+ */
+
+export interface SqlDb {
+	readonly dialect?: SqlDialect;
+	prepare(sql: string): SqlStatement;
+	/**
+	 * Run multiple prepared statements as a batch. On D1 this maps to a
+	 * single network round-trip; on a future better-sqlite3 adapter it
+	 * wraps the calls in a transaction. Returns one result per statement
+	 * in input order, mirroring D1's `batch`.
+	 *
+	 * Statements MUST have been produced by this same `SqlDb` instance —
+	 * mixing adapters is an error and runtime behavior is undefined.
+	 */
+	batch(
+		statements: SqlStatement[],
+	): Promise<Array<{ meta: { changes: number } }>>;
+}
+
+export type SqlDialectName = "sqlite" | "postgres";
+
+export interface SqlDialect {
+	readonly name: SqlDialectName;
+	now(): string;
+	sinceHours(param: string): string;
+	sinceMinutes(param: string): string;
+	jsonText(expr: string, path: string): string;
+}
+
+export interface SqlStatement {
+	bind(...args: unknown[]): SqlStatement;
+	first<T = Record<string, unknown>>(): Promise<T | null>;
+	all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;
+	run(): Promise<{ meta: { changes: number } }>;
+}
+
+/**
+ * D1 already conforms to this shape almost exactly; the adapter normalizes
+ * two small differences:
+ *  - `all()` on D1 returns `results?: T[]` (optional). We coerce to `[]`.
+ *  - `run()`'s `meta.changes` is optional on D1. We coerce to `0`.
+ * Both differences are runtime-undetectable for the queries this codebase
+ * issues (every successful all() returns results; every run() against an
+ * INSERT/UPDATE/DELETE reports changes), but coercing keeps the typed
+ * interface honest.
+ */
+export class D1Adapter implements SqlDb {
+	readonly dialect = sqliteDialect;
+
+	constructor(private readonly d1: D1Database) {}
+
+	prepare(sql: string): SqlStatement {
+		return new D1StatementAdapter(this.d1.prepare(sql));
+	}
+
+	async batch(
+		statements: SqlStatement[],
+	): Promise<Array<{ meta: { changes: number } }>> {
+		// Unwrap each statement back to its D1 form — D1's batch takes
+		// D1PreparedStatement[], not our typed wrapper.
+		const unwrapped = statements.map((s) => {
+			if (!(s instanceof D1StatementAdapter)) {
+				throw new Error(
+					"D1Adapter.batch: statement was not produced by D1Adapter",
+				);
+			}
+			return s.unwrap();
+		});
+		const results = await this.d1.batch(unwrapped);
+		return results.map((r) => ({
+			meta: { changes: r.meta?.changes ?? 0 },
+		}));
+	}
+}
+
+/**
+ * Convenience wrapper for the common case: take a `CollectorEnv`-shaped
+ * object and return an `SqlDb`. Most plugins don't have access to the
+ * `CollectorRuntime` (they get it at register time, not handler time)
+ * so they call this directly. Plugins that *do* hold the runtime should
+ * prefer `runtime.getSqlDb(env)` so a host-supplied `sqlDb` factory in
+ * `CollectorConfig` takes effect.
+ */
+export const sqlDbFor = (env: { DB: D1Database | SqlDb }): SqlDb =>
+	isSqlDb(env.DB) ? env.DB : new D1Adapter(env.DB);
+
+export const sqliteDialect: SqlDialect = {
+	name: "sqlite",
+	now: () => "datetime('now')",
+	sinceHours: (param) => `datetime('now', '-' || ${param} || ' hours')`,
+	sinceMinutes: (param) => `datetime('now', '-' || ${param} || ' minutes')`,
+	jsonText: (expr, path) => `json_extract(${expr}, '${path}')`,
+};
+
+export const postgresDialect: SqlDialect = {
+	name: "postgres",
+	now: () => "CURRENT_TIMESTAMP",
+	sinceHours: (param) =>
+		`(CURRENT_TIMESTAMP - (${param}::text || ' hours')::interval)`,
+	sinceMinutes: (param) =>
+		`(CURRENT_TIMESTAMP - (${param}::text || ' minutes')::interval)`,
+	jsonText: (expr, path) => {
+		const key = path
+			.replace(/^\$\./, "")
+			.replace(/^"|"$/g, "")
+			.replace(/\\u002E/g, ".");
+		return `(${expr}::jsonb ->> '${key.replace(/'/g, "''")}')`;
+	},
+};
+
+export const dialectFor = (db: SqlDb): SqlDialect =>
+	db.dialect ?? sqliteDialect;
+
+const isSqlDb = (db: unknown): db is SqlDb => {
+	if (!db || typeof db !== "object") return false;
+	const candidate = db as {
+		prepare?: unknown;
+		batch?: unknown;
+		exec?: unknown;
+	};
+	return (
+		typeof candidate.prepare === "function" &&
+		typeof candidate.batch === "function" &&
+		typeof candidate.exec !== "function"
+	);
+};
+
+class D1StatementAdapter implements SqlStatement {
+	constructor(private readonly stmt: D1PreparedStatement) {}
+
+	/** Internal escape hatch for `D1Adapter.batch` to recover the wrapped
+	 *  D1 statement. Not part of the public `SqlStatement` shape. */
+	unwrap(): D1PreparedStatement {
+		return this.stmt;
+	}
+
+	bind(...args: unknown[]): SqlStatement {
+		return new D1StatementAdapter(this.stmt.bind(...args));
+	}
+
+	first<T = Record<string, unknown>>(): Promise<T | null> {
+		return this.stmt.first<T>();
+	}
+
+	async all<T = Record<string, unknown>>(): Promise<{ results: T[] }> {
+		const r = await this.stmt.all<T>();
+		return { results: r.results ?? [] };
+	}
+
+	async run(): Promise<{ meta: { changes: number } }> {
+		const r = await this.stmt.run();
+		return { meta: { changes: r.meta?.changes ?? 0 } };
+	}
+}

package/src/lib/stage6.test.ts

@@ -0,0 +1,216 @@
+/**
+ * RFC 0002 Stage 6 — auto-pinning + alert→analysis binding behaviour tests.
+ *
+ * Uses the shared MemSqlDb test double from RFC 0008. The test asserts on
+ * the *decisions* — which SQL we issue, which value the evaluator returns —
+ * not the SQL grammar.
+ */
+
+import type { AlertRule } from "@obsunified/types";
+import { describe, expect, it } from "vitest";
+import { AlertsStore } from "./alerts-store";
+import { AnalysesStore } from "./analyses-store";
+import { MemSqlDb } from "./test-utils/mem-sql-db";
+
+// ── Auto-pin ──
+
+describe("AnalysesStore.recordAskEvidence", () => {
+	it("inserts one row per unique analysis id", async () => {
+		const db = new MemSqlDb();
+		const store = new AnalysesStore(db);
+		await store.recordAskEvidence("default", [
+			"a",
+			"b",
+			"a", // dedupe
+		]);
+		const inserts = db.callsMatching("INSERT INTO ask_evidence_events");
+		expect(inserts).toHaveLength(2);
+		expect(inserts.map((c) => c.binds[1])).toEqual(
+			expect.arrayContaining(["a", "b"]),
+		);
+	});
+
+	it("is a no-op when no ids supplied", async () => {
+		const db = new MemSqlDb();
+		const store = new AnalysesStore(db);
+		await store.recordAskEvidence("default", []);
+		expect(db.calls).toHaveLength(0);
+	});
+});
+
+describe("AnalysesStore.getTopAskedAnalyses", () => {
+	it("orders by citation count desc, returns analysisId+citations", async () => {
+		const db = new MemSqlDb({
+			all: () => [
+				{ analysis_id: "service_error_rate::checkout", citations: 7 },
+				{ analysis_id: "overall_error_rate", citations: 3 },
+			],
+		});
+		const store = new AnalysesStore(db);
+		const top = await store.getTopAskedAnalyses("default");
+		expect(top).toEqual([
+			{ analysisId: "service_error_rate::checkout", citations: 7 },
+			{ analysisId: "overall_error_rate", citations: 3 },
+		]);
+	});
+});
+
+// ── Alert binding ──
+
+const baseRule = (overrides: Partial<AlertRule> = {}): AlertRule => ({
+	id: "r1",
+	projectId: "default",
+	name: "checkout errors",
+	signal: "spans",
+	query: { kind: "spans" } as unknown as AlertRule["query"],
+	threshold: 1,
+	windowMins: 5,
+	comparison: ">",
+	channels: [],
+	enabled: true,
+	createdAt: "2026-04-29T00:00:00Z",
+	updatedAt: "2026-04-29T00:00:00Z",
+	...overrides,
+});
+
+describe("AlertsStore.evaluateRule with analysisId binding", () => {
+	it("reads analysis_results.primary_value when analysisId is set", async () => {
+		const db = new MemSqlDb({
+			first: (sql) => {
+				if (sql.includes("FROM analysis_results")) return { primary_value: 42 };
+				return null;
+			},
+		});
+		const store = new AlertsStore(db);
+		const rule = baseRule({ analysisId: "overall_error_rate" });
+		const value = await store.evaluateRule(rule);
+		expect(value).toBe(42);
+		// And we never fell through to the spans evaluator.
+		expect(db.callsMatching("FROM telemetry_spans")).toHaveLength(0);
+	});
+
+	it("returns 0 when the analysis has no result yet (rule treats as 'no signal')", async () => {
+		const db = new MemSqlDb({
+			first: () => null,
+		});
+		const store = new AlertsStore(db);
+		const rule = baseRule({ analysisId: "brand_new_analysis" });
+		const value = await store.evaluateRule(rule);
+		expect(value).toBe(0);
+	});
+
+	it("falls through to legacy signal evaluator when analysisId is not set", async () => {
+		const db = new MemSqlDb({
+			first: (sql) => {
+				if (sql.includes("FROM telemetry_spans")) return { c: 5 };
+				return null;
+			},
+		});
+		const store = new AlertsStore(db);
+		const rule = baseRule({ analysisId: null });
+		const value = await store.evaluateRule(rule);
+		expect(value).toBe(5);
+	});
+});
+
+describe("AlertsStore.getAnalysisNarrative", () => {
+	it("returns the most recent narrative + status row", async () => {
+		const db = new MemSqlDb({
+			first: () => ({
+				narrative: "p95 jumped to 320ms (was 90ms) starting 8m ago",
+				status: "warn",
+			}),
+		});
+		const store = new AlertsStore(db);
+		const out = await store.getAnalysisNarrative(
+			"default",
+			"latency_p95_overall",
+		);
+		expect(out).toEqual({
+			narrative: "p95 jumped to 320ms (was 90ms) starting 8m ago",
+			status: "warn",
+		});
+	});
+
+	it("returns null when there's no result yet", async () => {
+		const db = new MemSqlDb({ first: () => null });
+		const store = new AlertsStore(db);
+		const out = await store.getAnalysisNarrative("default", "nope");
+		expect(out).toBeNull();
+	});
+});
+
+describe("AlertsStore.listEvaluations evidence references", () => {
+	it("hoists alert and bound-analysis evidence references to the list response", async () => {
+		const db = new MemSqlDb({
+			first: (sql) => {
+				if (sql.includes("FROM alert_rules")) {
+					return {
+						id: "rule-1",
+						project_id: "default",
+						name: "Checkout latency",
+						signal: "spans",
+						query_json: "{}",
+						threshold: 100,
+						window_mins: 5,
+						comparison: ">",
+						channels_json: "[]",
+						enabled: 1,
+						created_at: "2026-05-01T00:00:00.000Z",
+						updated_at: "2026-05-01T00:00:00.000Z",
+						analysis_id: "latency.p95",
+					};
+				}
+				return null;
+			},
+			all: (sql) => {
+				if (sql.includes("FROM alert_evaluations")) {
+					return [
+						{
+							id: "eval-1",
+							rule_id: "rule-1",
+							project_id: "default",
+							evaluated_at: "2026-05-01T00:05:00.000Z",
+							value: 320,
+							state: "firing",
+							notified: 1,
+						},
+					];
+				}
+				return [];
+			},
+		});
+		const store = new AlertsStore(db);
+
+		const response = await store.listEvaluations({
+			ruleId: "rule-1",
+			projectId: "default",
+			hours: 24,
+		});
+
+		expect(response.evaluations).toEqual([
+			expect.objectContaining({
+				id: "eval-1",
+				value: 320,
+				state: "firing",
+			}),
+		]);
+		expect(response.evaluations[0].evidenceReferences).toBeUndefined();
+		expect(response.evidenceReferences).toEqual([
+			expect.objectContaining({
+				evidenceId: "alert:rule-1:rule",
+				entityKind: "alert",
+				entityId: "rule-1",
+				route: "#/alerts?alert=rule-1",
+				source: "alerts.rule_evaluation_preview",
+			}),
+			expect.objectContaining({
+				evidenceId: "alert:rule-1:analysis:latency.p95",
+				entityKind: "analysis",
+				entityId: "latency.p95",
+				route: "#/investigate/latency.p95",
+				source: "alert_rules.analysis_id",
+			}),
+		]);
+	});
+});

package/src/lib/store/export.ts

@@ -0,0 +1,65 @@
+import type { TelemetryOverviewOptions } from "@obsunified/types";
+import type { SqlDb } from "../sql-db";
+import { cutoffIso } from "./helpers";
+
+export async function getTelemetryExportRows(
+	db: SqlDb,
+	options: TelemetryOverviewOptions,
+): Promise<string> {
+	if (!options.projectId)
+		throw new Error("TelemetryStore.getExportRows: projectId is required");
+	const cutoff = cutoffIso(options.hours);
+	const now = new Date().toISOString();
+	let whereClause =
+		"WHERE project_id = ? AND received_at > ? AND expires_at > ?";
+	const params: unknown[] = [options.projectId, cutoff, now];
+
+	if (options.service) {
+		whereClause += " AND service_name = ?";
+		params.push(options.service);
+	}
+	if (options.status === "error") {
+		whereClause += " AND status_code = 2";
+	} else if (options.status === "ok") {
+		whereClause += " AND status_code != 2";
+	}
+	if (options.search) {
+		const term = `%${options.search}%`;
+		whereClause +=
+			" AND (span_name LIKE ? OR status_message LIKE ? OR attributes_json LIKE ? OR events_json LIKE ?)";
+		params.push(term, term, term, term);
+	}
+
+	const rows = await db
+		.prepare(`
+        SELECT trace_id, span_id, parent_span_id, service_name, span_name,
+               status_code, status_message, start_time, end_time, duration_ms,
+               attributes_json, events_json, received_at
+        FROM telemetry_spans
+        ${whereClause}
+        ORDER BY received_at DESC
+        LIMIT 1000
+      `)
+		.bind(...params)
+		.all<Record<string, unknown>>();
+
+	return (rows.results || [])
+		.map((row) =>
+			JSON.stringify({
+				trace_id: row.trace_id,
+				span_id: row.span_id,
+				parent_span_id: row.parent_span_id,
+				service: row.service_name,
+				span_name: row.span_name,
+				status_code: row.status_code,
+				status_message: row.status_message,
+				start_time: row.start_time,
+				end_time: row.end_time,
+				duration_ms: row.duration_ms,
+				attributes: JSON.parse((row.attributes_json as string) || "{}"),
+				events: JSON.parse((row.events_json as string) || "[]"),
+				received_at: row.received_at,
+			}),
+		)
+		.join("\n");
+}