@shawnstack/quickforge 1.7.9 → 1.7.11

package/server/session-state-service.mjs

@@ -1,25 +1,15 @@
 import { createSessionStateRepository, MESSAGES_PAGE_LIMIT_MAX, MESSAGES_SPLIT_VALUE, messageDigest } from './sqlite/session-state-repository.mjs'
 import { getSqliteStorage } from './sqlite/database.mjs'
 
-export const SESSION_STORAGE_PHASES = Object.freeze({
-  JSON_AUTHORITATIVE: 'json_authoritative',
-  CUTOVER_RUNNING: 'cutover_running',
-  JSON_PENDING: 'sqlite_authoritative_json_pending',
-  AUTHORITATIVE: 'authoritative',
-})
-
-// F9 split-on-write gate: sessions whose message array reaches this length are
-// stored incrementally in `session_messages` (body keeps only the split
-// marker). Sessions below the threshold stay inline for backward compatibility.
-export const MESSAGES_SPLIT_THRESHOLD = 200
+// Storage v2 integration: SQLite is the single authoritative session store.
+// The JSON→SQLite phase machine (cutover, mirror queue, JSON write barrier) is
+// retired; the v2 `sessions`/`session_messages`/`session_tombstones` schema
+// (migration v11) is the only representation, and legacy JSON session files are
+// consumed once by importSessionStateFromJson during startup.
 
 let repositoryInstance = null
-let cachedPhase = SESSION_STORAGE_PHASES.JSON_AUTHORITATIVE
-let jsonAdapter = null
-let mirrorAdapter = null
-let drainPromise = null
-let mirrorTimer = null
-const MIRROR_DRAIN_INTERVAL_MS = 1000
+let repositoryInstanceHandle = null
+let initializedAt = null
 
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
@@ -45,68 +35,58 @@ function storage() {
 }
 
 function repository() {
-  if (!repositoryInstance) repositoryInstance = createSessionStateRepository(storage())
+  // Rebuild when the process-wide SQLite handle changed (close/reopen cycles
+  // in tests and restart flows): cached statements are bound to one handle.
+  const handle = storage()
+  if (!repositoryInstance || (repositoryInstanceHandle !== null && repositoryInstanceHandle !== handle)) {
+    repositoryInstance = createSessionStateRepository(handle)
+    repositoryInstanceHandle = handle
+  }
   return repositoryInstance
 }
 
-function stateRow() {
-  return storage().prepare('SELECT * FROM session_storage_state WHERE singleton = 1').get()
-}
-
-function sqliteReadable() {
-  return cachedPhase === SESSION_STORAGE_PHASES.JSON_PENDING || cachedPhase === SESSION_STORAGE_PHASES.AUTHORITATIVE
-}
-
-function requireJsonAdapter(method) {
-  if (typeof jsonAdapter?.[method] !== 'function') throw new Error(`JSON authoritative session adapter does not implement ${method}`)
-  return jsonAdapter[method].bind(jsonAdapter)
-}
-
-export function configureSessionStateService({ repository: configuredRepository, json, mirror, phase } = {}) {
-  if (configuredRepository !== undefined) repositoryInstance = configuredRepository
-  if (json !== undefined) jsonAdapter = json
-  if (mirror !== undefined) mirrorAdapter = mirror
-  if (phase !== undefined) {
-    if (!Object.values(SESSION_STORAGE_PHASES).includes(phase)) throw new TypeError(`Invalid session storage phase: ${phase}`)
-    cachedPhase = phase
+// v2: only the repository override remains testable. The retired phase
+// machine's `json`/`mirror`/`phase` options are accepted and ignored so old
+// call sites keep working while they are cleaned up.
+export function configureSessionStateService({ repository: configuredRepository } = {}) {
+  if (configuredRepository !== undefined) {
+    repositoryInstance = configuredRepository
+    repositoryInstanceHandle = null
   }
 }
 
-export function setSessionStoragePhase(phase, values = {}) {
-  if (!Object.values(SESSION_STORAGE_PHASES).includes(phase)) throw new TypeError(`Invalid session storage phase: ${phase}`)
-  const updatedAt = new Date().toISOString()
-  storage().prepare(`UPDATE session_storage_state SET phase = ?, state_count = ?, digest = ?, backup_file = ?, diagnostic_json = ?, updated_at = ? WHERE singleton = 1`)
-    .run(phase, values.stateCount ?? null, values.digest ?? null, values.backupFile ?? null, values.diagnostic ? JSON.stringify(values.diagnostic) : null, updatedAt)
-  cachedPhase = phase
-  return readSessionStorageState()
-}
-
+// Constant authoritative state (startup-state/诊断展示用): there is no
+// session_storage_state table any more — SQLite is authoritative by
+// construction, and the live session count comes straight from the store.
 export function readSessionStorageState() {
-  const row = stateRow()
-  if (!row) throw new Error('Session storage state is missing')
-  cachedPhase = row.phase
+  let stateCount = null
+  try {
+    stateCount = repository().count()
+  } catch {
+    // SQLite not initialized yet (early startup diagnostics); the phase stays
+    // authoritative, the count is simply unknown until the store opens.
+  }
   return {
-    phase: row.phase,
-    stateCount: row.state_count === null ? null : Number(row.state_count),
-    digest: row.digest,
-    backupFile: row.backup_file,
-    diagnostic: row.diagnostic_json ? JSON.parse(row.diagnostic_json) : null,
-    updatedAt: row.updated_at,
+    phase: 'authoritative',
+    stateCount,
+    digest: null,
+    backupFile: null,
+    diagnostic: null,
+    updatedAt: initializedAt,
   }
 }
 
 export function initializeSessionStateService() {
+  initializedAt = new Date().toISOString()
   return readSessionStorageState()
 }
 
-export function getSessionStoragePhase() {
-  return cachedPhase
-}
-
 export function isSessionStateAuthoritative() {
-  return sqliteReadable()
+  return true
 }
 
+export function stopSessionStateService() {}
+
 function normalizeBucket(value, fallback = null) {
   const scope = value?.scope ?? fallback?.scope ?? 'global'
   if (scope === 'project') {
@@ -204,56 +184,39 @@ function assembleState(record) {
 }
 
 // Decide how an incoming full state should be persisted relative to the
-// currently stored session:
-// - inline: legacy whole-body storage (body keeps its `messages` array).
-// - body-only: split session whose messages are unchanged; body/metadata saved.
-// - replace: full message rewrite (first split / truncation / boundary change).
+// currently stored session. Storage v2 keeps every session's messages in
+// `session_messages` (the repository extracts any `messages` array on save),
+// so only the incremental tail decision remains:
+// - body-only: messages are unchanged (or absent); only the body is saved.
+// - replace: full message rewrite (first save / truncation / in-place edit).
 // - append: only the new tail rows are written (incremental).
 function messageStoragePlan(state, existing) {
   const incoming = state?.messages
-  const isSplit = existing?.state?.messageStorage === MESSAGES_SPLIT_VALUE
-  if (incoming === undefined) return isSplit ? { mode: 'body-only' } : { mode: 'inline' }
+  if (incoming === undefined) return { mode: 'body-only' }
   if (!Array.isArray(incoming)) throw new TypeError('state.messages must be an array')
-  if (isSplit) {
-    const storedCount = repository().messageCount({ scope: existing.scope, projectId: existing.projectId, sessionId: existing.sessionId })
-    if (incoming.length < storedCount) return { mode: 'replace', messages: incoming }
-    const tail = incoming.slice(storedCount)
-    if (tail.length === 0) {
-      if (storedCount > 0) {
-        const last = repository().readMessagesPage({ scope: existing.scope, projectId: existing.projectId, sessionId: existing.sessionId, limit: 1, offset: storedCount - 1 })
-        if (last.messages.length > 0 && last.messages[0].digest !== messageDigest(incoming[storedCount - 1])) {
-          return { mode: 'replace', messages: incoming }
-        }
+  if (!existing) return { mode: 'replace', messages: incoming }
+  if (incoming.length === 0) return { mode: 'replace', messages: incoming }
+  const storedCount = repository().messageCount({ scope: existing.scope, projectId: existing.projectId, sessionId: existing.sessionId })
+  if (incoming.length < storedCount) return { mode: 'replace', messages: incoming }
+  const tail = incoming.slice(storedCount)
+  if (tail.length === 0) {
+    if (storedCount > 0) {
+      const last = repository().readLastMessage({ scope: existing.scope, projectId: existing.projectId, sessionId: existing.sessionId })
+      if (last && last.digest !== messageDigest(incoming[storedCount - 1])) {
+        return { mode: 'replace', messages: incoming }
+      }
+      // Same-length in-place edits in the middle keep count and tail digest
+      // identical; probe one deterministic middle row so the edit is not
+      // silently dropped. A missing row also forces the full rewrite.
+      const midSeq = Math.floor(storedCount / 2)
+      if (midSeq !== storedCount - 1
+        && repository().readMessageDigestAt({ scope: existing.scope, projectId: existing.projectId, sessionId: existing.sessionId, seq: midSeq }) !== messageDigest(incoming[midSeq])) {
+        return { mode: 'replace', messages: incoming }
       }
-      return { mode: 'body-only' }
     }
-    return { mode: 'append', messages: tail }
+    return { mode: 'body-only' }
   }
-  if (incoming.length === 0) return { mode: 'inline' }
-  if (incoming.length >= MESSAGES_SPLIT_THRESHOLD) return { mode: 'replace', messages: incoming }
-  return { mode: 'inline' }
-}
-
-function scheduleSessionJsonMirrorDrain() {
-  if (!sqliteReadable() || !mirrorAdapter || mirrorTimer) return
-  mirrorTimer = setTimeout(() => {
-    mirrorTimer = null
-    void drainSessionJsonMirror().then(({ pending }) => {
-      if (pending > 0) scheduleSessionJsonMirrorDrain()
-    }).catch(() => {
-      scheduleSessionJsonMirrorDrain()
-    })
-  }, MIRROR_DRAIN_INTERVAL_MS)
-  mirrorTimer.unref?.()
-}
-
-export function requestSessionJsonMirrorDrain() {
-  scheduleSessionJsonMirrorDrain()
-}
-
-export function stopSessionStateService() {
-  if (mirrorTimer) clearTimeout(mirrorTimer)
-  mirrorTimer = null
+  return { mode: 'append', messages: tail }
 }
 
 function savePair(state, metadata, options = {}) {
@@ -262,12 +225,7 @@ function savePair(state, metadata, options = {}) {
   const plan = messageStoragePlan(state, existing)
   const record = synchronize(state, metadata, sessionId, existing)
   const finalMetadata = { ...record.metadata }
-  if (plan.mode === 'inline') {
-    if (Array.isArray(state.messages)) {
-      finalMetadata.messageCount = state.messages.length
-      if (finalMetadata.preview === undefined) finalMetadata.preview = previewFromMessages(state.messages)
-    }
-  } else if (plan.mode === 'replace' || plan.mode === 'append') {
+  if (plan.mode === 'replace' || plan.mode === 'append') {
     const fullMessages = Array.isArray(state.messages) ? state.messages : plan.messages
     finalMetadata.messageCount = plan.mode === 'append' ? fullMessages.length : plan.messages.length
     if (finalMetadata.preview === undefined) finalMetadata.preview = previewFromMessages(fullMessages)
@@ -290,37 +248,25 @@ function savePair(state, metadata, options = {}) {
       expectedStateVersion: options.expectedStateVersion,
     })
   }
-  requestSessionJsonMirrorDrain()
-  // F9 Phase 3: surface the storage plan and the exact persisted message count
-  // so agent-manager can maintain its conflict-detection counters without
+  // Surface the storage plan and the exact persisted message count so
+  // agent-manager can maintain its conflict-detection counters without
   // re-reading the message table on every save.
-  const totalMessageCount = plan.mode === 'inline'
-    ? (Array.isArray(state.messages) ? state.messages.length : finalMetadata.messageCount)
-    : repository().messageCount({ scope: saved.scope, projectId: saved.projectId, sessionId: saved.sessionId })
+  const totalMessageCount = repository().messageCount({ scope: saved.scope, projectId: saved.projectId, sessionId: saved.sessionId })
   return { ...saved, messageStoragePlan: plan.mode, messageCount: totalMessageCount }
 }
 
 /**
  * Current message representation of a stored session (conflict detection aid):
- * - `split`: messages live in `session_messages`; `count`/`tailDigest` describe
- *   the stored rows (tail digest = row digest of the last message).
- * - non-split: messages are inline in the body; `count`/`tailDigest` are derived
- *   from the body for parity, but agent-manager conflict detection relies on the
- *   body canonical comparison in that case.
+ * every v2 session is split (`split: true`); `count`/`tailDigest` describe the
+ * stored rows (tail digest = row digest of the last message).
  */
 export function storedMessagesState(sessionId) {
-  if (!sqliteReadable()) return { split: false, count: 0, tailDigest: '' }
   const record = repository().findBySessionId(sessionId)
   if (!record) return { split: false, count: 0, tailDigest: '' }
-  if (record.state?.messageStorage !== MESSAGES_SPLIT_VALUE) {
-    const messages = Array.isArray(record.state.messages) ? record.state.messages : []
-    return { split: false, count: messages.length, tailDigest: messages.length ? messageDigest(messages[messages.length - 1]) : '' }
-  }
   const count = repository().messageCount({ scope: record.scope, projectId: record.projectId, sessionId })
   let tailDigest = ''
   if (count > 0) {
-    const last = repository().readMessagesPage({ scope: record.scope, projectId: record.projectId, sessionId, limit: 1, offset: count - 1 })
-    tailDigest = last.messages[0]?.digest ?? ''
+    tailDigest = repository().readLastMessage({ scope: record.scope, projectId: record.projectId, sessionId })?.digest ?? ''
   }
   return { split: true, count, tailDigest }
 }
@@ -336,17 +282,14 @@ export function sessionMessagesTailDigest(messages) {
 }
 
 export function readSessionStateRecord(sessionId) {
-  if (!sqliteReadable()) return requireJsonAdapter('readRecord')(sessionId)
   return repository().findBySessionId(sessionId)
 }
 
 export function readSessionStateValue(sessionId) {
-  if (!sqliteReadable()) return requireJsonAdapter('readState')(sessionId)
   return assembleState(repository().findBySessionId(sessionId))
 }
 
 export function readSessionMetadataValue(sessionId) {
-  if (!sqliteReadable()) return requireJsonAdapter('readMetadata')(sessionId)
   return repository().findBySessionId(sessionId)?.metadata ?? null
 }
 
@@ -373,8 +316,13 @@ function applyMetadataToState(existing, metadata) {
 }
 
 function metadataBucketChanges(scope, projectId, updateFn) {
-  const snapshot = repository().exportSnapshot().records.filter((record) => !scope || (record.scope === scope && (scope !== 'project' || record.projectId === projectId)) )
-  const current = Object.fromEntries(snapshot.map((record) => [record.sessionId, structuredClone(record.metadata)]))
+  // Metadata-only projection (readSessionMetadataBuckets shape): building the
+  // bucket's current map must never materialize state bodies or message rows.
+  const current = {}
+  for (const bucket of readSessionMetadataBuckets()) {
+    if (scope && (bucket.scope !== scope || (scope === 'project' && bucket.projectId !== projectId))) continue
+    Object.assign(current, bucket.metadata)
+  }
   const updated = updateFn(structuredClone(current))
   if (!isPlainObject(updated)) throw new TypeError('Updated metadata bucket must be a plain object')
   const upserts = []
@@ -401,7 +349,6 @@ function metadataBucketChanges(scope, projectId, updateFn) {
 }
 
 export function updateSessionMetadataBucket(scope, projectId, updateFn) {
-  if (!sqliteReadable()) return requireJsonAdapter('updateMetadataBucket')(scope, projectId, updateFn)
   const changes = metadataBucketChanges(scope, projectId, updateFn)
   if (changes.deletes.length > 0) {
     const error = new TypeError('Metadata bucket updates cannot delete session bodies; use full session delete')
@@ -411,13 +358,24 @@ export function updateSessionMetadataBucket(scope, projectId, updateFn) {
   }
   if (changes.upserts.length > 0) {
     repository().applyBatch({ upserts: changes.upserts })
-    requestSessionJsonMirrorDrain()
   }
   return changes.updated
 }
 
 export function readSessionStateStore(storeName, { scope, projectId } = {}) {
-  if (!sqliteReadable()) return requireJsonAdapter('readStore')(storeName, { scope, projectId })
+  // JSON-era provenance: 'sessions-metadata' has always been a metadata-only
+  // bucket store ({sessionId: metadata}). Loading it must never materialize
+  // state bodies or message rows — read the metadata-only projection straight
+  // from the sessions table; without a filter this returns every bucket's map
+  // merged, matching the JSON-era merged-store read contract.
+  if (storeName === 'sessions-metadata') {
+    const merged = {}
+    for (const bucket of readSessionMetadataBuckets()) {
+      if (scope && (bucket.scope !== scope || (scope === 'project' && bucket.projectId !== projectId))) continue
+      Object.assign(merged, bucket.metadata)
+    }
+    return merged
+  }
   const records = repository().exportSnapshot().records.filter((record) => {
     if (!scope) return true
     if (record.scope !== scope) return false
@@ -426,14 +384,28 @@ export function readSessionStateStore(storeName, { scope, projectId } = {}) {
   return Object.fromEntries(records.map((record) => [record.sessionId, storeName === 'sessions' ? assembleState(record) : record.metadata]))
 }
 
+// Metadata bucket summaries straight from the authoritative sessions table
+// (meta_json projection only — state bodies and message rows are never
+// materialized; the historical OOM lesson). Consumed by session-index
+// wiring and the storage facade's per-bucket metadata updates.
+export function readSessionMetadataBuckets() {
+  const rows = storage().prepare('SELECT scope, project_id, session_id, meta_json FROM sessions ORDER BY scope, project_id, session_id').all()
+  const buckets = new Map()
+  for (const row of rows) {
+    const projectId = row.scope === 'project' ? row.project_id : null
+    const key = `${row.scope}\0${projectId || ''}`
+    if (!buckets.has(key)) buckets.set(key, { scope: row.scope, projectId, metadata: {} })
+    buckets.get(key).metadata[row.session_id] = JSON.parse(row.meta_json)
+  }
+  return [...buckets.values()]
+}
+
 export function saveSessionStatePair({ state, metadata, expectedRevision = null, expectedStateVersion = null } = {}) {
-  if (!sqliteReadable()) return requireJsonAdapter('savePair')({ state, metadata, expectedRevision, expectedStateVersion })
   return savePair(state, metadata ?? deriveMetadata(state), { expectedRevision, expectedStateVersion })
 }
 
 export function saveSessionBody(sessionId, value, { expectedRevision = null } = {}) {
   if (!isPlainObject(value)) throw new TypeError('Session body must be a plain object')
-  if (!sqliteReadable()) return requireJsonAdapter('saveBody')(sessionId, value, { expectedRevision })
   const existing = repository().findBySessionId(sessionId)
   const state = { ...(existing?.state || {}), ...structuredClone(value), id: sessionId }
   const metadata = deriveMetadata(state, existing?.metadata || {})
@@ -442,7 +414,6 @@ export function saveSessionBody(sessionId, value, { expectedRevision = null } =
 
 export function saveSessionMetadata(sessionId, value, { expectedRevision = null } = {}) {
   if (!isPlainObject(value)) throw new TypeError('Session metadata must be a plain object')
-  if (!sqliteReadable()) return requireJsonAdapter('saveMetadata')(sessionId, value, { expectedRevision })
   const existing = repository().findBySessionId(sessionId)
   if (!existing) {
     const error = new Error(`Session state does not exist: ${sessionId}`)
@@ -452,23 +423,17 @@ export function saveSessionMetadata(sessionId, value, { expectedRevision = null
   }
   const metadata = mergeMetadata(existing.metadata, value, sessionId)
   const synchronized = applyMetadataToState(existing, metadata)
-  const saved = repository().save(synchronized, { expectedRevision: expectedRevision ?? existing.revision })
-  requestSessionJsonMirrorDrain()
-  return saved
+  return repository().save(synchronized, { expectedRevision: expectedRevision ?? existing.revision })
 }
 
 export function deleteSessionState(sessionId, { expectedRevision = null } = {}) {
-  if (!sqliteReadable()) return requireJsonAdapter('delete')(sessionId, { expectedRevision })
   const existing = repository().findBySessionId(sessionId)
   if (!existing) return false
-  const deleted = repository().deleteBySessionId(sessionId, { expectedRevision: expectedRevision ?? existing.revision })
-  requestSessionJsonMirrorDrain()
-  return deleted
+  return repository().deleteBySessionId(sessionId, { expectedRevision: expectedRevision ?? existing.revision })
 }
 
 export function replaceSessionStateStore(storeName, values) {
   if (!isPlainObject(values)) throw new TypeError('Session store must be a plain object')
-  if (!sqliteReadable()) return requireJsonAdapter('replaceStore')(storeName, values)
   const current = new Map(repository().exportSnapshot().records.map((record) => [record.sessionId, record]))
   const records = []
   if (storeName === 'sessions') {
@@ -500,12 +465,10 @@ export function replaceSessionStateStore(storeName, values) {
     throw new TypeError(`Unsupported session state store: ${storeName}`)
   }
   repository().replaceAll(records)
-  requestSessionJsonMirrorDrain()
   return values
 }
 
 export async function atomicSessionRecordUpdate(sessionId, updateFn, { maxRetries = 3 } = {}) {
-  if (!sqliteReadable()) return requireJsonAdapter('atomicRecordUpdate')(sessionId, updateFn)
   for (let attempt = 0; attempt < maxRetries; attempt += 1) {
     const existing = repository().findBySessionId(sessionId)
     if (!existing) return null
@@ -532,7 +495,6 @@ export async function atomicSessionRecordUpdate(sessionId, updateFn, { maxRetrie
 }
 
 export async function atomicSessionStateUpdate(sessionId, updateFn, { maxRetries = 3 } = {}) {
-  if (!sqliteReadable()) return requireJsonAdapter('atomicStateUpdate')(sessionId, updateFn)
   for (let attempt = 0; attempt < maxRetries; attempt += 1) {
     const existing = repository().findBySessionId(sessionId)
     if (!existing) return null
@@ -547,7 +509,6 @@ export async function atomicSessionStateUpdate(sessionId, updateFn, { maxRetries
 }
 
 export async function atomicSessionMetadataStateUpdate(scope, projectId, updateFn, { maxRetries = 3 } = {}) {
-  if (!sqliteReadable()) return requireJsonAdapter('atomicMetadataUpdate')(scope, projectId, updateFn)
   for (let attempt = 0; attempt < maxRetries; attempt += 1) {
     try {
       return updateSessionMetadataBucket(scope, projectId, updateFn)
@@ -560,7 +521,15 @@ export async function atomicSessionMetadataStateUpdate(scope, projectId, updateF
 
 export function applySessionBatch(operations) {
   if (!Array.isArray(operations) || operations.length === 0) throw new TypeError('Session batch operations are required')
-  if (!sqliteReadable()) return requireJsonAdapter('applyBatch')(operations)
+  // pi-web-ui's SessionsStore.delete() emits a `sessions` delete AND a
+  // `sessions-metadata` delete for the same key in one transaction. The
+  // metadata delete is subsumed by the grouped full delete (idempotent no-op);
+  // only a metadata delete without a paired body delete stays rejected.
+  const fullDeleteKeys = new Set(
+    operations
+      .filter((operation) => operation?.type === 'delete' && operation?.store === 'sessions')
+      .map((operation) => operation.key),
+  )
   const grouped = new Map()
   for (const operation of operations) {
     if (!['sessions', 'sessions-metadata'].includes(operation?.store)) throw new TypeError('Session batch only accepts sessions and sessions-metadata')
@@ -568,8 +537,11 @@ export function applySessionBatch(operations) {
     if (typeof operation.key !== 'string' || !operation.key) throw new TypeError('Session batch key is required')
     const entry = grouped.get(operation.key) || { sessionId: operation.key }
     if (operation.type === 'delete') {
-      if (operation.store === 'sessions-metadata') throw new TypeError('Metadata-only delete is not allowed')
-      entry.delete = true
+      if (operation.store === 'sessions-metadata') {
+        if (!fullDeleteKeys.has(operation.key)) throw new TypeError('Metadata-only delete is not allowed')
+      } else {
+        entry.delete = true
+      }
     } else if (operation.store === 'sessions') entry.state = operation.value
     else entry.metadata = operation.value
     if (operation.expectedRevision !== undefined) entry.expectedRevision = operation.expectedRevision
@@ -623,12 +595,10 @@ export function applySessionBatch(operations) {
   // succeeds instead of tripping the repository's empty-change guard.
   if (upserts.length === 0 && deletes.length === 0) return { saved: 0, deleted: 0, revisions: [] }
   const result = repository().applyBatch({ upserts, deletes })
-  requestSessionJsonMirrorDrain()
   return { saved: result.saved.length, deleted: result.deleted.filter(Boolean).length, revisions: result.saved.map((record) => ({ sessionId: record.sessionId, revision: record.revision, stateVersion: record.stateVersion })) }
 }
 
 export function exportSessionStateSnapshot() {
-  if (!sqliteReadable()) return requireJsonAdapter('exportSnapshot')()
   const snapshot = repository().exportSnapshot()
   return {
     sessions: Object.fromEntries(snapshot.records.map((record) => [record.sessionId, assembleState(record)])),
@@ -654,56 +624,25 @@ export function normalizeSessionSnapshotValues({ sessions, sessionsMetadata }) {
 
 export function replaceSessionStateSnapshot({ sessions, sessionsMetadata }, { merge = false } = {}) {
   if (!isPlainObject(sessions) || !isPlainObject(sessionsMetadata)) throw new TypeError('sessions and sessionsMetadata must be objects')
-  if (!sqliteReadable()) return requireJsonAdapter('replaceSnapshot')({ sessions, sessionsMetadata }, { merge })
   const current = merge ? exportSessionStateSnapshot() : { sessions: {}, sessionsMetadata: {} }
   const targetSessions = { ...current.sessions, ...sessions }
   const targetMetadata = { ...current.sessionsMetadata, ...sessionsMetadata }
   const records = normalizeSessionSnapshotValues({ sessions: targetSessions, sessionsMetadata: targetMetadata })
   repository().replaceAll(records)
-  requestSessionJsonMirrorDrain()
   return { sessions: records.length, sessionsMetadata: records.length }
 }
 
-export async function drainSessionJsonMirror() {
-  if (drainPromise) return drainPromise
-  drainPromise = (async () => {
-    if (!mirrorAdapter) return { drained: 0, pending: repository().listMirrorQueue().length }
-    let drained = 0
-    for (const entry of repository().listMirrorQueue()) {
-      try {
-        if (entry.operation === 'upsert') {
-          const state = entry.state?.messageStorage === MESSAGES_SPLIT_VALUE
-            ? { ...entry.state, messages: allMessages(entry) }
-            : entry.state
-          await mirrorAdapter.upsert({ ...entry, state })
-        } else {
-          await mirrorAdapter.delete(entry)
-        }
-        repository().acknowledgeMirror(entry)
-        drained += 1
-      } catch (error) {
-        repository().failMirror(entry, error)
-      }
-    }
-    return { drained, pending: repository().listMirrorQueue().length }
-  })().finally(() => { drainPromise = null })
-  const result = await drainPromise
-  if (result.pending > 0) scheduleSessionJsonMirrorDrain()
-  return result
-}
-
 export function getSessionStateDiagnostics() {
-  const state = (() => {
-    try { return readSessionStorageState() } catch { return { phase: cachedPhase } }
-  })()
-  if (!sqliteReadable()) return { ...state, authority: 'json', integrity: null, mirrorPending: null }
+  const state = readSessionStorageState()
   let integrity
-  let mirrorPending = null
   try {
-    integrity = repository().verifyIntegrity()
-    mirrorPending = repository().listMirrorQueue().length
+    // Lightweight (SQL-level) integrity: startup diagnostics on large stores
+    // must not re-parse every stored body. The result carries
+    // `lightweight: true`; full per-row verification stays on maintenance
+    // entry points (backup export/restore, downgrade tooling).
+    integrity = repository().verifyIntegrity({ quickCheck: true })
   } catch (error) {
     integrity = { ok: false, error: error?.message || String(error) }
   }
-  return { ...state, authority: 'sqlite', integrity, mirrorPending }
+  return { ...state, authority: 'sqlite', integrity }
 }

package/server/share-cutover.mjs

@@ -14,6 +14,7 @@ import {
 import { readSharesJsonFile } from './share-json-file.mjs'
 import { createDefaultShareMirror } from './share-service.mjs'
 import { storageDir } from './storage.mjs'
+import { logger } from './utils/logger.mjs'
 
 const DEFAULT_LOCK_TTL_MS = 60_000
 const DEFAULT_WAIT_TIMEOUT_MS = 65_000
@@ -213,23 +214,29 @@ export async function initializeShareCutover(options = {}) {
   const storage = options.storage || getSqliteStorage()
   const repository = options.repository || createShareRepository(storage)
   configureShareService({ repository, mirror: options.mirror || createDefaultShareMirror() })
-  return runShareMaintenance(async () => {
+  const log = options.logger || logger
+  const migrate = async () => {
     const current = readShareStorageState()
     if (current.phase === SHARE_STORAGE_PHASES.JSON_PENDING) {
       const integrity = repository.verifyIntegrity({ quickCheck: true })
       if (!integrity.ok) throw new Error('Share state pending integrity verification failed')
       const drained = await drainShareJsonMirror()
-      if (drained.pending === 0) setShareStoragePhase(SHARE_STORAGE_PHASES.AUTHORITATIVE, { shareCount: integrity.count, digest: integrity.digest, backupFile: current.backupFile })
+      if (drained.pending === 0) {
+        setShareStoragePhase(SHARE_STORAGE_PHASES.AUTHORITATIVE, { shareCount: integrity.count, digest: integrity.digest, backupFile: current.backupFile })
+        log.info('Share storage cutover promoted to authoritative', { domain: 'share', phase: 'authoritative', count: integrity.count })
+      }
       return readShareStorageState()
     }
     if (current.phase === SHARE_STORAGE_PHASES.AUTHORITATIVE) {
       const integrity = repository.verifyIntegrity({ quickCheck: true })
       if (!integrity.ok) throw new Error('Share state authoritative integrity verification failed')
       await drainShareJsonMirror()
+      log.info('Share storage cutover startup check passed', { domain: 'share', phase: 'authoritative' })
       return readShareStorageState()
     }
 
     if (current.phase === SHARE_STORAGE_PHASES.CUTOVER_RUNNING && current.backupFile) {
+      log.warn('Share storage cutover recovery: rerunning the JSON migration', { domain: 'share', phase: 'cutover_running', backupFile: current.backupFile })
       setShareStoragePhase(SHARE_STORAGE_PHASES.JSON_AUTHORITATIVE, {
         backupFile: current.backupFile,
         diagnostic: { operation: 'cutover_recovery', recoveredFrom: SHARE_STORAGE_PHASES.CUTOVER_RUNNING },
@@ -244,6 +251,7 @@ export async function initializeShareCutover(options = {}) {
       if (first.count !== second.count || first.digest !== second.digest) {
         throw new Error('Share JSON source changed during cutover double read')
       }
+      log.info('Share storage cutover migration started', { domain: 'share', count: first.count })
       if (!backupFile) backupFile = await writeShareCutoverBackup(first, options.backupDirectory)
       const third = buildShareJsonSnapshot(await readJson())
       if (first.count !== third.count || first.digest !== third.digest) {
@@ -280,7 +288,9 @@ export async function initializeShareCutover(options = {}) {
           diagnostic: first.diagnostics,
         })
       }
-      return readShareStorageState()
+      const result = readShareStorageState()
+      log.info('Share storage cutover migration complete', { domain: 'share', phase: result.phase, count: first.count })
+      return result
     } catch (error) {
       const state = readShareStorageState()
       if (![SHARE_STORAGE_PHASES.JSON_PENDING, SHARE_STORAGE_PHASES.AUTHORITATIVE].includes(state.phase)) {
@@ -288,9 +298,16 @@ export async function initializeShareCutover(options = {}) {
           backupFile,
           diagnostic: { operation: 'cutover', errorName: error?.name || 'Error', error: error?.message || String(error) },
         })
+        log.warn('Share storage cutover failed; keeping the JSON store path', { domain: 'share', phase: 'json_authoritative', errorName: error?.name || 'Error', errorMessage: error?.message })
         return readShareStorageState()
       }
       throw error
     }
-  }, { ...options, storage, operation: 'share-cutover' })
+  }
+  try {
+    return await runShareMaintenance(migrate, { ...options, storage, operation: 'share-cutover' })
+  } catch (error) {
+    log.error('Share storage cutover failed and blocked startup', { domain: 'share', errorName: error?.name || 'Error', errorMessage: error?.message })
+    throw error
+  }
 }