@aryasaatvik/motel 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryasaatvik/motel",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",

package/src/services/TelemetryStore.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite"
 import * as BunFileSystem from "@effect/platform-bun/BunFileSystem"
 import { dirname } from "node:path"
 import { Cause, Clock, Effect, FileSystem, Layer, Schedule, Context } from "effect"
-import { installRetentionSchema, checkpointPassive, mergeFts, retainBatch, repairSearchRows } from "./retention.js"
+import { installRetentionSchema, checkpointPassive, mergeFts, retainBatch, repairSearchRows, SPAN_SEARCH_MAPPING_READY_KEY } from "./retention.js"
 import { WriterDiagnostics } from "../ingestReadiness.ts"
 import { config } from "../config.js"
 import type { AiCallDetail, AiCallSummary, FacetItem, LogItem, SpanItem, StatsItem, TraceItem, TraceSummaryItem, TraceSpanEvent, TraceSpanItem } from "../domain.js"
@@ -872,14 +872,21 @@ const makeTelemetryStoreEffect = (opts: TelemetryStoreOptions) =>
 			query.run(...entries.flatMap(([key, value]) => [traceId, spanId, key, value]))
 		}
 		const deleteSpanOperationSearch = db.query(`DELETE FROM span_operation_fts WHERE trace_id = ? AND span_id = ?`)
+		const spanSearchMappingReady = hasRetention ? db.query("SELECT 1 FROM motel_maintenance WHERE key = ? AND value = 'complete'") : null
+		const deleteMappedSpanOperationSearch = hasRetention ? db.query(`DELETE FROM span_operation_fts WHERE rowid IN (
+			SELECT id FROM span_search_rows WHERE trace_id = ? AND span_id = ?
+		)`) : null
 		const insertSpanOperationSearch = db.query(`INSERT INTO span_operation_fts (trace_id, span_id, operation_name) VALUES (?, ?, ?)`)
 		const deleteSpanOperationSearchManyByCount = new Map<number, ReturnType<Database["query"]>>()
 		const insertSpanOperationSearchManyByCount = new Map<number, ReturnType<Database["query"]>>()
 		const updateSpanOperationSearchMany = (operations: ReadonlyArray<readonly [string, string, string]>) => {
 			if (operations.length === 0) return
+			const mappedDelete = spanSearchMappingReady !== null && deleteMappedSpanOperationSearch !== null
+				&& spanSearchMappingReady.get(SPAN_SEARCH_MAPPING_READY_KEY) !== null ? deleteMappedSpanOperationSearch : null
 			if (operations.length === 1) {
 				const [traceId, spanId, operationName] = operations[0]!
-				deleteSpanOperationSearch.run(traceId, spanId)
+				if (mappedDelete !== null) mappedDelete.run(traceId, spanId)
+				else deleteSpanOperationSearch.run(traceId, spanId)
 				db.query("DELETE FROM span_search_rows WHERE trace_id = ? AND span_id = ?").run(traceId, spanId)
 				const result = insertSpanOperationSearch.run(traceId, spanId, operationName)
 				mapSpanSearch?.run(Number(result.lastInsertRowid), traceId, spanId)
@@ -891,7 +898,9 @@ const makeTelemetryStoreEffect = (opts: TelemetryStoreOptions) =>
 				deleteQuery = db.query(`DELETE FROM span_operation_fts WHERE ${operations.map(() => "(trace_id = ? AND span_id = ?)").join(" OR ")}`)
 				deleteSpanOperationSearchManyByCount.set(operations.length, deleteQuery)
 			}
-			deleteQuery.run(...operations.flatMap(([traceId, spanId]) => [traceId, spanId]))
+			if (mappedDelete !== null) {
+				for (const [traceId, spanId] of operations) mappedDelete.run(traceId, spanId)
+			} else deleteQuery.run(...operations.flatMap(([traceId, spanId]) => [traceId, spanId]))
 			for (const [traceId, spanId] of operations) db.query("DELETE FROM span_search_rows WHERE trace_id = ? AND span_id = ?").run(traceId, spanId)
 
 			let insertQuery = insertSpanOperationSearchManyByCount.get(operations.length)
@@ -904,6 +913,13 @@ const makeTelemetryStoreEffect = (opts: TelemetryStoreOptions) =>
 			const firstId = Number(result.lastInsertRowid) - operations.length + 1
 			for (const [index, [traceId, spanId]] of operations.entries()) mapSpanSearch?.run(firstId + index, traceId, spanId)
 		}
+		// An optional search-index failure must leave every FTS row mapped.
+		const updateSpanOperationSearch = db.transaction((operations: Parameters<typeof updateSpanOperationSearchMany>[0]) => {
+			const BATCH_SIZE = 500
+			for (let offset = 0; offset < operations.length; offset += BATCH_SIZE) {
+				updateSpanOperationSearchMany(operations.slice(offset, offset + BATCH_SIZE))
+			}
+		})
 		const insertLogAttribute = db.query(`INSERT INTO log_attributes (log_id, key, value) VALUES (?, ?, ?)`)
 		const logAttributeInsertManyByCount = new Map<number, ReturnType<Database["query"]>>()
 		const insertLogAttributesMany = (logId: number, attributes: Readonly<Record<string, string>>) => {
@@ -979,8 +995,8 @@ const makeTelemetryStoreEffect = (opts: TelemetryStoreOptions) =>
 					logs: config.otel.retentionLogBatch,
 					rows: config.otel.retentionRowBatch,
 				})
-				maintenancePending = result.pending && result.rows > 0
-				repairSearchRows(db, Math.min(100, config.otel.retentionRowBatch))
+				const spanMappingPending = repairSearchRows(db, Math.min(100, config.otel.retentionRowBatch))
+				maintenancePending = (result.pending && result.rows > 0) || spanMappingPending
 				mergeFts(db, 100)
 				checkpoint()
 			})
@@ -1114,12 +1130,9 @@ const makeTelemetryStoreEffect = (opts: TelemetryStoreOptions) =>
 						}
 					}
 					try {
-						const BATCH_SIZE = 500
-						for (let offset = 0; offset < touchedOperations.length; offset += BATCH_SIZE) {
-							updateSpanOperationSearchMany(touchedOperations.slice(offset, offset + BATCH_SIZE))
-						}
+						updateSpanOperationSearch(touchedOperations)
 					} catch {
-						// FTS is optional.
+						// FTS is optional; its nested transaction restores the index and mapping together.
 					}
 					for (const traceId of touchedTraceIds) {
 						upsertTraceSummary.run(traceId)

package/src/services/retention.test.ts

@@ -3,7 +3,7 @@ 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"
+import { checkpointPassive, installRetentionSchema, mergeFts, repairSearchRows, retainBatch, SPAN_SEARCH_MAPPING_READY_KEY } from "./retention.ts"
 
 const schema = (db: Database) => {
 	db.exec(`PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 15000;
@@ -168,3 +168,152 @@ test("stale upgraded summaries cannot evict active spans under age or size reten
 		} finally { db.close() }
 	}
 })
+
+
+test("operation mapping readiness waits for complete legacy repair and stays idle after reopen", () => {
+	const root = mkdtempSync(join(tmpdir(), "motel-mapping-ready-"))
+	const path = join(root, "test.sqlite")
+	let db = new Database(path)
+	try {
+		schema(db)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "complete" })
+		db.query("DELETE FROM motel_maintenance WHERE key = ?").run(SPAN_SEARCH_MAPPING_READY_KEY)
+		db.exec("INSERT INTO spans(trace_id,span_id) VALUES ('a','s'), ('b','s'); INSERT INTO span_operation_fts(trace_id,span_id,operation_name) VALUES ('a','s','alpha'), ('b','s','beta'), ('orphan','s','orphan')")
+		// All three unmapped historical rows are below the pre-upgrade durable cursor.
+		db.exec("INSERT OR REPLACE INTO motel_maintenance VALUES ('retention_repair_span_operation_fts', '999')")
+		db.exec("CREATE TRIGGER refuse_mapping_marker BEFORE INSERT ON motel_maintenance WHEN NEW.key = 'span_search_mapping_complete' BEGIN SELECT RAISE(ABORT, 'marker failure'); END")
+		expect(() => installRetentionSchema(db)).toThrow("marker failure")
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "999" })
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toBeNull()
+		db.exec("DROP TRIGGER refuse_mapping_marker")
+		installRetentionSchema(db)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toBeNull()
+		expect(repairSearchRows(db, 1)).toBe(true)
+		expect(count(db, "span_search_rows")).toBe(1)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "repairing:3" })
+		db.close()
+		db = new Database(path)
+		installRetentionSchema(db)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "1" })
+		expect(repairSearchRows(db, 1)).toBe(true)
+		expect(count(db, "span_search_rows")).toBe(2)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "repairing:3" })
+		expect(repairSearchRows(db, 1)).toBe(false)
+		expect(count(db, "span_operation_fts")).toBe(2)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "complete" })
+		expect(repairSearchRows(db, 1)).toBe(false)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "complete" })
+		db.close()
+		db = new Database(path)
+		installRetentionSchema(db)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "3" })
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "complete" })
+		const before = db.query("SELECT total_changes() AS n").get()
+		expect(repairSearchRows(db, 1)).toBe(false)
+		expect(db.query("SELECT total_changes() AS n").get()).toEqual(before)
+	} finally { db.close(); rmSync(root, { recursive: true, force: true }) }
+})
+
+
+test("a final partial span repair returns idle despite remaining log repair", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		db.query("DELETE FROM motel_maintenance WHERE key = ?").run(SPAN_SEARCH_MAPPING_READY_KEY)
+		db.exec("INSERT INTO spans(trace_id, span_id) VALUES ('a', 's'), ('b', 's'); INSERT INTO span_operation_fts(trace_id, span_id, operation_name) VALUES ('a', 's', 'alpha'), ('b', 's', 'beta')")
+		for (let id = 1; id <= 7; id++) {
+			db.query("INSERT INTO logs VALUES (?, NULL, 1000, 'INFO')").run(id)
+			db.query("INSERT INTO log_attributes VALUES (?, 'key', 'value')").run(id)
+			db.query("INSERT INTO log_body_fts(log_id, body) VALUES (?, 'searchable')").run(String(id))
+		}
+		installRetentionSchema(db)
+		expect(repairSearchRows(db, 3)).toBe(false)
+		expect(count(db, "span_search_rows")).toBe(2)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "complete" })
+		expect(count(db, "log_body_fts")).toBe(7)
+		expect(count(db, "log_search_rows")).toBe(3)
+	} finally { db.close() }
+})
+
+test("an unavailable optional span index does not request fast repair retries", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		db.query("UPDATE motel_maintenance SET value = 'repairing:3' WHERE key = ?").run(SPAN_SEARCH_MAPPING_READY_KEY)
+		db.exec("DROP TABLE span_operation_fts")
+		expect(repairSearchRows(db, 3)).toBe(false)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "repairing:3" })
+	} finally { db.close() }
+})
+
+
+test("legacy span mapping finishes its fixed range despite mapped arrivals and reopen", () => {
+	const root = mkdtempSync(join(tmpdir(), "motel-mapping-target-"))
+	const path = join(root, "test.sqlite")
+	let db = new Database(path)
+	const state = () => db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)
+	const append = (id: number, mapped: boolean) => {
+		db.query("INSERT INTO spans(trace_id, span_id) VALUES (?, 's')").run(String(id))
+		db.query("INSERT INTO span_operation_fts(rowid, trace_id, span_id, operation_name) VALUES (?, ?, 's', 'operation')").run(id, String(id))
+		if (mapped) db.query("INSERT INTO span_search_rows VALUES (?, ?, 's')").run(id, String(id))
+	}
+	try {
+		schema(db)
+		db.query("DELETE FROM motel_maintenance WHERE key = ?").run(SPAN_SEARCH_MAPPING_READY_KEY)
+		for (let id = 1; id <= 4; id++) append(id, false)
+		db.exec("INSERT OR REPLACE INTO motel_maintenance VALUES ('retention_repair_span_operation_fts', '999')")
+		installRetentionSchema(db)
+		const captured = state()
+		expect(repairSearchRows(db, 2)).toBe(true)
+		for (let id = 5; id <= 8; id++) append(id, true)
+		db.close()
+		db = new Database(path)
+		installRetentionSchema(db)
+		expect(state()).toEqual(captured)
+		// Complete the exact full-sized final batch without scanning the mapped arrivals.
+		expect(repairSearchRows(db, 2)).toBe(false)
+		expect(state()).toEqual({ value: "complete" })
+		expect(captured).toEqual({ value: "repairing:4" })
+		expect(count(db, "span_search_rows")).toBe(8)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "4" })
+		// Ordinary incremental repair still visits later rows, without requesting fast cadence.
+		expect(repairSearchRows(db, 2)).toBe(false)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "6" })
+		expect(repairSearchRows(db, 2)).toBe(false)
+		const before = db.query("SELECT total_changes() AS n").get()
+		expect(repairSearchRows(db, 2)).toBe(false)
+		expect(db.query("SELECT total_changes() AS n").get()).toEqual(before)
+	} finally { db.close(); rmSync(root, { recursive: true, force: true }) }
+})
+
+test("fixed-range repair rolls back failures and completes after its target row is removed", () => {
+	const db = new Database(":memory:")
+	try {
+		schema(db)
+		db.query("DELETE FROM motel_maintenance WHERE key = ?").run(SPAN_SEARCH_MAPPING_READY_KEY)
+		db.exec("INSERT INTO spans(trace_id,span_id) VALUES ('a','s'),('b','s'); INSERT INTO span_operation_fts(trace_id,span_id,operation_name) VALUES ('a','s','alpha'),('b','s','beta')")
+		installRetentionSchema(db)
+		expect(repairSearchRows(db, 1)).toBe(true)
+		db.exec("CREATE TRIGGER refuse_repair BEFORE INSERT ON span_search_rows WHEN NEW.trace_id = 'b' BEGIN SELECT RAISE(ABORT, 'repair failure'); END")
+		expect(() => repairSearchRows(db, 1)).toThrow("repair failure")
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "repairing:2" })
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "1" })
+		db.exec("DROP TRIGGER refuse_repair; DELETE FROM span_operation_fts WHERE rowid = 2")
+		expect(repairSearchRows(db, 1)).toBe(false)
+		expect(db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY)).toEqual({ value: "complete" })
+	} finally { db.close() }
+})
+
+test("malformed persistent span migration state fails without resetting its cursor", () => {
+	for (const state of ["repairing", "repairing:0", "repairing:1.5", "repairing:9007199254740992", "unknown"]) {
+		const db = new Database(":memory:")
+		try {
+			schema(db)
+			db.query("UPDATE motel_maintenance SET value = ? WHERE key = ?").run(state, SPAN_SEARCH_MAPPING_READY_KEY)
+			db.exec("INSERT OR REPLACE INTO motel_maintenance VALUES ('retention_repair_span_operation_fts', '7')")
+			expect(() => installRetentionSchema(db)).toThrow("Invalid span search mapping migration state")
+			expect(() => repairSearchRows(db, 1)).toThrow("Invalid span search mapping migration state")
+			expect(db.query("SELECT value FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").get()).toEqual({ value: "7" })
+		} finally { db.close() }
+	}
+})

package/src/services/retention.ts

@@ -1,5 +1,15 @@
 import type { Database } from "bun:sqlite"
 
+export const SPAN_SEARCH_MAPPING_READY_KEY = "span_search_mapping_complete"
+
+const spanMappingTarget = (state: string): number | null => {
+	if (state === "complete") return null
+	const match = /^repairing:([1-9][0-9]*)$/.exec(state)
+	const target = match === null ? NaN : Number(match[1])
+	if (!Number.isSafeInteger(target)) throw new Error("Invalid span search mapping migration state")
+	return target
+}
+
 /** Additive schema: unfinished eviction is hidden from every public query. */
 export const installRetentionSchema = (db: Database) => {
 	db.exec(`
@@ -22,6 +32,21 @@ export const installRetentionSchema = (db: Database) => {
 			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);
 	`)
+	if (db.query("SELECT 1 FROM sqlite_master WHERE name = 'span_operation_fts' AND type = 'table'").get()) {
+		db.transaction(() => {
+			const marker = db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY) as { value: string } | null
+			if (marker !== null) {
+				spanMappingTarget(marker.value)
+				return
+			}
+			// Earlier optional index failures can strand unmapped rows behind the old cursor.
+			db.query("DELETE FROM motel_maintenance WHERE key = 'retention_repair_span_operation_fts'").run()
+			const last = db.query("SELECT rowid AS target FROM span_operation_fts ORDER BY rowid DESC LIMIT 1").get() as { target: number } | null
+			const state = last === null ? "complete" : `repairing:${last.target}`
+			spanMappingTarget(state)
+			db.query("INSERT INTO motel_maintenance(key, value) VALUES (?, ?)").run(SPAN_SEARCH_MAPPING_READY_KEY, state)
+		}).immediate()
+	}
 }
 
 export type Checkpoint = { busy: number; log: number; checkpointed: number; deferred: boolean }
@@ -133,13 +158,23 @@ export const retainBatch = (db: Database, options: RetentionOptions) => db.trans
 
 /** 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(() => {
+	let spanMappingPending = false
 	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 }[]
+		let target: number | null = null
+		if (table === "span_operation_fts") {
+			const state = db.query("SELECT value FROM motel_maintenance WHERE key = ?").get(SPAN_SEARCH_MAPPING_READY_KEY) as { value: string } | null
+			if (state === null) throw new Error("Missing span search mapping migration state")
+			target = spanMappingTarget(state.value)
+		}
+		const rows = (target === null
+			? db.query(`SELECT rowid AS repair_id, ${columns} FROM ${table} WHERE rowid > ? ORDER BY rowid LIMIT ?`).all(cursor, limit)
+			: db.query(`SELECT rowid AS repair_id, ${columns} FROM ${table} WHERE rowid > ? AND rowid <= ? ORDER BY rowid LIMIT ?`).all(cursor, target, 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!)
@@ -154,5 +189,13 @@ export const repairSearchRows = (db: Database, limit: number) => db.transaction(
 			}
 		}
 		if (rows.length > 0) db.query("INSERT OR REPLACE INTO motel_maintenance VALUES (?, ?)").run(key, String(rows.at(-1)!.repair_id))
+		if (target !== null) {
+			const nextCursor = rows.at(-1)?.repair_id ?? cursor
+			spanMappingPending = db.query("SELECT 1 FROM span_operation_fts WHERE rowid > ? AND rowid <= ? LIMIT 1").get(nextCursor, target) !== null
+			if (!spanMappingPending) {
+				db.query("UPDATE motel_maintenance SET value = 'complete' WHERE key = ?").run(SPAN_SEARCH_MAPPING_READY_KEY)
+			}
+		}
 	}
+	return spanMappingPending
 })()

package/src/telemetry.test.ts

@@ -407,6 +407,194 @@ describe("motel telemetry store", () => {
 		}
 	})
 
+
+	it("keeps operation search and mappings atomic across updates, legacy repair and ingest rollback", async () => {
+		const isolatedPath = join(tempDir, "operation-savepoint.sqlite")
+		const script = `
+			const assert = (await import('node:assert/strict')).default
+			const { Database } = await import('bun:sqlite')
+			const { Effect, ManagedRuntime } = await import('effect')
+			const { TelemetryStore, makeTelemetryStoreLayer } = await import('./src/services/TelemetryStore.ts')
+			const { repairSearchRows, installRetentionSchema, SPAN_SEARCH_MAPPING_READY_KEY } = await import('./src/services/retention.ts')
+			const runtime = ManagedRuntime.make(makeTelemetryStoreLayer({ readonly: false, runRetention: false }))
+			let db
+			const now = BigInt(Date.now()) * 1000000n
+			const span = (traceId, spanId, name) => ({ traceId, spanId, name, startTimeUnixNano: String(now), endTimeUnixNano: String(now + 1000000n) })
+			const ingest = (spans) => runtime.runPromise(Effect.flatMap(TelemetryStore, (store) => store.ingestTraces({ resourceSpans: [{ resource: { attributes: [{ key: 'service.name', value: { stringValue: 'fts-regression' } }] }, scopeSpans: [{ spans }] }] })))
+			const names = (traceId) => db.query('SELECT operation_name FROM span_operation_fts WHERE trace_id = ? ORDER BY operation_name').all(traceId).map((row) => row.operation_name)
+			const ready = () => db.query('SELECT value FROM motel_maintenance WHERE key = ?').get(SPAN_SEARCH_MAPPING_READY_KEY)?.value
+			const mappingCounts = () => db.query('SELECT (SELECT count(*) FROM span_operation_fts) AS fts, (SELECT count(*) FROM span_search_rows) AS mapping, (SELECT count(*) FROM span_operation_fts f LEFT JOIN span_search_rows m ON m.id = f.rowid WHERE m.id IS NULL) AS unmapped').get()
+			try {
+				await ingest([span('normal', 'root', 'oldoperation')])
+				db = new Database(process.env.MOTEL_OTEL_DB_PATH)
+				assert.equal(ready(), 'complete')
+				await ingest([span('normal', 'root', 'newoperation')])
+				assert.deepEqual(names('normal'), ['newoperation'])
+				assert.equal((await runtime.runPromise(Effect.flatMap(TelemetryStore, (store) => store.searchSpans({ operation: 'oldoperation' })))).length, 0)
+				assert.equal((await runtime.runPromise(Effect.flatMap(TelemetryStore, (store) => store.searchSpans({ operation: 'newoperation' })))).length, 1)
+
+				await ingest(Array.from({ length: 32 }, (_, i) => span('mixed-' + i, 'root', 'mixedold')))
+				await ingest(Array.from({ length: 64 }, (_, i) => span('mixed-' + i, 'root', 'mixednew')))
+				assert.equal(db.query("SELECT count(*) AS n FROM span_operation_fts WHERE operation_name = 'mixedold'").get().n, 0)
+				assert.equal(db.query("SELECT count(*) AS n FROM span_operation_fts WHERE operation_name = 'mixednew'").get().n, 64)
+
+				await ingest([span('duplicate', 'root', 'first'), span('duplicate', 'root', 'second')])
+				assert.deepEqual(names('duplicate'), ['first', 'second'])
+				const acrossBoundary = [span('duplicate', 'root', 'early')]
+				for (let i = 1; i < 499; i++) acrossBoundary.push(span('filler-' + i, 'root', 'filler'))
+				acrossBoundary.push(span('duplicate', 'root', 'middle'), span('duplicate', 'root', 'lateone'), span('duplicate', 'root', 'latetwo'))
+				await ingest(acrossBoundary)
+				assert.deepEqual(names('duplicate'), ['lateone', 'latetwo'])
+				assert.equal(db.query("SELECT operation_name FROM spans WHERE trace_id = 'duplicate' AND span_id = 'root'").get().operation_name, 'latetwo')
+
+				// Simulate an upgraded database with unmapped historical FTS rows.
+				db.query("DELETE FROM motel_maintenance WHERE key IN (?, 'retention_repair_span_operation_fts')").run(SPAN_SEARCH_MAPPING_READY_KEY)
+				db.exec("DELETE FROM span_search_rows WHERE trace_id = 'normal'")
+				db.query("INSERT OR REPLACE INTO motel_maintenance VALUES ('retention_repair_span_operation_fts', '999999')").run()
+				installRetentionSchema(db)
+				await ingest([span('normal', 'root', 'legacyupdated')])
+				assert.deepEqual(names('normal'), ['legacyupdated'])
+				assert.match(ready(), /^repairing:[1-9][0-9]*$/)
+				for (let pass = 0; ready() !== 'complete' && pass < 20; pass++) repairSearchRows(db, 100)
+				assert.equal(ready(), 'complete')
+
+				// Fail mapping after FTS insertion; every chunk of the optional unit must roll back.
+				const before = names('normal')
+				const beforeCounts = mappingCounts()
+				db.exec("CREATE TRIGGER reject_mapping BEFORE INSERT ON span_search_rows WHEN NEW.trace_id = 'normal' BEGIN SELECT RAISE(ABORT, 'mapping failure'); END")
+				const failedChunks = Array.from({ length: 500 }, (_, i) => span('failed-chunk-' + i, 'root', 'mustrollback'))
+				failedChunks.push(span('normal', 'root', 'committedspan'))
+				await ingest(failedChunks)
+				assert.deepEqual(names('normal'), before)
+				assert.deepEqual(mappingCounts(), beforeCounts)
+				assert.equal(db.query("SELECT count(*) AS n FROM span_operation_fts WHERE operation_name = 'mustrollback'").get().n, 0)
+				assert.equal(db.query("SELECT operation_name FROM spans WHERE trace_id = 'normal' AND span_id = 'root'").get().operation_name, 'committedspan')
+				assert.equal(ready(), 'complete')
+				db.exec('DROP TRIGGER reject_mapping')
+				await ingest([span('normal', 'root', 'recovered')])
+				assert.deepEqual(names('normal'), ['recovered'])
+
+				const stableNames = names('normal')
+				const stableCounts = mappingCounts()
+				db.exec("CREATE TRIGGER reject_summary BEFORE INSERT ON trace_summaries WHEN NEW.trace_id = 'normal' BEGIN SELECT RAISE(ABORT, 'summary failure'); END")
+				await assert.rejects(ingest([span('normal', 'root', 'outerrollback')]))
+				assert.deepEqual(names('normal'), stableNames)
+				assert.deepEqual(mappingCounts(), stableCounts)
+				assert.equal(db.query("SELECT operation_name FROM spans WHERE trace_id = 'normal' AND span_id = 'root'").get().operation_name, 'recovered')
+				assert.equal(ready(), 'complete')
+				db.exec('DROP TRIGGER reject_summary')
+			} finally {
+				db?.close()
+				await runtime.dispose()
+			}
+		`
+		const child = Bun.spawn({
+			cmd: [process.execPath, "--no-env-file", "-e", script], cwd: process.cwd(),
+			env: { ...process.env, MOTEL_OTEL_DB_PATH: isolatedPath, MOTEL_OTEL_ENABLED: "false" },
+			stdout: "ignore", stderr: "pipe",
+		})
+		const stderr = await new Response(child.stderr).text()
+		expect(await child.exited, stderr).toBe(0)
+	})
+
+
+	it("repairs legacy span mappings at the pending cadence and idles after completion", async () => {
+		const isolatedPath = join(tempDir, "mapping-repair-pacing.sqlite")
+		const script = `
+			const assert = (await import('node:assert/strict')).default
+			const { Database } = await import('bun:sqlite')
+			const { Clock, Deferred, Effect, Layer, ManagedRuntime } = await import('effect')
+			const { TestClock } = await import('effect/testing')
+			const { TelemetryStore, makeTelemetryStoreLayer } = await import('./src/services/TelemetryStore.ts')
+			const { WriterDiagnostics } = await import('./src/ingestReadiness.ts')
+			const { SPAN_SEARCH_MAPPING_READY_KEY } = await import('./src/services/retention.ts')
+			const now = Date.now()
+			const nanos = BigInt(now) * 1000000n
+			const seed = ManagedRuntime.make(makeTelemetryStoreLayer({ readonly: false, runRetention: false }))
+			try {
+				await seed.runPromise(Effect.flatMap(TelemetryStore, (store) => store.ingestTraces({
+					resourceSpans: [{
+						resource: { attributes: [{ key: 'service.name', value: { stringValue: 'mapping-pacing' } }] },
+						scopeSpans: [{ spans: Array.from({ length: 250 }, (_, id) => ({
+							traceId: 'pacing-' + id, spanId: 'root', name: 'legacyoperation',
+							startTimeUnixNano: String(nanos), endTimeUnixNano: String(nanos + 1000000n),
+						})) }],
+					}],
+				})))
+			} finally { await seed.dispose() }
+			const db = new Database(process.env.MOTEL_OTEL_DB_PATH)
+			try {
+				db.exec('DELETE FROM span_search_rows')
+				db.query('DELETE FROM motel_maintenance WHERE key = ?').run(SPAN_SEARCH_MAPPING_READY_KEY)
+				db.exec("INSERT OR REPLACE INTO motel_maintenance VALUES ('retention_repair_span_operation_fts', '999999')")
+				await Effect.runPromise(Effect.scoped(Effect.gen(function* () {
+					const clock = yield* TestClock.make()
+					yield* clock.setTime(now + 2)
+					const firstPass = Deferred.makeUnsafe()
+					const passes = []
+					const publish = (event) => {
+						if (event._tag !== 'maintenance' || event.value.operation !== 'retention' || event.value.outcome === 'running') return
+						passes.push({
+							outcome: event.value.outcome,
+							mapped: db.query('SELECT count(*) AS n FROM span_search_rows').get().n,
+							state: db.query('SELECT value FROM motel_maintenance WHERE key = ?').get(SPAN_SEARCH_MAPPING_READY_KEY)?.value,
+						})
+						Deferred.doneUnsafe(firstPass, Effect.void)
+					}
+					const runtime = ManagedRuntime.make(makeTelemetryStoreLayer({ readonly: false, runRetention: true }).pipe(
+						Layer.provide(Layer.succeed(Clock.Clock, clock)),
+						Layer.provide(Layer.succeed(WriterDiagnostics, publish)),
+					))
+					yield* Effect.addFinalizer(() => runtime.disposeEffect)
+					yield* Effect.promise(() => runtime.runPromise(Effect.asVoid(TelemetryStore)))
+					yield* Deferred.await(firstPass).pipe(Effect.timeout('5 seconds'))
+					assert.deepEqual(passes, [{ outcome: 'completed', mapped: 100, state: 'repairing:250' }])
+					yield* clock.adjust('100 millis')
+					assert.deepEqual(passes, [
+						{ outcome: 'completed', mapped: 100, state: 'repairing:250' },
+						{ outcome: 'completed', mapped: 200, state: 'repairing:250' },
+					])
+					yield* clock.adjust('100 millis')
+					assert.deepEqual(passes, [
+						{ outcome: 'completed', mapped: 100, state: 'repairing:250' },
+						{ outcome: 'completed', mapped: 200, state: 'repairing:250' },
+						{ outcome: 'completed', mapped: 250, state: 'complete' },
+					])
+					yield* clock.adjust('100 millis')
+					assert.equal(passes.length, 3)
+					yield* clock.adjust('9900 millis')
+					assert.deepEqual(passes.at(-1), { outcome: 'completed', mapped: 250, state: 'complete' })
+					assert.equal(passes.length, 4)
+					yield* runtime.disposeEffect
+					yield* clock.adjust('30 seconds')
+					assert.equal(passes.length, 4)
+				})))
+			} finally { db.close() }
+		`
+		const child = Bun.spawn({
+			cmd: [process.execPath, "--no-env-file", "-e", script], cwd: process.cwd(),
+			env: {
+				...process.env,
+				MOTEL_OTEL_DB_PATH: isolatedPath, MOTEL_OTEL_ENABLED: "false",
+				MOTEL_OTEL_RETENTION_ROW_BATCH: "1000", MOTEL_OTEL_RETENTION_INTERVAL_SECONDS: "10",
+				MOTEL_OTEL_RETENTION_TRACE_BATCH: "100", MOTEL_OTEL_RETENTION_HOURS: "168",
+				MOTEL_OTEL_MAX_DB_SIZE_MB: "1024",
+			},
+			stdout: "ignore", stderr: "pipe",
+		})
+		let timedOut = false
+		const deadline = setTimeout(() => { timedOut = true; child.kill() }, 15_000)
+		try {
+			const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()])
+			expect(timedOut, stderr).toBe(false)
+			expect(exitCode, stderr).toBe(0)
+		} finally {
+			clearTimeout(deadline)
+			if (child.exitCode === null) child.kill()
+			await child.exited
+		}
+	}, 20_000)
+
 	it("incrementally backfills historical AI FTS content", async () => {
 		const historicalPath = join(tempDir, "historical-fts.sqlite")
 		const seedScript = `
@@ -468,6 +656,42 @@ describe("motel telemetry store", () => {
 		expect(result?.span.depth).toBe(1)
 	})
 
+
+	it("opens and searches a read-only pre-retention database without creating mappings", async () => {
+		const legacyPath = join(tempDir, "readonly-pre-retention.sqlite")
+		const script = `
+			const assert = (await import('node:assert/strict')).default
+			const { Database } = await import('bun:sqlite')
+			const { Effect, ManagedRuntime } = await import('effect')
+			const { TelemetryStore, makeTelemetryStoreLayer, TelemetryStoreReadonly, TelemetryStoreReadonlyLive } = await import('./src/services/TelemetryStore.ts')
+			const writer = ManagedRuntime.make(makeTelemetryStoreLayer({ readonly: false, runRetention: false }))
+			try {
+				const now = BigInt(Date.now()) * 1000000n
+				await writer.runPromise(Effect.flatMap(TelemetryStore, (store) => store.ingestTraces({ resourceSpans: [{ resource: { attributes: [{ key: 'service.name', value: { stringValue: 'legacy-readonly' } }] }, scopeSpans: [{ spans: [{ traceId: 'legacy-read', spanId: 'root', name: 'legacyoperation', startTimeUnixNano: String(now), endTimeUnixNano: String(now + 1000000n) }] }] }] })))
+			} finally { await writer.dispose() }
+			const legacy = new Database(process.env.MOTEL_OTEL_DB_PATH)
+			legacy.exec('DROP VIEW retained_spans; DROP VIEW retained_logs; DROP VIEW retained_trace_summaries; DROP TABLE span_search_rows; DROP TABLE log_search_rows; DROP TABLE retention_traces; DROP TABLE retention_logs;')
+			const version = legacy.query('PRAGMA schema_version').get().schema_version
+			legacy.close()
+			const reader = ManagedRuntime.make(TelemetryStoreReadonlyLive)
+			try {
+				const trace = await reader.runPromise(Effect.flatMap(TelemetryStoreReadonly, (store) => store.getTrace('legacy-read')))
+				assert.equal(trace?.spans.length, 1)
+				const found = await reader.runPromise(Effect.flatMap(TelemetryStoreReadonly, (store) => store.searchSpans({ operation: 'legacyoperation' })))
+				assert.equal(found.length, 1)
+				assert.equal(found[0].traceId, 'legacy-read')
+			} finally { await reader.dispose() }
+			const verify = new Database(process.env.MOTEL_OTEL_DB_PATH, { readonly: true })
+			try {
+				assert.equal(verify.query('PRAGMA schema_version').get().schema_version, version)
+				assert.equal(verify.query("SELECT count(*) AS n FROM sqlite_master WHERE name IN ('span_search_rows', 'log_search_rows', 'retained_spans')").get().n, 0)
+			} finally { verify.close() }
+		`
+		const child = Bun.spawn({ cmd: [process.execPath, "--no-env-file", "-e", script], cwd: process.cwd(), env: { ...process.env, MOTEL_OTEL_DB_PATH: legacyPath }, stdout: "ignore", stderr: "pipe" })
+		const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()])
+		expect(exitCode, stderr).toBe(0)
+	})
+
 	it("returns trace details through the query worker when spans share empty event arrays", async () => {
 		const workerDbPath = join(tempDir, "query-worker-shared-events.sqlite")
 		const script = `