@aryasaatvik/motel 0.5.1 → 0.5.3

package/AGENTS.md

@@ -130,27 +130,30 @@ The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugi
 - Health: `http://127.0.0.1:27686/api/health`
 
 ## Env Vars
-- `MOTEL_OTEL_ENABLED`: defaults to `false` (set to `true` to emit self-traces for debugging motel itself)
-- `MOTEL_OTEL_SERVICE_NAME`: defaults to `motel-otel-tui`; a nonblank explicit value also selects the initial TUI service, overriding the remembered selection (unset or blank values keep the remembered selection)
+Integer settings treat blank, non-numeric, and non-positive values as unset. `src/config.ts` resolves the base URL as `MOTEL_OTEL_BASE_URL`, then `MOTEL_OTEL_QUERY_URL`, then `MOTEL_OTEL_COLLECTOR_URL`, then `http://127.0.0.1:27686`. Host and port follow that URL unless set (`src/config.ts` uses port 80 when the URL has no port). The managed daemon in `src/daemon.ts` stops at `MOTEL_OTEL_QUERY_URL` and uses port 27686 when its URL has no port, then writes that listen address into the server's base URL, query URL, host, port, and exporter URLs. The server's database file is `MOTEL_OTEL_DB_PATH`, or `telemetry.sqlite` in the runtime directory, independent of the listen address.
+- `MOTEL_OTEL_ENABLED`: defaults to `false`. Blank, `0`, `false`, `no`, and `off` stay off; any other value makes the TUI and CLI export motel's own traces and logs.
+- `MOTEL_OTEL_SERVICE_NAME`: defaults to `motel-otel-tui`. A nonblank value is the exporter service name, the CLI default service, and the initial TUI service. Blank keeps the remembered TUI service.
 - `MOTEL_OTEL_BASE_URL`: defaults to `http://127.0.0.1:27686`
-- `MOTEL_OTEL_HOST`: defaults to `127.0.0.1`
-- `MOTEL_OTEL_PORT`: defaults to `27686`
-- `MOTEL_OTEL_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/traces`
-- `MOTEL_OTEL_LOGS_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/logs`
-- `MOTEL_OTEL_QUERY_URL`: defaults to `http://127.0.0.1:27686`
-- `MOTEL_OTEL_DB_PATH`: defaults to `${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite` (one shared DB per machine; daemon log + lock + instance registry live in the same directory)
-- `MOTEL_RUNTIME_DIR`: overrides the daemon log, lock, and instance-registry directory (primarily for isolated tests and custom managed instances)
-- `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES`: defaults to `1440` (24h)
-- `MOTEL_OTEL_TRACE_LIMIT`: defaults to `100`
-- `MOTEL_OTEL_LOG_LIMIT`: defaults to `80`
+- `MOTEL_OTEL_QUERY_URL`: base URL fallback when `MOTEL_OTEL_BASE_URL` is unset. The configured query URL is the resolved base URL.
+- `MOTEL_OTEL_COLLECTOR_URL`: base URL fallback when both URLs above are unset. The managed daemon leaves it unused.
+- `MOTEL_OTEL_HOST`: defaults to the base URL hostname (`127.0.0.1`)
+- `MOTEL_OTEL_PORT`: defaults to the base URL port (`27686`; `80` from `src/config.ts` when the URL has no port)
+- `MOTEL_OTEL_EXPORTER_URL`: defaults to the base URL plus `v1/traces`
+- `MOTEL_OTEL_LOGS_EXPORTER_URL`: defaults to the base URL plus `v1/logs`
+- `MOTEL_RUNTIME_DIR`: defaults to `${XDG_STATE_HOME:-~/.local/state}/motel` (default database, daemon log, lock, and instance registry; primarily overridden for isolated tests and custom managed instances)
+- `MOTEL_OTEL_DB_PATH`: defaults to `$MOTEL_RUNTIME_DIR/telemetry.sqlite` (one shared DB per machine)
+- `MOTEL_URL`: when set, the MCP client uses this base URL instead of the instance registry
+- `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES`: defaults to `1440` (24h) for service discovery and store queries that omit a lookback. HTTP list and search routes send their own `lookback` (default 60 minutes, maximum 1440).
+- `MOTEL_OTEL_TRACE_LIMIT`: defaults to `100` for the TUI and CLI. HTTP list routes send their own `limit`.
+- `MOTEL_OTEL_LOG_LIMIT`: defaults to `80` for TUI service logs, TUI trace logs, and CLI log commands. HTTP log routes send their own `limit`.
 - `MOTEL_OTEL_RETENTION_HOURS`: defaults to `168` (7d)
-- `MOTEL_OTEL_MAX_DB_SIZE_MB`: defaults to `1024` (size-based retention cap)
-- `MOTEL_OTEL_RETENTION_TRACE_BATCH`: defaults to `100` completed traces per cleanup pass
-- `MOTEL_OTEL_RETENTION_LOG_BATCH`: defaults to `5000` logs per cleanup pass
+- `MOTEL_OTEL_MAX_DB_SIZE_MB`: defaults to `1024` (active-data target, not a hard file cap)
+- `MOTEL_OTEL_RETENTION_TRACE_BATCH`: defaults to `100` completed traces marked per cleanup pass
+- `MOTEL_OTEL_RETENTION_LOG_BATCH`: defaults to `5000` logs marked per cleanup pass
 - `MOTEL_OTEL_QUERY_CAPACITY`: defaults to `8` outstanding queries per runtime (maximum `64`)
 - `MOTEL_OTEL_QUERY_DEADLINE_MS`: defaults to `5000` including queue and startup time (maximum `30000`)
-- `MOTEL_OTEL_RETENTION_ROW_BATCH`: defaults to `1000` physical rows per cleanup pass
-- `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`: defaults to `10`
+- `MOTEL_OTEL_RETENTION_ROW_BATCH`: defaults to `1000` rows deleted per cleanup pass, split across traces and logs. Bounds row count, not the size of one field.
+- `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`: defaults to `10` after an idle pass. Cleanup that is still making progress waits 100 ms.
 
 ## TUI Keys
 - `?`: toggle shortcut help

package/README.md

@@ -42,7 +42,7 @@ npm install -g @aryasaatvik/motel
 Don't have Bun?
 
 ```bash
-curl -fsSL https://bun.sh/install | bash
+curl -fsSL https://bun.sh/install | bash -s "bun-v1.4.4"
 ```
 
 `motel` starts the local OTLP ingest server on
@@ -50,7 +50,7 @@ curl -fsSL https://bun.sh/install | bash
 the keyboard cheat sheet, or `c` to copy paste-ready setup instructions
 for any Effect/OTEL app you want to trace.
 
-Requirements: [Bun](https://bun.sh/) matching `package.json` `engines.bun` (`>=1.3.0`).
+Requirements: [Bun](https://bun.sh/) matching `package.json` `engines.bun` (`>=1.4.4`).
 
 ### macOS service from the maintained checkout
 
@@ -90,12 +90,61 @@ The store retains seven days of telemetry by default and targets a 1 GB
 active-data ceiling using bounded background batches. Recent data is preserved while
 the oldest completed traces and logs are removed first. Configure the policy
 with `MOTEL_OTEL_RETENTION_HOURS`, `MOTEL_OTEL_MAX_DB_SIZE_MB`,
-`MOTEL_OTEL_RETENTION_TRACE_BATCH`, `MOTEL_OTEL_RETENTION_LOG_BATCH`, and
-`MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`. Existing databases created without
+`MOTEL_OTEL_RETENTION_TRACE_BATCH`, `MOTEL_OTEL_RETENTION_ROW_BATCH`,
+`MOTEL_OTEL_RETENTION_LOG_BATCH`, and
+`MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`.
+Existing databases created without
 incremental auto-vacuum are never silently rewritten at startup; deleted pages
 are reused, but shrinking such a historical file requires an explicit offline
 SQLite `VACUUM` chosen by the user.
 
+## Configuration
+
+Processes that load `src/config.ts` resolve one base URL, in order:
+`MOTEL_OTEL_BASE_URL`, `MOTEL_OTEL_QUERY_URL`, `MOTEL_OTEL_COLLECTOR_URL`,
+then `http://127.0.0.1:27686`. The query URL is that base URL. Host is
+`MOTEL_OTEL_HOST`, or the base URL hostname. Port is `MOTEL_OTEL_PORT` when
+it is a positive integer, otherwise the base URL port, otherwise 80. Trace
+and log exporter URLs default to that base with `v1/traces` and `v1/logs`.
+
+`motel start`, and the daemon the TUI launches, build the listen address
+from `MOTEL_OTEL_BASE_URL`, then `MOTEL_OTEL_QUERY_URL`, then
+`http://127.0.0.1:27686`. A missing port becomes 27686. The spawned server
+receives that listen address as its base URL, query URL, host, port, and
+exporter URLs (the listen origin plus `/v1/traces` and `/v1/logs`). The
+database file is resolved separately: `MOTEL_OTEL_DB_PATH`, or
+`telemetry.sqlite` in the runtime directory.
+
+Integer settings treat blank, non-numeric, and non-positive values as unset.
+`MOTEL_OTEL_QUERY_CAPACITY` is capped at 64 and
+`MOTEL_OTEL_QUERY_DEADLINE_MS` at 30000.
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `MOTEL_OTEL_BASE_URL` | `http://127.0.0.1:27686` | Resolved base URL and query URL. First choice in the fallback above. |
+| `MOTEL_OTEL_QUERY_URL` | unset | Base URL when `MOTEL_OTEL_BASE_URL` is unset. The query URL equals the resolved base URL. |
+| `MOTEL_OTEL_COLLECTOR_URL` | unset | Base URL only when both URLs above are unset. The managed daemon leaves it unused. |
+| `MOTEL_OTEL_HOST` | base URL hostname (`127.0.0.1`) | Hostname the server binds. |
+| `MOTEL_OTEL_PORT` | base URL port (`27686`) | Port the server binds. `src/config.ts` uses 80 when the URL has no port; the managed daemon uses 27686. |
+| `MOTEL_OTEL_SERVICE_NAME` | `motel-otel-tui` | Name on motel's own exporter, and the CLI default service. A nonblank value is also the TUI's initial service. Blank keeps the remembered TUI service. |
+| `MOTEL_OTEL_ENABLED` | `false` | Export motel's own traces and logs from the TUI and CLI. Blank, `0`, `false`, `no`, and `off` stay off; any other value turns it on. |
+| `MOTEL_OTEL_EXPORTER_URL` | base URL + `/v1/traces` | Where that self-export posts spans. |
+| `MOTEL_OTEL_LOGS_EXPORTER_URL` | base URL + `/v1/logs` | Where that self-export posts logs. |
+| `MOTEL_RUNTIME_DIR` | `${XDG_STATE_HOME:-~/.local/state}/motel` | State directory: default database, daemon log, lock, and instance registry. |
+| `MOTEL_OTEL_DB_PATH` | `$MOTEL_RUNTIME_DIR/telemetry.sqlite` | SQLite file. One shared database per machine unless this is set. |
+| `MOTEL_URL` | unset | Base URL for the MCP client. When set, discovery uses it instead of the instance registry. |
+| `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES` | `1440` | Age window, in minutes, for service discovery and for store queries that omit a lookback. HTTP list and search routes send their own `lookback` (default 60 minutes, maximum 1440). |
+| `MOTEL_OTEL_TRACE_LIMIT` | `100` | Trace count for the TUI and for CLI trace commands that omit a limit. HTTP list routes send their own `limit`. |
+| `MOTEL_OTEL_LOG_LIMIT` | `80` | Log count for TUI service logs, TUI trace logs, and CLI log commands. HTTP log routes send their own `limit`. |
+| `MOTEL_OTEL_QUERY_CAPACITY` | `8` (maximum 64) | Outstanding readonly queries per runtime. Overload is HTTP 503 `QUERY_OVERLOADED`. |
+| `MOTEL_OTEL_QUERY_DEADLINE_MS` | `5000` (maximum 30000) | Queue plus startup deadline for one readonly query. Expiry is HTTP 504 `QUERY_DEADLINE`. |
+| `MOTEL_OTEL_RETENTION_HOURS` | `168` | Age cutoff for completed traces and for logs. |
+| `MOTEL_OTEL_MAX_DB_SIZE_MB` | `1024` | Active-data target in MB: `(page_count - freelist_count) * page_size`. Not a hard file-size cap. |
+| `MOTEL_OTEL_RETENTION_TRACE_BATCH` | `100` | Completed traces marked per cleanup pass. |
+| `MOTEL_OTEL_RETENTION_ROW_BATCH` | `1000` | Rows deleted per cleanup pass, split across traces and logs. Bounds row count, not the size of one field. |
+| `MOTEL_OTEL_RETENTION_LOG_BATCH` | `5000` | Logs marked per cleanup pass. |
+| `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS` | `10` | Delay after an idle cleanup pass. Cleanup that is still making progress waits 100 ms. |
+
 ## How agents connect
 
 Agents with the `motel-debug` skill installed will automatically use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryasaatvik/motel",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",
@@ -26,8 +26,9 @@
   "workspaces": [
     "web"
   ],
+  "packageManager": "bun@1.4.4",
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.4"
   },
   "publishConfig": {
     "access": "public",

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 = `