dsh-manage-session 0.4.8 → 0.5.3

package/src/host/index/rebuild.ts

@@ -0,0 +1,368 @@
+/**
+ * Non-destructive index rebuild ("整理索引") for the independent index.
+ *
+ * A shadow index file is built from scratch beside the active one; the active
+ * engine keeps serving queries the whole time. When the shadow is complete the
+ * swap is three synchronous renames (active → archive, shadow → active), then
+ * the engine reopens. Old archives are kept (bounded) and stay readable.
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, rename, rm, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { SwitchIndexEngine } from './engine.ts'
+import { extractTitleFromEvents, type SwitchRawEvent } from './extract.ts'
+import type { SwitchArchiveSource } from './sync.ts'
+
+/** The corpus reader a rebuild needs (same faces as the syncer). */
+export interface SwitchRebuildSessionQuery {
+  listSessions(): Promise<readonly { header: { id: string; version: number; createdAt?: number; cwd?: string } }[]>
+  readSession(sessionId: string): Promise<{
+    session: { id: string; version: number; createdAt?: number; cwd?: string }
+    events: readonly SwitchRawEvent[]
+  }>
+}
+
+/** Live rebuild progress reported to the status endpoint. */
+export interface SwitchRebuildState {
+  state: 'idle' | 'building' | 'swapping' | 'error'
+  /** Sessions written into the shadow index so far. */
+  done: number
+  /** Sessions seen in the corpus when the build started. */
+  total: number
+  /** Epoch ms when the build started. */
+  startedAt: number
+  /** Epoch ms when the last build finished. */
+  finishedAt: number
+  /** Per-session failures during the last build. */
+  failures: { sessionId: string; error: string }[]
+  error?: string
+}
+
+/** Filesystem layout of one index directory. */
+export interface SwitchIndexLayout {
+  /** Directory holding every index file. */
+  dir: string
+  /** Active index file name. */
+  active: string
+  /** Shadow file name used while building. */
+  building: string
+  /** Archive file name prefix. */
+  archivePrefix: string
+}
+
+/** Default layout names. */
+export const DEFAULT_INDEX_LAYOUT: SwitchIndexLayout = {
+  dir: '.',
+  active: 'index.sqlite',
+  building: 'index.building.sqlite',
+  archivePrefix: 'index.archive-',
+}
+
+/**
+ * Inspect the index directory for half-built leftovers from an abnormally
+ * terminated rebuild and recover:
+ * - shadow present + active present: the build never finished — the shadow
+ *   is garbage (the active index kept serving) and is discarded.
+ * - shadow present + active missing: the crash hit the rename window — the
+ *   newest archive is restored as the active index, the shadow discarded.
+ * Runs at host activation, before the engine opens (opening would create a
+ * fresh empty active file and mask the swap-window case).
+ */
+export async function recoverIndex(
+  layout: SwitchIndexLayout,
+  log?: (msg: string) => void,
+): Promise<string[]> {
+  const actions: string[] = []
+  await mkdir(layout.dir, { recursive: true })
+  const activePath = join(layout.dir, layout.active)
+  const buildingPath = join(layout.dir, layout.building)
+  const activeExists = existsSync(activePath)
+  if (!existsSync(buildingPath)) return actions
+  const discardShadow = async (): Promise<void> => {
+    for (const suffix of ['', '-wal', '-shm']) {
+      await rm(`${buildingPath}${suffix}`, { force: true })
+    }
+  }
+  if (activeExists) {
+    await discardShadow()
+    actions.push(`discarded stale shadow index (a previous rebuild did not finish; the active index was never at risk)`)
+  } else {
+    const archives = await listArchives(layout)
+    if (archives.length > 0) {
+      const newest = archives[archives.length - 1]
+      await rename(join(layout.dir, newest), activePath)
+      actions.push(`active index was missing (crash during the swap window); restored "${newest}" as the active index`)
+    } else {
+      actions.push('no active index and no archive: the first build crashed mid-way; starting from a fresh index')
+    }
+    await discardShadow()
+  }
+  for (const action of actions) log?.(`index recovery: ${action}`)
+  return actions
+}
+
+/** List existing archive files, oldest first. */
+export async function listArchives(layout: SwitchIndexLayout): Promise<string[]> {
+  if (!existsSync(layout.dir)) return []
+  const entries = await readdir(layout.dir)
+  return entries.filter(name => name.startsWith(layout.archivePrefix) && name.endsWith('.sqlite')).sort()
+}
+
+/**
+ * Build a fresh index into the shadow file, then swap it in atomically.
+ *
+ * During the build the caller's active engine stays open and queryable; only
+ * the final swap briefly reopens the handle.
+ * @param activeEngine - the currently-serving engine (its file is replaced).
+ * @param layout - filesystem layout of the index directory.
+ * @param sessionQuery - corpus reader for the full rebuild.
+ * @param keepArchives - how many archive files to retain (oldest pruned).
+ * @param onProgress - optional progress callback after each session.
+ * @returns the rebuild state snapshot after completion.
+ */
+/** Optional observability callbacks for rebuildIndex. */
+export interface SwitchRebuildHooks {
+  /** Progress log line sink (cordis logger bridge). */
+  log?: (msg: string) => void
+  /** State-mutation sink: called after every change so index-status sees
+   * live progress (the "0/?" bug was state cloned only at completion). */
+  onState?: (state: SwitchRebuildState) => void
+  /**
+   * 文件级兜底读取器（与同步器同语义）：readSession 对归档/服务面退化会话
+   * 失败时改读转录文件；返回 undefined 表示文件也不可用（记失败）。
+   */
+  readSessionFromFile?: (sessionId: string) => Promise<{
+    session: { id: string; version: number; createdAt?: number; cwd?: string }
+    events: readonly SwitchRawEvent[]
+  } | undefined>
+}
+
+/** Sessions per batched transaction (one fsync checkpoint per chunk). */
+const REBUILD_CHUNK = 50
+
+export async function rebuildIndex(
+  activeEngine: SwitchIndexEngine,
+  layout: SwitchIndexLayout,
+  sessionQuery: SwitchRebuildSessionQuery,
+  keepArchives: number,
+  onProgress?: (done: number, total: number) => void,
+  archiveSource?: () => SwitchArchiveSource | undefined,
+  hooks?: SwitchRebuildHooks,
+): Promise<SwitchRebuildState> {
+  const startedMs = Date.now()
+  let docsWritten = 0
+  const emit = (): void => { hooks?.onState?.({ ...state }) }
+  const rate = (): string => {
+    const secs = Math.max(0.001, (Date.now() - startedMs) / 1000)
+    return `${(state.done / secs).toFixed(1)} sess/s`
+  }
+  const eta = (): string => {
+    if (state.total <= 0 || state.done === 0) return '?'
+    const secs = (Date.now() - startedMs) / 1000
+    return `${Math.max(0, Math.round((state.total - state.done) / (state.done / secs)))}s`
+  }
+  const state: SwitchRebuildState = {
+    state: 'building',
+    done: 0,
+    total: 0,
+    startedAt: Date.now(),
+    finishedAt: 0,
+    failures: [],
+  }
+  try {
+    hooks?.log?.(`rebuild started: dir=${layout.dir} keep=${keepArchives}`)
+    emit()
+    await mkdir(layout.dir, { recursive: true })
+    const buildingPath = join(layout.dir, layout.building)
+    // A stale shadow from a crashed run is discarded.
+    if (existsSync(buildingPath)) await unlink(buildingPath)
+    const shadow = new SwitchIndexEngine({ path: buildingPath })
+    await shadow.open()
+    try {
+      const records = await sessionQuery.listSessions()
+      state.total = records.length
+      hooks?.log?.(`rebuild corpus listed: ${state.total} sessions (archived included, full content)`)
+      emit()
+      // R1 合表语义：归档会话**同样全量读内容**入影子索引（readSession 对归档是
+      // replay-validate 不激活）；构建完成后按官方归档集合统一翻 flag。
+      const archivedSet = new Set(archiveSource?.()?.archivedSessionIds ?? [])
+      const readLog = async (header: { id: string; version: number; createdAt?: number; cwd?: string }) => {
+        let log: { session: { id: string; version: number; createdAt?: number; cwd?: string }; events: readonly SwitchRawEvent[] }
+        try {
+          log = await sessionQuery.readSession(header.id)
+        } catch (serviceError) {
+          if (hooks?.readSessionFromFile === undefined) throw serviceError
+          const fromFile = await hooks.readSessionFromFile(header.id)
+          if (fromFile === undefined) throw serviceError
+          log = fromFile
+        }
+        return {
+          sessionId: header.id,
+          version: log.session.version,
+          // 标题基础层随重建落行(beta.5 教训:重建不抽标题 + 版本对齐后同步
+          // 永不重读 = 全库标题永久空缺)。
+          title: extractTitleFromEvents(log.events),
+          cwd: log.session.cwd ?? '',
+          updatedAt: log.session.createdAt ?? 0,
+          archived: archivedSet.has(header.id),
+          events: log.events,
+        }
+      }
+      for (let i = 0; i < records.length; i += REBUILD_CHUNK) {
+        const chunk = records.slice(i, i + REBUILD_CHUNK)
+        const chunkStart = Date.now()
+        const reads: Array<{ sessionId: string; version: number; cwd: string; updatedAt: number; archived: boolean; events: readonly SwitchRawEvent[] }> = []
+        for (const record of chunk) {
+          try {
+            reads.push(await readLog(record.header))
+          } catch (err) {
+            state.failures.push({ sessionId: record.header.id, error: String(err instanceof Error ? err.message : err) })
+          }
+        }
+        // One transaction per chunk = one checkpoint; a chunk-level failure
+        // replays session-by-session to keep the bad session isolated.
+        try {
+          shadow.runBatched(() => {
+            for (const item of reads) {
+              shadow.upsertSession(item)
+              docsWritten += item.events.length
+            }
+          })
+        } catch (err) {
+          hooks?.log?.(`rebuild chunk txn failed, replaying individually: ${String(err instanceof Error ? err.message : err)}`)
+          for (const item of reads) {
+            try { shadow.upsertSession(item); docsWritten += item.events.length }
+            catch (e2) { state.failures.push({ sessionId: item.sessionId, error: String(e2 instanceof Error ? e2.message : e2) }) }
+          }
+        }
+        state.done = Math.min(state.total, i + chunk.length)
+        onProgress?.(state.done, state.total)
+        emit()
+        hooks?.log?.(`rebuild ${state.done}/${state.total} (${Math.round((state.done / Math.max(1, state.total)) * 100)}%) ${rate()} elapsed ${Math.round((Date.now() - startedMs) / 1000)}s eta ${eta()} chunk ${Date.now() - chunkStart}ms`)
+      }
+      // 归档标记统一翻转（upsertSession 不动已有行的 flag,此处是影子库的最终真值）。
+      shadow.setArchived(archivedSet)
+      shadow.close()
+    } catch (error) {
+      shadow.close()
+      await unlink(buildingPath).catch(() => {})
+      throw error
+    }
+
+    state.state = 'swapping'
+    emit()
+    hooks?.log?.(`rebuild shadow complete: ${state.done} sessions, ~${docsWritten} docs, ${state.failures.length} failures; swapping`)
+    // The swap window is three synchronous renames; queries fail only inside it.
+    const activePath = join(layout.dir, layout.active)
+    if (existsSync(activePath)) {
+      activeEngine.close()
+      await rename(activePath, join(layout.dir, `${layout.archivePrefix}${Date.now()}.sqlite`))
+    }
+    await rename(buildingPath, activePath)
+    await activeEngine.open()
+    await pruneArchives(layout, keepArchives)
+    state.finishedAt = Date.now()
+    state.state = 'idle'
+    emit()
+    hooks?.log?.(`rebuild done: total ${((state.finishedAt - startedMs) / 1000).toFixed(1)}s, archives pruned to ${keepArchives}`)
+  } catch (err) {
+    state.state = 'error'
+    state.error = String(err instanceof Error ? err.message : err)
+    hooks?.log?.(`rebuild FAILED at done=${state.done}: ${state.error}`)
+    emit()
+    // Leave the active engine usable if the swap itself failed before rename.
+    if (!activeEngine.isOpen) await activeEngine.open().catch(() => {})
+  }
+  return state
+}
+
+/** One doc-level record the snapshot importer feeds in. */
+export interface SwitchImportRecord {
+  sessionId: string
+  version: number
+  title?: string
+  /** 归档标记（旧快照缺省活跃）。 */
+  archived?: boolean
+  docs: readonly { seq: number; type: string; surface: string; time: number; text: string }[]
+}
+
+/** Import doc-level records into the shadow file and swap it in (same swap path). */
+export async function importIntoIndex(
+  activeEngine: SwitchIndexEngine,
+  layout: SwitchIndexLayout,
+  records: readonly SwitchImportRecord[],
+  keepArchives: number,
+): Promise<SwitchRebuildState> {
+  const state: SwitchRebuildState = {
+    state: 'building',
+    done: 0,
+    total: records.length,
+    startedAt: Date.now(),
+    finishedAt: 0,
+    failures: [],
+  }
+  try {
+    await mkdir(layout.dir, { recursive: true })
+    const buildingPath = join(layout.dir, layout.building)
+    if (existsSync(buildingPath)) await unlink(buildingPath)
+    const shadow = new SwitchIndexEngine({ path: buildingPath })
+    await shadow.open()
+    try {
+      for (const record of records) {
+        try {
+          shadow.importSessionDocs({
+            sessionId: record.sessionId,
+            version: record.version,
+            title: record.title ?? '',
+            archived: record.archived === true,
+            docs: record.docs,
+          })
+        } catch (err) {
+          state.failures.push({ sessionId: record.sessionId, error: String(err instanceof Error ? err.message : err) })
+        }
+        state.done += 1
+      }
+      shadow.close()
+    } catch (error) {
+      shadow.close()
+      await unlink(buildingPath).catch(() => {})
+      throw error
+    }
+    state.state = 'swapping'
+    const activePath = join(layout.dir, layout.active)
+    if (existsSync(activePath)) {
+      activeEngine.close()
+      await rename(activePath, join(layout.dir, `${layout.archivePrefix}${Date.now()}.sqlite`))
+    }
+    await rename(buildingPath, activePath)
+    await activeEngine.open()
+    await pruneArchives(layout, keepArchives)
+    state.finishedAt = Date.now()
+    state.state = 'idle'
+  } catch (err) {
+    state.state = 'error'
+    state.error = String(err instanceof Error ? err.message : err)
+    if (!activeEngine.isOpen) await activeEngine.open().catch(() => {})
+  }
+  return state
+}
+
+/** Remove the oldest archives beyond the retention bound. */
+async function pruneArchives(layout: SwitchIndexLayout, keep: number): Promise<void> {
+  const archives = await listArchives(layout)
+  const excess = archives.length - Math.max(0, keep)
+  for (let i = 0; i < excess; i += 1) {
+    await unlink(join(layout.dir, archives[i])).catch(() => {})
+  }
+}
+
+/**
+ * Resolve the index directory that hosts the independent index files:
+ * an explicit override wins, otherwise a plugin-owned directory under the
+ * user's home (never the official index path).
+ */
+export function resolveIndexDir(preferred?: string): string {
+  if (preferred !== undefined && preferred.trim() !== '') return preferred
+  return join(homedir(), '.dsh-switch-search')
+}

package/src/host/index/schema.ts

@@ -0,0 +1,136 @@
+/**
+ * SQLite schema for the independent switch-search full-text index.
+ *
+ * Fully separate from the official session-query derived index: a different
+ * application id, a different schema version lineage, and a plugin-owned file
+ * path. The official file (application id 0x44534851) is never opened here.
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { mkdir } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+/** Current switch-search index schema version. Incompatible versions reset in place.
+ * v5: 归档会话正文入索引（v4 库里归档行是 header-only,语义不兼容 → 就地重置重建）。 */
+export const SWITCH_SEARCH_SCHEMA_VERSION = 5
+
+/** Application id marking files owned by this plugin's index (ASCII "SWIS"). */
+export const SWITCH_SEARCH_APPLICATION_ID = 0x53574954
+
+/** The official derived-index application id this plugin must never touch. */
+export const OFFICIAL_SESSION_QUERY_APPLICATION_ID = 0x44534851
+
+/**
+ * Which SQLite driver served the handle (better-sqlite3 when the optional
+ * dependency installed, node:sqlite otherwise). Surfaced in logs and
+ * index-status so rebuild speed can be compared across drivers.
+ */
+export type SwitchSqliteDriver = 'better-sqlite3' | 'node:sqlite'
+
+/**
+ * Open the raw handle: better-sqlite3 (synchronous, faster statement
+ * dispatch) when the optional dependency is present, node:sqlite otherwise.
+ * Both expose the same prepare/exec/close shape this plugin uses.
+ */
+async function openRawHandle(actual: string): Promise<{ db: DatabaseSync; driver: SwitchSqliteDriver }> {
+  try {
+    // Non-literal specifier keeps typecheck green when the optional native
+    // dependency is absent; tsdown externalizes it via neverBundle.
+    const spec = 'better-sqlite3'
+    const mod = (await import(spec)) as unknown as { default?: new (p: string) => DatabaseSync }
+    const Ctor = mod.default ?? (mod as unknown as new (p: string) => DatabaseSync)
+    return { db: new Ctor(actual), driver: 'better-sqlite3' }
+  } catch {
+    const { DatabaseSync } = await import('node:sqlite')
+    return { db: new DatabaseSync(actual), driver: 'node:sqlite' }
+  }
+}
+
+/**
+ * Open, validate, and initialize one switch-search index file.
+ * Missing directories and files are created; a file that belongs to another
+ * application (including the official session-query index) is refused.
+ * @param path - absolute path to the index file.
+ * @returns initialized database handle owned by the caller, plus the driver.
+ */
+export async function openIndexDatabase(path: string): Promise<{ db: DatabaseSync; driver: SwitchSqliteDriver }> {
+  const actual = resolve(path)
+  await mkdir(dirname(actual), { recursive: true })
+  const { db, driver } = await openRawHandle(actual)
+  try {
+    const { application_id: applicationId } = db.prepare('PRAGMA application_id').get() as { application_id: number }
+    const { user_version: version } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+    if (applicationId === OFFICIAL_SESSION_QUERY_APPLICATION_ID) {
+      throw new Error(`switch-search: "${actual}" is the official session-query index, refusing to open it`)
+    }
+    if (applicationId !== 0 && applicationId !== SWITCH_SEARCH_APPLICATION_ID) {
+      throw new Error(`switch-search: database at "${actual}" belongs to another application`)
+    }
+    if (applicationId === SWITCH_SEARCH_APPLICATION_ID && version !== SWITCH_SEARCH_SCHEMA_VERSION) {
+      resetSchema(db)
+    }
+    db.exec(`PRAGMA journal_mode = wal`)
+    ensureSchema(db)
+    // Write-throughput pragmas: NORMAL is crash-safe under WAL (fsync moves
+    // to checkpoints), MEMORY temp + a 64MB page cache mostly serve rebuilds.
+    db.exec(`PRAGMA synchronous = NORMAL`)
+    db.exec(`PRAGMA temp_store = MEMORY`)
+    db.exec(`PRAGMA cache_size = -65536`)
+    return { db, driver }
+  } catch (error: unknown) {
+    db.close()
+    throw error
+  }
+}
+
+/** Reset an incompatible database in place, preserving the owning application id. */
+function resetSchema(db: DatabaseSync): void {
+  db.exec(`
+    PRAGMA writable_schema = OFF;
+    PRAGMA journal_mode = delete;
+  `)
+  for (const row of db.prepare(`
+    SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+  `).all() as { name: string }[]) {
+    db.exec(`DROP TABLE IF EXISTS "${row.name.replace(/"/g, '""')}"`)
+  }
+  db.exec(`PRAGMA user_version = 0`)
+}
+
+/** Create the persistent schema when absent. */
+function ensureSchema(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id TEXT PRIMARY KEY,
+      version INTEGER NOT NULL DEFAULT 0,
+      title TEXT NOT NULL DEFAULT '',
+      cwd TEXT NOT NULL DEFAULT '',
+      updated_at INTEGER NOT NULL DEFAULT 0,
+      indexed_at INTEGER NOT NULL DEFAULT 0,
+      archived INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE TABLE IF NOT EXISTS docs (
+      doc_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      seq INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      surface TEXT NOT NULL,
+      time INTEGER NOT NULL,
+      text TEXT NOT NULL,
+      index_text TEXT NOT NULL DEFAULT ''
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS docs_session_seq ON docs(session_id, seq);
+    CREATE INDEX IF NOT EXISTS docs_session ON docs(session_id);
+    CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+      index_text,
+      content = 'docs',
+      content_rowid = 'doc_id',
+      tokenize = 'unicode61'
+    );
+  `)
+  db.exec(`PRAGMA application_id = ${SWITCH_SEARCH_APPLICATION_ID}`)
+  db.exec(`PRAGMA user_version = ${SWITCH_SEARCH_SCHEMA_VERSION}`)
+}

package/src/host/index/snapshot.ts

@@ -0,0 +1,135 @@
+/**
+ * JSON Lines snapshot migration for the independent switch-search index.
+ *
+ * The snapshot is the "translation" seam: one JSON object per line, carrying a
+ * session's indexed documents in a self-contained shape. Export writes the
+ * active index out; import parses the lines and rebuilds them into a fresh
+ * shadow index that swaps in atomically (same swap path as 整理).
+ */
+import type { SwitchIndexEngine } from './engine.ts'
+import type { SwitchImportRecord } from './rebuild.ts'
+
+/** Snapshot format header line. */
+export interface SwitchSnapshotHeader {
+  v: 1
+  kind: 'dsh-switch-search-snapshot'
+  exportedAt: number
+}
+
+/** One snapshot line: a session and its indexed documents. */
+export interface SwitchSnapshotRecord {
+  v: 1
+  sessionId: string
+  version: number
+  title: string
+  /** 归档标记随快照往返；旧快照缺省按活跃导入。 */
+  archived?: boolean
+  docs: {
+    seq: number
+    type: string
+    surface: string
+    time: number
+    text: string
+  }[]
+}
+
+/** Render the snapshot header line. */
+export function snapshotHeader(): string {
+  return JSON.stringify({
+    v: 1,
+    kind: 'dsh-switch-search-snapshot',
+    exportedAt: Date.now(),
+  } satisfies SwitchSnapshotHeader)
+}
+
+/**
+ * Export the whole index (active AND archived) as a JSON Lines string.
+ * 归档行带 archived 标记一起导出——快照是完整备份,不是活跃子集。
+ * @param engine - the open active engine.
+ * @returns the complete snapshot text (header line first).
+ */
+export function exportSnapshot(engine: SwitchIndexEngine): string {
+  const lines: string[] = [snapshotHeader()]
+  for (const session of engine.listIndexedSessions()) {
+    lines.push(JSON.stringify({
+      v: 1,
+      sessionId: session.sessionId,
+      version: session.version,
+      title: session.title,
+      ...(session.archived ? { archived: true } : {}),
+      docs: engine.exportSessionDocs(session.sessionId),
+    } satisfies SwitchSnapshotRecord))
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/** One parsed snapshot: importable records plus skipped-line count. */
+export interface SwitchParsedSnapshot {
+  records: SwitchImportRecord[]
+  skipped: number
+}
+
+/**
+ * Parse a snapshot's JSON Lines text into importable records.
+ * The header line and any malformed line are skipped, not fatal.
+ * @param text - raw snapshot text.
+ * @returns importable records and how many lines were skipped.
+ */
+export function parseSnapshot(text: string): SwitchParsedSnapshot {
+  const records: SwitchImportRecord[] = []
+  let skipped = 0
+  for (const line of text.split(/\r?\n/)) {
+    if (line.trim() === '') continue
+    let value: unknown
+    try {
+      value = JSON.parse(line)
+    } catch {
+      skipped += 1
+      continue
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      skipped += 1
+      continue
+    }
+    const record = value as Record<string, unknown>
+    // The snapshot header line is recognized and skipped silently.
+    if (record['kind'] === 'dsh-switch-search-snapshot') continue
+    const sessionId = record['sessionId']
+    const rawDocs = record['docs']
+    if (typeof sessionId !== 'string' || sessionId === '' || !Array.isArray(rawDocs)) {
+      skipped += 1
+      continue
+    }
+    const docs: { seq: number; type: string; surface: string; time: number; text: string }[] = []
+    let docsValid = true
+    for (const rawDoc of rawDocs) {
+      if (typeof rawDoc !== 'object' || rawDoc === null
+        || typeof (rawDoc as { seq?: unknown }).seq !== 'number'
+        || typeof (rawDoc as { type?: unknown }).type !== 'string'
+        || typeof (rawDoc as { text?: unknown }).text !== 'string') {
+        docsValid = false
+        break
+      }
+      const doc = rawDoc as { seq: number; type: string; surface?: unknown; time?: unknown; text: string }
+      docs.push({
+        seq: doc.seq,
+        type: doc.type,
+        surface: typeof doc.surface === 'string' ? doc.surface : 'current',
+        time: typeof doc.time === 'number' ? doc.time : 0,
+        text: doc.text,
+      })
+    }
+    if (!docsValid) {
+      skipped += 1
+      continue
+    }
+    records.push({
+      sessionId,
+      version: typeof record['version'] === 'number' ? record['version'] : 0,
+      title: typeof record['title'] === 'string' ? record['title'] : undefined,
+      archived: record['archived'] === true,
+      docs,
+    })
+  }
+  return { records, skipped }
+}