@gregiteen/ssss-cli 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-09-24
+### Fixed
+- The file adapters are now safe to share between processes. Each one checked
+  state and then wrote it as two steps, so concurrent processes could both pass
+  the check: `FileSystemVfs` could lose an update behind a passed
+  compare-and-swap, `FileLeaseStore` could grant the same lease twice (spec §7),
+  `FileIdempotencyStore.put` could replace an existing entry, and
+  `JsonlEventStore` could append one `event_id` twice. Each check-then-write now
+  runs under an exclusive lock file (`O_EXCL`). A lock whose holder process has
+  exited is broken immediately; any lock older than 30 s is treated as stale;
+  a waiter gives up after 40 s with `SSSS_LOCK_TIMEOUT`. Adapters accept
+  `{ lock: { timeoutMs, staleMs } }`. `FileSystemVfs` keeps its locks in a
+  reserved `.ssss-locks/` directory that VFS paths cannot address and `list()`
+  skips. Locking costs about 0.5 ms per write on APFS.
+- `scripts/release.sh` bumps `package.json` and `package-lock.json` and moves the
+  `[Unreleased]` entries into the new version's section instead of inserting a
+  stub above `[Unreleased]`.
+
+### Added
+- `ssss help concurrency`.
+- Conformance checks that race six processes against each file adapter, plus
+  lock checks for dead holders, stale locks, timeouts, symlinked locks, and the
+  reserved VFS lock directory.
+- Git tags `v0.8.0` and `v0.9.0` on commits whose package files match the
+  published npm tarballs byte-for-byte. Both versions were published from
+  uncommitted trees, so no existing commit matched. The push skill now publishes
+  from a clean clone of the release tag.
+
 ## [0.9.1] - 2026-09-24
 ### Fixed
 - `JsonlEventStore.append` no longer re-reads and re-parses the whole

package/VERSION

@@ -1 +1 @@
-0.9.1
+0.9.2

package/conformance/reference-bundle.ucw.json

@@ -106,7 +106,7 @@
     "file_count": 14,
     "provenance": {
       "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@gregiteen/ssss-cli@0.9.1"
+      "exporter": "@gregiteen/ssss-cli@0.9.2"
     }
   },
   "files": [

package/docs/help/concurrency.md

@@ -0,0 +1,45 @@
+# File adapter concurrency
+
+The reference file adapters can be shared by several processes on one
+filesystem. Each adapter's check-then-write step runs under a lock file, so at
+most one racer wins:
+
+| Adapter | Guarantee across processes | Lock file |
+|---------|----------------------------|-----------|
+| `JsonlEventStore.append` | An `event_id` is appended at most once. | `<events>/<workspace>.jsonl.lock` |
+| `FileSystemVfs.writeAtomic` / `remove` | `ifAbsent`, `ifPresent`, and `version` preconditions are compare-and-swap. | `<vault>/.ssss-locks/<sha256(path)>.lock` |
+| `FileLeaseStore.acquire` / `renew` / `release` | At most one active lease per `(workspace_id, target)` (spec §7). | `<leases>/<sha256>.lease.json.lock` |
+| `FileIdempotencyStore.put` | A second `put` for a key fails instead of replacing the first. | `<idempotency>/<sha256>.json.lock` |
+
+`.ssss-locks/` is reserved: VFS paths under it are rejected and `list()` skips it.
+
+## Crashed holders
+
+A lock records its holder's pid and host. A waiter breaks the lock when the
+holder is on the same host and no longer running, or when the lock is older than
+`staleMs` (default 30 s). A waiter gives up after `timeoutMs` (default 40 s) with
+`SSSS_LOCK_TIMEOUT`. Both are adjustable per adapter:
+
+```js
+new JsonlEventStore(root, { lock: { timeoutMs: 10_000, staleMs: 15_000 } });
+new FileSystemVfs(root, { lock: { timeoutMs: 10_000 } });
+```
+
+Symlinked lock files are refused.
+
+## Limits
+
+- Locks are advisory: only writers using these adapters take them. Writers from
+  `@gregiteen/ssss-cli` 0.9.1 and earlier do not.
+- The kernel's idempotency check for `event` envelopes is read before commit and
+  written after, so two processes sending the same idempotency key at the same
+  moment can each append an event. `operation`, `patch`, and `delete` are
+  protected by the VFS compare-and-swap.
+- Network filesystems must support exclusive create (`O_EXCL`).
+- Dead-holder detection assumes processes that share the filesystem have
+  distinct hostnames (containers with the same hostname and separate pid
+  namespaces would look dead to each other). Stale detection compares the lock's
+  mtime with the local clock, so hosts' clocks must agree to well within
+  `staleMs`.
+
+See also: `ssss help leases`, `ssss help conformance`.

package/docs/help/overview.md

@@ -33,7 +33,8 @@ vault ──export──▶ .ucw bundle ──provision──▶ envelope plan
 
 Run `ssss help <topic>` for any of:
 `runtime`, `semantic`, `portability`, `bundle`, `provisioning`,
-`export`, `provision`, `import`, `conformance`, `autolink`.
+`export`, `provision`, `import`, `conformance`, `autolink`, `leases`,
+`concurrency`.
 
 Run `ssss <command> --help` for: `export`, `validate`, `inspect`, `provision`,
 `import`, `semantic`, `primitive`, `registry`, `adapter`, `migrate`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {

package/scripts/conformance-09.mjs

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { definePrimitive, definitionsToExtensionRegistry } from '../src/primitive.mjs';
@@ -25,7 +25,7 @@ import { createKernel } from '../src/kernel.mjs';
 import { UiRegistry, actionToEnvelope, createDeterministicUi, planUi, validateUiManifest } from '../src/ui.mjs';
 import { createCommandHandler, createDomainCommand } from '../src/http.mjs';
 import { detectDirectWrites } from '../src/guard.mjs';
-import { MemoryLeaseStore, FileLeaseStore, runLeaseContract } from '../src/leases.mjs';
+import { MemoryLeaseStore, FileLeaseStore, leaseStatePath, runLeaseContract } from '../src/leases.mjs';
 import { MemoryIdempotencyStore, FileIdempotencyStore, runIdempotencyContract } from '../src/idempotency.mjs';
 import { createCapabilityAuthorizer } from '../src/authorization.mjs';
 import { validateVerifiedPrincipal } from '../src/authorization.mjs';
@@ -40,25 +40,133 @@ async function replayed(store, options) {
   return items;
 }
 
-// Counts bytes JsonlEventStore reads from disk, to prove appends do not re-read the log.
-async function bytesReadDuring(fn) {
-  const { readSync, readFileSync } = fs;
+// Counts bytes read from `file` during `fn`, to prove appends do not re-read the log.
+async function bytesReadFrom(file, fn) {
+  const original = { openSync: fs.openSync, closeSync: fs.closeSync, readSync: fs.readSync, readFileSync: fs.readFileSync };
+  const fds = new Set();
   let bytes = 0;
-  fs.readSync = (...args) => { const read = readSync(...args); bytes += read; return read; };
-  fs.readFileSync = (...args) => { const out = readFileSync(...args); bytes += Buffer.byteLength(out); return out; };
-  try { await fn(); } finally { fs.readSync = readSync; fs.readFileSync = readFileSync; }
+  fs.openSync = (target, ...rest) => { const fd = original.openSync(target, ...rest); if (target === file) fds.add(fd); return fd; };
+  fs.closeSync = (fd) => { fds.delete(fd); return original.closeSync(fd); };
+  fs.readSync = (fd, ...rest) => { const read = original.readSync(fd, ...rest); if (fds.has(fd)) bytes += read; return read; };
+  fs.readFileSync = (target, ...rest) => {
+    const out = original.readFileSync(target, ...rest);
+    if (target === file || fds.has(target)) bytes += Buffer.byteLength(out);
+    return out;
+  };
+  try { await fn(); } finally { Object.assign(fs, original); }
   return bytes;
 }
 
+// Runs `body` in `count` child processes released on one shared deadline, so
+// their check-then-write sections overlap. Each resolves to { ok, racer, error }.
+function raceProcesses(count, imports, body) {
+  const startAt = Date.now() + 1000;
+  const code = [
+    ...Object.entries(imports).map(([name, file]) => `import { ${name} } from ${JSON.stringify(new URL(file, import.meta.url).href)};`),
+    'const racer = Number(process.env.SSSS_RACER);',
+    `while (Date.now() < ${startAt});`,
+    `try { ${body}; console.log(JSON.stringify({ ok: true, racer })); }`,
+    'catch (error) { console.log(JSON.stringify({ ok: false, racer, error: error.message })); }',
+  ].join('\n');
+  return Promise.all(Array.from({ length: count }, (_, racer) => new Promise((resolve) => {
+    const child = spawn(process.execPath, ['--input-type=module', '-e', code], { env: { ...process.env, SSSS_RACER: String(racer) } });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (chunk) => { out += chunk; });
+    child.stderr.on('data', (chunk) => { err += chunk; });
+    child.on('close', () => {
+      try { resolve(JSON.parse(out.trim().split('\n').pop())); }
+      catch { resolve({ ok: false, racer, error: `no result: ${err || out}` }); }
+    });
+  })));
+}
+
+const winners = (results) => results.filter((result) => result.ok);
+const describe = (results) => JSON.stringify(results.map(({ ok, racer, error }) => (ok ? racer : `${racer}:${error}`)));
+
+async function checkFileAdapterRaces(root, principal, check) {
+  const racers = 6;
+  const eventsRoot = path.join(root, 'events');
+  const event = createCanonicalEvent({ workspace_id: 'acme', action: 'event', subject: 'events/race.md', operation_id: 'race', idempotency_key: 'race', principal });
+  const appends = await raceProcesses(racers, { JsonlEventStore: '../src/events.mjs' },
+    `await new JsonlEventStore(${JSON.stringify(eventsRoot)}).append(${JSON.stringify(event)})`);
+  const lines = fs.readFileSync(path.join(eventsRoot, 'acme.jsonl'), 'utf8').split('\n').filter(Boolean);
+  check('jsonl event store lets one of several processes append the same event_id', winners(appends).length === 1 && lines.length === 1, describe(appends));
+
+  const vfsRoot = path.join(root, 'vfs');
+  const creates = await raceProcesses(racers, { FileSystemVfs: '../src/vfs.mjs' },
+    `await new FileSystemVfs(${JSON.stringify(vfsRoot)}).writeAtomic('race/create.md', 'racer-' + racer, { ifAbsent: true })`);
+  const created = fs.readFileSync(path.join(vfsRoot, 'race', 'create.md'), 'utf8');
+  check('filesystem VFS lets one of several processes create the same path',
+    winners(creates).length === 1 && created === `racer-${winners(creates)[0]?.racer}`, describe(creates));
+  const base = await new FileSystemVfs(vfsRoot).writeAtomic('race/cas.md', 'base', { ifAbsent: true });
+  const swaps = await raceProcesses(racers, { FileSystemVfs: '../src/vfs.mjs' },
+    `await new FileSystemVfs(${JSON.stringify(vfsRoot)}).writeAtomic('race/cas.md', 'racer-' + racer, { version: ${JSON.stringify(base.version)} })`);
+  const swapped = fs.readFileSync(path.join(vfsRoot, 'race', 'cas.md'), 'utf8');
+  check('filesystem VFS lets one of several processes compare-and-swap the same version',
+    winners(swaps).length === 1 && swapped === `racer-${winners(swaps)[0]?.racer}`, describe(swaps));
+
+  const leaseRoot = path.join(root, 'leases');
+  const leases = await raceProcesses(racers, { FileLeaseStore: '../src/leases.mjs' },
+    `await new FileLeaseStore(${JSON.stringify(leaseRoot)}).acquire({ workspace_id: 'acme', target: 'race.md', principal_id: 'p' + racer, operation_id: 'o' + racer }, 60000)`);
+  const held = JSON.parse(fs.readFileSync(leaseStatePath(fs.realpathSync(leaseRoot), 'acme', 'race.md'), 'utf8'));
+  check('filesystem lease store grants one of several processes the same lease',
+    winners(leases).length === 1 && held.principal_id === `p${winners(leases)[0]?.racer}`, describe(leases));
+
+  const idempotencyRoot = path.join(root, 'idempotency');
+  const puts = await raceProcesses(racers, { FileIdempotencyStore: '../src/idempotency.mjs' },
+    `await new FileIdempotencyStore(${JSON.stringify(idempotencyRoot)}).put('acme', 'race', { request_hash: 'racer-' + racer })`);
+  const stored = await new FileIdempotencyStore(idempotencyRoot).get('acme', 'race');
+  check('filesystem idempotency store accepts one of several processes putting the same key',
+    winners(puts).length === 1 && stored?.request_hash === `racer-${winners(puts)[0]?.racer}`, describe(puts));
+}
+
+async function checkFileLocks(root, principal, check) {
+  const make = (id) => createCanonicalEvent({ workspace_id: 'acme', action: 'event', subject: 'events/lock.md', operation_id: id, idempotency_key: id, principal });
+  const lock = path.join(root, 'acme.jsonl.lock');
+  const holder = (fields) => fs.writeFileSync(lock, JSON.stringify({ token: 'other', host: os.hostname(), ...fields }));
+  const store = new JsonlEventStore(root, { lock: { timeoutMs: 500, staleMs: 60_000 } });
+
+  holder({ pid: process.pid });
+  const started = Date.now();
+  check('file locks make a writer wait for a live holder and then time out',
+    await rejects(store.append(make('lock-live')), /Timed out waiting for lock/) && Date.now() - started >= 450 && fs.existsSync(lock));
+  const exited = spawnSync(process.execPath, ['-e', '']).pid;
+  holder({ pid: exited });
+  await store.append(make('lock-dead'));
+  check('file locks break a lock whose holder process has exited', !fs.existsSync(lock));
+  holder({ pid: process.pid, host: 'another-host' });
+  const past = new Date(Date.now() - 120_000);
+  fs.utimesSync(lock, past, past);
+  await new JsonlEventStore(root, { lock: { timeoutMs: 500, staleMs: 30_000 } }).append(make('lock-stale'));
+  check('file locks break a lock older than the stale threshold', !fs.existsSync(lock));
+  const decoy = path.join(root, 'decoy.txt');
+  fs.writeFileSync(decoy, 'untouched');
+  fs.symlinkSync(decoy, lock);
+  check('file locks refuse a symlinked lock file',
+    await rejects(store.append(make('lock-symlink')), /not a regular file/) && fs.readFileSync(decoy, 'utf8') === 'untouched');
+  fs.rmSync(lock);
+
+  const vfs = new FileSystemVfs(path.join(root, 'vfs'));
+  await vfs.writeAtomic('docs/one.md', 'one', { ifAbsent: true });
+  fs.writeFileSync(path.join(vfs.root, '.ssss-locks', 'leftover.lock'), '{}');
+  const listed = [];
+  for await (const entry of vfs.list()) listed.push(entry.path);
+  check('filesystem VFS reserves its lock directory',
+    await rejects(vfs.writeAtomic('.ssss-locks/forged.lock', 'x'), /reserved/)
+    && await rejects(vfs.writeAtomic('.SSSS-Locks/forged.lock', 'x'), /reserved/)
+    && JSON.stringify(listed) === JSON.stringify(['docs/one.md']));
+}
+
 async function checkJsonlEventStoreIndex(root, principal, check) {
   let seq = 0;
   const make = (workspace = 'acme') => createCanonicalEvent({
     workspace_id: workspace, action: 'event', subject: 'events/indexed.md',
     operation_id: `indexed-${++seq}`, idempotency_key: `indexed-${seq}`, principal,
   });
-  const log = path.join(root, 'acme.jsonl');
   const first = new JsonlEventStore(root);
   const second = new JsonlEventStore(root);
+  const log = path.join(first.root, 'acme.jsonl');
   const appended = [];
   const add = async (store, event) => { await store.append(event); appended.push(event.event_id); return event; };
 
@@ -78,10 +186,10 @@ async function checkJsonlEventStoreIndex(root, principal, check) {
 
   const seeded = fs.statSync(log).size;
   const fresh = new JsonlEventStore(root);
-  const batchBytes = await bytesReadDuring(async () => { for (let i = 0; i < 200; i++) await add(fresh, make()); });
+  const batchBytes = await bytesReadFrom(log, async () => { for (let i = 0; i < 200; i++) await add(fresh, make()); });
   check('jsonl event store reads the log once for many appends from one instance', batchBytes === seeded, `read ${batchBytes} bytes; log was ${seeded}`);
   await add(second, make());
-  const revalidateBytes = await bytesReadDuring(() => add(fresh, make()));
+  const revalidateBytes = await bytesReadFrom(log, () => add(fresh, make()));
   check('jsonl event store rebuilds its index after another writer appends', revalidateBytes > seeded);
 
   const other = [];
@@ -277,6 +385,8 @@ export async function runKernel09Conformance() {
       check(`${name} event store is append-only and replayable`, duplicate && replayed === 1);
     }
     await checkJsonlEventStoreIndex(path.join(temp, 'events-index'), principal, check);
+    await checkFileAdapterRaces(path.join(temp, 'races'), principal, check);
+    await checkFileLocks(path.join(temp, 'locks'), principal, check);
     const denied = await kernel.execute({ type: 'patch', workspace_id: 'acme', idempotency_key: 'denied', path: 'bookings/one.md', patches: { status: 'pending' } }, {
       principal: { ...principal, id: 'outsider', workspaceIds: [], capabilities: ['*:*'] },
     });

package/scripts/release.sh

@@ -2,7 +2,9 @@
 # ============================================================
 # SSSS — Version Release Script
 #
-# Bumps the VERSION file and adds a stub in CHANGELOG.md
+# Bumps VERSION, package.json and package-lock.json, and turns the
+# CHANGELOG's [Unreleased] entries into a section for the new version
+# (a stub when [Unreleased] is empty).
 # ============================================================
 
 set -euo pipefail
@@ -20,16 +22,21 @@ if [[ ! "$NEW_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
     exit 1
 fi
 
-echo "$NEW_VERSION" > VERSION
-
-# Quick sed to insert new version at the top of the changelog
-sed -i.bak "/^## \[.*\]/i \\
-## [$NEW_VERSION] - $(date +%Y-%m-%d)\\
-### Added\\
-- \\
-\\
-" CHANGELOG.md
+cd "$(dirname "$0")/.."
 
-rm -f CHANGELOG.md.bak
-
-echo "✅ Bumped version to $NEW_VERSION"
+echo "$NEW_VERSION" > VERSION
+npm version "$NEW_VERSION" --no-git-tag-version --allow-same-version > /dev/null
+
+node --input-type=module -e '
+import fs from "node:fs";
+const [version, date] = process.argv.slice(1);
+const text = fs.readFileSync("CHANGELOG.md", "utf8");
+if (text.includes(`## [${version}]`)) process.exit(0);
+const match = text.match(/^## \[Unreleased\]\n([\s\S]*?)(?=^## \[)/m);
+if (!match) { console.error("CHANGELOG.md has no ## [Unreleased] section followed by a release."); process.exit(1); }
+const entries = match[1].trim() || "### Added\n- ";
+const section = `## [Unreleased]\n\n## [${version}] - ${date}\n${entries}\n\n`;
+fs.writeFileSync("CHANGELOG.md", text.replace(match[0], section));
+' "$NEW_VERSION" "$(date +%Y-%m-%d)"
+
+echo "✅ Bumped version to $NEW_VERSION (VERSION, package.json, package-lock.json, CHANGELOG.md)"

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'];
@@ -90,10 +91,13 @@ export class JsonlEventStore {
   // 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) {
+  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.');
@@ -116,6 +120,9 @@ export class JsonlEventStore {
   }
   async append(event) {
     const file = this.#file(event.workspace_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`;
@@ -127,7 +134,8 @@ export class JsonlEventStore {
       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 another writer interleaved and the next append rebuilds.
+    // 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))) {

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']) {
@@ -56,10 +57,16 @@ export class FileLeaseStore {
     fs.mkdirSync(root, { recursive: true });
     this.root = fs.realpathSync(root);
     this.clock = options.clock || (() => Date.now());
+    this.lockOptions = options.lock || {};
   }
   #file(workspaceId, target) {
     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);
     if (!fs.existsSync(file)) return null;
@@ -78,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);
@@ -94,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 };
+    });
   }
 }
 

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 };
+    });
   }
 }