@gregiteen/ssss-cli 0.9.0 → 0.9.2

package/src/events.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { withFileLock } from './file-lock.mjs';
 
 export function createCanonicalEvent(input, options = {}) {
   const required = ['workspace_id', 'action', 'subject', 'operation_id', 'idempotency_key'];
@@ -33,12 +34,12 @@ export function createCanonicalEvent(input, options = {}) {
 
 export class MemoryEventStore {
   #events = [];
+  #ids = new Set();
   async append(event) {
-    if (this.#events.some((existing) => existing.event_id === event.event_id)) {
-      throw new Error(`Duplicate event_id '${event.event_id}'.`);
-    }
+    if (this.#ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
     const frozen = structuredClone(event);
     this.#events.push(frozen);
+    this.#ids.add(frozen.event_id);
     return structuredClone(frozen);
   }
   async *replay(options = {}) {
@@ -51,24 +52,96 @@ export class MemoryEventStore {
   async size() { return this.#events.length; }
 }
 
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const APPEND_FLAGS = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | NOFOLLOW;
+
+function openLog(file, flags, mode) {
+  try { return fs.openSync(file, flags, mode); }
+  catch (error) {
+    if (error.code === 'ELOOP') throw new Error('Symlinked event logs are forbidden.');
+    throw error;
+  }
+}
+
+function sameStat(a, b) {
+  return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+
+/** Read every event_id in a log, bounded to the bytes covered by the returned stat. */
+function loadIndex(file) {
+  const fd = openLog(file, fs.constants.O_RDONLY | NOFOLLOW);
+  try {
+    const stat = fs.fstatSync(fd);
+    const bytes = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (read === 0) break;
+      offset += read;
+    }
+    const ids = new Set();
+    for (const line of bytes.subarray(0, offset).toString('utf8').split('\n')) {
+      if (line.trim()) ids.add(JSON.parse(line).event_id);
+    }
+    return { ids, stat };
+  } finally { fs.closeSync(fd); }
+}
+
 export class JsonlEventStore {
-  constructor(root) {
+  // Per-log index of event_ids, built on the first append to that log. Each
+  // index records the stat of the bytes it covers; any change (another store
+  // instance or process appended, or the file was replaced) rebuilds it.
+  // Appenders serialize on `<log>.lock` so the duplicate check and the append
+  // are atomic across processes.
+  #indexes = new Map();
+  constructor(root, options = {}) {
     fs.mkdirSync(root, { recursive: true });
     this.root = fs.realpathSync(root);
+    this.lockOptions = options.lock || {};
   }
   #file(workspaceId) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(workspaceId || '')) throw new Error('Unsafe event workspace_id.');
     return path.join(this.root, `${workspaceId}.jsonl`);
   }
+  #index(file) {
+    let stat;
+    try { stat = fs.lstatSync(file); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      this.#indexes.delete(file);
+      return { ids: new Set(), stat: null };
+    }
+    if (stat.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
+    const cached = this.#indexes.get(file);
+    if (cached && sameStat(cached.stat, stat)) return cached;
+    const index = loadIndex(file);
+    this.#indexes.set(file, index);
+    return index;
+  }
   async append(event) {
     const file = this.#file(event.workspace_id);
-    if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
-    if (fs.existsSync(file)) {
-      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
-        if (line.trim() && JSON.parse(line).event_id === event.event_id) throw new Error(`Duplicate event_id '${event.event_id}'.`);
-      }
+    return withFileLock(`${file}.lock`, () => this.#appendLocked(file, event), this.lockOptions);
+  }
+  #appendLocked(file, event) {
+    const index = this.#index(file);
+    if (index.ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
+    const line = `${JSON.stringify(event)}\n`;
+    this.#indexes.delete(file);
+    const fd = openLog(file, APPEND_FLAGS, 0o600);
+    let after;
+    try {
+      fs.writeFileSync(fd, line);
+      after = fs.fstatSync(fd);
+    } finally { fs.closeSync(fd); }
+    // Keep the index only when the log grew by exactly this line on the same
+    // file; otherwise a writer that skips the lock interleaved, and the next
+    // append rebuilds.
+    const before = index.stat;
+    const expectedSize = (before?.size || 0) + Buffer.byteLength(line);
+    if (after.size === expectedSize && (!before || (before.dev === after.dev && before.ino === after.ino))) {
+      index.ids.add(event.event_id);
+      this.#indexes.set(file, { ids: index.ids, stat: after });
     }
-    fs.appendFileSync(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
     return structuredClone(event);
   }
   async *replay(options = {}) {

package/src/file-lock.mjs

@@ -0,0 +1,112 @@
+/**
+ * Cross-process exclusive lock files for the reference file adapters.
+ *
+ * A lock is a file created with O_EXCL and removed by its holder. A lock left
+ * behind by a crashed holder is broken once the holder is known to be dead
+ * (same host, process gone) or the lock is older than `staleMs`.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const CREATE_EXCLUSIVE = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW;
+const HOST = os.hostname();
+
+export const FILE_LOCK_DEFAULTS = Object.freeze({ timeoutMs: 40_000, staleMs: 30_000 });
+
+export class FileLockTimeoutError extends Error {
+  constructor(lockPath) {
+    super(`Timed out waiting for lock '${path.basename(lockPath)}'.`);
+    this.name = 'FileLockTimeoutError';
+    this.code = 'SSSS_LOCK_TIMEOUT';
+  }
+}
+
+function notRegular(lockPath) {
+  return new Error(`Lock '${path.basename(lockPath)}' is not a regular file.`);
+}
+
+function readHolder(lockPath) {
+  try {
+    const fd = fs.openSync(lockPath, fs.constants.O_RDONLY | NOFOLLOW);
+    try { return JSON.parse(fs.readFileSync(fd, 'utf8')); } finally { fs.closeSync(fd); }
+  } catch { return null; }
+}
+
+function holderIsDead(holder) {
+  if (holder?.host !== HOST || !Number.isInteger(holder.pid) || holder.pid === process.pid) return false;
+  try { process.kill(holder.pid, 0); return false; }
+  catch (error) { return error.code === 'ESRCH'; }
+}
+
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mtimeMs === b.mtimeMs;
+
+/** Create the lock and return its stat (proof of ownership), or null when it is held. */
+function tryAcquire(lockPath, createDir) {
+  let fd;
+  try { fd = fs.openSync(lockPath, CREATE_EXCLUSIVE, 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') return null;
+    if (error.code === 'ELOOP') throw notRegular(lockPath);
+    if (error.code === 'ENOENT' && createDir) {
+      fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+      return tryAcquire(lockPath, false);
+    }
+    throw error;
+  }
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, host: HOST, acquired_at: new Date().toISOString() }));
+    return fs.fstatSync(fd);
+  } catch (error) {
+    fs.rmSync(lockPath, { force: true });
+    throw error;
+  } finally { fs.closeSync(fd); }
+}
+
+function breakIfStale(lockPath, staleMs) {
+  let stat;
+  try { stat = fs.lstatSync(lockPath); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  if (!stat.isFile()) throw notRegular(lockPath);
+  if (Date.now() - stat.mtimeMs < staleMs && !holderIsDead(readHolder(lockPath))) return;
+  // Move the lock aside so only one breaker wins. If a live holder replaced it
+  // after the stat above, the moved file is a different inode: put it back.
+  const aside = `${lockPath}.${crypto.randomUUID()}.stale`;
+  try { fs.renameSync(lockPath, aside); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  const moved = fs.lstatSync(aside);
+  if (moved.ino !== stat.ino || moved.dev !== stat.dev) {
+    try { fs.linkSync(aside, lockPath); } catch {}
+  }
+  fs.rmSync(aside, { force: true });
+}
+
+// Remove the lock only if it is still the file we created; a lock broken as
+// stale and re-taken by another holder is a different file.
+function release(lockPath, owned) {
+  try {
+    if (sameFile(fs.lstatSync(lockPath), owned)) fs.unlinkSync(lockPath);
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+/**
+ * Run `fn` while holding the lock file at `lockPath`. With `createDir`, the
+ * lock's directory is created (mode 0700) when it is missing.
+ */
+export async function withFileLock(lockPath, fn, options = {}) {
+  const timeoutMs = options.timeoutMs ?? FILE_LOCK_DEFAULTS.timeoutMs;
+  const staleMs = options.staleMs ?? FILE_LOCK_DEFAULTS.staleMs;
+  const deadline = Date.now() + timeoutMs;
+  let owned = tryAcquire(lockPath, options.createDir);
+  for (let delay = 1; !owned; delay = Math.min(delay * 2, 50)) {
+    breakIfStale(lockPath, staleMs);
+    owned = tryAcquire(lockPath, options.createDir);
+    if (owned) break;
+    if (Date.now() >= deadline) throw new FileLockTimeoutError(lockPath);
+    await new Promise((resolve) => setTimeout(resolve, delay * (1 + Math.random())));
+  }
+  try { return await fn(); }
+  finally { release(lockPath, owned); }
+}

package/src/idempotency.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { withFileLock } from './file-lock.mjs';
 
 function key(workspaceId, idempotencyKey) { return JSON.stringify([workspaceId, idempotencyKey]); }
 
@@ -16,7 +17,11 @@ export class MemoryIdempotencyStore {
 }
 
 export class FileIdempotencyStore {
-  constructor(root) { fs.mkdirSync(root, { recursive: true }); this.root = fs.realpathSync(root); }
+  constructor(root, options = {}) {
+    fs.mkdirSync(root, { recursive: true });
+    this.root = fs.realpathSync(root);
+    this.lockOptions = options.lock || {};
+  }
   #file(workspaceId, idempotencyKey) {
     const digest = crypto.createHash('sha256').update(key(workspaceId, idempotencyKey)).digest('hex');
     return path.join(this.root, `${digest}.json`);
@@ -31,12 +36,15 @@ export class FileIdempotencyStore {
   }
   async put(workspaceId, idempotencyKey, value) {
     const file = this.#file(workspaceId, idempotencyKey);
-    if (fs.existsSync(file)) throw new Error('Idempotency entry already exists.');
-    const temp = `${file}.${crypto.randomUUID()}.tmp`;
-    try {
-      fs.writeFileSync(temp, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 });
-      fs.renameSync(temp, file);
-    } finally { fs.rmSync(temp, { force: true }); }
+    // Serialize writers of one key so a second put fails instead of replacing the first.
+    return withFileLock(`${file}.lock`, () => {
+      if (fs.existsSync(file)) throw new Error('Idempotency entry already exists.');
+      const temp = `${file}.${crypto.randomUUID()}.tmp`;
+      try {
+        fs.writeFileSync(temp, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 });
+        fs.renameSync(temp, file);
+      } finally { fs.rmSync(temp, { force: true }); }
+    }, this.lockOptions);
   }
 }
 

package/src/leases.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { withFileLock } from './file-lock.mjs';
 
 function validateLeaseInput(value) {
   for (const field of ['workspace_id', 'target', 'principal_id', 'operation_id']) {
@@ -46,15 +47,25 @@ export class MemoryLeaseStore {
   }
 }
 
+export function leaseStatePath(root, workspaceId, target) {
+  const hash = crypto.createHash('sha256').update(`${workspaceId}\0${target}`).digest('hex');
+  return path.join(root, `${hash}.lease.json`);
+}
+
 export class FileLeaseStore {
   constructor(root, options = {}) {
     fs.mkdirSync(root, { recursive: true });
     this.root = fs.realpathSync(root);
     this.clock = options.clock || (() => Date.now());
+    this.lockOptions = options.lock || {};
   }
   #file(workspaceId, target) {
-    const hash = crypto.createHash('sha256').update(`${workspaceId}\0${target}`).digest('hex');
-    return path.join(this.root, `${hash}.lease.json`);
+    return leaseStatePath(this.root, workspaceId, target);
+  }
+  // Mutations of one lease serialize on a lock so "at most one active lease"
+  // holds across processes.
+  #locked(input, fn) {
+    return withFileLock(`${this.#file(input.workspace_id, input.target)}.lock`, fn, this.lockOptions);
   }
   #load(workspaceId, target) {
     const file = this.#file(workspaceId, target);
@@ -74,11 +85,13 @@ export class FileLeaseStore {
   }
   async acquire(input, ttlMs = 30_000) {
     validateLeaseInput(input);
-    const existing = this.#load(input.workspace_id, input.target);
-    if (existing && existing.expires_at > this.clock()) throw new Error('Lease conflict.');
-    const lease = { ...input, lease_id: input.lease_id || crypto.randomUUID(), issued_at: this.clock(), expires_at: this.clock() + ttlMs };
-    this.#write(lease);
-    return { ...lease };
+    return this.#locked(input, () => {
+      const existing = this.#load(input.workspace_id, input.target);
+      if (existing && existing.expires_at > this.clock()) throw new Error('Lease conflict.');
+      const lease = { ...input, lease_id: input.lease_id || crypto.randomUUID(), issued_at: this.clock(), expires_at: this.clock() + ttlMs };
+      this.#write(lease);
+      return { ...lease };
+    });
   }
   async verify(input) {
     const lease = this.#load(input.workspace_id, input.target);
@@ -90,17 +103,21 @@ export class FileLeaseStore {
     return { valid: true, lease };
   }
   async renew(input, ttlMs = 30_000) {
-    const verified = await this.verify(input);
-    if (!verified.valid) throw new Error(verified.reason);
-    verified.lease.expires_at = this.clock() + ttlMs;
-    this.#write(verified.lease);
-    return verified.lease;
+    return this.#locked(input, async () => {
+      const verified = await this.verify(input);
+      if (!verified.valid) throw new Error(verified.reason);
+      verified.lease.expires_at = this.clock() + ttlMs;
+      this.#write(verified.lease);
+      return verified.lease;
+    });
   }
   async release(input) {
-    const verified = await this.verify(input);
-    if (!verified.valid) throw new Error(verified.reason);
-    fs.rmSync(this.#file(input.workspace_id, input.target), { force: true });
-    return { released: true, lease_id: input.lease_id };
+    return this.#locked(input, async () => {
+      const verified = await this.verify(input);
+      if (!verified.valid) throw new Error(verified.reason);
+      fs.rmSync(this.#file(input.workspace_id, input.target), { force: true });
+      return { released: true, lease_id: input.lease_id };
+    });
   }
 }
 
@@ -117,9 +134,53 @@ export async function runLeaseContract(store, { clock } = {}) {
   record('acquire returns bound lease', acquired.lease_id && acquired.principal_id === input.principal_id);
   record('matching lease verifies', (await store.verify({ ...input, lease_id: acquired.lease_id })).valid);
   record('mismatched owner fails closed', !(await store.verify({ ...input, principal_id: 'other', lease_id: acquired.lease_id })).valid);
+  record('mismatched lease_id fails closed', !(await store.verify({ ...input, lease_id: crypto.randomUUID() })).valid);
+  record('missing lease fails closed', !(await store.verify({
+    workspace_id: input.workspace_id,
+    target: `missing/${crypto.randomUUID()}.md`,
+    principal_id: input.principal_id,
+    operation_id: input.operation_id,
+    lease_id: acquired.lease_id,
+  })).valid);
   const renewed = await store.renew({ ...input, lease_id: acquired.lease_id }, 20_000);
   record('renew extends expiry', renewed.expires_at >= acquired.expires_at);
   await store.release({ ...input, lease_id: acquired.lease_id });
   record('released lease is missing', !(await store.verify({ ...input, lease_id: acquired.lease_id })).valid);
+
+  // Controllable clock proves expiry fail-closed for any store that accepts injection.
+  if (typeof store.clock === 'function' || clock) {
+    let now = 1_000_000;
+    const timed = store.constructor === MemoryLeaseStore
+      ? new MemoryLeaseStore({ clock: () => now })
+      : store.constructor === FileLeaseStore
+        ? new FileLeaseStore(path.join(store.root, `expiry-${crypto.randomUUID()}`), { clock: () => now })
+        : null;
+    if (timed) {
+      const timedInput = { ...input, target: `rules/expiry-${crypto.randomUUID()}.md` };
+      const short = await timed.acquire(timedInput, 50);
+      now = short.expires_at + 1;
+      record('expired lease fails closed', !(await timed.verify({ ...timedInput, lease_id: short.lease_id })).valid);
+    }
+  }
+
+  // Filesystem stores must fail closed on corrupt/unreadable state.
+  if (store instanceof FileLeaseStore) {
+    const corruptInput = {
+      workspace_id: `ws-${crypto.randomUUID()}`,
+      target: `rules/corrupt-${crypto.randomUUID()}.md`,
+      principal_id: 'principal',
+      operation_id: 'operation',
+    };
+    const good = await store.acquire(corruptInput, 30_000);
+    fs.writeFileSync(leaseStatePath(store.root, corruptInput.workspace_id, corruptInput.target), '{not-json', { mode: 0o600 });
+    let unreadable = false;
+    try {
+      await store.verify({ ...corruptInput, lease_id: good.lease_id });
+    } catch (error) {
+      unreadable = /unreadable/i.test(error.message);
+    }
+    record('unreadable lease state fails closed', unreadable);
+  }
+
   return { passed: checks.every((check) => check.passed), checks };
 }

package/src/projections.mjs

@@ -1,4 +1,4 @@
-/** Replayable, cursor-aware SSSS projection coordinator. */
+/** Replayable, cursor-aware SSSS projection coordinator and host adapter examples. */
 import crypto from 'node:crypto';
 
 function stable(value) {
@@ -11,6 +11,77 @@ export function projectionHash(value) {
   return `sha256:${crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex')}`;
 }
 
+/**
+ * Reference projection destination adapters.
+ * Hosts own durable destination writes; these prove the shared apply/reset/snapshot contract.
+ */
+export function createSqlProjectionAdapter({ table = 'ssss_events' } = {}) {
+  const rows = new Map();
+  return {
+    id: `sql:${table}`,
+    kind: 'sql',
+    apply: async (event) => {
+      rows.set(event.event_id, {
+        event_id: event.event_id,
+        subject: event.subject,
+        action: event.action,
+        after_hash: event.after_hash,
+        workspace_id: event.workspace_id,
+      });
+    },
+    reset: async () => rows.clear(),
+    snapshot: async () => Object.fromEntries([...rows.entries()].sort()),
+  };
+}
+
+export function createSearchProjectionAdapter({ index = 'ssss' } = {}) {
+  const documents = new Map();
+  return {
+    id: `search:${index}`,
+    kind: 'search',
+    apply: async (event) => {
+      documents.set(event.subject, {
+        subject: event.subject,
+        terms: [event.action, event.primitive_id, event.subject].filter(Boolean).join(' '),
+        after_hash: event.after_hash,
+      });
+    },
+    reset: async () => documents.clear(),
+    snapshot: async () => Object.fromEntries([...documents.entries()].sort()),
+  };
+}
+
+export function createQueueProjectionAdapter({ topic = 'ssss.mutations' } = {}) {
+  const messages = [];
+  return {
+    id: `queue:${topic}`,
+    kind: 'queue',
+    apply: async (event) => {
+      messages.push({ topic, event_id: event.event_id, subject: event.subject, action: event.action });
+    },
+    reset: async () => { messages.length = 0; },
+    snapshot: async () => messages.map((message) => ({ ...message })),
+  };
+}
+
+export function createViewModelProjectionAdapter({ view = 'detail' } = {}) {
+  const models = new Map();
+  return {
+    id: `view:${view}`,
+    kind: 'view_model',
+    apply: async (event) => {
+      models.set(event.subject, {
+        subject: event.subject,
+        version: event.after_hash || event.before_hash || null,
+        last_action: event.action,
+        principal_id: event.principal?.id || null,
+      });
+    },
+    reset: async () => models.clear(),
+    snapshot: async () => Object.fromEntries([...models.entries()].sort()),
+  };
+}
+
 export class ProjectionCoordinator {
   constructor({ eventStore, cursorStore = new Map() } = {}) {
     if (!eventStore) throw new Error('ProjectionCoordinator requires an eventStore.');

package/src/vfs.mjs

@@ -3,6 +3,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { isSafeDocumentPath } from './registry.mjs';
+import { withFileLock } from './file-lock.mjs';
+
+/** Reserved FileSystemVfs directory for per-path write locks; never a document path. */
+export const VFS_LOCK_DIR = '.ssss-locks';
 
 export class VfsConflictError extends Error {
   constructor(message) { super(message); this.name = 'VfsConflictError'; this.code = 'SSSS_VFS_CONFLICT'; }
@@ -77,14 +81,28 @@ export class MemoryVfs {
 }
 
 export class FileSystemVfs {
-  constructor(root) {
+  constructor(root, options = {}) {
     if (!root) throw new Error('FileSystemVfs requires a root directory.');
     fs.mkdirSync(root, { recursive: true });
     this.root = fs.realpathSync(root);
+    this.lockOptions = options.lock || {};
+  }
+
+  // Writers to one path serialize on a lock so precondition checks and commits
+  // are atomic across processes.
+  #locked(vfsPath, fn) {
+    const dir = path.join(this.root, VFS_LOCK_DIR);
+    let stat = null;
+    try { stat = fs.lstatSync(dir); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) throw new VfsPathError(`VFS lock directory '${VFS_LOCK_DIR}' must be a real directory.`);
+    const name = crypto.createHash('sha256').update(vfsPath).digest('hex');
+    return withFileLock(path.join(dir, `${name}.lock`), fn, { ...this.lockOptions, createDir: true });
   }
 
   #resolve(vfsPath, { allowMissing = true } = {}) {
     if (!isSafeDocumentPath(vfsPath)) throw new VfsPathError(`Unsafe VFS path '${vfsPath}'.`);
+    // Case-insensitive: on APFS/NTFS any casing reaches the same directory.
+    if (vfsPath.split('/')[0].toLowerCase() === VFS_LOCK_DIR) throw new VfsPathError(`VFS path '${vfsPath}' is reserved.`);
     const target = path.resolve(this.root, ...vfsPath.split('/'));
     if (target === this.root || !target.startsWith(`${this.root}${path.sep}`)) {
       throw new VfsPathError(`VFS path '${vfsPath}' escapes the root.`);
@@ -131,6 +149,7 @@ export class FileSystemVfs {
     while (stack.length) {
       const dir = stack.pop();
       for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (dir === this.root && entry.name === VFS_LOCK_DIR) continue;
         const absolute = path.join(dir, entry.name);
         const relative = path.relative(this.root, absolute).split(path.sep).join('/');
         if (entry.isSymbolicLink()) throw new VfsPathError(`Symlinked VFS entry is forbidden: '${relative}'.`);
@@ -144,6 +163,10 @@ export class FileSystemVfs {
 
   async writeAtomic(vfsPath, bytes, precondition = {}) {
     const target = this.#resolve(vfsPath);
+    return this.#locked(vfsPath, () => this.#commit(vfsPath, target, bytes, precondition));
+  }
+
+  async #commit(vfsPath, target, bytes, precondition) {
     const current = await this.read(vfsPath);
     checkPrecondition(current, precondition);
     fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -171,12 +194,15 @@ export class FileSystemVfs {
   }
 
   async remove(vfsPath, precondition = {}) {
-    const target = this.#resolve(vfsPath, { allowMissing: false });
-    const current = await this.read(vfsPath);
-    checkPrecondition(current, precondition);
-    if (!target || !current) return { path: vfsPath, removed: false };
-    fs.rmSync(target);
-    return { path: vfsPath, removed: true, previous_hash: current.hash };
+    this.#resolve(vfsPath);
+    return this.#locked(vfsPath, async () => {
+      const target = this.#resolve(vfsPath, { allowMissing: false });
+      const current = await this.read(vfsPath);
+      checkPrecondition(current, precondition);
+      if (!target || !current) return { path: vfsPath, removed: false };
+      fs.rmSync(target);
+      return { path: vfsPath, removed: true, previous_hash: current.hash };
+    });
   }
 }