pi-hermes-memory 0.7.22 → 0.8.0

package/src/store/memory-store.ts

@@ -11,6 +11,7 @@
  * - Content scanning before any write
  */
 
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { scanContent } from "./content-scanner.js";
@@ -26,13 +27,29 @@ import {
 } from "../constants.js";
 import type { MemoryConfig, MemoryResult, MemorySnapshot, ConsolidationResult, MemoryCategory, MemoryOverflowStrategy } from "../types.js";
 import { AGENT_ROOT } from "../paths.js";
+import { canonicalMarkdownIdentity, withMarkdownMutationLock } from "./markdown-mutation-lock.js";
+
+const MAX_EXTERNAL_WRITE_RETRIES = 2;
+const RECOVERY_ACTIVE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+const RETIRED_RECOVERY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const RETIRED_RECOVERY_MAX_COUNT = 32;
+const RETIRED_RECOVERY_MAX_BYTES = 64 * 1024 * 1024;
+const CONFLICT_ACTIVE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+const CONFLICT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const CONFLICT_MAX_COUNT = 32;
+const CONFLICT_MAX_BYTES = 64 * 1024 * 1024;
+
+class ExternalMemoryWriteConflict extends Error {}
 
 export class MemoryStore {
   private memoryEntries: string[] = [];
   private userEntries: string[] = [];
   private failureEntries: string[] = [];
+  private fileFingerprints: Record<string, string> = {};
+  private storagePaths: Partial<Record<"memory" | "user" | "failure", string>> = {};
   private snapshot: MemorySnapshot = { memory: "", user: "" };
   private consolidator: ((target: "memory" | "user" | "failure", signal?: AbortSignal) => Promise<ConsolidationResult>) | null = null;
+  private mutationObserver: ((target: "memory" | "user" | "failure", entries: string[]) => Promise<string | null | undefined>) | null = null;
 
   constructor(private config: MemoryConfig) {}
 
@@ -44,6 +61,12 @@ export class MemoryStore {
     this.consolidator = fn;
   }
 
+  setMutationObserver(
+    fn: (target: "memory" | "user" | "failure", entries: string[]) => Promise<string | null | undefined>,
+  ): void {
+    this.mutationObserver = fn;
+  }
+
   // ─── Path helpers ───
 
   private get memoryDir(): string {
@@ -56,6 +79,18 @@ export class MemoryStore {
     return path.join(this.memoryDir, MEMORY_FILE);
   }
 
+  async getStorageIdentity(target: "memory" | "user" | "failure"): Promise<string> {
+    return this.resolveStoragePath(target);
+  }
+
+  private async resolveStoragePath(target: "memory" | "user" | "failure"): Promise<string> {
+    const cached = this.storagePaths[target];
+    if (cached) return cached;
+    const resolved = await canonicalMarkdownIdentity(this.pathFor(target));
+    this.storagePaths[target] = resolved;
+    return resolved;
+  }
+
   private entriesFor(target: "memory" | "user" | "failure"): string[] {
     if (target === "user") return this.userEntries;
     if (target === "failure") return this.failureEntries;
@@ -86,15 +121,14 @@ export class MemoryStore {
 
   async loadFromDisk(): Promise<void> {
     await fs.mkdir(this.memoryDir, { recursive: true });
-    this.memoryEntries = await this.readFile(this.pathFor("memory"));
-    this.userEntries = await this.readFile(this.pathFor("user"));
-    this.failureEntries = await this.readFile(this.pathFor("failure"));
+    for (const target of ["memory", "user", "failure"] as const) {
+      const filePath = await this.resolveStoragePath(target);
+      const state = await this.readFileState(filePath);
+      this.setEntries(target, [...new Set(state.entries)]);
+      this.fileFingerprints[filePath] = state.fingerprint;
+    }
 
     // Deduplicate preserving order
-    this.memoryEntries = [...new Set(this.memoryEntries)];
-    this.userEntries = [...new Set(this.userEntries)];
-    this.failureEntries = [...new Set(this.failureEntries)];
-
     // Capture frozen snapshot for system prompt injection
     // Strip metadata comments — the LLM doesn't need to see timestamps
     const strippedMemory = this.memoryEntries.map((e) => this.stripMetadata(e));
@@ -108,7 +142,7 @@ export class MemoryStore {
   // ─── CRUD ───
 
   async add(target: "memory" | "user" | "failure", content: string, signal?: AbortSignal): Promise<MemoryResult> {
-    return this._add(target, content, signal);
+    return this.addWithConsolidation(target, content, signal, 1, "Entry added.");
   }
 
   async addFailure(content: string, options: {
@@ -119,7 +153,9 @@ export class MemoryStore {
     project?: string;
   }): Promise<MemoryResult> {
     const failureText = this.buildFailureMemoryText(content, options);
-    return this._add("failure", failureText, undefined, 1, "Failure memory saved: " + options.category);
+    return this.addWithConsolidation(
+      "failure", failureText, undefined, 1, "Failure memory saved: " + options.category, options.project,
+    );
   }
 
   getFailureEntries(maxAgeDays = 7): string[] {
@@ -139,8 +175,8 @@ export class MemoryStore {
     target: "memory" | "user" | "failure",
     content: string,
     signal?: AbortSignal,
-    _retriesLeft = 1,
     addedMessage = "Entry added.",
+    project?: string,
   ): Promise<MemoryResult> {
     content = content.trim();
     if (!content) return { success: false, error: "Content cannot be empty." };
@@ -148,18 +184,24 @@ export class MemoryStore {
     const scanError = scanContent(content);
     if (scanError) return { success: false, error: scanError };
 
+    await this.syncTargetFromDiskIfChanged(target);
     const entries = this.entriesFor(target);
     const limit = this.charLimit(target);
 
     // Check for duplicate — strip metadata from existing entries before comparing
-    const strippedEntries = entries.map((e) => this.stripMetadata(e));
-    if (strippedEntries.includes(content)) {
+    const normalizedProject = project?.trim() || null;
+    const duplicate = entries.some((entry) => {
+      const decoded = this.decodeEntry(entry);
+      return decoded.text === content
+        && (target !== "failure" || decoded.project === normalizedProject);
+    });
+    if (duplicate) {
       return this.successResponse(target, "Entry already exists (no duplicate added).");
     }
 
     // Encode metadata: both dates = today
     const today = new Date().toISOString().split("T")[0];
-    const encoded = this.encodeEntry(content, today, today);
+    const encoded = this.encodeEntry(content, today, today, project);
 
     const newTotal = [...entries, encoded].join(ENTRY_DELIMITER).length;
     if (newTotal > limit) {
@@ -169,20 +211,6 @@ export class MemoryStore {
         return this.fifoEvictAndAdd(target, entries, encoded, content.length, limit);
       }
 
-      // Auto-consolidate once if configured — limit retries to prevent infinite loops
-      if (strategy === "auto-consolidate" && this.consolidator && _retriesLeft > 0) {
-        try {
-          const result = await this.consolidator(target, signal);
-          if (result.consolidated) {
-            // CRITICAL: reload from disk — child process modified files, our arrays are stale
-            await this.loadFromDisk();
-            // Retry the add exactly once (retriesLeft = 0 means no more consolidation)
-            return this._add(target, content, signal, _retriesLeft - 1, addedMessage);
-          }
-        } catch {
-          // Consolidation failed — fall through to error
-        }
-      }
       return this.memoryFullError(target, content.length);
     }
 
@@ -193,6 +221,39 @@ export class MemoryStore {
     return this.successResponse(target, addedMessage);
   }
 
+  private async addWithConsolidation(
+    target: "memory" | "user" | "failure",
+    content: string,
+    signal: AbortSignal | undefined,
+    retriesLeft: number,
+    addedMessage: string,
+    project?: string,
+  ): Promise<MemoryResult> {
+    const result = await this.runTargetMutation(
+      target,
+      () => this._add(target, content, signal, addedMessage, project),
+    );
+    if (
+      result.success
+      || retriesLeft <= 0
+      || this.memoryOverflowStrategy() !== "auto-consolidate"
+      || !this.consolidator
+      || !result.error?.startsWith("Memory at ")
+    ) {
+      return result;
+    }
+
+    try {
+      const consolidation = await this.consolidator(target, signal);
+      if (consolidation.consolidated) {
+        await this.loadFromDisk();
+        return this.addWithConsolidation(target, content, signal, retriesLeft - 1, addedMessage, project);
+      }
+    } catch {
+    }
+    return result;
+  }
+
   private async fifoEvictAndAdd(
     target: "memory" | "user" | "failure",
     entries: string[],
@@ -236,6 +297,10 @@ export class MemoryStore {
   }
 
   async replace(target: "memory" | "user" | "failure", oldText: string, newContent: string): Promise<MemoryResult> {
+    return this.runTargetMutation(target, () => this.replaceUnlocked(target, oldText, newContent));
+  }
+
+  private async replaceUnlocked(target: "memory" | "user" | "failure", oldText: string, newContent: string): Promise<MemoryResult> {
     oldText = normalizeMemoryLookupText(oldText);
     newContent = newContent.trim();
     if (!oldText) return { success: false, error: "old_text cannot be empty." };
@@ -244,12 +309,13 @@ export class MemoryStore {
     const scanError = scanContent(newContent);
     if (scanError) return { success: false, error: scanError };
 
+    await this.syncTargetFromDiskIfChanged(target);
     const entries = this.entriesFor(target);
     // Match against stripped text (entries may have metadata comments)
     const matches = entries.filter((e) => this.stripMetadata(e).includes(oldText));
 
     if (matches.length === 0) return { success: false, error: `No entry matched '${oldText}'.` };
-    if (matches.length > 1 && new Set(matches).size > 1) {
+    if (matches.length > 1 && !this.areDistinctScopedFailureCopies(target, matches)) {
       return {
         success: false,
         error: `Multiple entries matched '${oldText}'. Be more specific.`,
@@ -257,14 +323,12 @@ export class MemoryStore {
       };
     }
 
-    const idx = entries.indexOf(matches[0]);
-    // Preserve original created date, update last_referenced to today
-    const decoded = this.decodeEntry(matches[0]);
     const today = new Date().toISOString().split("T")[0];
-    const encoded = this.encodeEntry(newContent, decoded.created, today);
-
-    const testEntries = [...entries];
-    testEntries[idx] = encoded;
+    const replacements = new Map(matches.map((entry) => {
+      const decoded = this.decodeEntry(entry);
+      return [entry, this.encodeEntry(newContent, decoded.created, today, decoded.project ?? undefined)];
+    }));
+    const testEntries = entries.map((entry) => replacements.get(entry) ?? entry);
     const newTotal = testEntries.join(ENTRY_DELIMITER).length;
 
     if (newTotal > this.charLimit(target)) {
@@ -274,22 +338,26 @@ export class MemoryStore {
       };
     }
 
-    entries[idx] = encoded;
-    this.setEntries(target, entries);
+    this.setEntries(target, testEntries);
     await this.saveToDisk(target);
 
     return this.successResponse(target, "Entry replaced.");
   }
 
   async remove(target: "memory" | "user" | "failure", oldText: string): Promise<MemoryResult> {
+    return this.runTargetMutation(target, () => this.removeUnlocked(target, oldText));
+  }
+
+  private async removeUnlocked(target: "memory" | "user" | "failure", oldText: string): Promise<MemoryResult> {
     oldText = normalizeMemoryLookupText(oldText);
     if (!oldText) return { success: false, error: "old_text cannot be empty." };
 
+    await this.syncTargetFromDiskIfChanged(target);
     const entries = this.entriesFor(target);
     const matches = entries.filter((e) => this.stripMetadata(e).includes(oldText));
 
     if (matches.length === 0) return { success: false, error: `No entry matched '${oldText}'.` };
-    if (matches.length > 1 && new Set(matches).size > 1) {
+    if (matches.length > 1 && !this.areDistinctScopedFailureCopies(target, matches)) {
       return {
         success: false,
         error: `Multiple entries matched '${oldText}'. Be more specific.`,
@@ -297,9 +365,8 @@ export class MemoryStore {
       };
     }
 
-    const idx = entries.indexOf(matches[0]);
-    entries.splice(idx, 1);
-    this.setEntries(target, entries);
+    const matchedEntries = new Set(matches);
+    this.setEntries(target, entries.filter((entry) => !matchedEntries.has(entry)));
     await this.saveToDisk(target);
 
     return this.successResponse(target, "Entry removed.");
@@ -355,28 +422,40 @@ export class MemoryStore {
     return this.userEntries.map((e) => this.stripMetadata(e));
   }
 
+  /** Raw Markdown entries, including metadata, for exact SQLite reconciliation. */
+  getRawEntriesForSync(target: "memory" | "user" | "failure"): string[] {
+    return [...this.entriesFor(target)];
+  }
+
   // ─── Internal helpers ───
 
   /**
    * Encode metadata (created, lastReferenced) as an HTML comment appended to entry text.
    * The comment is invisible in markdown and transparent to the § delimiter.
    */
-  private encodeEntry(text: string, created: string, lastReferenced: string): string {
-    return `${text} <!-- created=${created}, last=${lastReferenced} -->`;
+  private encodeEntry(text: string, created: string, lastReferenced: string, project?: string): string {
+    const projectMetadata = project?.trim()
+      ? `, project64=${Buffer.from(project.trim(), "utf-8").toString("base64url")}`
+      : "";
+    return `${text} <!-- created=${created}, last=${lastReferenced}${projectMetadata} -->`;
   }
 
   /**
    * Decode entry text, extracting metadata if present.
    * Falls back to today's date for legacy entries without metadata.
    */
-  private decodeEntry(raw: string): { text: string; created: string; lastReferenced: string } {
-    const match = raw.match(/^(.*?)\s*<!--\s*created=([^,]+),\s*last=([^>]+)\s*-->\s*$/);
+  private decodeEntry(raw: string): { text: string; created: string; lastReferenced: string; project: string | null } {
+    const match = raw.match(/^(.*?)\s*<!--\s*created=([^,]+),\s*last=([^,>]+)(?:,\s*project64=([A-Za-z0-9_-]+))?\s*-->\s*$/);
     if (match) {
-      return { text: match[1].trim(), created: match[2].trim(), lastReferenced: match[3].trim() };
+      let project: string | null = null;
+      if (match[4]) {
+        try { project = Buffer.from(match[4], "base64url").toString("utf-8").trim() || null; } catch {}
+      }
+      return { text: match[1].trim(), created: match[2].trim(), lastReferenced: match[3].trim(), project };
     }
     // Legacy entry without metadata — use today as default
     const today = new Date().toISOString().split("T")[0];
-    return { text: raw.trim(), created: today, lastReferenced: today };
+    return { text: raw.trim(), created: today, lastReferenced: today, project: null };
   }
 
   /** Strip metadata comment from entry text for display. */
@@ -384,6 +463,16 @@ export class MemoryStore {
     return this.decodeEntry(text).text;
   }
 
+  private areDistinctScopedFailureCopies(
+    target: "memory" | "user" | "failure",
+    entries: string[],
+  ): boolean {
+    if (target !== "failure") return false;
+    const visibleTexts = new Set(entries.map((entry) => this.stripMetadata(entry)));
+    const scopes = new Set(entries.map((entry) => this.decodeEntry(entry).project));
+    return visibleTexts.size === 1 && scopes.size === entries.length;
+  }
+
   private buildFailureMemoryText(content: string, options: {
     category: MemoryCategory;
     failureReason?: string;
@@ -397,7 +486,6 @@ export class MemoryStore {
     if (options.failureReason) parts.push("Failed: " + options.failureReason);
     if (options.toolState) parts.push("Tool state: " + options.toolState);
     if (options.correctedTo) parts.push("Corrected to: " + options.correctedTo);
-    if (options.project) parts.push("Project: " + options.project);
     return parts.join(" — ");
   }
 
@@ -470,16 +558,79 @@ export class MemoryStore {
     return `${header}\n${bulletList}`;
   }
 
-  private async readFile(filePath: string): Promise<string[]> {
+  private fingerprint(content: Buffer | string): string {
+    return createHash("sha256").update(content).digest("hex");
+  }
+
+  private async readFileState(filePath: string): Promise<{ entries: string[]; fingerprint: string }> {
     try {
-      const raw = await fs.readFile(filePath, "utf-8");
-      if (!raw.trim()) return [];
-      return raw.split(ENTRY_DELIMITER).map((e) => e.trim()).filter(Boolean);
-    } catch {
-      return [];
+      const raw = await fs.readFile(filePath);
+      const content = raw.toString("utf-8");
+      const entries = content.trim()
+        ? content.split(ENTRY_DELIMITER).map((entry) => entry.trim()).filter(Boolean)
+        : [];
+      return { entries, fingerprint: this.fingerprint(raw) };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return { entries: [], fingerprint: "missing" };
+      }
+      throw error;
     }
   }
 
+  private async syncTargetFromDiskIfChanged(target: "memory" | "user" | "failure"): Promise<void> {
+    const filePath = await this.resolveStoragePath(target);
+    const state = await this.readFileState(filePath);
+    if (this.fileFingerprints[filePath] === state.fingerprint) return;
+
+    this.setEntries(target, [...new Set(state.entries)]);
+    this.fileFingerprints[filePath] = state.fingerprint;
+  }
+
+  private async runTargetMutation(
+    target: "memory" | "user" | "failure",
+    mutation: () => Promise<MemoryResult>,
+  ): Promise<MemoryResult> {
+    const storagePath = await this.resolveStoragePath(target);
+    return withMarkdownMutationLock(storagePath, async () => {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          const result = await mutation();
+          if (result.success && this.mutationObserver) {
+            const filePath = storagePath;
+            const state = await this.readFileState(filePath);
+            this.setEntries(target, [...new Set(state.entries)]);
+            this.fileFingerprints[filePath] = state.fingerprint;
+            const warning = await this.mutationObserver(target, [...state.entries]);
+            if (warning) {
+              const warnings = [...(result.warnings ?? []), warning];
+              return {
+                ...result,
+                message: result.message ? `${result.message} Warning: ${warning}` : warning,
+                warning,
+                warnings,
+              };
+            }
+          }
+          return result;
+        } catch (error) {
+          const filePath = storagePath;
+          delete this.fileFingerprints[filePath];
+          const state = await this.readFileState(filePath);
+          this.setEntries(target, [...new Set(state.entries)]);
+          this.fileFingerprints[filePath] = state.fingerprint;
+          if (!(error instanceof ExternalMemoryWriteConflict)) throw error;
+          if (attempt >= MAX_EXTERNAL_WRITE_RETRIES) {
+            return {
+              success: false,
+              error: "Memory file changed repeatedly during this update. No external changes were overwritten.",
+            };
+          }
+        }
+      }
+    });
+  }
+
   /**
    * Atomic write: temp file + fs.rename().
    * Creates temp files in the same directory as the target to avoid
@@ -487,17 +638,87 @@ export class MemoryStore {
    * drive than the memory directory (common on Windows).
    */
   private async saveToDisk(target: "memory" | "user" | "failure"): Promise<void> {
-    const filePath = this.pathFor(target);
+    const filePath = await this.resolveStoragePath(target);
     const entries = this.entriesFor(target);
     const content = entries.length ? entries.join(ENTRY_DELIMITER) : "";
+    const expectedFingerprint = this.fileFingerprints[filePath] ?? "missing";
 
     // Use the memory directory for temp files so rename stays on the same device
-    const tmpDir = await fs.mkdtemp(path.join(this.memoryDir, ".tmp-"));
+    const tmpDir = await fs.mkdtemp(path.join(path.dirname(filePath), ".tmp-"));
     const tmpPath = path.join(tmpDir, "write.tmp");
 
     try {
       await fs.writeFile(tmpPath, content, "utf-8");
-      await fs.rename(tmpPath, filePath);
+      await this.pruneRecoveryFiles(filePath);
+      const currentState = await this.readFileState(filePath);
+      if (currentState.fingerprint !== expectedFingerprint) {
+        throw new ExternalMemoryWriteConflict();
+      }
+
+      if (expectedFingerprint === "missing") {
+        try {
+          await fs.link(tmpPath, filePath);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+            throw new ExternalMemoryWriteConflict();
+          }
+          throw error;
+        }
+      } else {
+        const recoveryPath = this.recoveryPathFor(filePath);
+        const publishedIdentity = await this.fileIdentity(tmpPath);
+        try {
+          await fs.rename(filePath, recoveryPath);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            throw new ExternalMemoryWriteConflict();
+          }
+          throw error;
+        }
+        let published = false;
+        try {
+          const displacedState = await this.readFileState(recoveryPath);
+          if (displacedState.fingerprint !== expectedFingerprint) {
+            throw new ExternalMemoryWriteConflict();
+          }
+
+          await fs.link(tmpPath, filePath);
+          published = true;
+
+          const verifiedDisplacedState = await this.readFileState(recoveryPath);
+          if (verifiedDisplacedState.fingerprint !== expectedFingerprint) {
+            throw new ExternalMemoryWriteConflict();
+          }
+        } catch (error) {
+          let rollbackError: unknown;
+          if (published) {
+            try {
+              await this.preserveConflictFile(tmpPath, filePath, "local");
+            } catch {
+            }
+            try {
+              await this.rollbackPublishedFile(recoveryPath, filePath, publishedIdentity);
+            } catch (restorePublishedError) {
+              rollbackError = restorePublishedError;
+            }
+          } else {
+            try {
+              await this.restoreDisplacedFile(recoveryPath, filePath);
+            } catch (restoreError) {
+              rollbackError = restoreError;
+            }
+          }
+          if (rollbackError) throw rollbackError;
+          if ((error as NodeJS.ErrnoException).code === "EEXIST"
+            || error instanceof ExternalMemoryWriteConflict) {
+            throw new ExternalMemoryWriteConflict();
+          }
+          throw error;
+        }
+      }
+
+      try { await this.unlinkPublishedTempLink(tmpPath); } catch { /* ignore */ }
+      this.fileFingerprints[filePath] = this.fingerprint(content);
     } catch (err) {
       try { await fs.unlink(tmpPath); } catch { /* ignore */ }
       throw err;
@@ -505,4 +726,181 @@ export class MemoryStore {
       try { await fs.rm(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
     }
   }
+
+  private async restoreDisplacedFile(displacedPath: string, filePath: string): Promise<void> {
+    try {
+      await fs.link(displacedPath, filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+
+  private async fileIdentity(filePath: string): Promise<{ dev: number; ino: number }> {
+    const state = await fs.lstat(filePath);
+    return { dev: state.dev, ino: state.ino };
+  }
+
+  private sameFileIdentity(
+    left: { dev: number; ino: number },
+    right: { dev: number; ino: number },
+  ): boolean {
+    return left.dev === right.dev && left.ino === right.ino;
+  }
+
+  private async rollbackPublishedFile(
+    displacedPath: string,
+    filePath: string,
+    publishedIdentity: { dev: number; ino: number },
+  ): Promise<void> {
+    const conflictPath = path.join(
+      path.dirname(filePath),
+      `.${path.basename(filePath)}.conflict-local-${Date.now()}-${randomUUID()}`,
+    );
+    try {
+      await fs.rename(filePath, conflictPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      await this.restoreDisplacedFile(displacedPath, filePath);
+      return;
+    }
+
+    const movedIdentity = await this.fileIdentity(conflictPath);
+    if (this.sameFileIdentity(movedIdentity, publishedIdentity)) {
+      await this.restoreDisplacedFile(displacedPath, filePath);
+      return;
+    }
+
+    try {
+      await fs.link(conflictPath, filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+
+  private recoveryPathFor(filePath: string): string {
+    return path.join(
+      path.dirname(filePath),
+      `.${path.basename(filePath)}.recovery-${Date.now()}-${randomUUID()}`,
+    );
+  }
+
+  private retiredRecoveryPathFor(filePath: string): string {
+    return path.join(
+      path.dirname(filePath),
+      `.${path.basename(filePath)}.retired-${Date.now()}-${randomUUID()}`,
+    );
+  }
+
+  private async unlinkPublishedTempLink(tmpPath: string): Promise<void> {
+    await fs.unlink(tmpPath);
+  }
+
+  private async pruneRecoveryFiles(filePath: string): Promise<void> {
+    const directory = path.dirname(filePath);
+    const escapedName = path.basename(filePath).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const uuidPattern = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+    const recoveryPattern = new RegExp(`^\\.${escapedName}\\.recovery-\\d+-${uuidPattern}$`, "i");
+    const retiredPattern = new RegExp(`^\\.${escapedName}\\.retired-\\d+-${uuidPattern}$`, "i");
+    const conflictPattern = new RegExp(
+      `^\\.${escapedName}\\.conflict-local-\\d+-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`,
+      "i",
+    );
+    const activeCutoff = Date.now() - RECOVERY_ACTIVE_GRACE_MS;
+    try {
+      const names = await fs.readdir(directory);
+      await Promise.all(names.filter((name) => recoveryPattern.test(name)).map(async (name) => {
+        const recoveryPath = path.join(directory, name);
+        try {
+          const state = await fs.lstat(recoveryPath);
+          if (!state.isFile()) return;
+          if (state.mtimeMs >= activeCutoff) return;
+          await this.retireRecoveryFile(recoveryPath, filePath);
+        } catch {
+        }
+      }));
+
+      const retiredNames = (await fs.readdir(directory)).filter((name) => retiredPattern.test(name));
+      const retired = await Promise.all(retiredNames.map(async (name) => {
+        const retiredPath = path.join(directory, name);
+        try {
+          const state = await fs.lstat(retiredPath);
+          return state.isFile() ? { path: retiredPath, state } : null;
+        } catch {
+          return null;
+        }
+      }));
+      const maxAgeCutoff = Date.now() - RETIRED_RECOVERY_MAX_AGE_MS;
+      const candidates = retired
+        .filter((item): item is NonNullable<typeof item> => item !== null)
+        .sort((left, right) => right.state.mtimeMs - left.state.mtimeMs);
+      let retainedCount = 0;
+      let retainedBytes = 0;
+      for (const item of candidates) {
+        const withinAge = item.state.mtimeMs >= maxAgeCutoff;
+        const withinCount = retainedCount < RETIRED_RECOVERY_MAX_COUNT;
+        const withinBytes = retainedBytes + item.state.size <= RETIRED_RECOVERY_MAX_BYTES;
+        if (withinAge && withinCount && withinBytes) {
+          retainedCount++;
+          retainedBytes += item.state.size;
+          continue;
+        }
+        try { await fs.unlink(item.path); } catch {}
+      }
+
+      const conflictNames = (await fs.readdir(directory)).filter((name) => conflictPattern.test(name));
+      const conflicts = await Promise.all(conflictNames.map(async (name) => {
+        const conflictPath = path.join(directory, name);
+        try {
+          const state = await fs.lstat(conflictPath);
+          return state.isFile() ? { path: conflictPath, state } : null;
+        } catch {
+          return null;
+        }
+      }));
+      const graceCutoff = Date.now() - CONFLICT_ACTIVE_GRACE_MS;
+      const conflictMaxAgeCutoff = Date.now() - CONFLICT_MAX_AGE_MS;
+      const conflictCandidates = conflicts
+        .filter((item): item is NonNullable<typeof item> => item !== null)
+        .sort((left, right) => right.state.mtimeMs - left.state.mtimeMs);
+      let conflictCount = 0;
+      let conflictBytes = 0;
+      for (const item of conflictCandidates) {
+        const withinCount = conflictCount < CONFLICT_MAX_COUNT;
+        const withinBytes = conflictBytes + item.state.size <= CONFLICT_MAX_BYTES;
+        const withinGrace = item.state.mtimeMs >= graceCutoff;
+        const withinAge = item.state.mtimeMs >= conflictMaxAgeCutoff;
+        if ((withinGrace || withinAge) && withinCount && withinBytes) {
+          conflictCount++;
+          conflictBytes += item.state.size;
+          continue;
+        }
+        try { await fs.unlink(item.path); } catch {}
+      }
+    } catch {
+    }
+  }
+
+  private async retireRecoveryFile(recoveryPath: string, filePath: string): Promise<void> {
+    const retiredPath = this.retiredRecoveryPathFor(filePath);
+    const snapshotPath = `${retiredPath}.tmp`;
+    const snapshot = await fs.readFile(recoveryPath);
+    const handle = await fs.open(snapshotPath, "wx", 0o600);
+    try {
+      await handle.writeFile(snapshot);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fs.rename(snapshotPath, retiredPath);
+    await fs.unlink(recoveryPath);
+  }
+
+  private async preserveConflictFile(sourcePath: string, filePath: string, kind: string): Promise<string> {
+    const conflictPath = path.join(
+      path.dirname(filePath),
+      `.${path.basename(filePath)}.conflict-${kind}-${Date.now()}-${randomUUID()}`,
+    );
+    await fs.copyFile(sourcePath, conflictPath);
+    return conflictPath;
+  }
 }