@kitlangton/motel 0.1.3 → 0.2.1

package/src/services/AsyncIngest.ts

@@ -0,0 +1,52 @@
+/**
+ * Main-thread client for the telemetry worker's ingest RPCs.
+ *
+ * The HTTP handlers for POST /v1/traces and POST /v1/logs call into
+ * this service instead of `TelemetryStore.ingestTraces/Logs`. Each
+ * method sends a typed message to the worker, awaits the reply, and
+ * returns the worker's result as an Effect. While the worker is
+ * serialising a big batch into SQLite, the main thread's event loop
+ * is FREE to answer /api/* queries — that's the whole point of the
+ * offload. Without this, /api/health and friends queued behind long
+ * ingests and reported p95 latencies of 3-5 seconds; after, they
+ * stay responsive regardless of ingest load.
+ *
+ * The worker is spawned as a scope'd resource inside the layer. The
+ * protocol pool is sized at 1 because SQLite only supports a single
+ * writer at a time anyway — running N concurrent workers would just
+ * queue them on SQLite's lock. When the outer scope closes (server
+ * shutdown), `BunWorker.layer`'s finalizer sends a close message and
+ * terminates the worker if it doesn't exit gracefully in 5s.
+ */
+
+import * as BunWorker from "@effect/platform-bun/BunWorker"
+import { Context, Layer } from "effect"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+import type { RpcClientError } from "effect/unstable/rpc/RpcClientError"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+import { IngestRpcs } from "./ingestRpc.ts"
+
+// RpcClient.make always surfaces RpcClientError in addition to the
+// group's declared errors (transport failures, worker crashes, etc.),
+// so the service shape has to mirror that. Without the explicit error
+// type param, TS treats the declared and observed client types as
+// unrelated structural mismatches.
+export class AsyncIngest extends Context.Service<
+	AsyncIngest,
+	RpcClient.FromGroup<typeof IngestRpcs, RpcClientError>
+>()("@motel/AsyncIngest") {}
+
+// Protocol: RpcClient.layerProtocolWorker manages a worker pool and
+// speaks msgpack over structured-clone messages. `size: 1` matches
+// SQLite's single-writer constraint.
+const WorkerProtocol = RpcClient.layerProtocolWorker({ size: 1 }).pipe(
+	Layer.provide(RpcSerialization.layerMsgPack),
+	Layer.provide(
+		BunWorker.layer(() => new Worker(new URL("./telemetryWorker.ts", import.meta.url))),
+	),
+)
+
+export const AsyncIngestLive = Layer.effect(
+	AsyncIngest,
+	RpcClient.make(IngestRpcs),
+).pipe(Layer.provide(WorkerProtocol))

package/src/services/TelemetryStore.ts

@@ -4,7 +4,7 @@ import { dirname } from "node:path"
 import { Clock, Effect, Layer, Schedule, Context } from "effect"
 import { config } from "../config.js"
 import type { AiCallDetail, AiCallSummary, FacetItem, LogItem, SpanItem, StatsItem, TraceItem, TraceSummaryItem, TraceSpanEvent, TraceSpanItem } from "../domain.js"
-import { AI_ATTR_MAP, AI_TEXT_SEARCH_KEYS, truncatePreview } from "../domain.js"
+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"
 
 interface SpanRow {
@@ -57,6 +57,13 @@ interface TraceSearch {
 	readonly status?: "ok" | "error" | null
 	readonly minDurationMs?: number | null
 	readonly attributeFilters?: Readonly<Record<string, string>>
+	/**
+	 * Full-text match against the AI prompt/response/tool attribute values
+	 * on any span in the trace (see AI_FTS_KEYS). When set, traces are
+	 * filtered to those containing at least one span whose indexed LLM
+	 * content matches. Powered by span_attr_fts (FTS5).
+	 */
+	readonly aiText?: string | null
 	readonly lookbackMinutes?: number
 	readonly limit?: number
 	readonly cursorStartedAtMs?: number
@@ -440,26 +447,74 @@ 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()
 			}),
 		)
+		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(`
 			PRAGMA journal_mode = WAL;
 			PRAGMA synchronous = NORMAL;
 			PRAGMA temp_store = MEMORY;
-			PRAGMA busy_timeout = 5000;
+			-- Longer busy timeout: the ingest worker holds the write lock
+			-- for up to a few seconds during big OTLP batches, and the main
+			-- daemon's retention passes can do the same. 15s gives either
+			-- side enough slack to serialise instead of erroring.
+			PRAGMA busy_timeout = 15000;
+			-- 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;
 			-- 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
@@ -549,8 +604,26 @@ export const TelemetryStoreLive = Layer.effect(
 			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);
 		`)
+		}
 
+		// 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(
@@ -571,6 +644,65 @@ export const TelemetryStoreLive = Layer.effect(
 			// FTS is optional; queries will fall back to LIKE if unavailable.
 		}
 
+		// External-content FTS5 over the subset of span_attributes.value rows
+		// whose key is in AI_FTS_KEYS (LLM prompts, responses, tool calls,
+		// etc.). External content means the inverted index is the only
+		// FTS storage — the value text itself continues to live once in
+		// span_attributes, not duplicated into the FTS table. On a 2 GB DB
+		// with 270 MB of prompt JSON this typically adds ~50-120 MB of
+		// index, turning a 500-800ms LIKE scan into a <50ms MATCH.
+		//
+		// 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).
+		if (hasFts) {
+			try {
+				const keyList = AI_FTS_KEYS.map((k) => `'${k.replace(/'/g, "''")}'`).join(", ")
+				db.exec(`
+					CREATE VIRTUAL TABLE IF NOT EXISTS span_attr_fts USING fts5(
+						value,
+						content='span_attributes',
+						content_rowid='rowid',
+						tokenize='unicode61 remove_diacritics 2'
+					);
+
+					-- Mirror inserts into FTS when the key carries LLM content.
+					-- NOTE: triggers MUST use fully-qualified name (new.rowid,
+					-- new.value) and emit rowid so external-content FTS can
+					-- fetch the value back via span_attributes.rowid.
+					CREATE TRIGGER IF NOT EXISTS span_attr_fts_ai AFTER INSERT ON span_attributes
+					WHEN new.key IN (${keyList})
+					BEGIN
+						INSERT INTO span_attr_fts(rowid, value) VALUES (new.rowid, new.value);
+					END;
+
+					-- Delete with the same guard so retention & re-ingest stay
+					-- in sync. External-content 'delete' command needs the
+					-- original value to remove from the inverted index.
+					CREATE TRIGGER IF NOT EXISTS span_attr_fts_ad AFTER DELETE ON span_attributes
+					WHEN old.key IN (${keyList})
+					BEGIN
+						INSERT INTO span_attr_fts(span_attr_fts, rowid, value)
+						VALUES ('delete', old.rowid, old.value);
+					END;
+
+					-- Handle in-place updates (rare; re-ingest usually goes
+					-- DELETE then INSERT but belt-and-braces).
+					CREATE TRIGGER IF NOT EXISTS span_attr_fts_au AFTER UPDATE ON span_attributes
+					WHEN old.key IN (${keyList}) OR new.key IN (${keyList})
+					BEGIN
+						INSERT INTO span_attr_fts(span_attr_fts, rowid, value)
+						VALUES ('delete', old.rowid, old.value);
+						INSERT INTO span_attr_fts(rowid, value)
+						SELECT new.rowid, new.value
+						WHERE new.key IN (${keyList});
+					END;
+				`)
+			} catch {
+				hasAttrFts = false
+			}
+		}
+
 		try {
 			db.exec(`ALTER TABLE trace_summaries ADD COLUMN active_span_count INTEGER NOT NULL DEFAULT 0`)
 		} catch {
@@ -594,6 +726,7 @@ export const TelemetryStoreLive = Layer.effect(
 			// ANALYZE / optimize failures are never fatal — queries still work,
 			// they just run with default row estimates.
 		}
+		} // end: if (!opts.readonly) writer init
 
 		const insertSpan = db.query(`
 			INSERT INTO spans (
@@ -641,8 +774,14 @@ export const TelemetryStoreLive = Layer.effect(
 			GROUP BY trace_id
 		`)
 
-		db.query(`DELETE FROM trace_summaries`).run()
-		rebuildTraceSummaries.run()
+		// One-time full rebuild of the trace_summaries table at open so
+		// any drift from interrupted ingests gets reconciled. Writer-only
+		// because the DELETE + INSERT would fail on a readonly connection
+		// (and would fight the daemon's writer for the lock anyway).
+		if (!opts.readonly) {
+			db.query(`DELETE FROM trace_summaries`).run()
+			rebuildTraceSummaries.run()
+		}
 
 		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 (?, ?, ?, ?)`)
@@ -725,21 +864,79 @@ 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")))
+		// 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) {
+			// 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")))
+		}
 
-		// 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. 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
+					if (ftsCount > 0) return
+					const keyList = AI_FTS_KEYS.map((k) => `'${k.replace(/'/g, "''")}'`).join(", ")
+					const attrCount = (db.query(
+						`SELECT COUNT(*) AS c FROM span_attributes WHERE key IN (${keyList})`,
+					).get() as { c: number }).c
+					if (attrCount === 0) return
+					// Single INSERT..SELECT is atomic and fast; FTS5 batches
+					// its internal segment writes. No transaction wrapper
+					// needed — it runs as one statement.
+					db.exec(`
+						INSERT INTO span_attr_fts(rowid, value)
+						SELECT rowid, value FROM span_attributes WHERE key IN (${keyList})
+					`)
+				} catch {
+					// Backfill failure is never fatal — new ingests still
+					// populate FTS via the trigger, and queries fall back to
+					// LIKE when FTS lookups return empty.
+				}
+			})
+			yield* Effect.forkScoped(backfillAttrFts)
+		}
 
 		const ingestTraces = Effect.fn("motel/TelemetryStore.ingestTraces")(function* (payload: OtlpTraceExportRequest) {
 			return yield* Effect.sync(() => {
@@ -965,6 +1162,25 @@ export const TelemetryStoreLive = Layer.effect(
 					params.push(...exactAttrMatch.params)
 				}
 
+				// `:ai <query>` — FTS match against LLM content keys. Joins
+				// span_attr_fts back to span_attributes to collect trace_ids
+				// whose spans carry matching prompt/response content. Falls
+				// through to no-op when the query tokenizes empty (e.g. only
+				// stopwords or operator-chars) so users don't get a silently
+				// empty list.
+				if (input.aiText) {
+					const aiFtsQuery = toFtsMatchQuery(input.aiText)
+					if (hasAttrFts && aiFtsQuery) {
+						clauses.push(`trace_id IN (
+							SELECT DISTINCT sa.trace_id
+							FROM span_attr_fts fts
+							JOIN span_attributes sa ON sa.rowid = fts.rowid
+							WHERE fts.value MATCH ?
+						)`)
+						params.push(aiFtsQuery)
+					}
+				}
+
 				const rows = db.query(`
 					SELECT trace_id, service_name, root_operation_name, started_at_ms, ended_at_ms, active_span_count, duration_ms, span_count, error_count
 					FROM trace_summaries
@@ -1588,7 +1804,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) {
@@ -1624,11 +1844,27 @@ export const TelemetryStoreLive = Layer.effect(
 				params.push(key, value)
 			}
 
-			// Text search across prompt/response/tool attribute values
+			// Text search across prompt/response/tool attribute values via
+			// FTS5. Prefers the external-content span_attr_fts index when
+			// available, falls back to case-insensitive LIKE so old DBs
+			// without FTS still work. FTS turns ~500ms full scans of 3 MB
+			// prompt JSON into <50ms MATCH lookups.
 			if ("text" in input && input.text) {
-				const textKeys = AI_TEXT_SEARCH_KEYS.map(() => "?").join(", ")
-				clauses.push(`EXISTS (SELECT 1 FROM span_attributes WHERE span_attributes.trace_id = s.trace_id AND span_attributes.span_id = s.span_id AND key IN (${textKeys}) AND value LIKE ? COLLATE NOCASE)`)
-				params.push(...AI_TEXT_SEARCH_KEYS, `%${input.text}%`)
+				const ftsQuery = toFtsMatchQuery(input.text)
+				if (hasAttrFts && ftsQuery) {
+					clauses.push(`EXISTS (
+						SELECT 1 FROM span_attr_fts fts
+						JOIN span_attributes sa ON sa.rowid = fts.rowid
+						WHERE sa.trace_id = s.trace_id
+						AND sa.span_id = s.span_id
+						AND fts.value MATCH ?
+					)`)
+					params.push(ftsQuery)
+				} else {
+					const textKeys = AI_TEXT_SEARCH_KEYS.map(() => "?").join(", ")
+					clauses.push(`EXISTS (SELECT 1 FROM span_attributes WHERE span_attributes.trace_id = s.trace_id AND span_attributes.span_id = s.span_id AND key IN (${textKeys}) AND value LIKE ? COLLATE NOCASE)`)
+					params.push(...AI_TEXT_SEARCH_KEYS, `%${input.text}%`)
+				}
 			}
 
 			return { clauses, params }
@@ -1961,3 +2197,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<
@@ -8,12 +8,13 @@ export class TraceQueryService extends Context.Service<
 		readonly listServices: Effect.Effect<readonly string[], Error>
 		readonly listRecentTraces: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly TraceItem[], Error>
 		readonly listTraceSummaries: (serviceName: string, options?: { readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly TraceSummaryItem[], Error>
-		readonly searchTraceSummaries: (input: { 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 TraceSummaryItem[], Error>
+		readonly searchTraceSummaries: (input: { 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>>; readonly aiText?: string | null }) => Effect.Effect<readonly TraceSummaryItem[], Error>
 		readonly listFacets: (input: { readonly type: "traces" | "logs"; readonly field: string; readonly serviceName?: string | null; readonly key?: string | null; readonly lookbackMinutes?: number; readonly limit?: number }) => Effect.Effect<readonly { readonly value: string; readonly count: number }[], Error>
 		readonly searchTraces: (input: { 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 TraceItem[], Error>
 		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)