@deepseek-ai/dsh-atomic-write 0.1.6-alpha.1 → 0.1.6-alpha.2

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: c3ce840f79c38fb7fac404786f0e5a7e41138d57
-README.zh.md: 9cc1f271f70e113637b88b7e3984d431e84c647f
+README.md: 89770a6d318da778e9dcb7a462dc7754244a0e41
+README.zh.md: a64771ae1266f132254c82aaa71f193dbf33cd06

package/README.md

@@ -58,6 +58,8 @@ Only writers contend — readers never take the lock — and a contender backs o
 
 ### Failures to plan for
 
+Windows retries one `EPERM` when the lock cannot be observed, because its holder can release between exclusive creation and the existence check. A repeated unconfirmed `EPERM` is rethrown without running the operation.
+
 The lock's parent directory must already exist, so `withFileLock` rejects an invalid parent hierarchy before running the operation. A process that exits while holding the lock leaves the lock sibling behind; later writers time out, and an operator removes it only after verifying that no writer still owns it.
 
 -----

package/README.zh.md

@@ -58,6 +58,8 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 
 ### 需要规划的失败
 
+Windows 在无法观察到锁时会对 `EPERM` 重试一次，因为持锁方可能在独占创建与存在性检查之间释放锁。再次出现无法确认锁存在的 `EPERM` 时，会重新抛出错误且不运行操作。
+
 锁的父目录必须已经存在，因此 `withFileLock` 会在运行操作之前拒绝无效的父目录层级。持锁进程退出时会把锁文件留在原地；后续写入方超时失败，操作者只有在确认没有写入方仍持有该锁后才会移除它。
 
 -----

package/lib/index.js

@@ -109,8 +109,9 @@ const DEFAULT_LOCK_WAIT_MS = 2e3;
 * rename-based commit of {@link writeFileAtomic}, readers stay lock-free and
 * 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
+* Windows exclusive-create behavior. Windows retries one unconfirmed EPERM
+* because the holder can release before the probe; a repeated unconfirmed
+* permission error is rethrown. Contention backs off exponentially and times out
 * 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.
@@ -123,6 +124,7 @@ async function withFileLock(filename, operation, options) {
 	const lockPath = `${filename}.lock`;
 	const deadline = Date.now() + (options?.waitMs ?? DEFAULT_LOCK_WAIT_MS);
 	let delay = LOCK_RETRY_INITIAL_MS;
+	let retriedUnconfirmedPermissionError = false;
 	for (;;) {
 		try {
 			await writeFile(lockPath, `${process.pid}\n`, {
@@ -131,7 +133,10 @@ async function withFileLock(filename, operation, options) {
 			});
 			break;
 		} catch (error) {
-			if (!await isLockContention(error, lockPath)) throw error;
+			if (!await isLockContention(error, lockPath)) {
+				if (process.platform !== "win32" || error?.code !== "EPERM" || retriedUnconfirmedPermissionError) throw error;
+				retriedUnconfirmedPermissionError = true;
+			}
 		}
 		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

@@ -61,8 +61,9 @@ export interface FileLockOptions {
  * rename-based commit of {@link writeFileAtomic}, readers stay lock-free and
  * 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
+ * Windows exclusive-create behavior. Windows retries one unconfirmed EPERM
+ * because the holder can release before the probe; a repeated unconfirmed
+ * permission error is rethrown. Contention backs off exponentially and times out
  * 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.

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.6-alpha.1",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },