@aryasaatvik/motel 0.3.4 → 0.4.0

package/src/services/ingestRpc.ts

@@ -27,12 +27,12 @@ export class IngestError extends Schema.TaggedError<IngestError>()("IngestError"
 
 export const IngestRpcs = RpcGroup.make(
 	Rpc.make("ingestTraces", {
-		payload: { payload: Schema.Unknown },
+		payload: { payload: Schema.Unknown, bytes: Schema.optionalKey(Schema.Number) },
 		success: Schema.Struct({ insertedSpans: Schema.Number }),
 		error: IngestError,
 	}),
 	Rpc.make("ingestLogs", {
-		payload: { payload: Schema.Unknown },
+		payload: { payload: Schema.Unknown, bytes: Schema.optionalKey(Schema.Number) },
 		success: Schema.Struct({ insertedLogs: Schema.Number }),
 		error: IngestError,
 	}),

package/src/services/queryRpc.ts

@@ -1,15 +1,15 @@
 import { Schema } from "effect"
-import * as Rpc from "effect/unstable/rpc/Rpc"
-import * as RpcGroup from "effect/unstable/rpc/RpcGroup"
 
-export class QueryError extends Schema.TaggedError<QueryError>()("QueryError", {
-	message: Schema.String,
-}) {}
+export class QueryError extends Schema.TaggedError<QueryError>()("QueryError", { message: Schema.String }) {}
+export class QueryOverloaded extends Schema.TaggedError<QueryOverloaded>()("QueryOverloaded", { message: Schema.String }) {}
+export class QueryDeadlineExceeded extends Schema.TaggedError<QueryDeadlineExceeded>()("QueryDeadlineExceeded", { message: Schema.String }) {}
+export class QueryUnavailable extends Schema.TaggedError<QueryUnavailable>()("QueryUnavailable", { message: Schema.String }) {}
 
-export const QueryRpcs = RpcGroup.make(
-	Rpc.make("query", {
-		payload: { method: Schema.String, args: Schema.Array(Schema.Unknown) },
-		success: Schema.Any,
-		error: QueryError,
-	}),
-)
+export const QueryRequest = Schema.Struct({ id: Schema.Int, method: Schema.String, args: Schema.Array(Schema.Unknown) })
+export const QueryReply = Schema.TaggedUnion({
+	ready: {},
+	result: { id: Schema.Int, value: Schema.Unknown },
+	error: { id: Schema.Int, message: Schema.String },
+})
+export type QueryRequest = typeof QueryRequest.Type
+export type QueryReply = typeof QueryReply.Type

package/src/services/queryScheduler.test.ts

@@ -0,0 +1,102 @@
+import { Database } from "bun:sqlite"
+import { expect, test } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { QueryScheduler } from "./queryScheduler.ts"
+import { QueryDeadlineExceeded, QueryOverloaded, QueryUnavailable } from "./queryRpc.ts"
+import { checkpointPassive } from "./retention.ts"
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+const fixture = (capacity = 2, deadlineMs = 800) => {
+	const root = mkdtempSync(join(tmpdir(), "motel-query-cancel-"))
+	const path = join(root, "db.sqlite")
+	const events = join(root, "events")
+	writeFileSync(events, "")
+	const db = new Database(path)
+	db.exec("PRAGMA journal_mode=WAL; CREATE TABLE t(x); INSERT INTO t VALUES(1); PRAGMA wal_checkpoint(PASSIVE)")
+	const worker = join(root, "readonly worker.ts")
+	writeFileSync(worker, `
+import { Database } from "bun:sqlite"
+import { appendFileSync } from "node:fs"
+const db = new Database(${JSON.stringify(path)}, { readonly: true })
+process.on("message", request => {
+ appendFileSync(${JSON.stringify(events)}, request.method + "\\n")
+ if (request.method === "slow") {
+  db.exec("BEGIN")
+  db.query("SELECT * FROM t").all()
+  appendFileSync(${JSON.stringify(events)}, "reader-held\\n")
+  db.query("WITH RECURSIVE n(x) AS (VALUES(0) UNION ALL SELECT x+1 FROM n WHERE x<1000000000) SELECT sum(x) FROM n").get()
+ }
+ process.send({_tag:"result", id:request.id, value:db.query("SELECT count(*) AS n FROM t").get()})
+})
+process.send({_tag:"ready"})
+`)
+	const scheduler = new QueryScheduler({ workerUrl: pathToFileURL(worker), capacity, deadlineMs })
+	const held = async () => {
+		for (let i = 0; i < 100 && !readFileSync(events, "utf8").includes("reader-held"); i++) await sleep(5)
+		expect(readFileSync(events, "utf8")).toContain("reader-held")
+	}
+	return { scheduler, db, held, events: () => readFileSync(events, "utf8"), close: async () => { await scheduler.close(); db.close(); rmSync(root, { recursive: true, force: true }) } }
+}
+
+test("deadline stops executing SQLite, releases its reader, and allows the next useful query", async () => {
+	const f = fixture()
+	try {
+		const slow = f.scheduler.query("slow", [], new AbortController().signal).catch((error) => error)
+		await f.held()
+		f.db.exec("INSERT INTO t VALUES(2)")
+		expect(checkpointPassive(f.db).deferred).toBe(true)
+		await sleep(200)
+		const next = f.scheduler.query("short", [], new AbortController().signal)
+		await expect(f.scheduler.query("overflow", [], new AbortController().signal)).rejects.toBeInstanceOf(QueryOverloaded)
+		expect(await slow).toBeInstanceOf(QueryDeadlineExceeded)
+		expect(checkpointPassive(f.db).deferred).toBe(false)
+		expect(await next).toEqual({ n: 2 })
+		expect(f.events()).not.toContain("overflow")
+	} finally { await f.close() }
+}, 5000)
+
+test("cancelling queued work prevents dispatch without interrupting the current reader", async () => {
+	const f = fixture()
+	try {
+		const active = new AbortController()
+		const slow = f.scheduler.query("slow", [], active.signal).catch((error) => error)
+		await f.held()
+		const queued = new AbortController()
+		const obsolete = f.scheduler.query("obsolete", [], queued.signal).catch((error) => error)
+		queued.abort()
+		expect(await obsolete).toBeInstanceOf(QueryUnavailable)
+		f.db.exec("INSERT INTO t VALUES(2)")
+		expect(checkpointPassive(f.db).deferred).toBe(true)
+		active.abort()
+		expect(await slow).toBeInstanceOf(QueryUnavailable)
+		expect(checkpointPassive(f.db).deferred).toBe(false)
+		expect(await f.scheduler.query("short", [], new AbortController().signal)).toEqual({ n: 2 })
+		expect(f.events()).not.toContain("obsolete")
+	} finally { await f.close() }
+}, 5000)
+
+test("expired queued requests are removed before a replacement process can dispatch them", async () => {
+	const f = fixture(4, 400)
+	try {
+		const queries = ["slow", "expired-one", "expired-two", "expired-three"].map((method) => f.scheduler.query(method, [], new AbortController().signal).catch((error) => error))
+		const results = await Promise.all(queries)
+		for (const result of results) expect(result).toBeInstanceOf(QueryDeadlineExceeded)
+		expect(f.events()).not.toContain("expired-")
+		expect(await f.scheduler.query("short", [], new AbortController().signal)).toEqual({ n: 1 })
+	} finally { await f.close() }
+}, 5000)
+
+
+test("query processes receive the explicit runtime environment", async () => {
+	const root = mkdtempSync(join(tmpdir(), "motel-query-env-"))
+	const worker = join(root, "environment.ts")
+	writeFileSync(worker, `process.on("message", request => process.send({_tag:"result", id:request.id, value:process.env.MOTEL_OTEL_DB_PATH})); process.send({_tag:"ready"})`)
+	const databasePath = join(root, "isolated.sqlite")
+	const scheduler = new QueryScheduler({ workerUrl: pathToFileURL(worker), capacity: 1, deadlineMs: 2000, environment: { ...process.env, MOTEL_OTEL_DB_PATH: databasePath } })
+	try {
+		expect(await scheduler.query("path", [], new AbortController().signal)).toBe(databasePath)
+	} finally { await scheduler.close(); rmSync(root, { recursive: true, force: true }) }
+})

package/src/services/queryScheduler.ts

@@ -0,0 +1,157 @@
+import { fileURLToPath } from "node:url"
+import { Schema } from "effect"
+import { QueryDeadlineExceeded, QueryError, QueryOverloaded, QueryReply, QueryUnavailable, type QueryRequest } from "./queryRpc.js"
+
+type Pending = {
+	readonly request: QueryRequest
+	readonly resolve: (value: unknown) => void
+	readonly reject: (error: Error) => void
+	readonly signal: AbortSignal
+	timer?: ReturnType<typeof setTimeout>
+	onAbort?: () => void
+	cancelled?: Error
+	generation?: QueryProcess
+}
+
+/** One readonly process. SIGKILL is required to interrupt synchronous SQLite native code. */
+class QueryProcess {
+	readonly child: ReturnType<typeof Bun.spawn>
+	readonly ready: Promise<void>
+	closed = false
+	private stopping?: Promise<void>
+	private call?: { id: number; resolve: (value: unknown) => void; reject: (error: Error) => void }
+
+	constructor(workerUrl: URL, environment: NodeJS.ProcessEnv) {
+		const ready = Promise.withResolvers<void>()
+		this.ready = ready.promise
+		// A process may exit between requests; keep its bootstrap rejection observed.
+		void this.ready.catch(() => {})
+		this.child = Bun.spawn([process.execPath, fileURLToPath(workerUrl)], {
+			stdin: "ignore", stdout: "ignore", stderr: "inherit",
+			env: environment,
+			serialization: "advanced",
+			ipc: (data: unknown) => {
+				let reply: QueryReply
+				try { reply = Schema.decodeUnknownSync(QueryReply)(data) }
+				catch {
+					ready.reject(new QueryUnavailable({ message: "Invalid reply from query process" }))
+					void this.stop()
+					return
+				}
+				if (this.closed) return
+				if (reply._tag === "ready") { ready.resolve(); return }
+				if (this.call?.id !== reply.id) return
+				const call = this.call
+				this.call = undefined
+				if (reply._tag === "result") call.resolve(reply.value)
+				else call.reject(new QueryError({ message: reply.message }))
+			},
+			onExit: () => {
+				this.closed = true
+				const error = new QueryUnavailable({ message: "Readonly query process exited" })
+				ready.reject(error)
+				this.call?.reject(error)
+				this.call = undefined
+			},
+		})
+	}
+
+	request(request: QueryRequest) {
+		return new Promise<unknown>((resolve, reject) => {
+			if (this.closed) { reject(new QueryUnavailable({ message: "Readonly query process is closed" })); return }
+			this.call = { id: request.id, resolve, reject }
+			try { this.child.send(request) }
+			catch (error) { this.call = undefined; reject(new QueryUnavailable({ message: String(error) })) }
+		})
+	}
+
+	stop(): Promise<void> {
+		return this.stopping ??= (async () => {
+			this.closed = true
+			this.child.kill("SIGKILL")
+			await this.child.exited
+		})()
+	}
+}
+
+/** FIFO admission includes startup and queue time in each request's deadline. */
+export class QueryScheduler {
+	private readonly queued: Pending[] = []
+	private readonly outstanding = new Set<Pending>()
+	private active?: Pending
+	private generation?: QueryProcess
+	private nextId = 0
+	private closed = false
+
+	constructor(private readonly options: { workerUrl: URL; capacity: number; deadlineMs: number; environment?: NodeJS.ProcessEnv }) {}
+
+	query(method: string, args: readonly unknown[], signal: AbortSignal): Promise<unknown> {
+		if (this.closed) return Promise.reject(new QueryUnavailable({ message: "Query scheduler is closed" }))
+		if (signal.aborted) return Promise.reject(new QueryUnavailable({ message: "Query cancelled before admission" }))
+		if (this.outstanding.size >= this.options.capacity) return Promise.reject(new QueryOverloaded({ message: "Readonly query capacity is exhausted; retry later" }))
+		return new Promise((resolve, reject) => {
+			const entry: Pending = { request: { id: ++this.nextId, method, args }, resolve, reject, signal }
+			entry.onAbort = () => this.cancel(entry, new QueryUnavailable({ message: "Query cancelled by caller" }))
+			entry.timer = setTimeout(() => this.cancel(entry, new QueryDeadlineExceeded({ message: `Query exceeded its ${this.options.deadlineMs} ms budget` })), this.options.deadlineMs)
+			signal.addEventListener("abort", entry.onAbort, { once: true })
+			this.outstanding.add(entry)
+			this.queued.push(entry)
+			this.pump()
+		})
+	}
+
+	private finish(entry: Pending) {
+		clearTimeout(entry.timer)
+		if (entry.onAbort) entry.signal.removeEventListener("abort", entry.onAbort)
+		this.outstanding.delete(entry)
+	}
+
+	private cancel(entry: Pending, error: Error) {
+		if (!this.outstanding.has(entry) || entry.cancelled) return
+		entry.cancelled = error
+		if (this.active === entry) {
+			// Do not release admission or report a deadline until the OS has closed the
+			// process, including its SQLite connection and any retained WAL snapshot.
+			void entry.generation?.stop()
+		} else {
+			const index = this.queued.indexOf(entry)
+			if (index !== -1) this.queued.splice(index, 1)
+			this.finish(entry)
+			entry.reject(error)
+		}
+	}
+
+	private pump() {
+		if (this.active || this.closed) return
+		const entry = this.queued.shift()
+		if (!entry) return
+		this.active = entry
+		void this.execute(entry)
+	}
+
+	private async execute(entry: Pending) {
+		try {
+			const generation = this.generation && !this.generation.closed ? this.generation : new QueryProcess(this.options.workerUrl, this.options.environment ?? { ...process.env })
+			this.generation = generation
+			entry.generation = generation
+			await generation.ready
+			if (entry.cancelled) throw entry.cancelled
+			const value = await generation.request(entry.request)
+			if (entry.cancelled) throw entry.cancelled
+			entry.resolve(value)
+		} catch (error) {
+			if (entry.cancelled) await entry.generation?.stop()
+			entry.reject(entry.cancelled ?? (error instanceof Error ? error : new QueryUnavailable({ message: String(error) })))
+		} finally {
+			this.finish(entry)
+			this.active = undefined
+			this.pump()
+		}
+	}
+
+	async close() {
+		this.closed = true
+		for (const entry of [...this.outstanding]) this.cancel(entry, new QueryUnavailable({ message: "Query scheduler is closing" }))
+		await this.generation?.stop()
+	}
+}

package/src/services/retention.test.ts

@@ -0,0 +1,170 @@
+import { Database } from "bun:sqlite"
+import { expect, test } from "bun:test"
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { checkpointPassive, installRetentionSchema, mergeFts, repairSearchRows, retainBatch } from "./retention.ts"
+
+const schema = (db: Database) => {
+	db.exec(`PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 15000;
+		CREATE TABLE spans(trace_id TEXT, span_id TEXT, start_time_ms INTEGER DEFAULT 1, end_time_ms INTEGER DEFAULT 2, PRIMARY KEY(trace_id, span_id));
+		CREATE TABLE span_attributes(trace_id TEXT, span_id TEXT, key TEXT, value TEXT);
+		CREATE INDEX attrs_trace ON span_attributes(trace_id);
+		CREATE TABLE trace_summaries(trace_id TEXT PRIMARY KEY, started_at_ms INTEGER, ended_at_ms INTEGER, active_span_count INTEGER);
+		CREATE TABLE logs(id INTEGER PRIMARY KEY, trace_id TEXT, timestamp_ms INTEGER, severity_text TEXT);
+		CREATE INDEX logs_trace ON logs(trace_id);
+		CREATE TABLE log_attributes(log_id INTEGER, key TEXT, value TEXT);
+		CREATE INDEX attrs_log ON log_attributes(log_id);
+		CREATE TABLE motel_maintenance(key TEXT PRIMARY KEY, value TEXT);
+		CREATE VIRTUAL TABLE span_operation_fts USING fts5(trace_id UNINDEXED, span_id UNINDEXED, operation_name);
+		CREATE VIRTUAL TABLE log_body_fts USING fts5(log_id UNINDEXED, body);
+	`)
+	installRetentionSchema(db)
+}
+const options = { cutoff: 100, maxBytes: Number.MAX_SAFE_INTEGER, traces: 10, logs: 10, rows: 24 }
+const count = (db: Database, table: string) => (db.query(`SELECT count(*) AS n FROM ${table}`).get() as { n: number }).n
+
+test("huge traces disappear atomically, drain by rows, survive reopen, and preserve active traces", () => {
+	const root = mkdtempSync(join(tmpdir(), "motel-retention-"))
+	const path = join(root, "test.sqlite")
+	let db = new Database(path)
+	try {
+		schema(db)
+		db.exec("INSERT INTO trace_summaries VALUES ('large', 1, 2, 0), ('active', 1, 0, 1), ('boundary', 1, 100, 0)")
+		db.transaction(() => {
+			for (let index = 0; index < 200; index++) {
+				db.query("INSERT INTO spans(trace_id, span_id) VALUES ('large', ?)").run(String(index))
+				for (let attr = 0; attr < 4; attr++) db.query("INSERT INTO span_attributes VALUES ('large', ?, ?, 'value')").run(String(index), String(attr))
+			}
+			db.exec("INSERT INTO spans(trace_id, span_id) VALUES ('active','a'), ('boundary','b'); INSERT INTO logs VALUES (1, 'large', 1000, 'INFO'); INSERT INTO log_attributes VALUES (1,'key','value')")
+		})()
+		const result = retainBatch(db, options)
+		expect(result.rows).toBeLessThanOrEqual(options.rows)
+		expect(count(db, "spans")).toBe(202)
+		expect(count(db, "retained_spans")).toBe(2)
+		expect(count(db, "retained_trace_summaries")).toBe(2)
+		expect(count(db, "retained_logs")).toBe(0)
+		db.close()
+		db = new Database(path)
+		expect(count(db, "retention_traces")).toBe(1)
+		let passes = 0
+		while (count(db, "retention_traces") > 0 && passes++ < 200) {
+			expect(retainBatch(db, options).rows).toBeLessThanOrEqual(options.rows)
+			expect(count(db, "retained_spans")).toBe(2)
+		}
+		expect(passes).toBeLessThan(200)
+		expect(count(db, "spans")).toBe(2)
+		expect(count(db, "span_attributes")).toBe(0)
+		expect(count(db, "logs")).toBe(0)
+		expect(count(db, "log_attributes")).toBe(0)
+	} finally { db.close(); rmSync(root, { recursive: true, force: true }) }
+})
+
+test("failed cleanup rolls back its visibility marker and rows", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		db.exec(`INSERT INTO trace_summaries VALUES ('trace',1,2,0); INSERT INTO spans(trace_id, span_id) VALUES ('trace','span');
+			INSERT INTO span_attributes VALUES ('trace','span','key','value');
+			CREATE TRIGGER fail_delete BEFORE DELETE ON span_attributes BEGIN SELECT RAISE(ABORT, 'injected failure'); END;`)
+		expect(() => retainBatch(db, options)).toThrow("injected failure")
+		expect(count(db, "retention_traces")).toBe(0)
+		expect(count(db, "retained_spans")).toBe(1)
+		expect(count(db, "span_attributes")).toBe(1)
+		db.exec("DROP TRIGGER fail_delete")
+		retainBatch(db, options)
+		expect(count(db, "retained_spans")).toBe(0)
+	} finally { db.close() }
+})
+
+test("PASSIVE reports an incomplete checkpoint without waiting for a held reader", () => {
+	const root = mkdtempSync(join(tmpdir(), "motel-checkpoint-"))
+	const path = join(root, "test.sqlite")
+	const writer = new Database(path)
+	let reader: Database | undefined
+	try {
+		schema(writer)
+		checkpointPassive(writer)
+		reader = new Database(path, { readonly: true })
+		reader.exec("BEGIN")
+		reader.query("SELECT * FROM spans").all()
+		writer.exec("INSERT INTO spans(trace_id, span_id) VALUES ('trace','span')")
+		const start = performance.now()
+		const result = checkpointPassive(writer)
+		expect(performance.now() - start).toBeLessThan(500)
+		expect(result.deferred).toBe(true)
+		expect(result.log).toBeGreaterThan(result.checkpointed)
+		reader.exec("ROLLBACK")
+		expect(checkpointPassive(writer).deferred).toBe(false)
+	} finally { reader?.close(); writer.close(); rmSync(root, { recursive: true, force: true }) }
+})
+
+test("explicit FTS merging consolidates segments and preserves search results", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		db.exec("INSERT INTO log_body_fts(log_body_fts, rank) VALUES ('automerge', 0); INSERT INTO log_body_fts(log_body_fts, rank) VALUES ('crisismerge', 1000)")
+		for (let index = 0; index < 40; index++) db.query("INSERT INTO log_body_fts(log_id, body) VALUES (?, 'searchable token')").run(String(index))
+		const before = count(db, "log_body_fts_idx")
+		mergeFts(db, 100)
+		expect(count(db, "log_body_fts_idx")).toBeLessThan(before)
+		expect((db.query("SELECT count(*) AS n FROM log_body_fts WHERE log_body_fts MATCH 'searchable'").get() as { n: number }).n).toBe(40)
+		db.exec("DROP TABLE log_body_fts; CREATE TABLE log_body_fts(broken TEXT)")
+		expect(() => mergeFts(db, 100)).toThrow()
+	} finally { db.close() }
+})
+
+test("legacy orphan repair advances a bounded cursor and maps live FTS rowids", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		for (let index = 1; index <= 20; index++) {
+			db.query("INSERT INTO logs VALUES (?,NULL,1000,'INFO')").run(index)
+			db.query("INSERT INTO log_attributes VALUES (?,'key','value')").run(index)
+			db.query("INSERT INTO log_body_fts(log_id,body) VALUES (?,'searchable')").run(String(index))
+		}
+		db.exec("INSERT INTO log_attributes VALUES (999,'orphan','value'); INSERT INTO log_body_fts(log_id,body) VALUES ('999','orphan')")
+		repairSearchRows(db, 5)
+		expect(count(db, "log_search_rows")).toBe(5)
+		expect(count(db, "log_attributes")).toBe(21)
+		for (let pass = 0; pass < 5; pass++) repairSearchRows(db, 5)
+		expect(count(db, "log_attributes")).toBe(20)
+		expect(count(db, "log_body_fts")).toBe(20)
+		expect(count(db, "log_search_rows")).toBe(20)
+		const before = db.query("SELECT total_changes() AS n").get() as { n: number }
+		for (let pass = 0; pass < 5; pass++) repairSearchRows(db, 5)
+		expect(db.query("SELECT total_changes() AS n").get()).toEqual(before)
+		const expired = retainBatch(db, { ...options, cutoff: 2000, logs: 1, rows: 100 })
+		expect(expired.markedLogs).toBe(1)
+		expect(count(db, "logs")).toBe(19)
+		expect(count(db, "log_body_fts")).toBe(19)
+	} finally { db.close() }
+})
+
+test("retention selectors use ordered partial indexes", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		const plan = db.query("EXPLAIN QUERY PLAN SELECT trace_id FROM trace_summaries WHERE active_span_count = 0 AND ended_at_ms > 0 AND ended_at_ms < ? ORDER BY ended_at_ms, trace_id LIMIT 100").all(100) as { detail: string }[]
+		expect(plan.some(({ detail }) => detail.includes("idx_retention_ended"))).toBe(true)
+		expect(plan.some(({ detail }) => detail.includes("TEMP B-TREE"))).toBe(false)
+	} finally { db.close() }
+})
+
+
+test("stale upgraded summaries cannot evict active spans under age or size retention", () => {
+	for (const maxBytes of [Number.MAX_SAFE_INTEGER, 0]) {
+		const db = new Database(":memory:")
+		try {
+			schema(db)
+			db.exec("INSERT INTO trace_summaries VALUES ('stale', 1, 2, 0)")
+			db.exec("INSERT INTO spans(trace_id,span_id,start_time_ms,end_time_ms) VALUES ('stale','running',1,0)")
+			retainBatch(db, { ...options, maxBytes })
+			expect(count(db, "retained_spans")).toBe(1)
+			expect(count(db, "retention_traces")).toBe(0)
+			db.exec("UPDATE spans SET end_time_ms = 2")
+			retainBatch(db, { ...options, maxBytes })
+			expect(count(db, "retained_spans")).toBe(0)
+		} finally { db.close() }
+	}
+})

package/src/services/retention.ts

@@ -0,0 +1,158 @@
+import type { Database } from "bun:sqlite"
+
+/** Additive schema: unfinished eviction is hidden from every public query. */
+export const installRetentionSchema = (db: Database) => {
+	db.exec(`
+		CREATE INDEX IF NOT EXISTS idx_retention_active_spans ON spans(trace_id) WHERE end_time_ms <= 0 OR end_time_ms < start_time_ms;
+		CREATE INDEX IF NOT EXISTS idx_retention_ended ON trace_summaries(ended_at_ms, trace_id) WHERE active_span_count = 0 AND ended_at_ms > 0;
+		CREATE INDEX IF NOT EXISTS idx_retention_started ON trace_summaries(started_at_ms, trace_id) WHERE active_span_count = 0;
+		CREATE INDEX IF NOT EXISTS idx_logs_severity_nocase_cursor ON logs(severity_text COLLATE NOCASE, timestamp_ms DESC, id DESC);
+		CREATE INDEX IF NOT EXISTS idx_logs_timestamp ON logs(timestamp_ms, id);
+		CREATE TABLE IF NOT EXISTS retention_traces (trace_id TEXT PRIMARY KEY);
+		CREATE TABLE IF NOT EXISTS retention_logs (id INTEGER PRIMARY KEY);
+		CREATE TABLE IF NOT EXISTS span_search_rows (id INTEGER PRIMARY KEY, trace_id TEXT NOT NULL, span_id TEXT NOT NULL);
+		CREATE INDEX IF NOT EXISTS idx_span_search_identity ON span_search_rows(trace_id, span_id);
+		CREATE TABLE IF NOT EXISTS log_search_rows (id INTEGER PRIMARY KEY, log_id INTEGER NOT NULL);
+		CREATE INDEX IF NOT EXISTS idx_log_search_identity ON log_search_rows(log_id);
+		CREATE VIEW IF NOT EXISTS retained_spans AS SELECT spans.rowid AS rowid, spans.* FROM spans
+			WHERE NOT EXISTS (SELECT 1 FROM retention_traces d WHERE d.trace_id = spans.trace_id);
+		CREATE VIEW IF NOT EXISTS retained_trace_summaries AS SELECT * FROM trace_summaries
+			WHERE NOT EXISTS (SELECT 1 FROM retention_traces d WHERE d.trace_id = trace_summaries.trace_id);
+		CREATE VIEW IF NOT EXISTS retained_logs AS SELECT * FROM logs
+			WHERE NOT EXISTS (SELECT 1 FROM retention_traces d WHERE d.trace_id = logs.trace_id)
+			AND NOT EXISTS (SELECT 1 FROM retention_logs d WHERE d.id = logs.id);
+	`)
+}
+
+export type Checkpoint = { busy: number; log: number; checkpointed: number; deferred: boolean }
+
+/** PASSIVE never waits for a reader to release its WAL snapshot. */
+export const checkpointPassive = (db: Database): Checkpoint => {
+	const result = db.query("PRAGMA wal_checkpoint(PASSIVE)").get() as { busy: number; log: number; checkpointed: number }
+	return { ...result, deferred: result.busy !== 0 || result.checkpointed < result.log }
+}
+
+/** FTS table presence is checked explicitly; genuine SQLite errors propagate. */
+export const mergeFts = (db: Database, pages: number) => {
+	for (const name of ["span_attr_fts", "log_body_fts", "span_operation_fts"]) {
+		if (db.query("SELECT 1 FROM sqlite_master WHERE name = ? AND type = 'table'").get(name)) {
+			db.query(`INSERT INTO ${name}(${name}, rank) VALUES ('merge', ?)`).run(pages)
+		}
+	}
+}
+
+type RetentionOptions = { cutoff: number; maxBytes: number; traces: number; logs: number; rows: number }
+
+/**
+ * Marks whole traces/logs atomically, then drains bounded dependent-row batches.
+ * Row budgets bound cardinality, not bytes inside a single telemetry field. Markers survive
+ * crashes; writers discard arrivals for marked traces until their eviction finishes.
+ */
+export const retainBatch = (db: Database, options: RetentionOptions) => db.transaction(() => {
+	const pageCount = (db.query("PRAGMA page_count").get() as { page_count: number }).page_count
+	const free = (db.query("PRAGMA freelist_count").get() as { freelist_count: number }).freelist_count
+	const pageSize = (db.query("PRAGMA page_size").get() as { page_size: number }).page_size
+	const oversized = (pageCount - free) * pageSize > options.maxBytes
+	const pending = (db.query("SELECT count(*) AS n FROM retention_traces").get() as { n: number }).n
+	const slots = Math.max(0, options.traces - pending)
+	// Upgrade-era summaries may undercount active spans. The partial index verifies
+	// actual span state before either age- or size-based eviction can select a trace.
+	if (slots > 0) {
+		db.query(`INSERT OR IGNORE INTO retention_traces SELECT trace_id FROM trace_summaries
+			WHERE active_span_count = 0 AND ended_at_ms > 0 AND ended_at_ms < ?
+			AND NOT EXISTS (SELECT 1 FROM retention_traces d WHERE d.trace_id = trace_summaries.trace_id)
+			AND NOT EXISTS (SELECT 1 FROM spans s WHERE s.trace_id = trace_summaries.trace_id AND (s.end_time_ms <= 0 OR s.end_time_ms < s.start_time_ms))
+			ORDER BY ended_at_ms, trace_id LIMIT ?`).run(options.cutoff, slots)
+		if (oversized) {
+			const remaining = Math.max(0, options.traces - (db.query("SELECT count(*) AS n FROM retention_traces").get() as { n: number }).n)
+			db.query(`INSERT OR IGNORE INTO retention_traces SELECT trace_id FROM trace_summaries
+				WHERE active_span_count = 0 AND NOT EXISTS (SELECT 1 FROM retention_traces d WHERE d.trace_id = trace_summaries.trace_id)
+				AND NOT EXISTS (SELECT 1 FROM spans s WHERE s.trace_id = trace_summaries.trace_id AND (s.end_time_ms <= 0 OR s.end_time_ms < s.start_time_ms))
+				ORDER BY started_at_ms, trace_id LIMIT ?`).run(remaining)
+		}
+	}
+	const traceIds = db.query("SELECT trace_id FROM retention_traces ORDER BY trace_id LIMIT ?").all(options.traces) as { trace_id: string }[]
+	// Correlated logs share trace visibility, including logs that have not yet been selected.
+	for (const { trace_id } of traceIds) {
+		const available = Math.max(0, options.logs - (db.query("SELECT count(*) AS n FROM retention_logs").get() as { n: number }).n)
+		if (available === 0) break
+		db.query(`INSERT OR IGNORE INTO retention_logs SELECT id FROM logs WHERE trace_id = ?
+			AND NOT EXISTS (SELECT 1 FROM retention_logs d WHERE d.id = logs.id) LIMIT ?`).run(trace_id, available)
+	}
+	const available = Math.max(0, options.logs - (db.query("SELECT count(*) AS n FROM retention_logs").get() as { n: number }).n)
+	db.query(`INSERT OR IGNORE INTO retention_logs SELECT id FROM logs WHERE timestamp_ms < ?
+		AND NOT EXISTS (SELECT 1 FROM retention_logs d WHERE d.id = logs.id)
+		ORDER BY timestamp_ms, id LIMIT ?`).run(oversized ? Number.MAX_SAFE_INTEGER : options.cutoff, available)
+
+	let remaining = options.rows
+	const remove = (sql: string, ...params: (string | number)[]) => {
+		if (remaining <= 0) return
+		const result = db.query(sql).run(...params, remaining)
+		remaining -= Number(result.changes)
+	}
+	// Split the row budget between traces and logs so neither stream starves the other.
+	remaining = Math.ceil(options.rows / 2)
+	for (const { trace_id } of traceIds) {
+		if (remaining <= 0) break
+		remove("DELETE FROM span_attributes WHERE rowid IN (SELECT rowid FROM span_attributes WHERE trace_id = ? LIMIT ?)", trace_id)
+		if (db.query("SELECT 1 FROM span_attributes WHERE trace_id = ? LIMIT 1").get(trace_id)) continue
+		const searches = db.query("SELECT id FROM span_search_rows WHERE trace_id = ? LIMIT ?").all(trace_id, remaining) as { id: number }[]
+		for (const { id } of searches) {
+			db.query("DELETE FROM span_operation_fts WHERE rowid = ?").run(id)
+			db.query("DELETE FROM span_search_rows WHERE id = ?").run(id)
+			remaining--
+		}
+		if (db.query("SELECT 1 FROM span_search_rows WHERE trace_id = ? LIMIT 1").get(trace_id)) continue
+		remove("DELETE FROM spans WHERE rowid IN (SELECT rowid FROM spans WHERE trace_id = ? LIMIT ?)", trace_id)
+		if (!db.query("SELECT 1 FROM spans WHERE trace_id = ? LIMIT 1").get(trace_id)
+			&& !db.query("SELECT 1 FROM logs WHERE trace_id = ? LIMIT 1").get(trace_id)) {
+			db.query("DELETE FROM trace_summaries WHERE trace_id = ?").run(trace_id)
+			db.query("DELETE FROM retention_traces WHERE trace_id = ?").run(trace_id)
+		}
+	}
+	const traceRows = Math.ceil(options.rows / 2) - remaining
+	remaining = options.rows - traceRows
+	const logIds = db.query("SELECT id FROM retention_logs ORDER BY id LIMIT ?").all(options.logs) as { id: number }[]
+	for (const { id } of logIds) {
+		if (remaining <= 0) break
+		remove("DELETE FROM log_attributes WHERE rowid IN (SELECT rowid FROM log_attributes WHERE log_id = ? LIMIT ?)", id)
+		if (db.query("SELECT 1 FROM log_attributes WHERE log_id = ? LIMIT 1").get(id)) continue
+		const searches = db.query("SELECT id FROM log_search_rows WHERE log_id = ? LIMIT ?").all(id, remaining) as { id: number }[]
+		for (const search of searches) {
+			db.query("DELETE FROM log_body_fts WHERE rowid = ?").run(search.id)
+			db.query("DELETE FROM log_search_rows WHERE id = ?").run(search.id)
+			remaining--
+		}
+		if (remaining <= 0 || db.query("SELECT 1 FROM log_search_rows WHERE log_id = ? LIMIT 1").get(id)) continue
+		db.query("DELETE FROM logs WHERE id = ?").run(id)
+		db.query("DELETE FROM retention_logs WHERE id = ?").run(id)
+		remaining--
+	}
+	return { pending: oversized || traceIds.length > 0 || logIds.length > 0, rows: options.rows - remaining, markedTraces: traceIds.length, markedLogs: logIds.length }
+})()
+
+/** Bounded repair scans only rowids beyond its durable high-water mark; idle passes do not write. */
+export const repairSearchRows = (db: Database, limit: number) => db.transaction(() => {
+	for (const table of ["log_attributes", "log_body_fts", "span_operation_fts"] as const) {
+		if (!db.query("SELECT 1 FROM sqlite_master WHERE name = ?").get(table)) continue
+		const key = `retention_repair_${table}`
+		const marker = (db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(key) as { value: string } | null)?.value
+		const cursor = Number(marker ?? 0)
+		const columns = table === "span_operation_fts" ? "trace_id, span_id" : "log_id"
+		const rows = db.query(`SELECT rowid AS repair_id, ${columns} FROM ${table} WHERE rowid > ? ORDER BY rowid LIMIT ?`).all(cursor, limit) as { repair_id: number; log_id?: number | string; trace_id?: string; span_id?: string }[]
+		for (const row of rows) {
+			const exists = table === "span_operation_fts"
+				? db.query("SELECT 1 FROM spans WHERE trace_id = ? AND span_id = ?").get(row.trace_id!, row.span_id!)
+				: db.query("SELECT 1 FROM logs WHERE id = ?").get(Number(row.log_id))
+			if (!exists) {
+				db.query(`DELETE FROM ${table} WHERE rowid = ?`).run(row.repair_id)
+				if (table !== "log_attributes") db.query(`DELETE FROM ${table === "log_body_fts" ? "log_search_rows" : "span_search_rows"} WHERE id = ?`).run(row.repair_id)
+			} else if (table === "span_operation_fts") {
+				db.query("INSERT OR REPLACE INTO span_search_rows VALUES (?, ?, ?)").run(row.repair_id, row.trace_id!, row.span_id!)
+			} else if (table === "log_body_fts") {
+				db.query("INSERT OR REPLACE INTO log_search_rows VALUES (?, ?)").run(row.repair_id, Number(row.log_id))
+			}
+		}
+		if (rows.length > 0) db.query("INSERT OR REPLACE INTO motel_maintenance VALUES (?, ?)").run(key, String(rows.at(-1)!.repair_id))
+	}
+})()

package/src/services/telemetryQueryProcess.ts

@@ -0,0 +1,10 @@
+// Keep the IPC owner outside SQLite's native call stack. If the daemon/TUI exits
+// unexpectedly, disconnect can terminate this process even while its thread is
+// executing a long SQLite query. A worker thread alone cannot interrupt that call.
+const worker = new Worker(new URL("./telemetryQueryWorker.ts", import.meta.url))
+worker.addEventListener("message", ({ data }) => process.send?.(data))
+worker.addEventListener("error", () => process.exit(1))
+worker.addEventListener("close", () => process.exit(1))
+process.on("message", (message) => worker.postMessage(message))
+process.on("disconnect", () => process.exit(0))
+process.on("SIGTERM", () => process.exit(0))