@deepseek-ai/dsh-atomic-write 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# 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:
+#   pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
+README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
+README.zh.md: 570a5243aefbe6870c1991786f711adc77faacae

package/README.md

@@ -0,0 +1,45 @@
+# dsh-atomic-write
+
+English | [中文](README.zh.md)
+
+Zero-dependency atomic file replacement shared by file-backed stores that must never leave partial, symlink-hijacked, or wider-than-intended content on disk — the user-settings document (`dsh-settings-local`) and the credentials store (`dsh-credentials-local`).
+
+## Surface
+
+```ts
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+
+declare const text: string
+declare const render: (previous: string) => string
+
+await writeFileAtomic('/home/u/.dsh/settings.yaml', text, { mode: 0o600 })
+
+// Read-modify-write against the same file from several processes.
+await withFileLock('/home/u/.dsh/settings.yaml', async () => {
+  await writeFileAtomic('/home/u/.dsh/settings.yaml', render(text), { mode: 0o600 })
+})
+```
+
+`writeFileAtomic` commits one already-rendered string. The contract, in the order failures would exploit it:
+
+- **Exclusive-create temp** (`wx`, random suffix): the open refuses to follow a symlink planted at a guessable temp path.
+- **The fresh inode carries `mode` through the rename**: replacing a wider-permission file narrows it without a chmod race. `mode` is required so the permission decision stays visible at every call site (subject to the process umask, like every fresh inode).
+- **`rename` replaces a symlinked target itself**, never writing through to its referent.
+- **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.
+
+## Model Experience
+
+None, as this is a pure filesystem primitive; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; nothing here enters a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **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 can leave the sibling behind. Later writers time out without deleting it; an operator removes it only after verifying that no writer still owns it. File age alone is not safe evidence of abandonment.

package/README.zh.md

@@ -0,0 +1,45 @@
+# dsh-atomic-write
+
+[English](README.md) | 中文
+
+零依赖的原子文件替换，供绝不允许在磁盘上留下不完整、被符号链接劫持或权限过宽内容的文件型存储共用：用户设置文档（`dsh-settings-local`）与凭据存储（`dsh-credentials-local`）。
+
+## 接口面
+
+```ts
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+
+declare const text: string
+declare const render: (previous: string) => string
+
+await writeFileAtomic('/home/u/.dsh/settings.yaml', text, { mode: 0o600 })
+
+// Read-modify-write against the same file from several processes.
+await withFileLock('/home/u/.dsh/settings.yaml', async () => {
+  await writeFileAtomic('/home/u/.dsh/settings.yaml', render(text), { mode: 0o600 })
+})
+```
+
+`writeFileAtomic` 提交一份已经渲染好的字符串。约定按故障利用它的先后顺序列出：
+
+- **独占创建临时文件**（`wx` + 随机后缀）：open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
+- **全新 inode 携带 `mode` 走完 rename**：替换权限过宽的旧文件时直接收窄，不存在 chmod 竞态。`mode` 为必填，让权限决策始终可见于每个调用点（与所有新建 inode 一样受进程 umask 影响）。
+- **`rename` 替换的是符号链接目标本身**，绝不写穿到其指向的文件。
+- **同目录兄弟文件**保证 rename 落在同一文件系统上，交换保持原子。
+- 自动创建父目录；任何失败都会移除临时文件并重新抛出该失败；读取方只会观察到旧内容或完整的新内容。
+
+`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。竞争者绝不移除现有锁：锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
+
+## 模型体验
+
+无：本包是纯文件系统原语，此处没有任何内容会到达模型请求。
+
+#### KV Cache 影响
+
+无；此处没有任何内容会进入请求前缀。
+
+## 已知限制与暂缓事项
+
+- **原子但不保证持久**——不对文件或其所在目录做 `fsync`，因此崩溃后可能观察到 rename 被回退。此处的文件型存储在启动时重新读取并重新发布，把持久性留作调用方的策略。
+- **仅支持字符串内容**——在有消费方需要之前，不提供 `Buffer` 或流式形态。
+- **遗留锁需要操作者恢复**——进程持锁退出时可能留下同级锁文件。后续写入方超时也不会删除它；操作者只有在确认没有写入方仍拥有该锁后才会移除。文件存续时间本身不能安全证明它已无人持有。

package/lib/index.js

@@ -0,0 +1,97 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+//#region lib/types/index.js
+/**
+* Zero-dependency atomic file replacement and writer coordination.
+* `writeFileAtomic` writes a random-suffix sibling with exclusive create and
+* the caller's permission bits, then renames it over the target, so readers
+* observe either the old or the new complete content and a replaced file ends
+* 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.
+* @module @deepseek-ai/dsh-atomic-write
+*/
+/**
+* Replace `filename` with `content` in one atomic step, creating parent
+* directories. The content is first written to a random-suffix sibling opened
+* with exclusive create (`wx`): the open refuses to follow a symlink planted
+* at the temp path, and the fresh inode carries `options.mode` through the
+* rename, so replacing a wider-permission file narrows it without a chmod
+* race. The rename also replaces a symlinked target itself instead of writing
+* through to its referent, and the same-directory sibling keeps the rename on
+* one filesystem. On any failure the temp file is removed and the failure
+* rethrown. Crash durability (fsync) is out of scope.
+* @param filename - final path receiving the content.
+* @param content - complete next file content.
+* @param options - permission bits for the replacement inode.
+*/
+async function writeFileAtomic(filename, content, options) {
+	await mkdir(dirname(filename), {
+		recursive: true,
+		...options.dirMode === void 0 ? {} : { mode: options.dirMode }
+	});
+	const temp = `${filename}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		await writeFile(temp, content, {
+			mode: options.mode,
+			flag: "wx"
+		});
+		await rename(temp, filename);
+	} catch (error) {
+		await rm(temp, { force: true });
+		throw error;
+	}
+}
+/** Whether an exclusive create failed because the path already exists. */
+function isEEXIST(error) {
+	return error?.code === "EEXIST";
+}
+/**
+* Writer-lock protocol constants. These are robustness invariants of the
+* cross-process write protocol, not deployment tunables: contention normally
+* resolves within the retry deadline, while expiry fails the contender without
+* guessing whether the existing lock still has an owner.
+*/
+const LOCK_RETRY_INITIAL_MS = 20;
+const LOCK_RETRY_MAX_MS = 200;
+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.
+* @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.
+*/
+async function withFileLock(filename, operation) {
+	const lockPath = `${filename}.lock`;
+	const deadline = Date.now() + LOCK_TIMEOUT_MS;
+	let delay = LOCK_RETRY_INITIAL_MS;
+	for (;;) {
+		try {
+			await writeFile(lockPath, `${process.pid}\n`, {
+				mode: 384,
+				flag: "wx"
+			});
+			break;
+		} catch (error) {
+			if (!isEEXIST(error)) 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));
+		delay = Math.min(delay * 2, LOCK_RETRY_MAX_MS);
+	}
+	try {
+		return await operation();
+	} finally {
+		await rm(lockPath, { force: true });
+	}
+}
+//#endregion
+export { withFileLock, writeFileAtomic };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-atomic-write`.
+* @module @deepseek-ai/dsh-atomic-write/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-atomic-write";
+/** Cordis companion plugin name. */
+const name = "atomic-write-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this pure filesystem primitive owns no event stream or mutable runtime
+* data; its replacement contract is enforced by unit tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Zero-dependency atomic file replacement and writer coordination.
+ * `writeFileAtomic` writes a random-suffix sibling with exclusive create and
+ * the caller's permission bits, then renames it over the target, so readers
+ * observe either the old or the new complete content and a replaced file ends
+ * 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.
+ * @module @deepseek-ai/dsh-atomic-write
+ */
+/**
+ * Filesystem options for {@link writeFileAtomic}; `mode` is required so the
+ * permission decision stays visible at every call site.
+ */
+export interface WriteFileAtomicOptions {
+    /**
+     * Permission bits stamped on the fresh temp inode and carried through the
+     * rename (subject to the process umask, like every fresh inode).
+     */
+    mode: number;
+    /**
+     * Permission bits for parent directories this call creates (subject to the
+     * umask; existing directories keep their mode). Omission uses the mkdir
+     * default — pass `0o700` when the tree holds user-private data.
+     */
+    dirMode?: number;
+}
+/**
+ * Replace `filename` with `content` in one atomic step, creating parent
+ * directories. The content is first written to a random-suffix sibling opened
+ * with exclusive create (`wx`): the open refuses to follow a symlink planted
+ * at the temp path, and the fresh inode carries `options.mode` through the
+ * rename, so replacing a wider-permission file narrows it without a chmod
+ * race. The rename also replaces a symlinked target itself instead of writing
+ * through to its referent, and the same-directory sibling keeps the rename on
+ * one filesystem. On any failure the temp file is removed and the failure
+ * rethrown. Crash durability (fsync) is out of scope.
+ * @param filename - final path receiving the content.
+ * @param content - complete next file content.
+ * @param options - permission bits for the replacement inode.
+ */
+export declare function writeFileAtomic(filename: string, content: string, options: WriteFileAtomicOptions): Promise<void>;
+/**
+ * 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.
+ * @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.
+ */
+export declare function withFileLock<T>(filename: string, operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-atomic-write`.
+ * @module @deepseek-ai/dsh-atomic-write/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "atomic-write-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "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.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/atomic-write"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}