@deepseek-ai/dsh-atomic-write 0.1.0-rc.6 → 0.1.0-rc.8

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
-README.md: a767f24064c368b60d85fed6fa1d88349cab9587
-README.zh.md: 6388e264898e0025fb6586acecab450be3eb9e55
+README.md: 4d0b55291955c9d37f4788c7d37ad8e6ce728f70
+README.zh.md: c2d7f0b49fa123befbb663ac43862a40b4ef19b4

package/README.md

@@ -28,7 +28,7 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 - **Same-directory sibling** keeps the rename on one filesystem, so the swap stays atomic.
 - Parent directories are created; on any failure the temp is removed and the failure rethrown; readers observe either the old or the new complete content.
 
-`withFileLock` serializes the writers of one file across processes, for the read-render-commit cycles a bare atomic commit cannot make safe on its own. The lock is a `wx`-created `<filename>.lock` sibling, so readers never contend; waiters back off exponentially and fail with a timeout rather than block forever. A contender never removes the existing lock: age cannot distinguish a crashed owner from a paused live writer.
+`withFileLock` serializes the writers of one file across processes, for the read-render-commit cycles a bare atomic commit cannot make safe on its own. The lock is a `wx`-created `<filename>.lock` sibling, so readers never contend; waiters back off exponentially and fail with a timeout rather than block forever. `EEXIST` identifies contention directly; `EPERM` does so only when a fresh `lstat` confirms that the lock path exists, covering Windows exclusive-create behavior without hiding an unrelated permission failure. A contender never removes the existing lock: age cannot distinguish a crashed owner from a paused live writer.
 
 ## Model Experience
 

package/README.zh.md

@@ -28,7 +28,7 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 - **同目录兄弟文件**保证 rename 落在同一文件系统上，交换保持原子。
 - 自动创建父目录；任何失败都会移除临时文件并重新抛出该失败；读取方只会观察到旧内容或完整的新内容。
 
-`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。竞争者绝不移除现有锁：锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
+`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。`EEXIST` 直接表示竞争；只有一次新的 `lstat` 确认锁路径存在时，`EPERM` 才表示竞争，从而兼容 Windows 的独占创建行为，又不掩盖无关的权限故障。竞争者绝不移除现有锁：锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
 
 ## 模型体验
 

package/lib/index.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 //#region lib/types/index.js
 /**
@@ -44,9 +44,17 @@ async function writeFileAtomic(filename, content, options) {
 		throw error;
 	}
 }
-/** Whether an exclusive create failed because the path already exists. */
-function isEEXIST(error) {
-	return error?.code === "EEXIST";
+/** Whether an exclusive create found an existing lock. */
+async function isLockContention(error, lockPath) {
+	const code = error?.code;
+	if (code === "EEXIST") return true;
+	if (code !== "EPERM") return false;
+	try {
+		await lstat(lockPath);
+		return true;
+	} catch {
+		return false;
+	}
 }
 /**
 * Writer-lock protocol constants. These are robustness invariants of the
@@ -61,10 +69,13 @@ const LOCK_TIMEOUT_MS = 2e3;
 * Hold the cross-process writer lock for `filename` around one operation. The
 * lock is a `wx`-created sibling (`<filename>.lock`); paired with the
 * rename-based commit of {@link writeFileAtomic}, readers stay lock-free and
-* only writers contend. Contention backs off exponentially and fails with a
-* timed-out error after the deadline. The contender never removes an existing
-* lock because file age cannot prove that its owner stopped; orphan recovery
-* is an operator action. The parent directory must exist.
+* only writers contend. `EEXIST` is contention directly; an `EPERM` is
+* contention only when a fresh `lstat` confirms the lock path exists, covering
+* Windows exclusive-create behavior without hiding an unrelated permission
+* failure. Contention backs off exponentially and fails with a timed-out error
+* after the deadline. The contender never removes an existing lock because
+* file age cannot prove that its owner stopped; orphan recovery is an operator
+* action. The parent directory must exist.
 * @param filename - the file whose writers this lock serializes.
 * @param operation - the read-render-commit cycle to run while holding the lock.
 * @returns the operation's result; the lock releases on both outcomes.
@@ -81,7 +92,7 @@ async function withFileLock(filename, operation) {
 			});
 			break;
 		} catch (error) {
-			if (!isEEXIST(error)) throw error;
+			if (!await isLockContention(error, lockPath)) throw error;
 		}
 		if (Date.now() >= deadline) throw new Error(`atomic-write: timed out waiting for the writer lock at ${lockPath}`);
 		await new Promise((resolve) => setTimeout(resolve, delay));

package/lib/types/index.d.ts

@@ -45,10 +45,13 @@ export declare function writeFileAtomic(filename: string, content: string, optio
  * Hold the cross-process writer lock for `filename` around one operation. The
  * lock is a `wx`-created sibling (`<filename>.lock`); paired with the
  * rename-based commit of {@link writeFileAtomic}, readers stay lock-free and
- * only writers contend. Contention backs off exponentially and fails with a
- * timed-out error after the deadline. The contender never removes an existing
- * lock because file age cannot prove that its owner stopped; orphan recovery
- * is an operator action. The parent directory must exist.
+ * only writers contend. `EEXIST` is contention directly; an `EPERM` is
+ * contention only when a fresh `lstat` confirms the lock path exists, covering
+ * Windows exclusive-create behavior without hiding an unrelated permission
+ * failure. Contention backs off exponentially and fails with a timed-out error
+ * after the deadline. The contender never removes an existing lock because
+ * file age cannot prove that its owner stopped; orphan recovery is an operator
+ * action. The parent directory must exist.
  * @param filename - the file whose writers this lock serializes.
  * @param operation - the read-render-commit cycle to run while holding the lock.
  * @returns the operation's result; the lock releases on both outcomes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-atomic-write",
   "description": "Zero-dependency atomic file replacement: exclusive-create random-suffix temp + rename carrying the caller-stated permissions (writeFileAtomic)",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.8",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,11 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8"
   }
 }