dsh-conversation-recycle-bin 0.2.0 → 0.2.2

package/lib/core/cascade.js

@@ -78,6 +78,7 @@ export async function performSessionDelete({
   config,
   now = Date.now,
   actor = 'local-user',
+  source = 'web-ui',
   requestId = null,
 }) {
   const startedAt = now()
@@ -142,10 +143,21 @@ export async function performSessionDelete({
       name: 'messages',
       run: async () => {
         const moved = await ops.sessionLog.moveToTrash(session, dir)
+        try {
+          // Record the move immediately. A crash between the move and the
+          // final manifest write used to leave a `pending` entry that knew
+          // nothing about the log sitting in its directory: discard refused
+          // it, restore had nothing to restore, and the payload was stranded.
+          await trash.update(entry.trashId, { sessionLog: moved })
+        } catch (error) {
+          await ops.sessionLog.restoreEntry(moved).catch(() => {})
+          throw error
+        }
         entry.sessionLog = moved
         return async () => {
           await ops.sessionLog.restoreEntry(moved)
           entry.sessionLog = null
+          await trash.update(entry.trashId, { sessionLog: null }).catch(() => {})
         }
       },
     })
@@ -190,7 +202,7 @@ export async function performSessionDelete({
         actor,
         requestId,
         durationMs: now() - startedAt,
-        source: 'web-ui',
+        source,
       })
     },
   })
@@ -226,7 +238,7 @@ export async function performSessionDelete({
           })),
         },
         durationMs: now() - startedAt,
-        source: 'web-ui',
+        source,
       })
       .catch(() => {})
     throw toDeleteError(result, { sessionId: session.id, title: entry.title })
@@ -263,26 +275,34 @@ const RESTORABLE_STATUSES = new Set(['trashed', 'pending', 'failed', 'restoring'
  * @param {string} [input.actor]
  * @param {string} [input.requestId]
  */
-export async function performRestore({ entry, ops, trash, audit, now = Date.now, actor = 'local-user', requestId = null }) {
+export async function performRestore({ entry, ops, trash, audit, now = Date.now, actor = 'local-user', source = 'web-ui', requestId = null }) {
   const previousStatus = entry.status
   if (!RESTORABLE_STATUSES.has(previousStatus)) {
     throw new DeleteError('E_TRASH_CONFLICT', 'This recycle-bin entry is not in a restorable state.', { trashId: entry.trashId, status: previousStatus })
   }
-  const hasLog = entry.sessionLog !== null && entry.sessionLog !== undefined && typeof entry.sessionLog === 'object'
+  const sessionLog = entry.sessionLog !== null && entry.sessionLog !== undefined && typeof entry.sessionLog === 'object'
+    ? entry.sessionLog
+    : null
   const catalog = entry.catalog !== null && entry.catalog !== undefined && typeof entry.catalog === 'object' ? entry.catalog : null
   const hasMemory = entry.includeMemory === true && entry.memory !== null && typeof entry.memory === 'object' && (entry.memory.total ?? 0) > 0
-  // Re-attaching a hard-deleted conversation whose log is missing would leave a
+  const canStat = typeof ops.pathExists === 'function'
+  const logInTrash = sessionLog !== null && (!canStat || await ops.pathExists(sessionLog.to))
+  const logInPlace = sessionLog !== null && canStat && await ops.pathExists(sessionLog.from)
+  const logMissing = sessionLog !== null && !logInTrash && !logInPlace
+  // Re-attaching a hard-deleted conversation whose log is nowhere would leave a
   // conversation with no messages on disk, so that combination stays refused.
-  if (catalog !== null && entry.mode === 'hard' && !hasLog) {
+  // A log that is already back in place is fine: an interrupted purge can leave
+  // exactly that state.
+  if (catalog !== null && entry.mode === 'hard' && (sessionLog === null || logMissing)) {
     throw new DeleteError('E_TRASH_CONFLICT', 'The recycle-bin entry has no session-log location; restore is unsafe.', { trashId: entry.trashId })
   }
 
   const steps = []
-  if (entry.mode === 'hard' && hasLog) {
+  if (entry.mode === 'hard' && logInTrash) {
     steps.push({
       name: 'messages',
       run: async () => {
-        const undo = await ops.sessionLog.restoreEntry(entry.sessionLog)
+        const undo = await ops.sessionLog.restoreEntry(sessionLog)
         return async () => {
           await undo()
         }
@@ -314,10 +334,15 @@ export async function performRestore({ entry, ops, trash, audit, now = Date.now,
     })
   }
   if (steps.length === 0) {
-    throw new DeleteError('E_TRASH_CONFLICT', 'The recycle-bin entry has nothing left to restore; discard it to reclaim the space.', {
-      trashId: entry.trashId,
-      status: previousStatus,
-    })
+    // The log is already back on disk (an interrupted purge can leave the
+    // manifest pointing at a log that was moved back): clearing the entry is
+    // the only remaining action, and it is safe.
+    if (!(entry.mode === 'hard' && logInPlace)) {
+      throw new DeleteError('E_TRASH_CONFLICT', 'The recycle-bin entry has nothing left to restore; discard it to reclaim the space.', {
+        trashId: entry.trashId,
+        status: previousStatus,
+      })
+    }
   }
 
   const startedAt = now()
@@ -340,7 +365,7 @@ export async function performRestore({ entry, ops, trash, audit, now = Date.now,
         requestId,
         failedStep: result.failedStep,
         rollback: { ok: result.rolledBack, errors: result.rollbackErrors.map((item) => ({ step: item.step, message: String(item.error) })) },
-        source: 'web-ui',
+        source,
       })
       .catch(() => {})
     throw toDeleteError(result, { sessionId: entry.sessionId, title: entry.title })
@@ -356,7 +381,7 @@ export async function performRestore({ entry, ops, trash, audit, now = Date.now,
     actor,
     requestId,
     durationMs: now() - startedAt,
-    source: 'web-ui',
+    source,
   })
   await trash.remove(entry.trashId).catch(() => {})
   return { trashId: entry.trashId, sessionId: entry.sessionId }
@@ -379,7 +404,7 @@ export async function performRestore({ entry, ops, trash, audit, now = Date.now,
  * @param {string} [input.actor]
  * @param {string} [input.requestId]
  */
-export async function performPurge({ entry, ops, trash, audit, now = Date.now, actor = 'local-user', requestId = null }) {
+export async function performPurge({ entry, ops, trash, audit, now = Date.now, actor = 'local-user', source = 'web-ui', requestId = null }) {
   if (!['trashed', 'restored'].includes(entry.status)) {
     throw new DeleteError('E_TRASH_CONFLICT', 'This recycle-bin entry cannot be purged in its current state.', { trashId: entry.trashId, status: entry.status })
   }
@@ -405,8 +430,17 @@ export async function performPurge({ entry, ops, trash, audit, now = Date.now, a
         name: 'messages',
         run: async () => {
           const moved = await ops.sessionLog.moveToTrash(session, trash.entryDir(entry.trashId))
+          try {
+            await trash.update(entry.trashId, { sessionLog: moved })
+          } catch (error) {
+            await ops.sessionLog.restoreEntry(moved).catch(() => {})
+            throw error
+          }
+          entry.sessionLog = moved
           return async () => {
             await ops.sessionLog.restoreEntry(moved)
+            entry.sessionLog = null
+            await trash.update(entry.trashId, { sessionLog: null }).catch(() => {})
           }
         },
       })
@@ -445,7 +479,7 @@ export async function performPurge({ entry, ops, trash, audit, now = Date.now, a
         requestId,
         failedStep: result.failedStep,
         rollback: { ok: result.rolledBack, errors: result.rollbackErrors.map((item) => ({ step: item.step, message: String(item.error) })) },
-        source: 'web-ui',
+        source,
       })
       .catch(() => {})
     throw toDeleteError(result, { sessionId: entry.sessionId, title: entry.title })
@@ -461,7 +495,7 @@ export async function performPurge({ entry, ops, trash, audit, now = Date.now, a
     actor,
     requestId,
     durationMs: now() - startedAt,
-    source: 'web-ui',
+    source,
   })
   return { trashId: entry.trashId, sessionId: entry.sessionId }
 }
@@ -484,7 +518,7 @@ export async function performPurge({ entry, ops, trash, audit, now = Date.now, a
  * @param {string} [input.actor]
  * @param {string} [input.requestId]
  */
-export async function performDiscard({ entry, ops, trash, audit, now = Date.now, actor = 'local-user', requestId = null }) {
+export async function performDiscard({ entry, ops, trash, audit, now = Date.now, actor = 'local-user', source = 'web-ui', requestId = null }) {
   if (entry.status === 'trashed') {
     throw new DeleteError('E_TRASH_CONFLICT', 'This entry is a committed deletion; restore or purge it instead of discarding it.', {
       trashId: entry.trashId,
@@ -524,7 +558,7 @@ export async function performDiscard({ entry, ops, trash, audit, now = Date.now,
       actor,
       requestId,
       durationMs: now() - startedAt,
-      source: 'web-ui',
+      source,
     })
     .catch(() => {})
   return { trashId: entry.trashId, sessionId: entry.sessionId }

package/lib/core/config.js

@@ -92,7 +92,10 @@ function readBool(raw, fallback, field, warnings) {
 }
 
 function readString(raw, fallback, field, warnings) {
-  if (raw === undefined) return fallback
+  // `null` is the documented "unset" spelling for nullable fields
+  // (`memory.lingshu.rootDir`, `memory.generic.indexFile`), so it must not be
+  // reported as a type error on every activation.
+  if (raw === undefined || raw === null) return fallback
   if (typeof raw === 'string') return raw.trim()
   warnings.push(`${field}: expected a string, using ${fallback}`)
   return fallback

package/lib/core/errors.js

@@ -5,12 +5,14 @@
  * maps `code` to an HTTP status once, so the UI can branch on the code without
  * parsing prose. Codes are stable API: add new ones, never rename existing ones.
  */
+import { redactDetails } from './redact.js'
 
 /** HTTP status per error code. Keep this table exhaustive for every thrown code. */
 export const ERROR_STATUS = Object.freeze({
   E_DISABLED: 503,
   E_FORBIDDEN_ORIGIN: 403,
   E_FORBIDDEN_HOST: 403,
+  E_UNAUTHORIZED: 401,
   E_BAD_REQUEST: 400,
   E_NOT_FOUND: 404,
   E_POLICY_PROTECTED: 403,
@@ -29,6 +31,7 @@ export const ERROR_STATUS = Object.freeze({
   E_TRASH_NOT_FOUND: 404,
   E_TRASH_CONFLICT: 409,
   E_MEMORY_FAILED: 500,
+  E_LOCK_BUSY: 409,
   E_INTERNAL: 500,
 })
 
@@ -69,10 +72,10 @@ export function asDeleteError(error, fallbackCode = 'E_INTERNAL') {
   }, { cause: error })
 }
 
-/** Wire shape for a failed call. */
+/** Wire shape for a failed call. Host paths are redacted before crossing HTTP. */
 export function toWireError(error) {
   const normalized = asDeleteError(error)
-  return { ok: false, error: normalized.toJSON() }
+  return { ok: false, error: redactDetails(normalized.toJSON()) }
 }
 
 /** Wire shape for a successful call. */

package/lib/core/file-lock.js

@@ -0,0 +1,151 @@
+/**
+ * Small cross-process advisory lock built from an exclusively-created file.
+ *
+ * This is NOT a replacement for an OS byte-range lock: it coordinates writers
+ * that use the same protocol (this plugin's Host processes and its memory
+ * adapter). It deliberately never touches another program's lock file — the
+ * 灵枢 (md_cg) store keeps a permanent, zero-byte `<index>.lock` that is
+ * guarded by `msvcrt.locking`/`flock`; treating that file's existence as a
+ * lock (or deleting it) breaks its writer instead of excluding it.
+ *
+ * Semantics:
+ *   - acquisition creates `<lockPath>` with `wx`, writes `{pid, nonce, at}`;
+ *   - a holder refreshes the file mtime on a heartbeat, so a long operation is
+ *     never mistaken for a crashed one;
+ *   - a lock is stale when its mtime is older than `staleMs`, or when the
+ *     recorded pid is provably gone; a stale lock is removed and retried;
+ *   - release only removes the file when it still carries this owner's nonce,
+ *     so a lock broken by a peer cannot make us delete the peer's lock.
+ *
+ * Every wait sleeps, and the wait budget is checked on every iteration: a
+ * held lock can never spin forever (the bug this module replaces).
+ */
+import * as defaultFs from 'node:fs/promises'
+import { randomBytes } from 'node:crypto'
+
+const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function defaultIsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM means the process exists but is owned by someone else.
+    return error?.code === 'EPERM'
+  }
+}
+
+function parseOwner(raw) {
+  try {
+    const value = JSON.parse(String(raw))
+    if (value !== null && typeof value === 'object') {
+      return { pid: Number.isInteger(value.pid) ? value.pid : null, nonce: typeof value.nonce === 'string' ? value.nonce : null }
+    }
+  } catch {
+    // A legacy/foreign lock may be empty or plain text; it has no owner.
+  }
+  return { pid: null, nonce: null }
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.lockPath absolute path of the lock file
+ * @param {number} [options.timeoutMs] wait budget for one acquisition
+ * @param {number} [options.staleMs] age after which an ownerless lock is broken
+ * @param {number} [options.heartbeatMs] mtime refresh interval while held
+ * @param {number} [options.retryMs] poll interval
+ * @param {() => number} [options.now]
+ * @param {(ms: number) => Promise<void>} [options.sleep]
+ * @param {(pid: number) => boolean} [options.isProcessAlive]
+ * @param {object} [options.fsApi]
+ * @param {number} [options.pid]
+ */
+export function createFileLock({
+  lockPath,
+  timeoutMs = 15_000,
+  staleMs = 120_000,
+  heartbeatMs = 5_000,
+  retryMs = 50,
+  now = Date.now,
+  sleep = sleepDefault,
+  isProcessAlive = defaultIsProcessAlive,
+  fsApi = defaultFs,
+  pid = process.pid,
+}) {
+  if (typeof lockPath !== 'string' || lockPath === '') throw new Error('file-lock: lockPath is required')
+
+  /**
+   * Acquire the lock.
+   * @returns {Promise<() => Promise<void>>} release
+   */
+  async function acquire() {
+    const nonce = randomBytes(8).toString('hex')
+    const started = now()
+    let handle = null
+
+    while (handle === null) {
+      try {
+        handle = await fsApi.open(lockPath, 'wx')
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        let info
+        try {
+          info = await fsApi.stat(lockPath)
+        } catch (statError) {
+          if (statError?.code === 'ENOENT') continue
+          throw statError
+        }
+        const age = Math.max(0, now() - info.mtimeMs)
+        let owner = { pid: null, nonce: null }
+        try {
+          owner = parseOwner(await fsApi.readFile(lockPath, 'utf8'))
+        } catch {
+          // Unreadable owner text is treated as ownerless, not as a crash.
+        }
+        const deadOwner = owner.pid !== null && !isProcessAlive(owner.pid)
+        if (age > staleMs || deadOwner) {
+          await fsApi.rm(lockPath, { force: true }).catch(() => {})
+          continue
+        }
+        if (now() - started >= timeoutMs) {
+          const busy = new Error(`The lock ${lockPath} is held by another process.`)
+          busy.code = 'E_LOCK_BUSY'
+          throw busy
+        }
+        await sleep(retryMs)
+        continue
+      }
+
+      try {
+        await handle.writeFile(`${JSON.stringify({ pid, nonce, at: now() })}\n`, 'utf8')
+      } catch (error) {
+        await handle.close().catch(() => {})
+        await fsApi.rm(lockPath, { force: true }).catch(() => {})
+        throw error
+      }
+      break
+    }
+
+    const heartbeat = setInterval(() => {
+      const stamp = new Date()
+      fsApi.utimes(lockPath, stamp, stamp).catch(() => {})
+    }, Math.max(250, heartbeatMs))
+    if (typeof heartbeat.unref === 'function') heartbeat.unref()
+
+    let released = false
+    return async () => {
+      if (released) return
+      released = true
+      clearInterval(heartbeat)
+      try {
+        const owner = parseOwner(await fsApi.readFile(lockPath, 'utf8').catch(() => ''))
+        if (owner.nonce === nonce) await fsApi.rm(lockPath, { force: true }).catch(() => {})
+      } finally {
+        await handle?.close().catch(() => {})
+      }
+    }
+  }
+
+  return { acquire, lockPath }
+}

package/lib/core/memory/generic-json.js

@@ -17,13 +17,13 @@ export function createGenericJsonAdapter({ indexFile, rootDir, sessionField = 's
   if (typeof indexFile !== 'string' || indexFile === '') return null
   return createJsonIndexMemoryAdapter({
     id: 'generic-json',
-    label: 'Generic JSON memory store',
+    // Neutral label: the Client localizes by adapter id.
+    label: 'generic-json',
     indexFile,
     rootDir: typeof rootDir === 'string' && rootDir !== '' ? rootDir : null,
     sessionField,
     nodesPointer,
     contentField: rootDir === null ? null : 'path',
-    useStoreLock: false,
     now,
     fsApi,
   })