@deepseek-ai/dsh-atomic-write 0.1.7-rc.1 → 0.2.0-rc.1

package/README.i18n.yaml

@@ -1,6 +1,55 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# 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: fa2a77c8ba11e1dd80fecef6da09fa32a608b523
-README.zh.md: 020d379c876733d5de11c63887de8d3168eac3b3
+/:
+  en: 1065a4fcafd0430d
+  zh: 40bc911b6d01288b
+/deepseek-ai-dsh-atomic-write:
+  en: ed491d62812ad8cc
+  zh: 653e184dd035ec71
+/deepseek-ai-dsh-atomic-write/summary:
+  en: 6c4c49bda04ed05f
+  zh: 1080ddd179d0a3d2
+/deepseek-ai-dsh-atomic-write/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-atomic-write/use-this-package:
+  en: 9cc27a0ee5ae0808
+  zh: d0ee06b54452f600
+/deepseek-ai-dsh-atomic-write/use-this-package/writing-a-file-atomically:
+  en: 7b757dc3c3b27335
+  zh: a097d90a2561475d
+/deepseek-ai-dsh-atomic-write/use-this-package/coordinating-writers:
+  en: 77c865c1f78d2a0c
+  zh: 5a91874c352c6f18
+/deepseek-ai-dsh-atomic-write/use-this-package/failures-to-plan-for:
+  en: 59308dc757e25273
+  zh: 01113ed577a413cb
+/deepseek-ai-dsh-atomic-write/understand-the-implementation:
+  en: 93b537308f7c88c7
+  zh: 282e0d2042aeb1be
+/deepseek-ai-dsh-atomic-write/understand-the-implementation/source-map:
+  en: 725509a8b621c668
+  zh: c11e3ffdf73af844
+/deepseek-ai-dsh-atomic-write/understand-the-implementation/write-path:
+  en: 2e6561c9282f0c0d
+  zh: 7f0e76f6dbdea501
+/deepseek-ai-dsh-atomic-write/understand-the-implementation/why-the-swap-stays-safe:
+  en: 784e985c1fb3a25e
+  zh: 4afda1b9bf5f29cc
+/deepseek-ai-dsh-atomic-write/further-exploration:
+  en: 16ece9b754f7fff6
+  zh: 2456fe14cc5a658b
+/deepseek-ai-dsh-atomic-write/model-experience:
+  en: 225fc1d94a284905
+  zh: 7319a43c3b8a884d
+/deepseek-ai-dsh-atomic-write/model-experience/kv-cache-effect:
+  en: 815e93723a98919c
+  zh: 921da870f67e4033
+/deepseek-ai-dsh-atomic-write/known-limitations-and-deferred-work:
+  en: 5d0b395da8833bbb
+  zh: 6191bab46d288be7
+/deepseek-ai-dsh-atomic-write/known-limitations-and-deferred-work/dev-note:
+  en: d3461ceeaf041974
+  zh: f59df2adbf52fed9

package/README.md

@@ -54,13 +54,13 @@ await withFileLock('/home/u/.dsh/cordis.patch.yml', async () => {
 })
 ```
 
-Only writers contend — readers never take the lock — and a contender backs off exponentially and fails with a timed-out error rather than blocking forever. How long a contender waits is stated per call through `waitMs`: the default is sized for file work alone, so a holder whose cycle includes a network round trip — a credential mutation that refreshes an expired token — states a longer one, because leaving the default would fail every other writer of that file for the duration. The retry cadence stays fixed. A contender never removes an existing lock, because file age cannot prove that its owner stopped.
+Only writers contend — readers never take the lock — and a contender backs off exponentially and fails with a timed-out error rather than blocking forever. How long a contender waits is stated per call through `waitMs`: the default is sized for file work alone, so a holder whose cycle includes a network round trip — a credential mutation that refreshes an expired token — states a longer one, because leaving the default would fail every other writer of that file for the duration. The retry cadence stays fixed. A contender removes an existing lock only when the lock names a process that no longer exists; file age alone never removes a lock.
 
 ### 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.
+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, and the next writer takes it over. A lock whose record is empty or incomplete, or names a PID that a live process reused, is not taken over; later writers time out, and an operator removes it only after verifying that no writer still owns it.
 
 -----
 
@@ -83,13 +83,13 @@ The package is built on one separation: the atomic commit owns the swap, and the
 
 `writeFileAtomic` writes a random-suffix sibling opened with exclusive create (`wx`), then renames it over the target. The exclusive open refuses to follow a symlink planted at a guessable temp path; the same-directory sibling keeps the rename on one filesystem; and the rename replaces a symlinked target itself instead of writing through to its referent. A Windows retry keeps the same complete sibling and uses bounded exponential backoff, so temporary use of the target by software outside the cooperative writer lock cannot turn a safe replacement into an immediate failure; the archived [retry decision record](../../../.agents/notes/archived/bug-fix/2026-08-29-windows-atomic-replace-retry.md) documents the original rationale and rejected alternatives.
 
-`withFileLock` creates a `<filename>.lock` sibling with `wx`. `EEXIST` identifies contention directly; `EPERM` does so only when a fresh `lstat` confirms the lock path exists, covering Windows exclusive-create behavior without hiding an unrelated permission failure. The lock records its creator's PID and is removed by the holder in a `finally`; contention backs off exponentially and fails when the per-call `waitMs` deadline (default two seconds) passes.
+`withFileLock` creates a `<filename>.lock` sibling with `wx`. `EEXIST` identifies contention directly; `EPERM` does so only when a fresh `lstat` confirms the lock path exists, covering Windows exclusive-create behavior without hiding an unrelated permission failure. The lock records its creator's PID as `<pid>\n` and is removed by the holder in a `finally`. A contender that reads a record whose PID a signal probe reports as absent (`ESRCH`) creates a `<filename>.lock.takeover-<record hash>` claim with `wx`, re-reads the lock and probes its PID again, removes it only if it still holds the same record and that PID is still absent, removes the claim, and retries at once. A holder that exists under another user (`EPERM`) and a record naming the contender's own process are waited for. Contenders that read the same record contend for one claim, and the second probe rejects a holder that reused the exited PID, so a takeover never removes a lock that another contender acquired after the exited holder's. Takeover proves only that the recorded process exited; an operation that starts other writers leaves its successor a way to find them, as the [Plugin Manager](../../boot/plugin-manager/README.md) does for its pnpm runs. Contention backs off exponentially and fails when the per-call `waitMs` deadline (default two seconds) passes; the [takeover decision record](../../../.agents/notes/implemented/bug-fix/2026-09-24-exited-holder-lock-takeover.md) owns the rationale.
 
 ### Why the swap stays safe
 
 - **Fresh inode, caller-stated mode** — the temp carries `mode` through the rename, so narrowing a wider-permission file has no chmod race. `mode` is required so the permission decision stays visible at every call site.
 - **Readers never contend** — the rename commit is atomic, so a reader needs no lock.
-- **A contender never deletes a lock** — age cannot distinguish a crashed owner from a paused live writer; recovery is an operator action.
+- **A contender deletes only an exited holder's lock** — age cannot distinguish a crashed owner from a paused live writer, but a missing process can.
 
 </details>
 
@@ -124,7 +124,8 @@ These limits define where the package is not the right tool. They are current pa
 
 - **Atomic, not durable** — no `fsync` of the file or its directory, so after a crash the rename may be observed unwound. The file-backed stores here re-read and republish on boot, keeping durability the caller's policy.
 - **String content only** — no `Buffer` or stream form until a consumer needs one.
-- **Orphaned locks require operator recovery** — a process that exits while holding the lock leaves the sibling behind; later writers time out without deleting it.
+- **Some orphaned locks require operator recovery** — a lock whose record is empty or incomplete, or names a PID a live process reused, stays in place; later writers time out without deleting it. A contender that ends between creating a claim and removing the lock leaves both `<filename>.lock` and `<filename>.lock.takeover-<record hash>`, and the operator removes both.
+- **One host and one PID namespace** — the probe runs on the contender's host. Writers on several hosts sharing a network filesystem, or containers sharing a volume, can see a live holder as exited, take over its lock, and write at the same time as it.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -54,13 +54,13 @@ await withFileLock('/home/u/.dsh/cordis.patch.yml', async () => {
 })
 ```
 
-只有写入方会竞争——读取方从不取锁——竞争者按指数退避，超时后报错，而不是无限阻塞。竞争者等待多久由每次调用经 `waitMs` 声明：默认值只按纯文件工作量级选定，因此持锁方循环若包含一次网络往返——例如刷新过期 token 的凭据变更——就应声明更长的值，否则该文件的其他写入方在这段时间内都会失败。退避节奏保持固定。竞争者绝不移除已有锁，因为文件存续时间无法证明其持有者已经停止。
+只有写入方会竞争——读取方从不取锁——竞争者按指数退避，超时后报错，而不是无限阻塞。竞争者等待多久由每次调用经 `waitMs` 声明：默认值只按纯文件工作量级选定，因此持锁方循环若包含一次网络往返——例如刷新过期 token 的凭据变更——就应声明更长的值，否则该文件的其他写入方在这段时间内都会失败。退避节奏保持固定。只有当锁记录的进程已不存在时，竞争者才会移除已有锁；单凭文件存续时间绝不会移除锁。
 
 ### 需要规划的失败
 
 Windows 在无法观察到锁时会对 `EPERM` 重试一次，因为持锁方可能在独占创建与存在性检查之间释放锁。再次出现无法确认锁存在的 `EPERM` 时，会重新抛出错误且不运行操作。
 
-锁的父目录必须已经存在，因此 `withFileLock` 会在运行操作之前拒绝无效的父目录层级。持锁进程退出时会把锁文件留在原地；后续写入方超时失败，操作者只有在确认没有写入方仍持有该锁后才会移除它。
+锁的父目录必须已经存在，因此 `withFileLock` 会在运行操作之前拒绝无效的父目录层级。持锁进程退出时会把锁文件留在原地，下一个写入方会接管它。锁记录为空或不完整，或其 PID 已被存活进程复用时，锁不会被接管；后续写入方超时失败，操作者只有在确认没有写入方仍持有该锁后才会移除它。
 
 -----
 
@@ -83,13 +83,13 @@ Windows 在无法观察到锁时会对 `EPERM` 重试一次，因为持锁方可
 
 `writeFileAtomic` 先以独占创建（`wx`）打开一个随机后缀的同级文件并写入内容，然后 rename 到目标上。独占打开拒绝跟随预先埋在可猜测临时路径上的符号链接；同目录兄弟文件保证 rename 落在同一文件系统上；rename 替换的是目标位置的符号链接本身，绝不写穿到该链接指向的文件。Windows 重试会保留同一份完整的兄弟文件，并采用有界指数退避，因此协作式写锁之外的软件瞬时占用目标时，不会让安全替换立即失败；已归档的[重试决策记录](../../../.agents/notes/archived/bug-fix/2026-08-29-windows-atomic-replace-retry.md)记录了最初的理由与被拒绝的替代方案。
 
-`withFileLock` 以 `wx` 创建 `<filename>.lock` 同级文件。`EEXIST` 直接表示竞争；只有一次新的 `lstat` 确认锁路径存在时，`EPERM` 才表示竞争，从而兼容 Windows 的独占创建行为，又不掩盖无关的权限故障。锁记录创建者的 PID，由持有者在 `finally` 中移除；竞争按指数退避，在每次调用声明的 `waitMs` 期限（默认两秒）过后失败。
+`withFileLock` 以 `wx` 创建 `<filename>.lock` 同级文件。`EEXIST` 直接表示竞争；只有一次新的 `lstat` 确认锁路径存在时，`EPERM` 才表示竞争，从而兼容 Windows 的独占创建行为，又不掩盖无关的权限故障。锁以 `<pid>\n` 记录创建者的 PID，由持有者在 `finally` 中移除。竞争者读到的记录若经信号探测报告该 PID 不存在（`ESRCH`），就以 `wx` 创建 `<filename>.lock.takeover-<记录哈希>` 认领文件，重新读取锁并再次探测其 PID，仅当锁仍是同一条记录且该 PID 仍不存在时才移除它，随后移除认领文件并立即重试。以其他用户身份存在的持有者（`EPERM`）和指向竞争者自身进程的记录会继续等待。读到同一条记录的竞争者争用同一个认领文件，第二次探测会排除复用了已退出 PID 的持有者，因此接管绝不会移除另一个竞争者在已退出持有者之后获得的锁。接管只能证明记录中的进程已退出；启动了其他写入者的操作要为后继者留下找到它们的途径，[Plugin Manager](../../boot/plugin-manager/README.zh.md) 对其 pnpm 运行就是这样做的。竞争按指数退避，在每次调用声明的 `waitMs` 期限（默认两秒）过后失败；[接管决策记录](../../../.agents/notes/implemented/bug-fix/2026-09-24-exited-holder-lock-takeover.zh.md)负责说明理由。
 
 ### 交换为何安全
 
 - **全新 inode，调用方声明的权限位**——临时文件带着 `mode` 走完 rename，因此收窄权限过宽的文件没有 chmod 竞态。`mode` 为必填，让权限决策始终可见于每个调用点。
 - **读取方从不竞争**——rename 提交是原子的，读取方无需加锁。
-- **竞争者绝不移除锁**——文件存续时间无法区分已崩溃的所有者与暂停但仍存活的写入方；恢复是操作者的动作。
+- **竞争者只移除已退出持有者的锁**——文件存续时间无法区分已崩溃的所有者与暂停但仍存活的写入方，但进程已不存在可以区分。
 
 </details>
 
@@ -124,7 +124,8 @@ Windows 在无法观察到锁时会对 `EPERM` 重试一次，因为持锁方可
 
 - **原子但不保证持久**——不对文件或其所在目录做 `fsync`，因此崩溃后可能观察到 rename 被回退。此处的文件型存储在启动时重新读取并重新发布，把持久性留作调用方的策略。
 - **仅支持字符串内容**——在有消费方需要之前，不提供 `Buffer` 或流式形态。
-- **遗留锁需要操作者恢复**——持锁进程退出时可能留下同级锁文件；后续写入方超时也不会删除它。
+- **部分遗留锁需要操作者恢复**——锁记录为空或不完整，或其 PID 已被存活进程复用时，锁会留在原地；后续写入方超时也不会删除它。竞争者若在创建认领文件与移除锁之间结束，会同时留下 `<filename>.lock` 和 `<filename>.lock.takeover-<记录哈希>`，由操作者删除两者。
+- **单一主机与单一 PID 命名空间**——探测在竞争者所在主机上进行。多台主机通过网络文件系统共享、或多个容器共享同一卷时，写入方可能把存活持有者视为已退出，接管其锁并与之同时写入。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -1,5 +1,5 @@
-import { randomBytes } from "node:crypto";
-import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 //#region lib/types/index.js
 /**
@@ -10,7 +10,8 @@ import { dirname } from "node:path";
 * up with exactly the stated mode. `withFileLock` serializes cross-process
 * writers of one file through a `wx`-created `<file>.lock` sibling, so a
 * read-modify-write cycle can never resurrect a state another writer just
-* replaced; readers stay lock-free because the rename commit is atomic.
+* replaced; readers stay lock-free because the rename commit is atomic. A lock
+* whose recorded holder process no longer exists is taken over.
 * @module @deepseek-ai/dsh-atomic-write
 */
 const WINDOWS_TRANSIENT_RENAME_ERRORS = new Set([
@@ -86,6 +87,63 @@ async function isLockContention(error, lockPath) {
 		return false;
 	}
 }
+/** Whether the holder a `<pid>\n` record names is proven gone: a signal probe finds no such process. */
+function holderExited(record) {
+	if (!/^\d+\n$/.test(record)) return false;
+	const pid = Number(record.trim());
+	if (pid === 0 || pid > 2147483647) return false;
+	if (pid === process.pid) return false;
+	try {
+		process.kill(pid, 0);
+		return false;
+	} catch (error) {
+		return error.code === "ESRCH";
+	}
+}
+/** The lock file's content, or undefined when it cannot be read. */
+async function readLockRecord(lockPath) {
+	try {
+		return await readFile(lockPath, "utf8");
+	} catch (error) {
+		return;
+	}
+}
+/**
+* Remove the lock when its recorded holder exited. Contenders that read the
+* same record serialize on a claim file named after it. Under the claim, the
+* claimant re-reads the lock and probes its PID again, and removes it only
+* when it still holds that record and that PID is still gone: the record's
+* holder can no longer release it, and no other contender can remove it
+* without the claim, so a removal never deletes a lock another contender
+* acquired after the dead holder's, including one whose holder reused the PID.
+* @returns Whether this call removed the dead holder's lock.
+*/
+async function takeOverExitedLock(lockPath) {
+	const record = await readLockRecord(lockPath);
+	if (record === void 0 || !holderExited(record)) return false;
+	const claim = `${lockPath}.takeover-${createHash("sha256").update(record).digest("hex").slice(0, 16)}`;
+	try {
+		await writeFile(claim, `${process.pid}\n`, {
+			mode: 384,
+			flag: "wx"
+		});
+	} catch (error) {
+		const code = error.code;
+		if (code === "EEXIST" || code === "EPERM") return false;
+		throw error;
+	}
+	try {
+		if (await readLockRecord(lockPath) !== record || !holderExited(record)) return false;
+		try {
+			await rm(lockPath, { force: true });
+		} catch (error) {
+			return false;
+		}
+		return true;
+	} finally {
+		await rm(claim, { force: true }).catch((error) => {});
+	}
+}
 /**
 * Retry cadence for a contended lock. These stay robustness invariants of the
 * cross-process write protocol rather than deployment tunables: they govern how
@@ -111,10 +169,17 @@ const DEFAULT_LOCK_WAIT_MS = 2e3;
 * contention only when a fresh `lstat` confirms the lock path exists, covering
 * 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.
+* permission error is rethrown. The lock records its holder's PID. A contender
+* removes the lock and retries at once when no process with that PID exists
+* (`ESRCH`); any other lock, including one whose holder exists under another
+* user (`EPERM`) or whose record is incomplete, is waited for. Contention backs
+* off exponentially and times out after the deadline. A holder whose PID a
+* live process reused keeps its lock until an operator removes it. Takeover
+* proves only that the recorded process exited: an operation that starts other
+* writers must stop them with it or leave its successor a way to find them.
+* PIDs are compared on the contender's host, so writers on other hosts or in
+* other PID namespaces sharing the file are unsupported and could both hold
+* the lock. 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.
 * @param options - acquisition options; omitted waits {@link DEFAULT_LOCK_WAIT_MS}.
@@ -136,7 +201,7 @@ async function withFileLock(filename, operation, options) {
 			if (!await isLockContention(error, lockPath)) {
 				if (process.platform !== "win32" || error?.code !== "EPERM" || retriedUnconfirmedPermissionError) throw error;
 				retriedUnconfirmedPermissionError = true;
-			}
+			} else if (await takeOverExitedLock(lockPath)) continue;
 		}
 		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

@@ -6,7 +6,8 @@
  * up with exactly the stated mode. `withFileLock` serializes cross-process
  * writers of one file through a `wx`-created `<file>.lock` sibling, so a
  * read-modify-write cycle can never resurrect a state another writer just
- * replaced; readers stay lock-free because the rename commit is atomic.
+ * replaced; readers stay lock-free because the rename commit is atomic. A lock
+ * whose recorded holder process no longer exists is taken over.
  * @module @deepseek-ai/dsh-atomic-write
  */
 /**
@@ -63,10 +64,17 @@ export interface FileLockOptions {
  * contention only when a fresh `lstat` confirms the lock path exists, covering
  * 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.
+ * permission error is rethrown. The lock records its holder's PID. A contender
+ * removes the lock and retries at once when no process with that PID exists
+ * (`ESRCH`); any other lock, including one whose holder exists under another
+ * user (`EPERM`) or whose record is incomplete, is waited for. Contention backs
+ * off exponentially and times out after the deadline. A holder whose PID a
+ * live process reused keeps its lock until an operator removes it. Takeover
+ * proves only that the recorded process exited: an operation that starts other
+ * writers must stop them with it or leave its successor a way to find them.
+ * PIDs are compared on the contender's host, so writers on other hosts or in
+ * other PID namespaces sharing the file are unsupported and could both hold
+ * the lock. 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.
  * @param options - acquisition options; omitted waits {@link DEFAULT_LOCK_WAIT_MS}.

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.7-rc.1",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },