@aryasaatvik/motel 0.5.0 → 0.5.2

package/AGENTS.md

@@ -90,7 +90,7 @@ The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugi
 - `src/ui/useKeyboardNav.ts` centralises the keyboard handlers and
   cross-pane navigation state transitions.
 - `src/motel.ts` composes and runs the public Effect command tree; `src/cli.ts` exports typed telemetry query leaves and handlers.
-- `src/runtime.ts` wires the Effect beta runtime and OTEL trace + log exporters.
+- `src/runtime.ts` wires the Effect runtime and OTEL trace + log exporters.
 - `src/localServer.ts` starts the local Bun OTLP/query server.
 - `src/httpApi.ts` defines the typed Effect HttpApi surface and OpenAPI spec for the local server.
 - `src/httpListPolicy.ts` owns pure HTTP list/search parameter decoding, bounds, cursors, and pagination metadata shaping.
@@ -118,7 +118,7 @@ The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugi
 ## Effect Observability Guidance
 - Inspect the target repo’s existing Effect runtime and observability wiring before adding anything new.
 - Prefer the repo’s existing Effect-native observability APIs if available.
-- If `effect/unstable/observability` is already the best fit, prefer it over adding `@effect/opentelemetry`.
+- If `effect/observability` is already the best fit, prefer it over adding `@effect/opentelemetry`.
 - Only add new OpenTelemetry SDK packages when the repo already uses them or they are clearly required.
 - Merge telemetry into the main runtime once, not per-feature.
 - Prefer structured log annotations so fields like `sessionID`, `modelID`, `providerID`, and `tool` are queryable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryasaatvik/motel",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",
@@ -98,10 +98,10 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@effect/atom-react": "4.0.0-rc.117",
-    "@effect/opentelemetry": "4.0.0-rc.117",
-    "@effect/platform-bun": "4.0.0-rc.117",
-    "@effect/platform-node-shared": "4.0.0-rc.117",
+    "@effect/atom-react": "4.0.0",
+    "@effect/opentelemetry": "4.0.0",
+    "@effect/platform-bun": "4.0.0",
+    "@effect/platform-node-shared": "4.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.219.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
@@ -112,7 +112,7 @@
     "@opentelemetry/sdk-trace-node": "^2.8.0",
     "@opentui/core": "0.4.2",
     "@opentui/react": "0.4.2",
-    "effect": "4.0.0-rc.117",
+    "effect": "4.0.0",
     "protobufjs": "7.6.4",
     "react": "^19.2.7",
     "scheduler": "^0.27.0"

package/skills/motel-debug/references/effect.md

@@ -6,7 +6,7 @@ Apply these only when the target repo already uses Effect or `@effect/*`.
 
 - Inspect the existing runtime and observability wiring before adding anything new.
 - Prefer the repo's existing Effect-native observability APIs if they already exist.
-- If `effect/unstable/observability` is already the best fit, prefer it over adding new OTEL packages.
+- If `effect/observability` is already the best fit, prefer it over adding new OTEL packages.
 - Merge telemetry into the main runtime once, not per feature or per request path.
 
 ## Instrumentation

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { Console, Effect, Option, References } from "effect"
-import { Argument, Command } from "effect/unstable/cli"
+import { Argument, Command } from "effect/cli"
 import { config } from "./config.js"
 import { otelServerInstructions } from "./instructions.js"
 import { attributeFiltersFromArgs, isAttributeFilterToken } from "./queryFilters.js"

package/src/httpApi.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect"
-import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/http-api"
 import {
 	AiCallSummary, AiCallDetail,
 	FacetItem, StatsItem, TraceSpanStatus,

package/src/localServer.ts

@@ -1,11 +1,11 @@
 import path from "node:path"
 import { Effect, FileSystem, Layer } from "effect"
 import { config } from "./config.js"
-import { HttpApiBuilder, HttpApiScalar } from "effect/unstable/httpapi"
-import * as HttpMiddleware from "effect/unstable/http/HttpMiddleware"
-import * as HttpRouter from "effect/unstable/http/HttpRouter"
-import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
-import * as HttpStaticServer from "effect/unstable/http/HttpStaticServer"
+import { HttpApiBuilder, HttpApiScalar } from "effect/http-api"
+import * as HttpMiddleware from "effect/http/HttpMiddleware"
+import * as HttpRouter from "effect/http/HttpRouter"
+import * as HttpServerResponse from "effect/http/HttpServerResponse"
+import * as HttpStaticServer from "effect/http/HttpStaticServer"
 import * as BunHttpServer from "@effect/platform-bun/BunHttpServer"
 import { MotelHttpApi } from "./httpApi.js"
 import { AI_LIST, LOG_LIST, LOG_STATS, SPAN_LIST, TRACE_LIST, TRACE_STATS, listMeta, logCursorArgs, paginateLogs, paginateSummaries, parseLimit, parseListParams as decodeListParams, parseLookbackMinutes, requestUrl as decodeRequestUrl, traceCursorArgs, type ListBounds, type ListParams } from "./httpListPolicy.js"

package/src/mcp.ts

@@ -2,7 +2,7 @@
 import { BunRuntime, BunStdio } from "@effect/platform-bun"
 import { Effect, Layer, Logger, Schema } from "effect"
 import { MOTEL_VERSION } from "./registry.js"
-import { McpProtocol, McpServer, Tool, Toolkit } from "effect/unstable/ai"
+import { McpProtocol, McpServer, Tool, Toolkit } from "effect/ai"
 import { TraceSpanStatus } from "./domain.js"
 import { MotelClient, MotelClientLive } from "./motelClient.js"
 import { Locator, LocatorLive } from "./locator.js"

package/src/motel.ts

@@ -2,7 +2,7 @@
 
 import { BunRuntime, BunServices } from "@effect/platform-bun"
 import { Console, Effect, Layer } from "effect"
-import { CliOutput, Command, Flag } from "effect/unstable/cli"
+import { CliOutput, Command, Flag } from "effect/cli"
 import packageJson from "../package.json" with { type: "json" }
 import { queryCommands } from "./cli.js"
 import { applyManagedDaemonEnv } from "./daemon.js"

package/src/services/AsyncIngest.ts

@@ -21,9 +21,9 @@
 
 import * as BunWorker from "@effect/platform-bun/BunWorker"
 import { Context, Effect, Latch, Layer, Scope, Schema } from "effect"
-import * as RpcClient from "effect/unstable/rpc/RpcClient"
-import type { RpcClientError } from "effect/unstable/rpc/RpcClientError"
-import type { WorkerError } from "effect/unstable/workers/WorkerError"
+import * as RpcClient from "effect/rpc/RpcClient"
+import type { RpcClientError } from "effect/rpc/RpcClientError"
+import type { WorkerError } from "effect/workers/WorkerError"
 import { IngestProgress, WriterEvent, type IngestReadiness } from "../ingestReadiness.ts"
 import { IngestRpcs } from "./ingestRpc.ts"
 

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/ingestRpc.ts

@@ -18,8 +18,8 @@
  */
 
 import { Schema } from "effect"
-import * as Rpc from "effect/unstable/rpc/Rpc"
-import * as RpcGroup from "effect/unstable/rpc/RpcGroup"
+import * as Rpc from "effect/rpc/Rpc"
+import * as RpcGroup from "effect/rpc/RpcGroup"
 
 export class IngestError extends Schema.TaggedError<IngestError>()("IngestError", {
 	message: Schema.String,

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/services/telemetryWorker.ts

@@ -17,7 +17,7 @@
 import { BunRuntime } from "@effect/platform-bun"
 import * as BunWorkerRunner from "@effect/platform-bun/BunWorkerRunner"
 import { Effect, Layer } from "effect"
-import * as RpcServer from "effect/unstable/rpc/RpcServer"
+import * as RpcServer from "effect/rpc/RpcServer"
 import type { OtlpLogExportRequest, OtlpTraceExportRequest } from "../otlp.ts"
 import { WriterDiagnostics, type WriterEvent } from "../ingestReadiness.ts"
 import { IngestError, IngestRpcs } from "./ingestRpc.ts"