@kitlangton/motel 0.2.0 → 0.2.4

package/src/services/TelemetryStore.ts

@@ -7,6 +7,9 @@ import type { AiCallDetail, AiCallSummary, FacetItem, LogItem, SpanItem, StatsIt
 import { AI_ATTR_MAP, AI_FTS_KEYS, AI_TEXT_SEARCH_KEYS, truncatePreview } from "../domain.js"
 import { attributeMap, nanosToMilliseconds, parseAnyValue, spanKindLabel, spanStatusLabel, stringifyValue, type OtlpLogExportRequest, type OtlpTraceExportRequest } from "../otlp.js"
 
+const isSqliteLockError = (error: unknown) =>
+	error instanceof Error && /(database is locked|database table is locked|SQLITE_BUSY)/i.test(error.message)
+
 interface SpanRow {
 	readonly trace_id: string
 	readonly span_id: string
@@ -447,117 +450,185 @@ export class TelemetryStore extends Context.Service<
 >()("motel/TelemetryStore") {}
 
 
-export const TelemetryStoreLive = Layer.effect(
+/**
+ * How this TelemetryStore instance behaves:
+ *
+ * - `readonly` — opens the SQLite connection read-only and skips every
+ *   DDL/DML initialisation. Use this from the TUI (and anywhere else
+ *   that only queries); it avoids the "database is locked" race that
+ *   happens when a TUI process races a daemon's writer for the schema
+ *   pragmas on startup. Writes through the service interface become
+ *   runtime errors — but readers don't call them.
+ *
+ * - `runRetention` — fork the background cleanup loop (age + size cap
+ *   eviction, WAL checkpoint). Only one process should own this at a
+ *   time. Currently the main daemon (localServer) does; the ingest
+ *   worker and the TUI skip it.
+ */
+export interface TelemetryStoreOptions {
+	readonly readonly: boolean
+	readonly runRetention: boolean
+}
+
+export const makeTelemetryStoreLayer = (opts: TelemetryStoreOptions) => Layer.effect(
 	TelemetryStore,
 	Effect.gen(function* () {
 		mkdirSync(dirname(config.otel.databasePath), { recursive: true })
 		const db = yield* Effect.acquireRelease(
-			Effect.sync(() => new Database(config.otel.databasePath, { create: true })),
+			Effect.sync(() => new Database(config.otel.databasePath, {
+				create: !opts.readonly,
+				readonly: opts.readonly,
+			})),
 			(db) => Effect.sync(() => {
-				// `PRAGMA optimize` at close persists any stats SQLite gathered
-				// during the session, so the next process start gets an accurate
-				// query planner on the first query instead of a 3-second cold
-				// run. Cheap: it skips work unless stats have drifted.
-				try { db.exec(`PRAGMA optimize;`) } catch { /* nothing */ }
+				if (!opts.readonly) {
+					// `PRAGMA optimize` at close persists any stats SQLite gathered
+					// during the session, so the next process start gets an accurate
+					// query planner on the first query instead of a 3-second cold
+					// run. Cheap: it skips work unless stats have drifted.
+					try { db.exec(`PRAGMA optimize;`) } catch { /* nothing */ }
+				}
 				db.close()
 			}),
 		)
-		db.exec(`
-			PRAGMA journal_mode = WAL;
-			PRAGMA synchronous = NORMAL;
-			PRAGMA temp_store = MEMORY;
-			PRAGMA busy_timeout = 5000;
-			-- Bump cache above the 2MB default. 64MB fits most hot index pages
-			-- (trace_summaries, spans, span_attributes indexes) in RAM even on
-			-- multi-GB databases, cutting cold-read latency meaningfully on
-			-- picker / search queries that sweep the index.
-			PRAGMA cache_size = -65536;
-			-- Let SQLite memory-map the first 256MB of the file. This is a
-			-- cheap way to avoid read() syscalls on hot pages and lets the OS
-			-- page cache serve index lookups directly. Safe on macOS and Linux;
-			-- SQLite silently caps at actual file size for smaller DBs.
-			PRAGMA mmap_size = 268435456;
-
-			CREATE TABLE IF NOT EXISTS spans (
-				trace_id TEXT NOT NULL,
-				span_id TEXT NOT NULL,
-				parent_span_id TEXT,
-				service_name TEXT NOT NULL,
-				scope_name TEXT,
-				operation_name TEXT NOT NULL,
-				kind TEXT,
-				start_time_ms INTEGER NOT NULL,
-				end_time_ms INTEGER NOT NULL,
-				duration_ms REAL NOT NULL,
-				status TEXT NOT NULL,
-				attributes_json TEXT NOT NULL,
-				resource_json TEXT NOT NULL,
-				events_json TEXT NOT NULL,
-				PRIMARY KEY (trace_id, span_id)
-			);
-
-			CREATE INDEX IF NOT EXISTS idx_spans_service_time ON spans(service_name, start_time_ms DESC);
-			CREATE INDEX IF NOT EXISTS idx_spans_trace_time ON spans(trace_id, start_time_ms ASC);
-			CREATE INDEX IF NOT EXISTS idx_spans_span_id ON spans(span_id);
-			CREATE INDEX IF NOT EXISTS idx_spans_status_time ON spans(status, start_time_ms DESC);
-
-			CREATE TABLE IF NOT EXISTS logs (
-				id INTEGER PRIMARY KEY AUTOINCREMENT,
-				trace_id TEXT,
-				span_id TEXT,
-				service_name TEXT NOT NULL,
-				scope_name TEXT,
-				severity_text TEXT NOT NULL,
-				timestamp_ms INTEGER NOT NULL,
-				body TEXT NOT NULL,
-				attributes_json TEXT NOT NULL,
-				resource_json TEXT NOT NULL
-			);
-
-			CREATE INDEX IF NOT EXISTS idx_logs_service_time ON logs(service_name, timestamp_ms DESC);
-			CREATE INDEX IF NOT EXISTS idx_logs_trace_time ON logs(trace_id, timestamp_ms DESC);
-			CREATE INDEX IF NOT EXISTS idx_logs_span_time ON logs(span_id, timestamp_ms DESC);
-			CREATE INDEX IF NOT EXISTS idx_logs_severity_time ON logs(severity_text, timestamp_ms DESC);
-
-			CREATE TABLE IF NOT EXISTS trace_summaries (
-				trace_id TEXT PRIMARY KEY,
-				service_name TEXT NOT NULL,
-				root_operation_name TEXT NOT NULL,
-				started_at_ms INTEGER NOT NULL,
-				ended_at_ms INTEGER NOT NULL,
-				active_span_count INTEGER NOT NULL DEFAULT 0,
-				duration_ms REAL NOT NULL,
-				span_count INTEGER NOT NULL,
-				error_count INTEGER NOT NULL
-			);
-
-			CREATE INDEX IF NOT EXISTS idx_trace_summaries_started_at ON trace_summaries(started_at_ms DESC, trace_id DESC);
-			CREATE INDEX IF NOT EXISTS idx_trace_summaries_service_started_at ON trace_summaries(service_name, started_at_ms DESC, trace_id DESC);
-			CREATE INDEX IF NOT EXISTS idx_trace_summaries_duration ON trace_summaries(duration_ms DESC);
-
-			CREATE TABLE IF NOT EXISTS span_attributes (
-				trace_id TEXT NOT NULL,
-				span_id TEXT NOT NULL,
-				key TEXT NOT NULL,
-				value TEXT NOT NULL,
-				PRIMARY KEY (trace_id, span_id, key)
-			);
-
-			CREATE INDEX IF NOT EXISTS idx_span_attributes_key_value ON span_attributes(key, value, trace_id, span_id);
-			CREATE INDEX IF NOT EXISTS idx_span_attributes_trace_span ON span_attributes(trace_id, span_id);
-
-			CREATE TABLE IF NOT EXISTS log_attributes (
-				log_id INTEGER NOT NULL,
-				key TEXT NOT NULL,
-				value TEXT NOT NULL,
-				PRIMARY KEY (log_id, key)
-			);
-
-			CREATE INDEX IF NOT EXISTS idx_log_attributes_key_value ON log_attributes(key, value, log_id);
-			CREATE INDEX IF NOT EXISTS idx_log_attributes_log_id ON log_attributes(log_id);
-		`)
+		if (opts.readonly) {
+			// Readonly connections skip schema init entirely — the schema
+			// already exists (a writer created it) and any `CREATE TABLE IF
+			// NOT EXISTS` / `PRAGMA journal_mode = WAL` statement would
+			// attempt a write and fight the daemon for the write lock.
+			// `query_only = 1` logically blocks any DML the app might
+			// accidentally send; still bump cache + mmap since those are
+			// safe and keep queries fast.
+			db.exec(`
+				PRAGMA query_only = 1;
+				PRAGMA busy_timeout = 15000;
+				PRAGMA cache_size = -65536;
+				PRAGMA mmap_size = 268435456;
+			`)
+		} else {
+			db.exec(`
+				-- Bump cache above the 2MB default. 64MB fits most hot index pages
+				-- (trace_summaries, spans, span_attributes indexes) in RAM even on
+				-- multi-GB databases, cutting cold-read latency meaningfully on
+				-- picker / search queries that sweep the index.
+				PRAGMA cache_size = -65536;
+				-- Let SQLite memory-map the first 256MB of the file. This is a
+				-- cheap way to avoid read() syscalls on hot pages and lets the OS
+				-- page cache serve index lookups directly. Safe on macOS and Linux;
+				-- SQLite silently caps at actual file size for smaller DBs.
+				PRAGMA mmap_size = 268435456;
+			`)
+			try {
+				db.exec(`
+					PRAGMA journal_mode = WAL;
+					PRAGMA synchronous = NORMAL;
+					PRAGMA temp_store = MEMORY;
+					-- WAL checkpoint automatically when it grows past ~16MB. Without
+					-- this the WAL happily runs into the hundreds of MB and queries
+					-- start paying the cost of walking the WAL on every read.
+					PRAGMA wal_autocheckpoint = 4000;
+
+					CREATE TABLE IF NOT EXISTS spans (
+						trace_id TEXT NOT NULL,
+						span_id TEXT NOT NULL,
+						parent_span_id TEXT,
+						service_name TEXT NOT NULL,
+						scope_name TEXT,
+						operation_name TEXT NOT NULL,
+						kind TEXT,
+						start_time_ms INTEGER NOT NULL,
+						end_time_ms INTEGER NOT NULL,
+						duration_ms REAL NOT NULL,
+						status TEXT NOT NULL,
+						attributes_json TEXT NOT NULL,
+						resource_json TEXT NOT NULL,
+						events_json TEXT NOT NULL,
+						PRIMARY KEY (trace_id, span_id)
+					);
+
+					CREATE INDEX IF NOT EXISTS idx_spans_service_time ON spans(service_name, start_time_ms DESC);
+					CREATE INDEX IF NOT EXISTS idx_spans_trace_time ON spans(trace_id, start_time_ms ASC);
+					CREATE INDEX IF NOT EXISTS idx_spans_span_id ON spans(span_id);
+					CREATE INDEX IF NOT EXISTS idx_spans_status_time ON spans(status, start_time_ms DESC);
+
+					CREATE TABLE IF NOT EXISTS logs (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						trace_id TEXT,
+						span_id TEXT,
+						service_name TEXT NOT NULL,
+						scope_name TEXT,
+						severity_text TEXT NOT NULL,
+						timestamp_ms INTEGER NOT NULL,
+						body TEXT NOT NULL,
+						attributes_json TEXT NOT NULL,
+						resource_json TEXT NOT NULL
+					);
+
+					CREATE INDEX IF NOT EXISTS idx_logs_service_time ON logs(service_name, timestamp_ms DESC);
+					CREATE INDEX IF NOT EXISTS idx_logs_trace_time ON logs(trace_id, timestamp_ms DESC);
+					CREATE INDEX IF NOT EXISTS idx_logs_span_time ON logs(span_id, timestamp_ms DESC);
+					CREATE INDEX IF NOT EXISTS idx_logs_severity_time ON logs(severity_text, timestamp_ms DESC);
+
+					CREATE TABLE IF NOT EXISTS trace_summaries (
+						trace_id TEXT PRIMARY KEY,
+						service_name TEXT NOT NULL,
+						root_operation_name TEXT NOT NULL,
+						started_at_ms INTEGER NOT NULL,
+						ended_at_ms INTEGER NOT NULL,
+						active_span_count INTEGER NOT NULL DEFAULT 0,
+						duration_ms REAL NOT NULL,
+						span_count INTEGER NOT NULL,
+						error_count INTEGER NOT NULL
+					);
+
+					CREATE INDEX IF NOT EXISTS idx_trace_summaries_started_at ON trace_summaries(started_at_ms DESC, trace_id DESC);
+					CREATE INDEX IF NOT EXISTS idx_trace_summaries_service_started_at ON trace_summaries(service_name, started_at_ms DESC, trace_id DESC);
+					CREATE INDEX IF NOT EXISTS idx_trace_summaries_duration ON trace_summaries(duration_ms DESC);
+
+					CREATE TABLE IF NOT EXISTS span_attributes (
+						trace_id TEXT NOT NULL,
+						span_id TEXT NOT NULL,
+						key TEXT NOT NULL,
+						value TEXT NOT NULL,
+						PRIMARY KEY (trace_id, span_id, key)
+					);
+
+					CREATE INDEX IF NOT EXISTS idx_span_attributes_key_value ON span_attributes(key, value, trace_id, span_id);
+					CREATE INDEX IF NOT EXISTS idx_span_attributes_trace_span ON span_attributes(trace_id, span_id);
 
+					CREATE TABLE IF NOT EXISTS log_attributes (
+						log_id INTEGER NOT NULL,
+						key TEXT NOT NULL,
+						value TEXT NOT NULL,
+						PRIMARY KEY (log_id, key)
+					);
+
+					CREATE INDEX IF NOT EXISTS idx_log_attributes_key_value ON log_attributes(key, value, log_id);
+					CREATE INDEX IF NOT EXISTS idx_log_attributes_log_id ON log_attributes(log_id);
+				`)
+			} catch (err) {
+				if (!isSqliteLockError(err)) throw err
+				console.warn(`motel: writer bootstrap skipped during startup: ${(err as Error).message}`)
+			}
+		}
+
+		// Tables detected at runtime. For writer connections these flags are
+		// set by the FTS `CREATE VIRTUAL TABLE IF NOT EXISTS` try/catch; for
+		// readonly connections we probe `sqlite_master` and set them based on
+		// what the writer has already provisioned.
 		let hasFts = true
+		let hasAttrFts = true
+		if (opts.readonly) {
+			try {
+				const row = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name='span_operation_fts'`).get()
+				hasFts = row !== null
+			} catch { hasFts = false }
+			try {
+				const row = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name='span_attr_fts'`).get()
+				hasAttrFts = row !== null
+			} catch { hasAttrFts = false }
+		}
+
+		if (!opts.readonly) {
 		try {
 			db.exec(`
 				CREATE VIRTUAL TABLE IF NOT EXISTS span_operation_fts USING fts5(
@@ -589,7 +660,6 @@ export const TelemetryStoreLive = Layer.effect(
 		// Keys are inlined into the trigger DDL rather than looked up in a
 		// side table so the `WHEN` guard stays constant-cost (a subquery
 		// would run on every span_attributes insert — ~60/span).
-		let hasAttrFts = hasFts
 		if (hasFts) {
 			try {
 				const keyList = AI_FTS_KEYS.map((k) => `'${k.replace(/'/g, "''")}'`).join(", ")
@@ -661,6 +731,13 @@ export const TelemetryStoreLive = Layer.effect(
 			// ANALYZE / optimize failures are never fatal — queries still work,
 			// they just run with default row estimates.
 		}
+			// Longer busy timeout: the ingest worker holds the write lock for up
+			// to a few seconds during big OTLP batches, and the daemon's retention
+			// passes can do the same. Apply this AFTER startup maintenance so
+			// lock-conflicted bootstrap steps fail fast instead of stalling health
+			// for the full 15s timeout.
+			try { db.exec(`PRAGMA busy_timeout = 15000;`) } catch { /* ignore */ }
+		} // end: if (!opts.readonly) writer init
 
 		const insertSpan = db.query(`
 			INSERT INTO spans (
@@ -708,8 +785,15 @@ export const TelemetryStoreLive = Layer.effect(
 			GROUP BY trace_id
 		`)
 
-		db.query(`DELETE FROM trace_summaries`).run()
-		rebuildTraceSummaries.run()
+		const reconcileTraceSummaries = Effect.sync(() => {
+			try {
+				db.query(`DELETE FROM trace_summaries`).run()
+				rebuildTraceSummaries.run()
+			} catch (err) {
+				if (!isSqliteLockError(err)) throw err
+				console.warn(`motel: trace summary rebuild skipped during startup: ${(err as Error).message}`)
+			}
+		})
 
 		const deleteSpanAttributes = db.query(`DELETE FROM span_attributes WHERE trace_id = ? AND span_id = ?`)
 		const insertSpanAttribute = db.query(`INSERT INTO span_attributes (trace_id, span_id, key, value) VALUES (?, ?, ?, ?)`)
@@ -792,28 +876,61 @@ export const TelemetryStoreLive = Layer.effect(
 				} catch {
 					// FTS table may not exist on old DBs.
 				}
+
+				// Truncate the WAL after a big delete pass. Without this the
+				// WAL keeps growing (observed: 640MB) because wal_autocheckpoint
+				// only triggers when WAL pages exceed the threshold during
+				// writes — a retention pass that evicts millions of rows can
+				// blow far past that before the auto-checkpoint fires. Using
+				// PASSIVE so active readers aren't interrupted; if the WAL
+				// can't be fully reclaimed right now, we'll try again next
+				// cycle.
+				try { db.exec(`PRAGMA wal_checkpoint(PASSIVE);`) } catch { /* ignore */ }
+
+				// Incremental vacuum reclaims some of the freed pages back
+				// to the OS so the file size actually shrinks over time
+				// instead of just growing the freelist. Bounded to 2000
+				// pages per pass (≈8MB) to avoid a long-running transaction.
+				try { db.exec(`PRAGMA incremental_vacuum(2000);`) } catch { /* ignore */ }
 			})
 		})
 
-		// Run cleanup every 60 seconds in the background, tied to the layer's scope
-		yield* Effect.forkScoped(Effect.repeat(cleanupExpired(), Schedule.spaced("60 seconds")))
-
-		// Periodically refresh query planner stats. `PRAGMA optimize` is a
-		// no-op when nothing has changed, so this is essentially free on idle
-		// servers and keeps facet/search planner estimates accurate as data
-		// grows. 15 minutes is slower than ingestion rates we care about but
-		// frequent enough that the attribute picker stays snappy.
-		const refreshPlannerStats = Effect.sync(() => {
-			try { db.exec(`PRAGMA optimize;`) } catch { /* ignore */ }
-		})
-		yield* Effect.forkScoped(Effect.repeat(refreshPlannerStats, Schedule.spaced("15 minutes")))
+		// Retention only runs in processes that opt in (currently the main
+		// daemon). The ingest worker and TUI skip it to avoid two writers
+		// competing for the write lock with overlapping DELETE passes.
+		if (opts.runRetention) {
+			// Reconcile any summary drift from interrupted ingests, but do it
+			// after the server becomes healthy. Running this synchronously at
+			// open can sit behind another writer's lock for ~15s and make the
+			// daemon look hung even though the port is already bound.
+			yield* Effect.forkScoped(reconcileTraceSummaries)
+
+			// Enable incremental vacuum so retention can reclaim freed
+			// pages over time instead of needing a stop-the-world VACUUM.
+			// Idempotent: repeat calls after the first are no-ops.
+			try { db.exec(`PRAGMA auto_vacuum = INCREMENTAL;`) } catch { /* ignore */ }
+
+			// Run cleanup every 60 seconds in the background, tied to the layer's scope
+			yield* Effect.forkScoped(Effect.repeat(cleanupExpired(), Schedule.spaced("60 seconds")))
+
+			// Periodically refresh query planner stats. `PRAGMA optimize` is a
+			// no-op when nothing has changed, so this is essentially free on idle
+			// servers and keeps facet/search planner estimates accurate as data
+			// grows. 15 minutes is slower than ingestion rates we care about but
+			// frequent enough that the attribute picker stays snappy.
+			const refreshPlannerStats = Effect.sync(() => {
+				try { db.exec(`PRAGMA optimize;`) } catch { /* ignore */ }
+			})
+			yield* Effect.forkScoped(Effect.repeat(refreshPlannerStats, Schedule.spaced("15 minutes")))
+		}
 
 		// One-time backfill for existing DBs: if span_attr_fts is empty but
 		// span_attributes has rows with AI_FTS_KEYS, populate the index.
 		// Runs forked so server startup isn't blocked; queries hitting the
 		// FTS will just return empty until the fill lands. On a 2 GB DB with
-		// ~400 matching rows this takes ~3-8 seconds.
-		if (hasAttrFts) {
+		// ~400 matching rows this takes ~3-8 seconds. Writer-only because
+		// it does INSERT INTO ... — readonly connections would error.
+		if (hasAttrFts && !opts.readonly) {
 			const backfillAttrFts = Effect.sync(() => {
 				try {
 					const ftsCount = (db.query(`SELECT COUNT(*) AS c FROM span_attr_fts`).get() as { c: number }).c
@@ -1705,7 +1822,11 @@ export const TelemetryStoreLive = Layer.effect(
 
 		/** Builds WHERE clauses for AI call search against the spans table (aliased as s) */
 		const buildAiWhereClauses = (input: AiCallSearch | AiCallStatsSearch, cutoff: number) => {
-			const clauses: string[] = ["s.operation_name LIKE 'ai.%'", "s.start_time_ms >= ?"]
+			const clauses: string[] = [
+				"s.operation_name LIKE 'ai.%'",
+				"s.operation_name NOT LIKE 'ai.%.do%'",
+				"s.start_time_ms >= ?",
+			]
 			const params: Array<string | number> = [cutoff]
 
 			if (input.service) {
@@ -2094,3 +2215,25 @@ export const TelemetryStoreLive = Layer.effect(
 		})
 	}),
 )
+
+/**
+ * Default writer instance: the main daemon uses this. Owns schema
+ * migrations, FTS backfill, and the retention loop.
+ */
+export const TelemetryStoreLive = makeTelemetryStoreLayer({ readonly: false, runRetention: true })
+
+/**
+ * Writer instance that SKIPS retention. The ingest worker uses this
+ * so the daemon and the worker aren't both running DELETE passes at
+ * the same time (they'd just serialise behind the write lock and
+ * duplicate work).
+ */
+export const TelemetryStoreWorkerLive = makeTelemetryStoreLayer({ readonly: false, runRetention: false })
+
+/**
+ * Read-only instance for query-only processes (currently the TUI).
+ * Skips every DDL/DML statement at startup so the connection can be
+ * opened while a writer is mid-transaction without racing for the
+ * write lock. Writes through the service interface will throw.
+ */
+export const TelemetryStoreReadonlyLive = makeTelemetryStoreLayer({ readonly: true, runRetention: false })

package/src/services/TraceQueryService.ts

@@ -1,5 +1,5 @@
 import { Effect, Layer, Context } from "effect"
-import type { SpanItem, TraceItem, TraceSummaryItem } from "../domain.js"
+import type { AiCallDetail, SpanItem, TraceItem, TraceSummaryItem } from "../domain.js"
 import { TelemetryStore } from "./TelemetryStore.js"
 
 export class TraceQueryService extends Context.Service<
@@ -14,6 +14,7 @@ export class TraceQueryService extends Context.Service<
 		readonly traceStats: (input: { readonly groupBy: string; readonly agg: "count" | "avg_duration" | "p95_duration" | "error_rate"; readonly serviceName?: string | null; readonly operation?: string | null; readonly status?: "ok" | "error" | null; readonly minDurationMs?: number | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly { readonly group: string; readonly value: number; readonly count: number }[], Error>
 		readonly getTrace: (traceId: string) => Effect.Effect<TraceItem | null, Error>
 		readonly getSpan: (spanId: string) => Effect.Effect<SpanItem | null, Error>
+		readonly getAiCall: (spanId: string) => Effect.Effect<AiCallDetail | null, Error>
 		readonly listTraceSpans: (traceId: string) => Effect.Effect<readonly SpanItem[], Error>
 		readonly searchSpans: (input: { readonly serviceName?: string | null; readonly operation?: string | null; readonly parentOperation?: string | null; readonly status?: "ok" | "error" | null; readonly lookbackMinutes?: number; readonly limit?: number; readonly attributeFilters?: Readonly<Record<string, string>> }) => Effect.Effect<readonly SpanItem[], Error>
 	}
@@ -68,6 +69,7 @@ export const TraceQueryServiceLive = Layer.effect(
 			traceStats: store.traceStats,
 			getTrace,
 			getSpan,
+			getAiCall: store.getAiCall,
 			listTraceSpans: store.listTraceSpans,
 			searchSpans: store.searchSpans,
 		})

package/src/services/ingestRpc.ts

@@ -0,0 +1,41 @@
+/**
+ * RPC contract for OTLP ingest. Lives in its own file so both the
+ * main thread (client) and the telemetry worker (server) can import
+ * the schema without pulling in each other's runtime code.
+ *
+ * Only ingestTraces and ingestLogs run through RPC — those are the
+ * methods whose SQLite writes used to block the main event loop for
+ * seconds at a time. Every other TelemetryStore method stays on the
+ * main thread with its own direct DB connection; SQLite's WAL mode
+ * lets the reader (main) and writer (worker) hold independent
+ * connections to the same file concurrently without contention.
+ *
+ * Payloads are typed as Schema.Unknown because OTLP's protobuf-JSON
+ * shape is enormous and nested — the store validates structurally
+ * during the actual insert loop, and serialising a schema through
+ * the worker boundary would add overhead that beats the purpose of
+ * the offload. If a payload is malformed we surface it as an
+ * IngestError rather than a RpcSchemaError, which keeps the failure
+ * mode consistent with the old direct-call behaviour.
+ */
+
+import { Schema } from "effect"
+import * as Rpc from "effect/unstable/rpc/Rpc"
+import * as RpcGroup from "effect/unstable/rpc/RpcGroup"
+
+export class IngestError extends Schema.TaggedErrorClass<IngestError>()("IngestError", {
+	message: Schema.String,
+}) {}
+
+export const IngestRpcs = RpcGroup.make(
+	Rpc.make("ingestTraces", {
+		payload: { payload: Schema.Unknown },
+		success: Schema.Struct({ insertedSpans: Schema.Number }),
+		error: IngestError,
+	}),
+	Rpc.make("ingestLogs", {
+		payload: { payload: Schema.Unknown },
+		success: Schema.Struct({ insertedLogs: Schema.Number }),
+		error: IngestError,
+	}),
+)

package/src/services/telemetryWorker.ts

@@ -0,0 +1,62 @@
+/**
+ * Worker-thread entry point for OTLP ingest.
+ *
+ * Spawned by the main process via `new Worker(new URL("./telemetryWorker.ts", import.meta.url))`.
+ * This file runs inside a Bun Worker, so anything it imports is
+ * evaluated in a FRESH module graph on the worker side. In particular
+ * `TelemetryStoreWorkerLive` opens its own SQLite connection here — the main
+ * thread's store connection is unrelated. SQLite's WAL journal mode
+ * lets both connections coexist against the same `.sqlite` file: the
+ * worker writes, the main thread reads, and neither blocks the other.
+ *
+ * The worker only exposes `ingestTraces` / `ingestLogs` (see
+ * ingestRpc.ts). Query methods stay on the main thread because they're
+ * already fast (1-14ms) and round-tripping them through structured-
+ * clone would add more overhead than it saves. This is a deliberately
+ * narrow interface — the payoff is that main-thread HTTP queries
+ * never queue behind a heavy OTLP batch again.
+ */
+
+import { BunRuntime } from "@effect/platform-bun"
+import * as BunWorkerRunner from "@effect/platform-bun/BunWorkerRunner"
+import { Effect, Layer } from "effect"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+import * as RpcServer from "effect/unstable/rpc/RpcServer"
+import type { OtlpLogExportRequest, OtlpTraceExportRequest } from "../otlp.ts"
+import { IngestError, IngestRpcs } from "./ingestRpc.ts"
+import { TelemetryStore, TelemetryStoreWorkerLive } from "./TelemetryStore.ts"
+
+// Wire the two RPC methods to the existing TelemetryStore service.
+// The store's ingest methods already carry their own Effect.fn spans,
+// so the worker-side traces show up correctly attributed — the RPC
+// framework also auto-spans each incoming request with method +
+// payload-size attributes, giving us visibility into how ingest is
+// splitting its time across the queue / wire / SQL stages.
+const IngestHandlers = IngestRpcs.toLayer(
+	Effect.gen(function*() {
+		const store = yield* TelemetryStore
+		return {
+			ingestTraces: ({ payload }) =>
+				store.ingestTraces(payload as OtlpTraceExportRequest).pipe(
+					Effect.mapError((cause) => new IngestError({ message: String(cause) })),
+				),
+			ingestLogs: ({ payload }) =>
+				store.ingestLogs(payload as OtlpLogExportRequest).pipe(
+					Effect.mapError((cause) => new IngestError({ message: String(cause) })),
+				),
+		}
+	}),
+)
+
+const WorkerLive = RpcServer.layer(IngestRpcs).pipe(
+	Layer.provide(IngestHandlers),
+	Layer.provide(TelemetryStoreWorkerLive),
+	Layer.provide(RpcServer.layerProtocolWorkerRunner),
+	Layer.provide(RpcSerialization.layerMsgPack),
+	Layer.provide(BunWorkerRunner.layer),
+)
+
+// BunRuntime.runMain installs signal handlers so the scope closes
+// cleanly on termination; the BunHttpServer layer pattern from the
+// main server carries over here.
+Layer.launch(WorkerLive).pipe(BunRuntime.runMain)