@shawnstack/quickforge 1.7.6 → 1.7.8

package/server/share-backup.mjs

@@ -0,0 +1,255 @@
+import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { getSqliteStorage } from './sqlite/database.mjs'
+import { createShareRepository, shareSnapshotDigest } from './sqlite/share-repository.mjs'
+import {
+  buildShareJsonSnapshot,
+  currentShareMaintenanceContext,
+  runShareMaintenance,
+} from './share-cutover.mjs'
+import { getShareStoragePhase, isShareStorageAuthoritative } from './share-service.mjs'
+import { storageDir } from './storage.mjs'
+
+// F10 Phase 3 share backup/restore: mirrors the session-state-backup pattern in
+// the independent share storage domain. Exports run under the share maintenance
+// lock with quick_check + verifyIntegrity + exportSnapshot (count/digest fail
+// closed). Restores run under the same lock, persist a crash-recoverable plan
+// file and compensate back to the exact before-state if the apply or its
+// verification fails. Only share_sessions/share_tokens/share_json_mirror_queue
+// are touched; scheduled_task_runs, session_index and session_messages are
+// never modified here.
+const RESTORE_PLAN_FILE = path.join(storageDir, 'share-restore-plan.json')
+const ROLL_FORWARD_STATUSES = new Set(['prepared', 'applying', 'target_applied'])
+const ROLL_BACK_STATUSES = new Set(['compensating', 'compensation_failed'])
+
+function repositoryRequired() {
+  try {
+    return createShareRepository(getSqliteStorage())
+  } catch (error) {
+    throw new Error('SQLite storage is required for authoritative share state', { cause: error })
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+function isPlainPlanValue(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+// Strip repository-internal fields before writing records into backups or plans
+// so the exported JSON is exactly the v1 conversation-shares.json shape.
+function publicShareRecord(record) {
+  if (!isPlainObject(record)) return record
+  const rest = { ...record }
+  delete rest.revision
+  delete rest.deletedAt
+  return rest
+}
+
+function shareValuesFromRecords(records) {
+  return {
+    shares: Object.fromEntries((Array.isArray(records) ? records : []).map((record) => [record.id, publicShareRecord(record)])),
+  }
+}
+
+// Public digest helper for backup tooling: returns the exact repository-style
+// digest a restored snapshot must produce, given backup `{ shares }` values.
+export function computeShareSnapshotDigest(values) {
+  return shareSnapshotDigest(buildShareJsonSnapshot(values?.shares).records)
+}
+
+/**
+ * Authoritative share state export for the backup route and offline tools.
+ * Runs under the share maintenance lock so a concurrent restore can never be
+ * observed mid-transaction, and fail-closes when integrity or digest
+ * verification fails.
+ */
+export async function exportShareStateForBackup(options = {}) {
+  const operation = async () => {
+    const repository = options.repository || repositoryRequired()
+    const integrity = repository.verifyIntegrity({ quickCheck: true })
+    if (!integrity.ok) throw new Error('Share state integrity verification failed during backup export')
+    const snapshot = repository.exportSnapshot()
+    if (snapshot.count !== integrity.count || snapshot.digest !== integrity.digest) {
+      throw new Error('Share backup count/digest verification failed')
+    }
+    return {
+      ...shareValuesFromRecords(snapshot.records),
+      records: snapshot.records,
+      count: snapshot.count,
+      digest: snapshot.digest,
+      phase: getShareStoragePhase(),
+    }
+  }
+  if (!options.maintenance || currentShareMaintenanceContext()) return operation()
+  return runShareMaintenance(operation, { storage: options.storage, operation: 'share-backup-export' })
+}
+
+async function writePlan(plan, planFile = RESTORE_PLAN_FILE) {
+  await fs.mkdir(path.dirname(planFile), { recursive: true })
+  const temporary = `${planFile}.${process.pid}.${randomUUID()}.tmp`
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(plan, null, 2)}\n`, 'utf8')
+    await fs.rename(temporary, planFile)
+  } catch (error) {
+    await fs.rm(temporary, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+function countShares(values) {
+  return isPlainPlanValue(values) && values.shares && typeof values.shares === 'object' && !Array.isArray(values.shares)
+    ? Object.keys(values.shares).length
+    : 0
+}
+
+function validatePlan(plan) {
+  if (
+    !plan || plan.version !== 1 || plan.operation !== 'share_state_restore' ||
+    !isPlainPlanValue(plan.before) || !isPlainPlanValue(plan.target)
+  ) {
+    throw new Error('Share restore plan is invalid')
+  }
+  if (!ROLL_FORWARD_STATUSES.has(plan.status) && !ROLL_BACK_STATUSES.has(plan.status)) {
+    throw new Error('Share restore plan status is invalid')
+  }
+  const beforeCount = countShares(plan.before)
+  const targetCount = countShares(plan.target)
+  if (plan.beforeCount !== beforeCount || plan.targetCount !== targetCount) {
+    throw new Error('Share restore plan count is invalid')
+  }
+  const beforeDigest = computeShareSnapshotDigest(plan.before)
+  const targetDigest = computeShareSnapshotDigest(plan.target)
+  if (plan.beforeDigest !== beforeDigest || plan.targetDigest !== targetDigest) {
+    throw new Error('Share restore plan digest is invalid')
+  }
+  return plan
+}
+
+/**
+ * Restore the authoritative share state from a backup snapshot. Always runs
+ * under the share maintenance lock, persists a crash-recoverable plan file, and
+ * compensates back to the exact before-state if the apply or its verification
+ * fails. replace mode wipes local shares; merge mode keeps local-only records
+ * while backup records override same-key entries. `values` is the v1
+ * conversation-shares.json shape (`{ shares: { [shareId]: record } }`).
+ */
+export async function restoreShareStateSnapshot(values, options = {}) {
+  if (!isShareStorageAuthoritative()) {
+    throw new Error('Share state restore requires authoritative SQLite storage')
+  }
+  if (!isPlainPlanValue(values) || !isPlainObject(values.shares)) {
+    throw new TypeError('Share restore values must be a shares object')
+  }
+  const repository = options.repository || repositoryRequired()
+  const mode = options.mode === 'merge' ? 'merge' : 'replace'
+  const planFile = options.planFile || RESTORE_PLAN_FILE
+  return runShareMaintenance(async () => {
+    const before = repository.exportSnapshot()
+    const beforeValues = shareValuesFromRecords(before.records)
+    const merged = mode === 'merge'
+      ? { ...beforeValues.shares, ...values.shares }
+      : values.shares
+    // Normalize once before writing the plan: validation failures (invalid
+    // records, duplicate ids) surface here and never leave a plan file.
+    const targetRecords = buildShareJsonSnapshot(merged).records
+    const targetValues = shareValuesFromRecords(targetRecords)
+    const beforeCount = before.count
+    const beforeDigest = before.digest
+    const targetCount = targetRecords.length
+    const targetDigest = shareSnapshotDigest(targetRecords)
+    let plan = {
+      version: 1,
+      operation: 'share_state_restore',
+      status: 'prepared',
+      createdAt: new Date().toISOString(),
+      before: beforeValues,
+      target: targetValues,
+      beforeCount,
+      beforeDigest,
+      targetCount,
+      targetDigest,
+    }
+    await writePlan(plan, planFile)
+    try {
+      plan = { ...plan, status: 'applying' }
+      await writePlan(plan, planFile)
+      repository.replaceAll(targetRecords, { expectedCount: targetCount, expectedDigest: targetDigest })
+      const after = repository.exportSnapshot()
+      if (after.count !== targetCount || after.digest !== targetDigest) {
+        throw new Error('Share restore count/digest verification failed')
+      }
+      const integrity = repository.verifyIntegrity()
+      if (!integrity.ok) throw new Error('Share restore integrity verification failed')
+      plan = { ...plan, status: 'target_applied' }
+      await writePlan(plan, planFile)
+      await fs.rm(planFile, { force: true })
+      return { shares: targetCount }
+    } catch (error) {
+      try {
+        plan = { ...plan, status: 'compensating', failedAt: new Date().toISOString() }
+        await writePlan(plan, planFile)
+        const beforeRecords = buildShareJsonSnapshot(beforeValues.shares).records
+        repository.replaceAll(beforeRecords, { expectedCount: beforeCount, expectedDigest: beforeDigest })
+        const restored = repository.exportSnapshot()
+        if (restored.count !== beforeCount || restored.digest !== beforeDigest) {
+          throw new Error('Share restore compensation verification failed', { cause: error })
+        }
+        await fs.rm(planFile, { force: true })
+      } catch (compensationError) {
+        await writePlan({
+          ...plan,
+          status: 'compensation_failed',
+          compensationFailedAt: new Date().toISOString(),
+          errorName: error?.name || 'Error',
+          compensationErrorName: compensationError?.name || 'Error',
+        }, planFile).catch(() => {})
+        const retained = new Error('Share restore failed and compensation failed', { cause: compensationError })
+        retained.retainShareMaintenance = true
+        throw retained
+      }
+      throw error
+    }
+  }, { storage: options.storage, operation: 'share-restore' })
+}
+
+/**
+ * Startup recovery for an interrupted share restore plan: roll forward to the
+ * target for prepared/applying/target_applied plans and roll back to the before
+ * state for compensating/compensation_failed plans, then remove the plan file.
+ */
+export async function recoverShareRestorePlan({
+  repository: repositoryOverride,
+  planFile = RESTORE_PLAN_FILE,
+  storage,
+} = {}) {
+  let plan
+  try {
+    plan = validatePlan(JSON.parse(await fs.readFile(planFile, 'utf8')))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw new Error(`Share restore plan is unreadable or invalid: ${error?.message || error}`, { cause: error })
+  }
+  if (!isShareStorageAuthoritative()) {
+    throw new Error('Share restore plan exists outside authoritative mode')
+  }
+  const repository = repositoryOverride || repositoryRequired()
+  return runShareMaintenance(async () => {
+    const rollBack = ROLL_BACK_STATUSES.has(plan.status)
+    const records = buildShareJsonSnapshot(rollBack ? plan.before.shares : plan.target.shares).records
+    const expectedCount = rollBack ? plan.beforeCount : plan.targetCount
+    const expectedDigest = rollBack ? plan.beforeDigest : plan.targetDigest
+    repository.replaceAll(records, { expectedCount, expectedDigest })
+    const after = repository.exportSnapshot()
+    if (after.count !== expectedCount || after.digest !== expectedDigest) {
+      throw new Error('Share restore plan recovery verification failed')
+    }
+    const integrity = repository.verifyIntegrity()
+    if (!integrity.ok) throw new Error('Share restore plan recovery integrity verification failed')
+    await fs.rm(planFile, { force: true })
+    return true
+  }, { storage, operation: 'share-restore-recovery' })
+}

package/server/share-cutover.mjs

@@ -0,0 +1,296 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { getSqliteStorage } from './sqlite/database.mjs'
+import { createShareRepository, normalizeShareRecord, shareSnapshotDigest } from './sqlite/share-repository.mjs'
+import {
+  SHARE_STORAGE_PHASES,
+  configureShareService,
+  drainShareJsonMirror,
+  readShareStorageState,
+  setShareStoragePhase,
+} from './share-service.mjs'
+import { readSharesJsonFile } from './share-json-file.mjs'
+import { createDefaultShareMirror } from './share-service.mjs'
+import { storageDir } from './storage.mjs'
+
+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
+}
+
+/**
+ * Validate and normalize the whole `shares/conversation-shares.json` store
+ * (top-level object keyed by shareId) into canonical share records. Fails
+ * closed on: missing sessionId, invalid permission/scope, malformed `tokens`
+ * array, inconsistent password hash fields, key/id mismatch and duplicate
+ * shareIds across keys. The count/digest are computed with the exact
+ * repository digest algorithm so the SQLite replace verification can compare
+ * digests 1:1.
+ */
+export function buildShareJsonSnapshot(shares) {
+  if (!isPlainObject(shares)) throw new TypeError('Share JSON store must be an object')
+  const records = []
+  const seen = new Set()
+  const diagnostics = { invalidRecords: [], duplicateShareIds: [] }
+  for (const [key, raw] of Object.entries(shares)) {
+    let record
+    try {
+      record = normalizeShareRecord(raw.id === undefined ? { ...raw, id: key } : raw)
+    } catch (error) {
+      diagnostics.invalidRecords.push(key)
+      throw error instanceof Error ? error : new TypeError(`Invalid share record: ${key}`)
+    }
+    if (seen.has(record.id)) {
+      diagnostics.duplicateShareIds.push(record.id)
+      throw new TypeError(`Duplicate share ids: ${record.id}`)
+    }
+    seen.add(record.id)
+    if (raw.id !== undefined && raw.id !== key) {
+      throw new TypeError(`Share record id mismatch: ${key}`)
+    }
+    records.push(record)
+  }
+  records.sort((left, right) => left.id.localeCompare(right.id))
+  return { records, count: records.length, digest: shareSnapshotDigest(records), diagnostics }
+}
+
+async function writeShareCutoverBackup(snapshot, directory = path.join(storageDir, 'backups')) {
+  await fs.mkdir(directory, { recursive: true })
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const finalPath = path.join(directory, `quickforge-shares-cutover-${stamp}.json`)
+  const temporaryPath = `${finalPath}.${process.pid}.${randomUUID()}.tmp`
+  const backup = {
+    app: 'quickforge',
+    version: 1,
+    exportedAt: new Date().toISOString(),
+    scope: 'shares',
+    includeSecrets: false,
+    shares: { count: snapshot.count, digest: snapshot.digest },
+    data: {
+      shares: Object.fromEntries(snapshot.records.map((record) => [record.id, record])),
+    },
+  }
+  try {
+    await fs.writeFile(temporaryPath, `${JSON.stringify(backup, null, 2)}\n`, 'utf8')
+    const verified = JSON.parse(await fs.readFile(temporaryPath, 'utf8'))
+    const verifiedSnapshot = buildShareJsonSnapshot(verified.data?.shares)
+    if (verified.shares?.count !== snapshot.count || verified.shares?.digest !== snapshot.digest
+      || verifiedSnapshot.count !== snapshot.count || verifiedSnapshot.digest !== snapshot.digest) {
+      throw new Error('Share cutover backup verification failed')
+    }
+    await fs.rename(temporaryPath, finalPath)
+    return finalPath
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+function ownerPid(row) {
+  const value = Number(row?.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 acquireShareMaintenanceLock(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 share_maintenance_lock WHERE singleton = 1').get()
+    if (current && current.owner === identity.id) {
+      database.prepare(`UPDATE share_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 share_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 || 'share-maintenance', acquiredAt, acquiredAt, expiresAt)
+    return { owner: identity.id, ownerPid: identity.pid, fencing, expiresAt }
+  }, { mode: 'immediate' })
+}
+
+export function renewShareMaintenanceLock(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 share_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 releaseShareMaintenanceLock(storage, lease) {
+  return Number(storage.prepare('DELETE FROM share_maintenance_lock WHERE singleton = 1 AND owner = ? AND fencing = ?').run(lease.owner, lease.fencing).changes) === 1
+}
+
+async function waitForShareLock(storage, options) {
+  const deadline = Date.now() + (options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS)
+  while (Date.now() < deadline) {
+    const lease = acquireShareMaintenanceLock(storage, options)
+    if (lease) return lease
+    await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 100))
+  }
+  throw new Error('Timed out waiting for share maintenance lock')
+}
+
+export async function runShareMaintenance(operation, options = {}) {
+  const existing = maintenanceContext.getStore()
+  if (existing) return operation(existing)
+  const storage = options.storage || getSqliteStorage()
+  const lease = await waitForShareLock(storage, options)
+  const interval = options.heartbeatIntervalMs ?? Math.max(10, Math.floor((options.ttlMs ?? DEFAULT_LOCK_TTL_MS) / 3))
+  let rejectHeartbeat
+  let heartbeatError = null
+  const heartbeatFailure = new Promise((_, reject) => { rejectHeartbeat = reject })
+  const timer = setInterval(() => {
+    try {
+      if (!renewShareMaintenanceLock(storage, lease, options)) throw new Error('Share maintenance lock fencing was lost')
+    } catch (error) {
+      heartbeatError = error
+      rejectHeartbeat(error)
+    }
+  }, interval)
+  timer.unref?.()
+  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)
+    releaseShareMaintenanceLock(storage, lease)
+    maintenanceCount = Math.max(0, maintenanceCount - 1)
+  }
+}
+
+export function isShareMaintenanceActive(storage) {
+  if (!storage) {
+    try { storage = getSqliteStorage() } catch { return false }
+  }
+  return maintenanceCount > 0 || Boolean(storage.prepare('SELECT 1 AS active FROM share_maintenance_lock WHERE singleton = 1').get())
+}
+
+export function currentShareMaintenanceContext() {
+  return maintenanceContext.getStore() || null
+}
+
+/**
+ * JSON → SQLite share cutover. Phase machine:
+ * json_authoritative → cutover_running → sqlite_authoritative_json_pending →
+ * authoritative, backed by `share_storage_state` and the independent
+ * `share_maintenance_lock`. Runs a stable double snapshot (+ backup reread and
+ * a third stability read), then commits the SQLite replace and the pending
+ * phase in one transaction. Any failure before pending returns to
+ * json_authoritative; after pending the phase stays pending (fail-closed,
+ * recoverable on the next start by draining the mirror).
+ */
+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 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 })
+      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()
+      return readShareStorageState()
+    }
+
+    if (current.phase === SHARE_STORAGE_PHASES.CUTOVER_RUNNING && current.backupFile) {
+      setShareStoragePhase(SHARE_STORAGE_PHASES.JSON_AUTHORITATIVE, {
+        backupFile: current.backupFile,
+        diagnostic: { operation: 'cutover_recovery', recoveredFrom: SHARE_STORAGE_PHASES.CUTOVER_RUNNING },
+      })
+    }
+
+    let backupFile = current.backupFile
+    try {
+      const readJson = options.readJson || readSharesJsonFile
+      const first = buildShareJsonSnapshot(await readJson())
+      const second = buildShareJsonSnapshot(await readJson())
+      if (first.count !== second.count || first.digest !== second.digest) {
+        throw new Error('Share JSON source changed during cutover double read')
+      }
+      if (!backupFile) backupFile = await writeShareCutoverBackup(first, options.backupDirectory)
+      const third = buildShareJsonSnapshot(await readJson())
+      if (first.count !== third.count || first.digest !== third.digest) {
+        throw new Error('Share JSON source changed before cutover commit')
+      }
+      setShareStoragePhase(SHARE_STORAGE_PHASES.CUTOVER_RUNNING, {
+        shareCount: first.count,
+        digest: first.digest,
+        backupFile,
+        diagnostic: first.diagnostics,
+      })
+      const pendingValues = {
+        phase: SHARE_STORAGE_PHASES.JSON_PENDING,
+        backupFile,
+        diagnostic: first.diagnostics,
+      }
+      repository.replaceAll(first.records, {
+        expectedCount: first.count,
+        expectedDigest: first.digest,
+        storageState: pendingValues,
+      })
+      const integrity = repository.verifyIntegrity({ quickCheck: true })
+      if (!integrity.ok || integrity.count !== first.count || integrity.digest !== first.digest) {
+        throw new Error('Share SQLite replace verification failed')
+      }
+      // Refresh the cached phase so the mirror drain runs in pending mode.
+      readShareStorageState()
+      const drained = await drainShareJsonMirror()
+      if (drained.pending === 0) {
+        setShareStoragePhase(SHARE_STORAGE_PHASES.AUTHORITATIVE, {
+          shareCount: integrity.count,
+          digest: integrity.digest,
+          backupFile,
+          diagnostic: first.diagnostics,
+        })
+      }
+      return readShareStorageState()
+    } catch (error) {
+      const state = readShareStorageState()
+      if (![SHARE_STORAGE_PHASES.JSON_PENDING, SHARE_STORAGE_PHASES.AUTHORITATIVE].includes(state.phase)) {
+        setShareStoragePhase(SHARE_STORAGE_PHASES.JSON_AUTHORITATIVE, {
+          backupFile,
+          diagnostic: { operation: 'cutover', errorName: error?.name || 'Error', error: error?.message || String(error) },
+        })
+        return readShareStorageState()
+      }
+      throw error
+    }
+  }, { ...options, storage, operation: 'share-cutover' })
+}

package/server/share-json-file.mjs

@@ -0,0 +1,60 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { ensureStorage, storageDir } from './storage.mjs'
+
+// F10 mirror/backup file: `shares/conversation-shares.json` stays as the
+// best-effort JSON mirror (and cutover source) once SQLite is authoritative.
+export function sharesJsonPath() {
+  return path.join(storageDir, 'shares', 'conversation-shares.json')
+}
+
+export async function ensureSharesJsonFile() {
+  await ensureStorage()
+  await fs.mkdir(path.dirname(sharesJsonPath()), { recursive: true })
+  try {
+    await fs.access(sharesJsonPath())
+  } catch {
+    await fs.writeFile(sharesJsonPath(), '{}\n', 'utf8')
+  }
+}
+
+export async function readSharesJsonFile() {
+  await ensureSharesJsonFile()
+  try {
+    const raw = await fs.readFile(sharesJsonPath(), 'utf8')
+    const text = raw.trimStart()
+    const parsed = text ? JSON.parse(text) : {}
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    throw error
+  }
+}
+
+export async function writeSharesJsonFile(data) {
+  await ensureSharesJsonFile()
+  const finalPath = sharesJsonPath()
+  const temporaryPath = `${finalPath}.${process.pid}.tmp`
+  try {
+    await fs.writeFile(temporaryPath, `${JSON.stringify(data || {}, null, 2)}\n`, 'utf8')
+    await fs.rename(temporaryPath, finalPath)
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+// Materialize one mirror entry into the whole-file JSON store.
+export async function materializeShareJsonEntry(entry) {
+  if (!entry || typeof entry !== 'object') throw new Error('Share mirror entry is invalid')
+  const data = await readSharesJsonFile()
+  if (entry.operation === 'delete') {
+    if (!entry.shareId) throw new Error('Share mirror delete requires a shareId')
+    delete data[entry.shareId]
+  } else if (entry.operation === 'upsert' && entry.record?.id) {
+    data[entry.record.id] = entry.record
+  } else {
+    throw new Error('Share mirror entry is invalid')
+  }
+  await writeSharesJsonFile(data)
+}