@shawnstack/quickforge 1.7.9 → 1.7.11

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'])
@@ -86,20 +87,58 @@ export async function exportSessionStateForBackup(options = {}) {
     const integrity = repository.verifyIntegrity({ quickCheck: true })
     if (!integrity.ok) throw new Error('Session state integrity verification failed during backup export')
     const snapshot = repository.exportSnapshot()
-    if (snapshot.count !== integrity.count || snapshot.digest !== integrity.digest) {
-      throw new Error('Session state backup count/digest verification failed')
+    // The lightweight integrity result has no digest (null); the count
+    // cross-check plus exportSnapshot's own digest computation stay.
+    if (snapshot.count !== integrity.count) {
+      throw new Error('Session state backup count verification failed')
     }
     return {
       ...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`
@@ -212,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 {
@@ -237,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,
+  })
 }
 
 /**
@@ -249,6 +294,8 @@ export async function recoverSessionStateRestorePlan({
   repository: repositoryOverride,
   planFile = RESTORE_PLAN_FILE,
   storage,
+  waitTimeoutMs,
+  pollIntervalMs,
 } = {}) {
   let plan
   try {
@@ -272,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,
+  })
 }

package/server/session-state-import.mjs

@@ -0,0 +1,157 @@
+import { getSqliteStorage } from './sqlite/database.mjs'
+import { createSessionStateRepository } from './sqlite/session-state-repository.mjs'
+import { logger as defaultLogger } from './utils/logger.mjs'
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+// Bucket validation mirrors session-state-cutover.mjs's normalizeBucket: the
+// importer walks the same physical JSON tree the cutover source did.
+function normalizeBucket(raw) {
+  if (raw.scope === 'global') {
+    if (raw.projectId !== undefined && raw.projectId !== null && raw.projectId !== '') throw new TypeError('Global session bucket cannot have projectId')
+    return { scope: 'global', projectId: null }
+  }
+  if (raw.scope !== 'project' || typeof raw.projectId !== 'string' || !raw.projectId.trim() || raw.projectId === '.' || raw.projectId === '..' || /[\\/]/.test(raw.projectId)) {
+    throw new TypeError('Invalid session bucket')
+  }
+  return { scope: 'project', projectId: raw.projectId }
+}
+
+// Metadata derivation for body-only files (no sessions-metadata entry) —
+// identical shaping to the cutover's deriveMetadata.
+function deriveMetadata(sessionId, state, bucket) {
+  const createdAt = typeof state.createdAt === 'string'
+    ? state.createdAt
+    : (typeof state.lastModified === 'string' ? state.lastModified : '1970-01-01T00:00:00.000Z')
+  return {
+    id: sessionId,
+    title: typeof state.title === 'string' ? state.title : 'New chat',
+    titleSource: state.titleSource,
+    createdAt,
+    lastModified: typeof state.lastModified === 'string' ? state.lastModified : createdAt,
+    messageCount: state.messages.length,
+    stateVersion: Number.isInteger(state.stateVersion) && state.stateVersion >= 0 ? state.stateVersion : 0,
+    thinkingLevel: typeof state.thinkingLevel === 'string' ? state.thinkingLevel : 'off',
+    scope: bucket.scope,
+    ...(bucket.scope === 'project' ? { projectId: bucket.projectId } : {}),
+    taskStatus: state.taskStatus || 'idle',
+    taskStartedAt: state.taskStartedAt ?? null,
+    taskFinishedAt: state.taskFinishedAt ?? null,
+  }
+}
+
+// Per-session normalization with the cutover's normalizeSessionEntry
+// validation semantics: id/scope/projectId consistency between bucket, body
+// and metadata; orphan metadata-only entries are dropped (diagnosed by the
+// caller); body-only files derive their metadata. Returns the repository
+// record, or null for a metadata-only orphan.
+function normalizeSessionEntry(bucket, sessionId, rawState, rawMetadata, diagnostics) {
+  if (!rawState && rawMetadata) {
+    diagnostics.push({ kind: 'metadata-only-orphan', scope: bucket.scope, projectId: bucket.projectId, sessionId })
+    return null
+  }
+  if (!isPlainObject(rawState)) throw new TypeError(`Invalid session state: ${sessionId}`)
+  if (!Array.isArray(rawState.messages)) throw new TypeError(`Session messages must be an array: ${sessionId}`)
+  if (rawState.id !== undefined && rawState.id !== sessionId) throw new TypeError(`Session body id mismatch: ${sessionId}`)
+  if (rawState.scope !== undefined && rawState.scope !== bucket.scope) throw new TypeError(`Session body scope mismatch: ${sessionId}`)
+  if (bucket.scope === 'project' && rawState.projectId !== undefined && rawState.projectId !== bucket.projectId) throw new TypeError(`Session body project mismatch: ${sessionId}`)
+  if (bucket.scope === 'global' && rawState.projectId !== undefined && rawState.projectId !== null) throw new TypeError(`Global session body project mismatch: ${sessionId}`)
+  let metadata
+  if (rawMetadata === undefined) {
+    diagnostics.push({ kind: 'body-only', scope: bucket.scope, projectId: bucket.projectId, sessionId })
+    metadata = deriveMetadata(sessionId, rawState, bucket)
+  } else {
+    if (!isPlainObject(rawMetadata)) throw new TypeError(`Invalid session metadata: ${sessionId}`)
+    if (rawMetadata.id !== undefined && rawMetadata.id !== sessionId) throw new TypeError(`Session metadata id mismatch: ${sessionId}`)
+    if (rawMetadata.scope !== undefined && rawMetadata.scope !== bucket.scope) throw new TypeError(`Session metadata scope mismatch: ${sessionId}`)
+    if (bucket.scope === 'project' && rawMetadata.projectId !== undefined && rawMetadata.projectId !== bucket.projectId) throw new TypeError(`Session metadata project mismatch: ${sessionId}`)
+    if (bucket.scope === 'global' && rawMetadata.projectId !== undefined && rawMetadata.projectId !== null) throw new TypeError(`Global session metadata project mismatch: ${sessionId}`)
+    metadata = structuredClone(rawMetadata)
+  }
+  const stateVersion = rawState.stateVersion ?? metadata.stateVersion ?? 0
+  if (!Number.isInteger(stateVersion) || stateVersion < 0) throw new TypeError(`Invalid session stateVersion: ${sessionId}`)
+  const state = { ...structuredClone(rawState), id: sessionId, scope: bucket.scope, stateVersion }
+  metadata = { ...metadata, id: sessionId, scope: bucket.scope, stateVersion }
+  if (bucket.scope === 'project') {
+    state.projectId = bucket.projectId
+    metadata.projectId = bucket.projectId
+  } else {
+    delete state.projectId
+    delete metadata.projectId
+  }
+  for (const field of ['pinnedAt', 'archivedAt']) {
+    if (metadata[field] !== undefined) state[field] = metadata[field]
+  }
+  return { scope: bucket.scope, projectId: bucket.projectId ?? null, sessionId, state, metadata }
+}
+
+// Schema v11 JSON importer: streams the physical session-state JSON tree
+// (the same layout createPhysicalSessionStateFsAdapter walks for the old
+// cutover) and re-imports every session into the v2 SQLite store, one
+// transaction per session — repository.save extracts the messages (inline or
+// legacy split-marked bodies alike), so the import is idempotent and can be
+// re-run after any interruption. JSON files are read-only here: nothing is
+// written back, no mirror, no phase state.
+//
+// Resilience: a failing entry (unreadable file, validation mismatch,
+// cross-bucket duplicate) never aborts the run — it is counted in `skipped`
+// and described in `diagnostics` so the operator can inspect and fix the
+// source tree, then simply re-run.
+export async function importSessionStateFromJson({ storage = null, logger = defaultLogger } = {}) {
+  const storageModule = storage ?? await import('./storage.mjs')
+  const fsAdapter = storageModule.createPhysicalSessionStateFsAdapter()
+  const repository = createSessionStateRepository(getSqliteStorage())
+  const diagnostics = []
+  let imported = 0
+  let skipped = 0
+
+  for await (const rawBucket of fsAdapter.listBuckets()) {
+    const bucket = normalizeBucket(rawBucket)
+    const metadata = await fsAdapter.readMetadataBucket(rawBucket)
+    if (!isPlainObject(metadata)) throw new TypeError('Session bucket stores must be objects')
+    const fileIds = new Set()
+    for await (const sessionId of fsAdapter.listSessionFiles(rawBucket)) fileIds.add(sessionId)
+    const ids = [...new Set([...fileIds, ...Object.keys(metadata)])].sort((left, right) => left.localeCompare(right))
+    for (const sessionId of ids) {
+      let record
+      try {
+        const rawState = fileIds.has(sessionId) ? await fsAdapter.readSessionState(rawBucket, sessionId) : undefined
+        record = normalizeSessionEntry(bucket, sessionId, rawState, metadata[sessionId], diagnostics)
+      } catch (error) {
+        skipped += 1
+        diagnostics.push({ kind: 'invalid-entry', scope: bucket.scope, projectId: bucket.projectId, sessionId, message: error instanceof Error ? error.message : String(error) })
+        continue
+      }
+      if (!record) {
+        skipped += 1
+        continue
+      }
+      try {
+        repository.save(record)
+        imported += 1
+      } catch (error) {
+        skipped += 1
+        diagnostics.push({
+          kind: 'save-error',
+          scope: record.scope,
+          projectId: record.projectId,
+          sessionId,
+          errorCode: error?.errorCode ?? null,
+          message: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+  }
+
+  try {
+    repository.checkpointWal()
+  } catch (error) {
+    logger.warn('Session state import WAL checkpoint failed', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+  logger.info('Session state JSON import finished', { imported, skipped })
+  return { imported, skipped, diagnostics }
+}

package/server/session-state-maintenance.mjs

@@ -0,0 +1,126 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+import { getSqliteStorage } from './sqlite/database.mjs'
+
+// Session-domain maintenance lock (extracted from the retired
+// session-state-cutover.mjs when the JSON→SQLite phase machine was removed):
+// restore/verify operations serialize across processes through the
+// `session_state_maintenance_lock` table (created by SQLite migration v6 and
+// kept by schema v11), with owner liveness, fencing tokens and a TTL renewed
+// by heartbeat while an operation runs.
+
+const DEFAULT_LOCK_TTL_MS = 60_000
+const DEFAULT_WAIT_TIMEOUT_MS = 65_000
+const maintenanceContext = new AsyncLocalStorage()
+let maintenanceCount = 0
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+function ownerPid(current) {
+  const value = Number(current.owner_pid)
+  return Number.isInteger(value) && value > 0 ? value : null
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true } catch (error) { return error?.code === 'EPERM' }
+}
+
+export function acquireSessionStateMaintenanceLock(storage, options = {}) {
+  const nowMs = Number(options.now?.() ?? Date.now())
+  const acquiredAt = new Date(nowMs).toISOString()
+  const expiresAt = new Date(nowMs + (options.ttlMs ?? DEFAULT_LOCK_TTL_MS)).toISOString()
+  const identity = isPlainObject(options.owner)
+    ? { id: options.owner.id || `${options.owner.pid || process.pid}:${randomUUID()}`, pid: options.owner.pid || process.pid }
+    : { id: options.owner || `${process.pid}:${randomUUID()}`, pid: process.pid }
+  const isPidAlive = options.pidAlive || pidAlive
+  return storage.transaction((database) => {
+    const current = database.prepare('SELECT * FROM session_state_maintenance_lock WHERE singleton = 1').get()
+    if (current && current.owner === identity.id) {
+      database.prepare(`UPDATE session_state_maintenance_lock SET owner_pid = ?, operation = ?, heartbeat_at = ?, expires_at = ?
+        WHERE singleton = 1 AND owner = ? AND fencing = ?`)
+        .run(identity.pid, options.operation || current.operation, acquiredAt, expiresAt, identity.id, current.fencing)
+      return { owner: identity.id, ownerPid: identity.pid, fencing: Number(current.fencing), expiresAt }
+    }
+    if (current) {
+      const expired = Date.parse(current.expires_at) <= nowMs
+      const pid = ownerPid(current)
+      if (!expired || pid === null || isPidAlive(pid)) return null
+    }
+    const fencing = Number(current?.fencing || 0) + 1
+    database.prepare(`INSERT INTO session_state_maintenance_lock
+      (singleton, owner, owner_pid, fencing, operation, acquired_at, heartbeat_at, expires_at)
+      VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(singleton) DO UPDATE SET owner=excluded.owner, owner_pid=excluded.owner_pid, fencing=excluded.fencing,
+      operation=excluded.operation, acquired_at=excluded.acquired_at, heartbeat_at=excluded.heartbeat_at, expires_at=excluded.expires_at`)
+      .run(identity.id, identity.pid, fencing, options.operation || 'session-state-maintenance', acquiredAt, acquiredAt, expiresAt)
+    return { owner: identity.id, ownerPid: identity.pid, fencing, expiresAt }
+  }, { mode: 'immediate' })
+}
+
+export function renewSessionStateMaintenanceLock(storage, lease, options = {}) {
+  const nowMs = Number(options.now?.() ?? Date.now())
+  const heartbeatAt = new Date(nowMs).toISOString()
+  const expiresAt = new Date(nowMs + (options.ttlMs ?? DEFAULT_LOCK_TTL_MS)).toISOString()
+  const result = storage.prepare(`UPDATE session_state_maintenance_lock SET heartbeat_at = ?, expires_at = ? WHERE singleton = 1 AND owner = ? AND fencing = ?`)
+    .run(heartbeatAt, expiresAt, lease.owner, lease.fencing)
+  lease.expiresAt = expiresAt
+  return Number(result.changes) === 1
+}
+
+export function releaseSessionStateMaintenanceLock(storage, lease) {
+  return Number(storage.prepare('DELETE FROM session_state_maintenance_lock WHERE singleton = 1 AND owner = ? AND fencing = ?').run(lease.owner, lease.fencing).changes) === 1
+}
+
+async function waitForLock(storage, options) {
+  const deadline = Date.now() + (options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS)
+  while (Date.now() < deadline) {
+    const lease = acquireSessionStateMaintenanceLock(storage, options)
+    if (lease) return lease
+    await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 100))
+  }
+  throw new Error('Timed out waiting for session state maintenance lock')
+}
+
+export async function runSessionStateMaintenance(operation, options = {}) {
+  const existing = maintenanceContext.getStore()
+  if (existing) return operation(existing)
+  const storage = options.storage || getSqliteStorage()
+  const lease = await waitForLock(storage, options)
+  const interval = options.heartbeatIntervalMs ?? Math.max(10, Math.floor((options.ttlMs ?? DEFAULT_LOCK_TTL_MS) / 3))
+  const timer = setInterval(() => {
+    try {
+      if (!renewSessionStateMaintenanceLock(storage, lease, options)) throw new Error('Session state maintenance lock fencing was lost')
+    } catch (error) {
+      heartbeatError = error
+      rejectHeartbeat(error)
+    }
+  }, interval)
+  timer.unref?.()
+  let rejectHeartbeat
+  let heartbeatError = null
+  const heartbeatFailure = new Promise((_, reject) => { rejectHeartbeat = reject })
+  maintenanceCount += 1
+  try {
+    const context = { storage, lease }
+    const result = await Promise.race([maintenanceContext.run(context, () => Promise.resolve().then(() => operation(context))), heartbeatFailure])
+    if (heartbeatError) throw heartbeatError
+    return result
+  } finally {
+    clearInterval(timer)
+    releaseSessionStateMaintenanceLock(storage, lease)
+    maintenanceCount = Math.max(0, maintenanceCount - 1)
+  }
+}
+
+export function isSessionStateMaintenanceActive(storage) {
+  if (!storage) {
+    try { storage = getSqliteStorage() } catch { return false }
+  }
+  return maintenanceCount > 0 || Boolean(storage.prepare('SELECT 1 AS active FROM session_state_maintenance_lock WHERE singleton = 1').get())
+}
+
+export function currentSessionStateMaintenanceContext() {
+  return maintenanceContext.getStore() || null
+}