pi-hermes-memory 0.7.23 → 0.8.0

package/src/store/atomic-lock-coordinator.ts

@@ -0,0 +1,252 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+
+type StatementLike = {
+  run: (...args: unknown[]) => unknown;
+  get: (...args: unknown[]) => unknown;
+  all: (...args: unknown[]) => unknown[];
+};
+
+type DatabaseLike = {
+  prepare: (sql: string) => StatementLike;
+  exec: (sql: string) => void;
+  close: () => void;
+};
+
+type DatabaseCtor = new (dbPath: string) => DatabaseLike;
+
+export interface AtomicLockOptions {
+  staleMs: number;
+}
+
+export interface AtomicLockLease {
+  token: string;
+  release: () => void;
+}
+
+export interface AtomicLockCoordinatorOptions {
+  pid?: number;
+  incarnation?: string;
+  probeIncarnation?: (pid: number) => string | null;
+}
+
+function loadDatabaseCtor(): DatabaseCtor {
+  const require = createRequire(import.meta.url);
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') {
+    const bunSqlite = require('bun:sqlite') as { Database: DatabaseCtor };
+    return bunSqlite.Database;
+  }
+  const mod = require('better-sqlite3') as { default?: DatabaseCtor } | DatabaseCtor;
+  return (mod as { default?: DatabaseCtor }).default ?? (mod as DatabaseCtor);
+}
+
+const Database = loadDatabaseCtor();
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== 'ESRCH';
+  }
+}
+
+function probeProcessIncarnation(pid: number): string | null {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (process.platform === 'linux') {
+    try {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+      const end = stat.lastIndexOf(')');
+      const fields = stat.slice(end + 2).split(' ');
+      return fields[19] || null;
+    } catch {
+      return null;
+    }
+  }
+
+  if (process.platform !== 'win32') {
+    const result = spawnSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+      encoding: 'utf-8',
+      timeout: 250,
+    });
+    return result.status === 0 ? result.stdout.trim() || null : null;
+  }
+
+  const result = spawnSync(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-Command', `(Get-Process -Id ${pid} -ErrorAction SilentlyContinue).StartTime.ToUniversalTime().Ticks`],
+    { encoding: 'utf-8', timeout: 500 },
+  );
+  return result.status === 0 ? result.stdout.trim() || null : null;
+}
+
+const currentProcessIncarnation = probeProcessIncarnation(process.pid);
+const RELEASE_ATTEMPTS = 3;
+const pendingReleases = new Map<string, () => void>();
+
+export class AtomicLockCoordinator {
+  private readonly pid: number;
+  private readonly incarnation: string | null;
+  private readonly probeIncarnation: (pid: number) => string | null;
+
+  constructor(private readonly dbPath: string, options: AtomicLockCoordinatorOptions = {}) {
+    this.pid = options.pid ?? process.pid;
+    this.probeIncarnation = options.probeIncarnation
+      ?? ((pid) => pid === process.pid ? currentProcessIncarnation : probeProcessIncarnation(pid));
+    this.incarnation = options.incarnation
+      ?? this.probeIncarnation(this.pid)
+      ?? null;
+  }
+
+  tryAcquire(key: string, options: AtomicLockOptions): AtomicLockLease | null {
+    this.retryPendingReleases(key);
+    const token = randomUUID();
+    const now = Date.now();
+    const db = this.open();
+    let acquired = false;
+
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      try {
+        const owner = db.prepare(`
+          SELECT token, pid, incarnation, acquired_at
+          FROM locks
+          WHERE lock_key = ?
+        `).get(key) as { token: string; pid: number; incarnation: string | null; acquired_at: number } | undefined;
+
+        if (!owner) {
+          db.prepare(`
+            INSERT INTO locks (lock_key, token, pid, incarnation, acquired_at)
+            VALUES (?, ?, ?, ?, ?)
+          `).run(key, token, this.pid, this.incarnation, now);
+          acquired = true;
+        } else {
+          const observedIncarnation = this.probeIncarnation(owner.pid);
+          const alive = observedIncarnation !== null || processIsAlive(owner.pid);
+          const sameIncarnation = alive
+            && owner.incarnation !== null
+            && observedIncarnation !== null
+            && owner.incarnation === observedIncarnation;
+          const unknownIncarnation = alive && (owner.incarnation === null || observedIncarnation === null);
+          // A lease is reclaimable once it has been held for longer than staleMs,
+          // regardless of whether the owning process is still alive — it may be
+          // making no progress (blocked I/O, wedged, suspended) rather than dead.
+          // This is the sole backstop for that case: liveness/incarnation checks
+          // alone cannot distinguish "alive and working" from "alive and stuck".
+          // staleMs <= 0 disables time-based takeover (liveness checks only).
+          const stale = options.staleMs > 0 && now - owner.acquired_at >= options.staleMs;
+          if (stale || (!sameIncarnation && !unknownIncarnation)) {
+            db.prepare(`
+              UPDATE locks
+              SET token = ?, pid = ?, incarnation = ?, acquired_at = ?
+              WHERE lock_key = ? AND token = ?
+            `).run(token, this.pid, this.incarnation, now, key, owner.token);
+            acquired = true;
+          }
+        }
+
+        db.exec('COMMIT');
+      } catch (error) {
+        try { db.exec('ROLLBACK'); } catch {}
+        throw error;
+      }
+    } finally {
+      db.close();
+    }
+
+    if (!acquired) return null;
+    return {
+      token,
+      release: () => this.release(key, token),
+    };
+  }
+
+  /**
+   * Fencing check for destructive operations that lack their own independent
+   * compare-and-swap (e.g. a plain fs.renameSync with no content/inode
+   * verification). A lease can be legitimately stolen from a stale-but-alive
+   * holder (see tryAcquire); a holder resuming after being stuck must verify
+   * it is still the current owner immediately before publishing, or abort.
+   * This narrows — it cannot fully close — the check-then-act race, since
+   * synchronous work between this call and the actual write is not atomic
+   * with it.
+   */
+  isCurrentOwner(key: string, token: string): boolean {
+    const db = this.open();
+    try {
+      const row = db.prepare('SELECT token FROM locks WHERE lock_key = ?').get(key) as { token: string } | undefined;
+      return row?.token === token;
+    } finally {
+      db.close();
+    }
+  }
+
+  release(key: string, token: string): void {
+    const pendingKey = this.pendingReleaseKey(key, token);
+    for (let attempt = 0; attempt < RELEASE_ATTEMPTS; attempt++) {
+      try {
+        this.deleteOwnedLock(key, token);
+        pendingReleases.delete(pendingKey);
+        return;
+      } catch {
+      }
+    }
+    pendingReleases.set(pendingKey, () => this.release(key, token));
+  }
+
+  private deleteOwnedLock(key: string, token: string): void {
+    const db = this.open();
+    try {
+      db.prepare('DELETE FROM locks WHERE lock_key = ? AND token = ?').run(key, token);
+    } finally {
+      db.close();
+    }
+  }
+
+  private retryPendingReleases(key: string): void {
+    const prefix = `${path.resolve(this.dbPath)}\0${key}\0`;
+    for (const [pendingKey, release] of [...pendingReleases.entries()]) {
+      if (pendingKey.startsWith(prefix)) release();
+    }
+  }
+
+  private pendingReleaseKey(key: string, token: string): string {
+    return `${path.resolve(this.dbPath)}\0${key}\0${token}`;
+  }
+
+  private open(): DatabaseLike {
+    fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+    const existed = fs.existsSync(this.dbPath);
+    const db = new Database(this.dbPath);
+    try {
+      db.exec(`
+        PRAGMA busy_timeout = 5000;
+        PRAGMA journal_mode = WAL;
+        CREATE TABLE IF NOT EXISTS locks (
+          lock_key TEXT PRIMARY KEY,
+          token TEXT NOT NULL,
+          pid INTEGER NOT NULL,
+          incarnation TEXT,
+          acquired_at INTEGER NOT NULL
+        );
+      `);
+      const columns = db.prepare('PRAGMA table_info(locks)').all() as Array<{ name: string }>;
+      if (!columns.some(({ name }) => name === 'incarnation')) {
+        try {
+          db.exec('ALTER TABLE locks ADD COLUMN incarnation TEXT');
+        } catch (error) {
+          const refreshed = db.prepare('PRAGMA table_info(locks)').all() as Array<{ name: string }>;
+          if (!refreshed.some(({ name }) => name === 'incarnation')) throw error;
+        }
+      }
+      if (!existed) fs.chmodSync(this.dbPath, 0o600);
+      return db;
+    } catch (error) {
+      db.close();
+      throw error;
+    }
+  }
+}

package/src/store/canonical-storage-path.ts

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const MAX_SYMLINK_DEPTH = 40;
+
+function pathParts(absolutePath: string): { root: string; parts: string[] } {
+  const root = path.parse(absolutePath).root;
+  return {
+    root,
+    parts: absolutePath.slice(root.length).split(path.sep).filter(Boolean),
+  };
+}
+
+export function canonicalStoragePathSync(filePath: string): string {
+  const input = path.resolve(filePath);
+  let { root, parts } = pathParts(input);
+  let current = root;
+  let depth = 0;
+
+  while (parts.length > 0) {
+    const part = parts.shift()!;
+    const candidate = path.join(current, part);
+    let state: fs.Stats;
+    try {
+      state = fs.lstatSync(candidate);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      return path.join(fs.realpathSync.native(current), part, ...parts);
+    }
+
+    if (!state.isSymbolicLink()) {
+      current = candidate;
+      continue;
+    }
+
+    if (depth++ >= MAX_SYMLINK_DEPTH) {
+      const error = new Error(`Symbolic link loop detected while resolving ${input}`) as NodeJS.ErrnoException;
+      error.code = "ELOOP";
+      throw error;
+    }
+    const target = fs.readlinkSync(candidate);
+    const targetPath = path.resolve(path.dirname(candidate), target);
+    const targetParts = pathParts(targetPath);
+    root = targetParts.root;
+    current = root;
+    parts = [...targetParts.parts, ...parts];
+  }
+
+  return fs.realpathSync.native(current);
+}
+
+export async function canonicalStoragePath(filePath: string): Promise<string> {
+  return canonicalStoragePathSync(filePath);
+}

package/src/store/db.ts

@@ -2,6 +2,8 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import { SCHEMA_SQL } from './schema.js';
+import { AtomicLockCoordinator } from './atomic-lock-coordinator.js';
+import { canonicalStoragePathSync } from './canonical-storage-path.js';
 
 type StatementLike = {
   run: (...args: any[]) => any;
@@ -34,12 +36,30 @@ type MovedDatabaseFile = {
 };
 
 export interface DatabaseRecoveryResult {
-  strategy: 'rebuilt' | 'recreated-empty';
+  strategy: 'rebuilt' | 'recreated-empty' | 'reused';
   backupPaths: string[];
   recoveredRows?: Record<string, number>;
   error?: string;
 }
 
+export interface DatabaseRecoveryOptions {
+  recoveryLockWaitMs?: number;
+  recoveryLockPollMs?: number;
+  recoveryLockStaleMs?: number;
+  recoveryCircuitLimit?: number;
+  recoveryCircuitWindowMs?: number;
+  recoveryBackupRetention?: number;
+}
+
+interface ResolvedDatabaseRecoveryOptions {
+  recoveryLockWaitMs: number;
+  recoveryLockPollMs: number;
+  recoveryLockStaleMs: number;
+  recoveryCircuitLimit: number;
+  recoveryCircuitWindowMs: number;
+  recoveryBackupRetention: number;
+}
+
 class DatabaseCorruptionError extends Error {
   code = 'SQLITE_CORRUPT';
 
@@ -54,6 +74,14 @@ export const SQLITE_WAL_AUTOCHECKPOINT_PAGES = 1000;
 const DATABASE_FILE_SUFFIXES: readonly DatabaseFileSuffix[] = ['', '-wal', '-shm'];
 const MEMORY_TARGETS = new Set(['memory', 'user', 'failure']);
 const MEMORY_CATEGORIES = new Set(['failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk']);
+const DEFAULT_RECOVERY_OPTIONS: ResolvedDatabaseRecoveryOptions = {
+  recoveryLockWaitMs: 5000,
+  recoveryLockPollMs: 50,
+  recoveryLockStaleMs: 300000,
+  recoveryCircuitLimit: 3,
+  recoveryCircuitWindowMs: 300000,
+  recoveryBackupRetention: 3,
+};
 
 function quoteIdentifier(identifier: string): string {
   return `"${identifier.replace(/"/g, '""')}"`;
@@ -110,11 +138,27 @@ const Database = loadDatabaseCtor();
 
 export class DatabaseManager {
   private db: DatabaseLike | null = null;
-  private readonly dbPath: string;
+  private readonly displayDbPath: string;
+  private canonicalDbPath: string | null = null;
+  private readonly recoveryOptions: ResolvedDatabaseRecoveryOptions;
   private lastRecovery: DatabaseRecoveryResult | null = null;
+  private openGuard: (() => void) | null = null;
+  private activeRecoveryLease: { coordinator: AtomicLockCoordinator; key: string; token: string } | null = null;
+
+  constructor(memoryDir: string, recoveryOptions: DatabaseRecoveryOptions = {}) {
+    this.displayDbPath = path.join(memoryDir, 'sessions.db');
+    this.recoveryOptions = { ...DEFAULT_RECOVERY_OPTIONS, ...recoveryOptions };
+  }
+
+  private get dbPath(): string {
+    if (!this.canonicalDbPath) {
+      this.canonicalDbPath = canonicalStoragePathSync(this.displayDbPath);
+    }
+    return this.canonicalDbPath;
+  }
 
-  constructor(memoryDir: string) {
-    this.dbPath = path.join(memoryDir, 'sessions.db');
+  setOpenGuard(guard: (() => void) | null): void {
+    this.openGuard = guard;
   }
 
   /**
@@ -147,6 +191,7 @@ export class DatabaseManager {
    */
   getDb(): DatabaseLike {
     if (!this.db) {
+      this.openGuard?.();
       this.db = this.open();
     }
     return this.db;
@@ -181,7 +226,15 @@ export class DatabaseManager {
    */
   recoverFromCorruption(cause?: unknown): DatabaseRecoveryResult {
     this.close();
-    const recovery = this.recoverDatabaseFile(cause);
+    let verifiedDb: DatabaseLike | null = null;
+    let recovery: DatabaseRecoveryResult;
+    try {
+      recovery = this.recoverDatabaseFile(cause, () => {
+        verifiedDb = this.openUnchecked();
+      });
+    } finally {
+      if (verifiedDb) this.safeClose(verifiedDb);
+    }
     this.lastRecovery = recovery;
     return recovery;
   }
@@ -202,9 +255,19 @@ export class DatabaseManager {
         throw err;
       }
 
-      const recovery = this.recoverDatabaseFile(err);
+      let recoveredDb: DatabaseLike | null = null;
+      let recovery: DatabaseRecoveryResult;
+      try {
+        recovery = this.recoverDatabaseFile(err, () => {
+          recoveredDb = this.openUnchecked();
+        });
+      } catch (error) {
+        if (recoveredDb) this.safeClose(recoveredDb);
+        throw error;
+      }
       this.lastRecovery = recovery;
-      return this.openUnchecked();
+      if (!recoveredDb) throw new Error(`SQLite recovery verification did not open ${this.displayDbPath}`);
+      return recoveredDb;
     }
   }
 
@@ -297,7 +360,57 @@ export class DatabaseManager {
     }
   }
 
-  private recoverDatabaseFile(cause?: unknown): DatabaseRecoveryResult {
+  private recoverDatabaseFile(cause: unknown, verify: () => void): DatabaseRecoveryResult {
+    const coordinator = new AtomicLockCoordinator(path.join(path.dirname(this.dbPath), '.pi-hermes-locks.sqlite'));
+    const lockKey = `recovery:${this.dbPath}`;
+    const deadline = Date.now() + Math.max(0, this.recoveryOptions.recoveryLockWaitMs);
+
+    while (true) {
+      const lease = coordinator.tryAcquire(lockKey, { staleMs: this.recoveryOptions.recoveryLockStaleMs });
+      if (!lease) {
+        if (Date.now() >= deadline) {
+          throw new Error(`SQLite recovery already in progress for ${this.displayDbPath}; timed out after ${this.recoveryOptions.recoveryLockWaitMs}ms`);
+        }
+        DatabaseManager.sleepSync(Math.min(
+          this.recoveryOptions.recoveryLockPollMs,
+          Math.max(1, deadline - Date.now()),
+        ));
+        continue;
+      }
+
+      this.activeRecoveryLease = { coordinator, key: lockKey, token: lease.token };
+      try {
+        if (this.currentDatabaseIsHealthy()) {
+          try {
+            verify();
+            this.clearRecoveryFailuresBestEffort();
+            return { strategy: 'reused', backupPaths: [] };
+          } catch (error) {
+            this.recordRecoveryFailure();
+            throw error;
+          }
+        }
+
+        this.assertRecoveryCircuitClosed();
+        try {
+          this.cleanupRecoveryArtifactsBestEffort();
+          const result = this.recoverDatabaseFileUnlocked(cause);
+          verify();
+          this.cleanupRecoveryArtifactsBestEffort();
+          this.clearRecoveryFailuresBestEffort();
+          return result;
+        } catch (error) {
+          this.recordRecoveryFailure();
+          throw error;
+        }
+      } finally {
+        this.activeRecoveryLease = null;
+        lease.release();
+      }
+    }
+  }
+
+  private recoverDatabaseFileUnlocked(cause?: unknown): DatabaseRecoveryResult {
     const backupBase = this.corruptBackupBase();
     let rebuildError: unknown;
 
@@ -317,6 +430,112 @@ export class DatabaseManager {
     };
   }
 
+  private currentDatabaseIsHealthy(): boolean {
+    if (!this.hasExistingMainDatabaseFile()) return false;
+    let db: DatabaseLike | null = null;
+    try {
+      db = new Database(this.dbPath);
+      this.assertIntegrityOk(db, 'quick_check', 'while joining corruption recovery');
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (db) this.safeClose(db);
+    }
+  }
+
+  private recoveryCircuitPath(): string {
+    return `${this.dbPath}.recovery-state.json`;
+  }
+
+  private recentRecoveryFailures(): number[] {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.recoveryCircuitPath(), 'utf-8')) as { failures?: unknown };
+      if (!Array.isArray(parsed.failures)) return [];
+      const cutoff = Date.now() - Math.max(0, this.recoveryOptions.recoveryCircuitWindowMs);
+      return parsed.failures.filter((value): value is number => typeof value === 'number' && value >= cutoff);
+    } catch {
+      return [];
+    }
+  }
+
+  private assertRecoveryCircuitClosed(): void {
+    if (this.recentRecoveryFailures().length >= Math.max(1, this.recoveryOptions.recoveryCircuitLimit)) {
+      throw new Error(
+        `SQLite recovery circuit is open for ${this.displayDbPath}: too many failed recovery attempts within ${this.recoveryOptions.recoveryCircuitWindowMs}ms`,
+      );
+    }
+  }
+
+  private recordRecoveryFailure(): void {
+    const statePath = this.recoveryCircuitPath();
+    const tempPath = `${statePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2, 8)}`;
+    const failures = [...this.recentRecoveryFailures(), Date.now()];
+    try {
+      fs.writeFileSync(tempPath, JSON.stringify({ failures }), { encoding: 'utf-8', mode: 0o600 });
+      fs.renameSync(tempPath, statePath);
+    } finally {
+      fs.rmSync(tempPath, { force: true });
+    }
+  }
+
+  private clearRecoveryFailures(): void {
+    fs.rmSync(this.recoveryCircuitPath(), { force: true });
+  }
+
+  private clearRecoveryFailuresBestEffort(): void {
+    try { this.clearRecoveryFailures(); } catch {}
+  }
+
+  private cleanupRecoveryArtifactsBestEffort(): void {
+    try { this.cleanupRecoveryArtifacts(); } catch {}
+  }
+
+  private cleanupRecoveryArtifacts(): void {
+    const dir = path.dirname(this.dbPath);
+    const databaseName = path.basename(this.dbPath);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const name of names) {
+      if (name.startsWith(`${databaseName}.rebuild-`)) {
+        fs.rmSync(path.join(dir, name), { recursive: true, force: true });
+      }
+    }
+
+    const backupGroups = new Map<string, number>();
+    for (const name of names) {
+      if (!name.startsWith(`${databaseName}.corrupt-`)) continue;
+      const group = name.replace(/-(?:wal|shm)$/, '');
+      try {
+        const mtimeMs = fs.statSync(path.join(dir, name)).mtimeMs;
+        backupGroups.set(group, Math.max(backupGroups.get(group) ?? 0, mtimeMs));
+      } catch {
+        // Artifact disappeared while scanning.
+      }
+    }
+
+    const retained = Math.max(0, this.recoveryOptions.recoveryBackupRetention);
+    const expired = [...backupGroups.entries()]
+      .sort((left, right) => right[1] - left[1])
+      .slice(retained);
+    for (const [group] of expired) {
+      for (const suffix of DATABASE_FILE_SUFFIXES) {
+        fs.rmSync(path.join(dir, `${group}${suffix}`), { force: true });
+      }
+    }
+  }
+
+  private static sleepSync(milliseconds: number): void {
+    if (milliseconds <= 0) return;
+    const signal = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(signal, 0, 0, milliseconds);
+  }
+
   private rebuildDatabaseFromReadableRows(backupBase: string): DatabaseRecoveryResult {
     const tempPath = this.rebuildTempPath();
     this.removeDatabaseFileSet(tempPath);
@@ -555,6 +774,7 @@ export class DatabaseManager {
   }
 
   private moveDatabaseFilesToBackup(backupBase: string): MovedDatabaseFile[] {
+    this.assertStillRecoveryOwner();
     const moved: MovedDatabaseFile[] = [];
     for (const suffix of DATABASE_FILE_SUFFIXES) {
       const original = `${this.dbPath}${suffix}`;
@@ -568,6 +788,21 @@ export class DatabaseManager {
     return moved;
   }
 
+  /**
+   * Verifies this instance still holds the recovery lease immediately before
+   * a destructive rename that has no independent compare-and-swap of its
+   * own (unlike the Markdown mutation path, which re-checks a content
+   * fingerprint at publish time). If the lease was reclaimed as stale while
+   * this call was in flight, abort rather than race the new owner.
+   */
+  private assertStillRecoveryOwner(): void {
+    const active = this.activeRecoveryLease;
+    if (!active) return;
+    if (!active.coordinator.isCurrentOwner(active.key, active.token)) {
+      throw new Error(`SQLite recovery lease lost for ${this.displayDbPath}; another process took over`);
+    }
+  }
+
   private restoreMovedDatabaseFiles(moved: MovedDatabaseFile[]): void {
     for (const file of [...moved].reverse()) {
       try {
@@ -765,7 +1000,7 @@ export class DatabaseManager {
    * Get the database file path.
    */
   getPath(): string {
-    return this.dbPath;
+    return this.displayDbPath;
   }
 
   /**

package/src/store/markdown-mutation-lock.ts

@@ -0,0 +1,38 @@
+import * as path from "node:path";
+import { AtomicLockCoordinator, type AtomicLockLease } from "./atomic-lock-coordinator.js";
+import { canonicalStoragePath } from "./canonical-storage-path.js";
+
+const MUTATION_WAIT_MS = 5_000;
+const MUTATION_STALE_MS = 300_000;
+
+export async function canonicalMarkdownIdentity(filePath: string): Promise<string> {
+  return canonicalStoragePath(filePath);
+}
+
+export async function acquireMarkdownMutationLock(filePath: string): Promise<AtomicLockLease> {
+  const identity = await canonicalMarkdownIdentity(filePath);
+  const coordinatorDir = path.dirname(path.dirname(identity));
+  const coordinator = new AtomicLockCoordinator(path.join(coordinatorDir, ".pi-hermes-locks.sqlite"));
+  const lockKey = `mutation:${identity}`;
+  const deadline = Date.now() + MUTATION_WAIT_MS;
+  let lease = coordinator.tryAcquire(lockKey, { staleMs: MUTATION_STALE_MS });
+
+  while (!lease) {
+    if (Date.now() >= deadline) {
+      throw new Error(`Memory mutation already in progress for ${identity}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    lease = coordinator.tryAcquire(lockKey, { staleMs: MUTATION_STALE_MS });
+  }
+
+  return lease;
+}
+
+export async function withMarkdownMutationLock<T>(filePath: string, operation: () => Promise<T> | T): Promise<T> {
+  const lease = await acquireMarkdownMutationLock(filePath);
+  try {
+    return await operation();
+  } finally {
+    lease.release();
+  }
+}