@hydraharness/harness-atomic-write 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @hydraharness/harness-atomic-write
+
+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 (`@hydraharness/harness-settings-file`) and the credentials store (`@hydraharness/harness-credentials-local`).
+
+## Surface
+
+```ts
+import { withFileLock, writeFileAtomic } from '@hydraharness/harness-atomic-write'
+
+declare const text: string
+declare const render: (previous: string) => string
+
+await writeFileAtomic('/home/u/.hydra/settings.yaml', text, { mode: 0o600 })
+
+// Read-modify-write against the same file from several processes.
+await withFileLock('/home/u/.hydra/settings.yaml', async () => {
+  await writeFileAtomic('/home/u/.hydra/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.
+- **Windows replacement retries transient `EPERM`** for a bounded interval, covering unrelated readers that are closing the target; other failures remain immediate.
+- **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. `EEXIST` identifies contention directly; `EPERM` does so when a fresh `lstat` confirms that the lock path exists, and one unconfirmed Windows `EPERM` is retried because the holder may have released the lock before that check. A contender never removes the existing lock: age cannot distinguish a crashed owner from a paused live writer.
+
+How long a contender waits is a property of the operation the holder runs, so it is stated per call through `waitMs`. The default is sized for file work alone; 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: it governs how often a contender asks, which no caller has a reason to vary.
+
+## 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/lib/index.js

@@ -0,0 +1,149 @@
+import { randomBytes } from "node:crypto";
+import { lstat, 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 @hydraharness/harness-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 renameWithRetry(temp, filename);
+	} catch (error) {
+		await rm(temp, { force: true });
+		throw error;
+	}
+}
+/** 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;
+	}
+}
+/**
+* Retry cadence for a contended lock. These stay robustness invariants of the
+* cross-process write protocol rather than deployment tunables: they govern how
+* often a contender asks, which no caller has a reason to vary.
+*/
+const LOCK_RETRY_INITIAL_MS = 20;
+const LOCK_RETRY_MAX_MS = 200;
+/**
+* Windows can briefly deny replacing a file while an unrelated reader closes
+* its handle. Keep the retry local to the publish step; the writer lock still
+* owns application-level coordination.
+*/
+const RENAME_RETRY_INITIAL_MS = 20;
+const RENAME_RETRY_MAX_MS = 200;
+const RENAME_RETRY_WAIT_MS = 2e3;
+/** Replace a file, absorbing only a transient Windows replacement denial. */
+async function renameWithRetry(source, target) {
+	const retryable = process.platform === "win32";
+	const deadline = Date.now() + RENAME_RETRY_WAIT_MS;
+	let delay = RENAME_RETRY_INITIAL_MS;
+	for (;;) {
+		try {
+			await rename(source, target);
+			return;
+		} catch (error) {
+			const code = error?.code;
+			if (!retryable || code !== "EPERM" || Date.now() >= deadline) throw error;
+		}
+		await new Promise((resolve) => setTimeout(resolve, delay));
+		delay = Math.min(delay * 2, RENAME_RETRY_MAX_MS);
+	}
+}
+/**
+* How long a contender waits when the caller states no limit — sized for the
+* render-and-rename cycle every call site had when this package was written.
+* Expiry fails the contender rather than guessing whether the existing lock
+* still has an owner. How long is *worth* waiting is a property of the
+* operation the lock holder runs, which is why {@link FileLockOptions.waitMs}
+* exists; the value here is the floor for an operation that does file work
+* alone.
+*/
+const DEFAULT_LOCK_WAIT_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. `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. One unconfirmed Windows `EPERM` gets one retry because a contender
+* can observe the lock after its owner has already released it. 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.
+* @param options - acquisition options; omitted waits {@link DEFAULT_LOCK_WAIT_MS}.
+* @returns the operation's result; the lock releases on both outcomes.
+*/
+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 unconfirmedWindowsEpermRetried = false;
+	for (;;) {
+		try {
+			await writeFile(lockPath, `${process.pid}\n`, {
+				mode: 384,
+				flag: "wx"
+			});
+			break;
+		} catch (error) {
+			if (!await isLockContention(error, lockPath)) {
+				const code = error?.code;
+				if (process.platform !== "win32" || code !== "EPERM" || unconfirmedWindowsEpermRetried) throw error;
+				unconfirmedWindowsEpermRetried = 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));
+		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 `@hydraharness/harness-atomic-write`.
+* @module @hydraharness/harness-atomic-write/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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,75 @@
+/**
+ * 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 @hydraharness/harness-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>;
+/** Options for one {@link withFileLock} acquisition. */
+export interface FileLockOptions {
+    /**
+     * Maximum time to wait for the lock, in milliseconds. State one when the
+     * holder's operation legitimately runs longer than file work — a credential
+     * mutation that refreshes a token performs a network round trip while
+     * holding the lock, and leaving the default in place would fail every other
+     * writer of the same file for the duration. Waiting is productive: a
+     * contender that acquires the lock afterwards re-reads the committed state.
+     */
+    waitMs?: number;
+}
+/**
+ * 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. `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. One unconfirmed Windows `EPERM` gets one retry because a contender
+ * can observe the lock after its owner has already released it. 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.
+ * @param options - acquisition options; omitted waits {@link DEFAULT_LOCK_WAIT_MS}.
+ * @returns the operation's result; the lock releases on both outcomes.
+ */
+export declare function withFileLock<T>(filename: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-atomic-write`.
+ * @module @hydraharness/harness-atomic-write/invariant
+ */
+import type { Context } from '@hydraharness/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": "@hydraharness/harness-atomic-write",
+  "description": "Zero-dependency atomic file replacement: exclusive-create random-suffix temp + rename carrying the caller-stated permissions (writeFileAtomic)",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-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": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}