@shawnstack/quickforge 1.7.10 → 1.7.12

package/server/session-index-service.mjs

@@ -1,168 +1,18 @@
-import { createHash } from 'node:crypto'
 import { createSessionIndexRepository } from './sqlite/session-index-repository.mjs'
 import { getSqliteStorage } from './sqlite/database.mjs'
 import { logger } from './utils/logger.mjs'
 
-const DEFAULT_MAX_REBUILD_ATTEMPTS = 3
-const DEFAULT_VERIFY_TTL_MS = 5_000
+// Storage v2 session index service. The JSON-metadata convergence machinery
+// (shadow verification, verify TTL, scheduled rebuilds, incremental
+// syncMetadataCommit) is retired together with the session_index projection
+// table: queries read the authoritative `sessions` table directly, so there is
+// no second data source that could drift. The service keeps the route-facing
+// boundary (readiness/analysis/queryPage) and the diagnostics shape the
+// /api/system status surface renders.
 
-let defaultReader = null
 let defaultRepository = null
 let activeService = null
 
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
-}
-
-function canonicalValue(value) {
-  if (Array.isArray(value)) return value.map(canonicalValue)
-  if (!isPlainObject(value)) return value
-  const result = {}
-  for (const key of Object.keys(value).sort()) {
-    if (value[key] !== undefined) result[key] = canonicalValue(value[key])
-  }
-  return result
-}
-
-export function canonicalSessionMetadata(metadata, { scope, projectId, sessionId }) {
-  if (!isPlainObject(metadata)) throw new TypeError('Session metadata must be a plain object')
-  const canonical = canonicalValue(metadata)
-  canonical.id = sessionId
-  canonical.scope = scope
-  if (scope === 'project') canonical.projectId = projectId
-  else delete canonical.projectId
-  return canonicalValue(canonical)
-}
-
-function sha256(value) {
-  return createHash('sha256').update(value).digest('hex')
-}
-
-export function sessionMetadataDigest(metadata) {
-  return sha256(JSON.stringify(canonicalValue(metadata)))
-}
-
-export function sessionIndexAggregateDigest(entries) {
-  const normalized = [...entries]
-    .map((entry) => `${entry.scope}\0${entry.projectId || ''}\0${entry.sessionId}\0${entry.metadataDigest}`)
-    .sort()
-  return sha256(normalized.join('\n'))
-}
-
-function normalizeBucket(bucket) {
-  if (!bucket || typeof bucket !== 'object' || Array.isArray(bucket)) throw new TypeError('Session metadata bucket must be an object')
-  if (bucket.scope === 'global') return { scope: 'global', projectId: null }
-  if (bucket.scope !== 'project' || typeof bucket.projectId !== 'string' || !bucket.projectId.trim()) {
-    throw new TypeError('Session metadata bucket scope/projectId is invalid')
-  }
-  return { scope: 'project', projectId: bucket.projectId }
-}
-
-function nullableString(value) {
-  return typeof value === 'string' ? value : null
-}
-
-function nullableInteger(value) {
-  return Number.isInteger(value) && value >= 0 ? value : null
-}
-
-function isCanonicalIso(value) {
-  if (typeof value !== 'string' || !value) return false
-  const timestamp = Date.parse(value)
-  return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value
-}
-
-function fieldCompatibility(metadata, field, { iso = false } = {}) {
-  if (metadata[field] === undefined) return true
-  if (typeof metadata[field] !== 'string') return false
-  return !iso || isCanonicalIso(metadata[field])
-}
-
-function metadataCompatibility(bucket, sessionId, metadata, canonical) {
-  const issues = {
-    keyIdMismatch: metadata.id !== undefined && metadata.id !== sessionId,
-    scopeConflict: (metadata.scope !== undefined && metadata.scope !== bucket.scope)
-      || (bucket.scope === 'project'
-        ? metadata.projectId !== undefined && metadata.projectId !== bucket.projectId
-        : Object.prototype.hasOwnProperty.call(metadata, 'projectId')),
-    invalidCreatedAt: !fieldCompatibility(metadata, 'createdAt', { iso: true }),
-    invalidLastModified: !fieldCompatibility(metadata, 'lastModified', { iso: true }),
-    invalidPinnedAt: !fieldCompatibility(metadata, 'pinnedAt', { iso: true }),
-    invalidArchivedAt: !fieldCompatibility(metadata, 'archivedAt'),
-    canonicalMismatch: JSON.stringify(canonicalValue(metadata)) !== JSON.stringify(canonical),
-  }
-  return { compatible: !Object.values(issues).some(Boolean), issues }
-}
-
-function buildRow(bucket, sessionId, metadata, indexedAt) {
-  const canonical = canonicalSessionMetadata(metadata, { ...bucket, sessionId })
-  return {
-    ...bucket,
-    sessionId,
-    createdAt: nullableString(canonical.createdAt),
-    lastModified: nullableString(canonical.lastModified),
-    messageCount: nullableInteger(canonical.messageCount),
-    pinnedAt: nullableString(canonical.pinnedAt),
-    archivedAt: nullableString(canonical.archivedAt),
-    stateVersion: nullableInteger(canonical.stateVersion),
-    metadata: canonical,
-    metadataDigest: sessionMetadataDigest(canonical),
-    indexedAt,
-  }
-}
-
-function snapshotFromBuckets(buckets, indexedAt) {
-  if (!Array.isArray(buckets)) throw new TypeError('Session metadata reader must return an array')
-  const rows = []
-  const keys = new Set()
-  const sessionBuckets = new Map()
-  const compatibilityIssues = {
-    keyIdMismatch: 0,
-    scopeConflict: 0,
-    invalidCreatedAt: 0,
-    invalidLastModified: 0,
-    invalidPinnedAt: 0,
-    invalidArchivedAt: 0,
-    canonicalMismatch: 0,
-  }
-  let duplicateSessionIdCount = 0
-
-  for (const rawBucket of buckets) {
-    const bucket = normalizeBucket(rawBucket)
-    if (!isPlainObject(rawBucket.metadata)) throw new TypeError('Session metadata bucket content must be a plain object')
-    for (const [sessionId, metadata] of Object.entries(rawBucket.metadata)) {
-      if (!sessionId || !isPlainObject(metadata)) throw new TypeError('Session metadata entries must be keyed plain objects')
-      const compositeKey = `${bucket.scope}\0${bucket.projectId || ''}\0${sessionId}`
-      if (keys.has(compositeKey)) throw new TypeError('Duplicate session metadata bucket composite key')
-      keys.add(compositeKey)
-      const seenBuckets = sessionBuckets.get(sessionId) || 0
-      if (seenBuckets === 1) duplicateSessionIdCount += 1
-      sessionBuckets.set(sessionId, seenBuckets + 1)
-      const row = buildRow(bucket, sessionId, metadata, indexedAt)
-      const compatibility = metadataCompatibility(bucket, sessionId, metadata, row.metadata)
-      for (const [issue, present] of Object.entries(compatibility.issues)) {
-        if (present) compatibilityIssues[issue] += 1
-      }
-      rows.push(row)
-    }
-  }
-
-  rows.sort((left, right) => {
-    const leftKey = `${left.scope}\0${left.projectId || ''}\0${left.sessionId}`
-    const rightKey = `${right.scope}\0${right.projectId || ''}\0${right.sessionId}`
-    return leftKey.localeCompare(rightKey)
-  })
-  return {
-    rows,
-    count: rows.length,
-    digest: sessionIndexAggregateDigest(rows),
-    keyIdMismatchCount: compatibilityIssues.keyIdMismatch,
-    duplicateSessionIdCount,
-    compatibilityIssues,
-    queryCompatible: Object.values(compatibilityIssues).every((count) => count === 0),
-  }
-}
-
 function safeError(error) {
   return {
     name: error instanceof Error ? error.name : 'Error',
@@ -170,148 +20,54 @@ function safeError(error) {
   }
 }
 
-export function createSessionIndexService({
-  repository,
-  readBuckets,
-  now = () => new Date().toISOString(),
-  nowMs = () => Date.now(),
-  verifyTtlMs = DEFAULT_VERIFY_TTL_MS,
-  maxRebuildAttempts = DEFAULT_MAX_REBUILD_ATTEMPTS,
-  log = logger,
-} = {}) {
-  if (!repository || typeof repository.replaceAll !== 'function' || typeof repository.applyChanges !== 'function') {
+export function createSessionIndexService({ repository, log = logger } = {}) {
+  if (!repository || typeof repository.listPage !== 'function' || typeof repository.analyzeQuery !== 'function') {
     throw new TypeError('Session index service requires a repository')
   }
-  if (typeof readBuckets !== 'function') throw new TypeError('Session index service requires a bucket reader')
-
-  let rebuildPromise = null
-  const emptyDigest = sessionIndexAggregateDigest([])
   const diagnostics = {
     status: 'uninitialized',
     initialized: false,
-    degraded: true,
-    dirty: true,
+    degraded: false,
+    dirty: false,
     sourceCount: 0,
-    sourceDigest: emptyDigest,
     indexCount: 0,
-    indexDigest: emptyDigest,
     count: 0,
-    digest: emptyDigest,
     lastVerifiedAt: null,
     rebuildCount: 0,
     rebuildGeneration: 0,
-    keyIdMismatchCount: 0,
     duplicateSessionIdCount: 0,
-    queryCompatible: false,
-    compatibilityIssues: null,
+    queryCompatible: true,
     lastFailure: null,
   }
 
-  async function readSnapshot() {
-    return snapshotFromBuckets(await readBuckets(), now())
-  }
-
-  function indexedVerification() {
-    const entries = repository.listVerification()
-    return { count: entries.length, digest: sessionIndexAggregateDigest(entries) }
-  }
-
-  function projectionIntegrity() {
-    if (typeof repository.listIntegrity !== 'function') return true
-    return repository.listIntegrity().every((row) => {
-      const metadata = row.metadata
-      if (!isPlainObject(metadata)) return false
-      if (row.isArchived !== Boolean(metadata.archivedAt)) return false
-      if (row.isPinned !== Boolean(metadata.pinnedAt)) return false
-      if (row.createdAt !== nullableString(metadata.createdAt)) return false
-      if (row.lastModified !== nullableString(metadata.lastModified)) return false
-      if (row.pinnedAt !== nullableString(metadata.pinnedAt)) return false
-      if (row.archivedAt !== nullableString(metadata.archivedAt)) return false
-      if (row.messageCount !== nullableInteger(metadata.messageCount)) return false
-      return true
-    })
-  }
-
-  function setVerification(snapshot, verification, { dirty = false } = {}) {
-    diagnostics.sourceCount = snapshot.count
-    diagnostics.sourceDigest = snapshot.digest
-    diagnostics.indexCount = verification.count
-    diagnostics.indexDigest = verification.digest
-    diagnostics.count = snapshot.count
-    diagnostics.digest = snapshot.digest
-    diagnostics.keyIdMismatchCount = snapshot.keyIdMismatchCount
-    diagnostics.duplicateSessionIdCount = snapshot.duplicateSessionIdCount
-    diagnostics.queryCompatible = snapshot.queryCompatible
-    diagnostics.compatibilityIssues = { ...snapshot.compatibilityIssues }
-    diagnostics.dirty = dirty
-    diagnostics.degraded = dirty || !snapshot.queryCompatible
-    diagnostics.status = diagnostics.degraded ? 'degraded' : 'ready'
-    diagnostics.lastVerifiedAt = now()
-    if (!diagnostics.degraded) diagnostics.lastFailure = null
-  }
-
-  async function rebuildInternal(initialSnapshot = null) {
-    let snapshot = initialSnapshot
-    for (let attempt = 1; attempt <= maxRebuildAttempts; attempt += 1) {
-      snapshot ||= await readSnapshot()
-      repository.replaceAll(snapshot.rows)
-      const afterSource = await readSnapshot()
-      if (afterSource.count !== snapshot.count || afterSource.digest !== snapshot.digest) {
-        snapshot = afterSource
-        continue
-      }
-      const verification = indexedVerification()
-      if (verification.count !== snapshot.count || verification.digest !== snapshot.digest) {
-        snapshot = afterSource
-        continue
-      }
-      diagnostics.rebuildCount += 1
-      diagnostics.rebuildGeneration += 1
-      setVerification(snapshot, verification)
-      return { ok: true, rebuilt: true, attempts: attempt, ...getDiagnostics() }
-    }
-    throw new Error(`Session index source changed during ${maxRebuildAttempts} rebuild attempts`)
-  }
-
-  function rebuild(initialSnapshot = null) {
-    if (rebuildPromise) return rebuildPromise
-    rebuildPromise = rebuildInternal(initialSnapshot).catch((error) => {
-      diagnostics.dirty = true
-      diagnostics.degraded = true
-      diagnostics.status = 'degraded'
-      diagnostics.lastFailure = safeError(error)
-      log.warn('Session index rebuild failed; JSON metadata remains authoritative.', {
-        operation: 'session_index_rebuild',
-        error: diagnostics.lastFailure,
-      })
-      throw error
-    }).finally(() => { rebuildPromise = null })
-    return rebuildPromise
+  function getDiagnostics() {
+    return { ...diagnostics }
   }
 
-  function scheduleRebuild() {
-    if (!rebuildPromise) {
-      setTimeout(() => {
-        if (!rebuildPromise && diagnostics.dirty) void rebuild().catch(() => {})
-      }, 0).unref?.()
+  function readiness() {
+    return {
+      ready: diagnostics.initialized && !diagnostics.degraded,
+      reason: diagnostics.initialized ? null : 'uninitialized',
+      ...getDiagnostics(),
     }
   }
 
   async function initialize() {
     try {
-      const snapshot = await readSnapshot()
-      const verification = indexedVerification()
-      if (verification.count !== snapshot.count || verification.digest !== snapshot.digest) await rebuild(snapshot)
-      else setVerification(snapshot, verification)
+      diagnostics.count = repository.count()
+      diagnostics.sourceCount = diagnostics.count
+      diagnostics.indexCount = diagnostics.count
       diagnostics.initialized = true
-      return { ok: !diagnostics.degraded, rebuilt: diagnostics.rebuildCount > 0, ...getDiagnostics() }
+      diagnostics.status = 'ready'
+      diagnostics.lastVerifiedAt = new Date().toISOString()
+      return { ok: true, rebuilt: false, ...getDiagnostics() }
     } catch (error) {
       diagnostics.initialized = true
-      diagnostics.dirty = true
       diagnostics.degraded = true
+      diagnostics.dirty = true
       diagnostics.status = 'degraded'
       diagnostics.lastFailure = safeError(error)
-      log.warn('Session index initialization degraded; JSON metadata remains authoritative.', {
+      log.warn('Session index initialization failed; queries will fall back.', {
         operation: 'session_index_initialize',
         error: diagnostics.lastFailure,
       })
@@ -319,147 +75,62 @@ export function createSessionIndexService({
     }
   }
 
-  async function verifyIntegrity({ force = false } = {}) {
+  async function verifyIntegrity() {
     if (!diagnostics.initialized) return { ready: false, reason: 'uninitialized', ...getDiagnostics() }
-    const lastVerifiedMs = diagnostics.lastVerifiedAt ? Date.parse(diagnostics.lastVerifiedAt) : Number.NaN
-    if (!force && Number.isFinite(lastVerifiedMs) && nowMs() - lastVerifiedMs < verifyTtlMs) {
-      return { ready: !diagnostics.dirty && !diagnostics.degraded && diagnostics.queryCompatible, ...getDiagnostics() }
-    }
-    try {
-      const snapshot = await readSnapshot()
-      const verification = indexedVerification()
-      const projectionValid = projectionIntegrity()
-      const matches = verification.count === snapshot.count && verification.digest === snapshot.digest && projectionValid
-      setVerification(snapshot, verification, { dirty: !matches })
-      if (!matches) scheduleRebuild()
-      return {
-        ready: matches && snapshot.queryCompatible,
-        reason: !projectionValid ? 'projection_mismatch' : !matches ? 'digest_mismatch' : snapshot.queryCompatible ? null : 'source_incompatible',
-        ...getDiagnostics(),
-      }
-    } catch (error) {
-      diagnostics.dirty = true
-      diagnostics.degraded = true
-      diagnostics.status = 'degraded'
-      diagnostics.lastFailure = safeError(error)
-      scheduleRebuild()
-      return { ready: false, reason: 'verify_failed', ...getDiagnostics() }
-    }
+    return readiness()
   }
 
-  async function syncMetadataCommit({ scope, projectId, previous, next }) {
-    const bucket = normalizeBucket({ scope, projectId })
-    if (!isPlainObject(previous) || !isPlainObject(next)) throw new TypeError('previous and next metadata buckets must be plain objects')
-    if (!diagnostics.initialized) return { ok: true, skipped: true }
-    diagnostics.lastVerifiedAt = null
+  async function queryPage(options) {
+    if (!diagnostics.initialized) return { ok: false, reason: 'uninitialized', readiness: getDiagnostics() }
     try {
-      const indexedAt = now()
-      const upserts = []
-      const deletes = []
-      const ids = new Set([...Object.keys(previous), ...Object.keys(next)])
-      for (const sessionId of ids) {
-        const previousMetadata = previous[sessionId]
-        const nextMetadata = next[sessionId]
-        if (nextMetadata === undefined) {
-          deletes.push({ ...bucket, sessionId })
-          continue
-        }
-        const nextRow = buildRow(bucket, sessionId, nextMetadata, indexedAt)
-        if (previousMetadata !== undefined) {
-          const previousRow = buildRow(bucket, sessionId, previousMetadata, indexedAt)
-          if (previousRow.metadataDigest === nextRow.metadataDigest) continue
-        }
-        upserts.push(nextRow)
-      }
-      repository.applyChanges({ upserts, deletes })
-      const verification = indexedVerification()
-      diagnostics.indexCount = verification.count
-      diagnostics.indexDigest = verification.digest
-      diagnostics.count = verification.count
-      diagnostics.digest = verification.digest
-      diagnostics.sourceCount = verification.count
-      diagnostics.sourceDigest = verification.digest
-      if (!diagnostics.dirty) diagnostics.lastFailure = null
-      return { ok: true, upserted: upserts.length, deleted: deletes.length, dirty: diagnostics.dirty }
+      // Duplicate session ids and complete sort-key ties make LIMIT/OFFSET
+      // pagination unstable; the route falls back to its legacy sorted read.
+      const analysis = repository.analyzeQuery(options)
+      if (analysis.duplicateSessionIdCount > 0) return { ok: false, reason: 'duplicate_session_id', analysis, readiness: readiness() }
+      if (analysis.fullSortKeyTieCount > 0) return { ok: false, reason: 'sort_key_tie', analysis, readiness: readiness() }
+      return { ok: true, page: repository.listPage(options), analysis, readiness: readiness() }
     } catch (error) {
       diagnostics.dirty = true
       diagnostics.degraded = true
       diagnostics.status = 'degraded'
       diagnostics.lastFailure = safeError(error)
-      scheduleRebuild()
-      log.warn('Session index incremental sync failed; JSON metadata commit remains successful.', {
-        operation: 'session_index_sync',
-        scope: bucket.scope,
-        hasProjectId: bucket.scope === 'project',
+      log.warn('Session index query failed; route falls back.', {
+        operation: 'session_index_query',
         error: diagnostics.lastFailure,
       })
-      return { ok: false, degraded: true }
-    }
-  }
-
-  function markQueryFailure(reason, error = null) {
-    diagnostics.dirty = true
-    diagnostics.degraded = true
-    diagnostics.status = 'degraded'
-    diagnostics.lastFailure = error ? safeError(error) : { name: 'SessionIndexQueryMismatch', code: reason }
-    log.warn('Session index query degraded; JSON metadata remains authoritative.', {
-      operation: 'session_index_query',
-      reason,
-      error: error ? diagnostics.lastFailure : null,
-    })
-    scheduleRebuild()
-  }
-
-  async function queryPage(options) {
-    const readiness = await verifyIntegrity()
-    if (!readiness.ready) {
-      return {
-        ok: false,
-        reason: readiness.reason || (readiness.queryCompatible === false ? 'source_incompatible' : 'not_ready'),
-        readiness,
-      }
-    }
-    try {
-      const analysis = repository.analyzeQuery(options)
-      if (analysis.duplicateSessionIdCount > 0) return { ok: false, reason: 'duplicate_session_id', analysis, readiness }
-      if (analysis.fullSortKeyTieCount > 0) return { ok: false, reason: 'sort_key_tie', analysis, readiness }
-      return { ok: true, page: repository.listPage(options), analysis, readiness }
-    } catch (error) {
-      markQueryFailure('repository_error', error)
-      return { ok: false, reason: 'repository_error', error: safeError(error), readiness: getDiagnostics() }
+      return { ok: false, reason: 'repository_error', error: diagnostics.lastFailure, readiness: getDiagnostics() }
     }
   }
 
-  async function snapshot() {
-    return readSnapshot()
+  // Storage v2: the index IS the sessions table, so metadata commits have
+  // nothing to mirror. Kept for the storage.mjs commit-hook wiring contract.
+  async function syncMetadataCommit() {
+    return { ok: true, skipped: true }
   }
 
-  function getDiagnostics() {
-    return { ...diagnostics, compatibilityIssues: diagnostics.compatibilityIssues ? { ...diagnostics.compatibilityIssues } : null }
+  function markQueryFailure() {
+    // No-op: there is no separate projection to mark dirty.
   }
 
   return Object.freeze({
-    snapshot, initialize, rebuild, verifyIntegrity, queryPage, markQueryFailure,
-    syncMetadataCommit, getDiagnostics,
+    initialize, verifyIntegrity, queryPage, syncMetadataCommit, markQueryFailure, getDiagnostics,
   })
 }
 
-export function configureSessionIndex({ readBuckets, repository } = {}) {
-  if (readBuckets !== undefined && typeof readBuckets !== 'function') throw new TypeError('readBuckets must be a function')
-  defaultReader = readBuckets ?? defaultReader
+export function configureSessionIndex({ repository } = {}) {
+  if (repository !== undefined && repository !== null && typeof repository !== 'object') throw new TypeError('repository must be an object')
   defaultRepository = repository ?? defaultRepository
 }
 
 export async function initializeSessionIndex(options = {}) {
-  const readBuckets = options.readBuckets ?? defaultReader
   const repository = options.repository ?? defaultRepository ?? createSessionIndexRepository(getSqliteStorage())
-  activeService = createSessionIndexService({ ...options, repository, readBuckets })
+  activeService = createSessionIndexService({ ...options, repository })
   return activeService.initialize()
 }
 
-export async function syncSessionMetadataCommit(change) {
+export async function syncSessionMetadataCommit() {
   if (!activeService) return { ok: true, skipped: true }
-  return activeService.syncMetadataCommit(change)
+  return activeService.syncMetadataCommit()
 }
 
 export async function querySessionIndexPage(options) {
@@ -467,29 +138,24 @@ export async function querySessionIndexPage(options) {
   return activeService.queryPage(options)
 }
 
-export function markSessionIndexQueryFailure(reason, error) {
-  activeService?.markQueryFailure(reason, error)
+export function markSessionIndexQueryFailure() {
+  activeService?.markQueryFailure()
 }
 
 export function getSessionIndexDiagnostics() {
   return activeService?.getDiagnostics() ?? {
     status: 'uninitialized',
     initialized: false,
-    degraded: true,
-    dirty: true,
+    degraded: false,
+    dirty: false,
     sourceCount: 0,
-    sourceDigest: sessionIndexAggregateDigest([]),
     indexCount: 0,
-    indexDigest: sessionIndexAggregateDigest([]),
     count: 0,
-    digest: sessionIndexAggregateDigest([]),
     lastVerifiedAt: null,
     rebuildCount: 0,
     rebuildGeneration: 0,
-    keyIdMismatchCount: 0,
     duplicateSessionIdCount: 0,
-    queryCompatible: false,
-    compatibilityIssues: null,
+    queryCompatible: true,
     lastFailure: null,
   }
 }

package/server/session-state-backup.mjs

@@ -6,14 +6,15 @@ import { createSessionStateRepository, messagesDigestFromValues, snapshotDigestL
 import {
   currentSessionStateMaintenanceContext,
   runSessionStateMaintenance,
-} from './session-state-cutover.mjs'
+} from './session-state-maintenance.mjs'
 import {
-  getSessionStoragePhase,
   isSessionStateAuthoritative,
   normalizeSessionSnapshotValues,
+  readSessionStorageState,
   replaceSessionStateSnapshot,
 } from './session-state-service.mjs'
 import { storageDir } from './storage.mjs'
+import { logger } from './utils/logger.mjs'
 
 const RESTORE_PLAN_FILE = path.join(storageDir, 'session-state-restore-plan.json')
 const ROLL_FORWARD_STATUSES = new Set(['prepared', 'applying', 'target_applied'])
@@ -95,13 +96,49 @@ export async function exportSessionStateForBackup(options = {}) {
       ...snapshotValues(snapshot),
       count: snapshot.count,
       digest: snapshot.digest,
-      phase: getSessionStoragePhase(),
+      phase: readSessionStorageState().phase,
     }
   }
   if (!options.maintenance || currentSessionStateMaintenanceContext()) return operation()
   return runSessionStateMaintenance(operation, { storage: options.storage, operation: 'session-state-backup-export' })
 }
 
+/**
+ * Manual integrity verification entry point for the maintenance route
+ * (design review suggestion 9): the startup chain only runs the lightweight
+ * SQL-level check, so silent per-row digest rot would stay invisible until
+ * an offline full verification. `{ full: true }` recomputes every stored
+ * digest (quickCheck: false); the default is the lightweight check. Runs
+ * under the session state maintenance lock (same pattern as the backup
+ * export above) so the scan serializes with cutover/restore, and returns
+ * only summary counters plus the elapsed time — never row payloads.
+ */
+export async function verifySessionStateIntegrityForMaintenance(options = {}) {
+  const operation = async () => {
+    const repository = options.repository || repositoryRequired()
+    const startedAt = Date.now()
+    // forceQuickCheck: a manual maintenance trigger must run a real quick_check
+    // scan, never the process-cache/marker shortcut.
+    const integrity = repository.verifyIntegrity({ quickCheck: options.full !== true, forceQuickCheck: options.forceQuickCheck === true })
+    return { ...integrity, full: options.full === true, durationMs: Date.now() - startedAt }
+  }
+  if (!options.maintenance || currentSessionStateMaintenanceContext()) return operation()
+  return runSessionStateMaintenance(operation, { storage: options.storage, operation: 'session-state-verify-integrity' })
+}
+
+// A restore rewrites every session row inside one transaction, so the WAL
+// grows by roughly the library size before converging; truncating right
+// after success reclaims that space (same rationale as the post-promote
+// checkpoint in the cutover). Best-effort: a busy or failed checkpoint
+// leaves the WAL to a later auto-checkpoint and must never fail the restore.
+function checkpointWalAfterRestore(repository, operation) {
+  try {
+    repository.checkpointWal()
+  } catch (error) {
+    logger.warn('Session state WAL checkpoint failed after restore', { domain: 'session-state', operation, errorName: error?.name || 'Error', errorMessage: error?.message })
+  }
+}
+
 async function writePlan(plan, planFile = RESTORE_PLAN_FILE) {
   await fs.mkdir(path.dirname(planFile), { recursive: true })
   const temporary = `${planFile}.${process.pid}.${randomUUID()}.tmp`
@@ -214,6 +251,7 @@ export async function restoreSessionStateSnapshot(values, options = {}) {
       plan = { ...plan, status: 'target_applied' }
       await writePlan(plan, planFile)
       await fs.rm(planFile, { force: true })
+      checkpointWalAfterRestore(repository, 'session-state-restore')
       return { sessions: targetCount, sessionsMetadata: targetCount }
     } catch (error) {
       try {
@@ -239,7 +277,12 @@ export async function restoreSessionStateSnapshot(values, options = {}) {
       }
       throw error
     }
-  }, { storage: options.storage, operation: 'session-state-restore' })
+  }, {
+    storage: options.storage,
+    operation: 'session-state-restore',
+    waitTimeoutMs: options.waitTimeoutMs,
+    pollIntervalMs: options.pollIntervalMs,
+  })
 }
 
 /**
@@ -251,6 +294,8 @@ export async function recoverSessionStateRestorePlan({
   repository: repositoryOverride,
   planFile = RESTORE_PLAN_FILE,
   storage,
+  waitTimeoutMs,
+  pollIntervalMs,
 } = {}) {
   let plan
   try {
@@ -274,6 +319,12 @@ export async function recoverSessionStateRestorePlan({
     const integrity = repository.verifyIntegrity()
     if (!integrity.ok) throw new Error('Session state restore plan recovery integrity verification failed')
     await fs.rm(planFile, { force: true })
+    checkpointWalAfterRestore(repository, 'session-state-restore-recovery')
     return true
-  }, { storage, operation: 'session-state-restore-recovery' })
+  }, {
+    storage,
+    operation: 'session-state-restore-recovery',
+    waitTimeoutMs,
+    pollIntervalMs,
+  })
 }