@worldapptechnologies/nulu-atomic-write 0.0.0-stage → 1.6.4

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

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+---
+description: "Atomic file replacement and cross-process writer locking for packages that must never leave partial, symlink-hijacked, or wider-permission content on disk."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @worldapptechnologies/nulu-atomic-write
+
+
+## Summary
+
+Use `nulu-atomic-write` to replace a file without exposing partial content or following a symlinked temporary path. Its writer lock serializes read-modify-write cycles across processes so concurrent writers cannot overwrite one another with stale state. Each replacement uses caller-selected permission bits on a fresh inode, which safely narrows an existing file's permissions. This zero-dependency library accepts strings; it does not provide a `cordis.yml` plugin or crash durability because it does not call `fsync`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use `writeFileAtomic` when a file-backed store must replace one already-rendered string without ever exposing a partial, symlink-hijacked, or wider-permission state, and `withFileLock` when several processes read-modify-write the same file. The smallest path is one call with the final content and the replacement's permission bits.
+
+### Writing a file atomically
+
+```ts
+import { writeFileAtomic } from '@worldapptechnologies/nulu-atomic-write'
+
+declare const text: string
+await writeFileAtomic('/home/u/.nulu/settings.yaml', text, { mode: 0o600 })
+```
+
+Parent directories are created as needed, and readers observe either the old or the new complete content. On Windows, transient replacement interference reported as `EACCES`, `EBUSY`, or `EPERM` is retried for a bounded interval; any remaining failure removes the temporary file and leaves the target untouched.
+
+### Coordinating writers
+
+For a read-render-commit cycle that a bare atomic commit cannot make safe on its own, hold the writer lock around the operation:
+
+```text
+import { withFileLock, writeFileAtomic } from '@worldapptechnologies/nulu-atomic-write'
+
+declare const render: (previous: string) => string
+declare const readCurrent: () => Promise<string>
+
+await withFileLock('/home/u/.nulu/settings.yaml', async () => {
+  const previous = await readCurrent()
+  await writeFileAtomic('/home/u/.nulu/settings.yaml', render(previous), { mode: 0o600 })
+})
+```
+
+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.
+
+### Failures to plan for
+
+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.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The package is built on one separation: the atomic commit owns the swap, and the writer lock owns cross-process ordering.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `writeFileAtomic` and `withFileLock`, the package's whole surface |
+| — | No runtime invariant companion is published; this pure filesystem primitive owns no event stream or mutable runtime data; its replacement contract is enforced by unit tests. |
+
+### Write path
+
+`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.
+
+### 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.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when you need the consuming stores or the family this primitive belongs to.
+
+- [User-settings file store](../../settings/settings-file/README.md) — the settings document every write replaces through this package.
+- [Credentials store](../../credentials/credentials-local/README.md) — the credentials file this package locks and replaces.
+- [util group map](../README.md) — the zero-dependency utility family this package belongs to.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this is a pure filesystem write primitive that registers nothing model-facing.
+
+#### KV Cache effect
+
+Nothing here enters a request prefix, so provider cache reuse is unaffected.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the package is not the right tool. They are current package constraints, not a task backlog.
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+A durability-replacement that `fsync`s the file and parent directory and preserves owner-only permissions on Windows remains open (tracked as `settings-atomic-durability` in source).
+
+</details>

package/lib/index.js

@@ -0,0 +1,147 @@
+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 @worldapptechnologies/nulu-atomic-write
+*/
+const WINDOWS_TRANSIENT_RENAME_ERRORS = new Set([
+	"EACCES",
+	"EBUSY",
+	"EPERM"
+]);
+const WINDOWS_RENAME_RETRY_INITIAL_MS = 20;
+const WINDOWS_RENAME_RETRY_MAX_MS = 200;
+const WINDOWS_RENAME_RETRY_LIMIT = 8;
+/** Whether Windows reported temporary interference with an atomic replacement. */
+function isTransientWindowsRenameError(error) {
+	if (process.platform !== "win32") return false;
+	return WINDOWS_TRANSIENT_RENAME_ERRORS.has(error?.code ?? "");
+}
+/** Replace the target after bounded retries for transient Windows interference. */
+async function renameAtomicTemp(temp, filename) {
+	let delay = WINDOWS_RENAME_RETRY_INITIAL_MS;
+	for (let retries = 0;; retries += 1) {
+		try {
+			await rename(temp, filename);
+			return;
+		} catch (error) {
+			if (!isTransientWindowsRenameError(error)) throw error;
+			if (retries >= WINDOWS_RENAME_RETRY_LIMIT) throw error;
+		}
+		await new Promise((resolve) => setTimeout(resolve, delay));
+		delay = Math.min(delay * 2, WINDOWS_RENAME_RETRY_MAX_MS);
+	}
+}
+/**
+* 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. Windows replacement retries transient `EACCES`, `EBUSY`,
+* and `EPERM` failures for a bounded interval while the complete temp file
+* remains the rename source. On any remaining 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 renameAtomicTemp(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;
+/**
+* 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. 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;
+	for (;;) {
+		try {
+			await writeFile(lockPath, `${process.pid}\n`, {
+				mode: 384,
+				flag: "wx"
+			});
+			break;
+		} catch (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));
+		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/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 @worldapptechnologies/nulu-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. Windows replacement retries transient `EACCES`, `EBUSY`,
+ * and `EPERM` failures for a bounded interval while the complete temp file
+ * remains the rename source. On any remaining 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. 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/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@worldapptechnologies/nulu-atomic-write",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Zero-dependency atomic file replacement: exclusive-create random-suffix temp + rename carrying the caller-stated permissions (writeFileAtomic)",
+  "version": "1.6.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/worldapptechnologies/nulu-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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@worldapptechnologies/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@worldapptechnologies/cordis": "^4.0.2"
+  }
 }