@jini-ai/platform 0.1.2 → 0.5.0

package/dist/fs/durable-json.js

@@ -0,0 +1,166 @@
+/**
+ * Shared stores once wrote JSON directly, treated torn reads as empty, then persisted the empty
+ * state on the next write, erasing recoverable records. One mechanism keeps stores from drifting:
+ * atomic replacement, explicit unreadable state, quarantine, and locks for shared read-modify-write.
+ * Recovery policy stays with each store: salvage, restart, or leave untouched is not decided here.
+ * Native effects are Electron-free so desktop, CLI, and bridge processes can share the mechanism.
+ */
+import nodeFs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { createNodeAtomicFilesystem, writeJsonFileAtomic } from "./atomic-write.js";
+import { withFileLockSync } from "./file-lock.js";
+/** Native synchronous adapters. Liveness probes treat permission errors as alive. */
+export function createNodeDurableJsonPorts(_required) {
+    const cell = new Int32Array(new SharedArrayBuffer(4));
+    return {
+        filesystem: nodeFs,
+        clock: { nowMs: () => Date.now() },
+        // Synchronous store/IPC writers cannot await lock polling without changing all callers' ABI.
+        sleep: { sleep: ({ durationMs }) => { Atomics.wait(cell, 0, 0, durationMs); } },
+        process: { pid: process.pid, isAlive: ({ pid }) => {
+                // Signal zero sends nothing. Only ESRCH proves death; permission failure must count as alive
+                // because a false "dead" authorizes breaking a lock still owned by another process.
+                try {
+                    process.kill(pid, 0);
+                    return true;
+                }
+                catch (error) {
+                    return error.code !== "ESRCH";
+                }
+            } },
+        random: { token: (_required) => randomBytes(4).toString("hex") },
+        report: { error: ({ message }) => console.error(message) },
+    };
+}
+/** Atomic replacement, distinct corrupt reads, quarantine, and token-owned synchronous locks.
+ * Lock stealing rechecks inode, bytes and mtime; conditional unlink is not available on all hosts.
+ * File fsync precedes rename; directory fsync follows it. Persistence remains filesystem-dependent.
+ */
+export function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }, { pollMs = 10, staleMs = 30000 } = {}) {
+    if (!filePath)
+        throw new TypeError("filePath is required");
+    for (const value of [pollMs, staleMs])
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new TypeError("lock intervals must be positive safe integers");
+    // A synchronous read-modify-write normally takes milliseconds; five seconds allows contention
+    // while refusing a wedged change. Short ten-millisecond polling fits those short critical sections.
+    // Thirty-second staleness also handles pid reuse after a crash:
+    // an unrelated live process must not hold the abandoned file forever merely by inheriting its pid.
+    const LOCK_WAIT_MS = 5000, LOCK_POLL_MS = pollMs, LOCK_STALE_MS = staleMs;
+    function readJsonFile(filePath) {
+        let text;
+        try {
+            text = fs.readFileSync(filePath, "utf8");
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? { state: "missing" } : { state: "unreadable" };
+        }
+        try {
+            return { state: "ok", value: JSON.parse(text) };
+        }
+        catch {
+            return { state: "unreadable", text };
+        }
+    }
+    // Per-process sibling temps prevent one writer truncating another's pending replacement. Writes
+    // within one process are synchronous, so it cannot collide with itself; its next write reuses the temp.
+    function tempPathFor(filePath, pid = process.pid) {
+        return `${filePath}.${pid}.tmp`;
+    }
+    // Same-directory rename gives readers complete old/new versions rather than a torn intermediate.
+    // Flush bytes before rename so metadata cannot precede content. The canonical writer also syncs
+    // the parent directory; platform/filesystem support determines persistence after that sync.
+    // Keep the legacy temp path, pretty JSON bytes and new-file create mode for these shared stores.
+    function writeJson(filePath, value) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        writeJsonFileAtomic({ filePath, data: value, fs: createNodeAtomicFilesystem({}, { filesystem: fs }) }, {
+            defaultMode: 0o666 & ~globalThis.process.umask(), tempPath: () => tempPathFor(filePath),
+        });
+    }
+    // Preserve damaged bytes for inspection instead of deleting/overwriting them. False means callers
+    // must leave the original alone; an already-moved file is safe because another process cleared it.
+    function quarantineUnreadableFile(filePath, notice) {
+        const asidePath = `${filePath}.corrupt-${clock.nowMs()}`;
+        try {
+            fs.renameSync(filePath, asidePath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return true;
+            report.error({ message: `${notices.prefix}: ${notice.label} ${filePath} is unreadable and could not be moved aside (${String(error)}). Left untouched; nothing was written over it.` });
+            return false;
+        }
+        report.error({ message: `${notices.prefix}: ${notice.label} ${filePath} was unreadable (torn or corrupt). Moved it aside to ${asidePath}; ${notice.consequence}` });
+        return true;
+    }
+    // Atomic replacement prevents tears; this lock serializes shared read-modify-write operations.
+    // Deliberately non-reentrant. Token-owned release must not evict a later owner after a stale break.
+    // The canonical lock rechecks the inode at steal time; its documented check-to-unlink race remains.
+    return {
+        read: (_required) => readJsonFile(filePath),
+        tempPath: (_required, { pid = process.pid } = {}) => tempPathFor(filePath, pid),
+        write: ({ value }) => writeJson(filePath, value),
+        quarantine: ({ notice }) => quarantineUnreadableFile(filePath, notice),
+        withLock: ({ critical }, optional = {}) => {
+            if (optional.waitMs !== undefined && (!Number.isSafeInteger(optional.waitMs) || optional.waitMs < 0))
+                throw new TypeError("waitMs must be a nonnegative safe integer");
+            return withFileLockSync({ lockPath: `${filePath}.lock`, run: critical }, {
+                timeoutMs: optional.waitMs ?? LOCK_WAIT_MS, staleMs: LOCK_STALE_MS, pollMs: LOCK_POLL_MS,
+                filesystem: fs, clock, sleep: ({ durationMs }) => sleep.sleep({ durationMs }), process,
+                token: () => random.token({}), format: "token", createParent: true,
+                timeoutMessage: notices.lockTimeout, suppressReleaseErrors: true,
+            });
+        },
+    };
+}
+// Bound recovery to the latest 1,000 parse attempts by default, rather than parsing once per quoted
+// character in a large damaged file. Stores must validate recovered values normally: partial objects
+// are not trustworthy merely because their brackets can be closed into syntactically valid JSON.
+export function salvageJsonPrefix({ text }, { maxAttempts = 1000 } = {}) {
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts <= 0)
+        throw new TypeError("maxAttempts must be a positive safe integer");
+    const cuts = elementEnds(text);
+    const floor = Math.max(0, cuts.length - maxAttempts);
+    for (let index = cuts.length - 1; index >= floor; index -= 1) {
+        const cut = cuts[index];
+        try {
+            return JSON.parse(text.slice(0, cut.end) + cut.closers);
+        }
+        catch {
+            // A cut after an object key cannot close validly; try an earlier completed value.
+        }
+    }
+    return undefined;
+}
+// Cut only at completed strings/objects/arrays, sufficient for string-valued lists. Damage inside a
+// bare number/boolean falls back to the previous cut and loses that element rather than guessing it.
+function elementEnds(text) {
+    const open = [];
+    const cuts = [];
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '"')
+            index = endOfString(text, index);
+        else if (char === "{" || char === "[") {
+            open.push(char === "{" ? "}" : "]");
+            continue;
+        }
+        else if (char === "}" || char === "]")
+            open.pop();
+        else
+            continue;
+        cuts.push({ end: index + 1, closers: [...open].reverse().join("") });
+    }
+    return cuts;
+}
+function endOfString(text, start) {
+    for (let index = start + 1; index < text.length; index += 1) {
+        if (text[index] === "\\")
+            index += 1;
+        else if (text[index] === '"')
+            return index;
+    }
+    return text.length;
+}
+//# sourceMappingURL=durable-json.js.map

package/dist/fs/env-text.d.ts

@@ -0,0 +1,11 @@
+/** Narrow env-text transforms: first exact KEY= match, preserve unrelated lines, one final newline. */
+export declare function upsertEnvLine({ source, key, value }: {
+    source: string;
+    key: string;
+    value: string;
+}): string;
+export declare function readEnvLine({ source, key }: {
+    source: string;
+    key: string;
+}): string | null;
+//# sourceMappingURL=env-text.d.ts.map

package/dist/fs/env-text.js

@@ -0,0 +1,22 @@
+/** Narrow env-text transforms: first exact KEY= match, preserve unrelated lines, one final newline. */
+export function upsertEnvLine({ source, key, value }) {
+    const lines = source.length === 0 ? [] : source.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    const prefix = `${key}=`;
+    const index = lines.findIndex((line) => line.startsWith(prefix));
+    const newLine = `${prefix}${value}`;
+    if (index === -1) {
+        lines.push(newLine);
+    }
+    else {
+        lines[index] = newLine;
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function readEnvLine({ source, key }) {
+    const prefix = `${key}=`;
+    const match = source.split("\n").find((line) => line.startsWith(prefix));
+    return match === undefined ? null : match.slice(prefix.length).trim();
+}
+//# sourceMappingURL=env-text.js.map

package/dist/fs/file-lock.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Atomic writes prevent tears but not lost updates between shared read-modify-writes. Plain readers
+ * need no lock. Deliberately non-reentrant: nesting times out rather than silently sharing an
+ * exclusive section; compose store operations from unlocked internals instead.
+ * Kernel exclusive create chooses the winner. A unique token AND inode identify that owner;
+ * pid alone cannot distinguish a later owner after a stale break. Signal-zero liveness probes
+ * treat only ESRCH as death: permission failure must never authorize evicting a live process.
+ * Stale removal rechecks inode, bytes and mtime immediately before unlink. There is still a residual
+ * check-to-unlink race on filesystems without conditional unlink; rename/restore chains create wider
+ * multi-process races and are deliberately avoided. Atomic file replacement independently prevents
+ * torn content. Hosts whose operations can legitimately exceed the stale budget use staleMs: Infinity.
+ */
+import fs from "node:fs";
+import * as asyncFs from "node:fs/promises";
+import { type Clock } from "@jini-ai/core/primitives";
+import { type PlatformMessages } from "../messages.js";
+export declare const DEFAULT_LOCK_TIMEOUT_MS = 15000;
+export declare const DEFAULT_LOCK_STALE_AFTER_MS = 10000;
+export interface FileLockHolder {
+    readonly pid: number;
+    readonly hostname: string;
+    readonly token: string;
+    readonly acquiredAt: string;
+}
+export interface HeldFileLock {
+    readonly lockPath: string;
+    assertHeld(required: Record<string, never>): Promise<void>;
+}
+export interface HeldFileLockSync {
+    readonly lockPath: string;
+    assertHeld(required: Record<string, never>): void;
+}
+export type FileLockSyncFilesystem = Pick<typeof fs, "mkdirSync" | "openSync" | "writeSync" | "fstatSync" | "readFileSync" | "statSync" | "closeSync" | "rmSync">;
+export type FileLockAsyncFilesystem = Pick<typeof asyncFs, "mkdir" | "open" | "stat" | "rm">;
+export interface FileLockOptions {
+    timeoutMs?: number;
+    /** Infinity disables age stealing; dead local owners remain reclaimable. */
+    staleMs?: number;
+    pollMs?: number;
+    clock?: Clock;
+    /** Times the wait budget (start and timeout check). Defaults to `clock.nowMs`; hosts with a
+     * monotonic source pass it so a wall-clock jump can neither end nor stretch the wait. Stale age
+     * stays on `clock.nowMs`, because lock-file mtimes are wall-clock times. */
+    monotonicMs?: () => number;
+    sleep?: (required: {
+        durationMs: number;
+    }) => void | Promise<void>;
+    process?: {
+        pid: number;
+        isAlive(required: {
+            pid: number;
+        }): boolean;
+    };
+    token?: () => string;
+    hostname?: () => string;
+    onStaleLockRemoved?: (required: {
+        holder: FileLockHolder | undefined;
+    }) => void;
+    createParent?: boolean;
+    format?: "json" | "token";
+    /** Host stores keep their existing user-facing timeout copy. */
+    timeoutMessage?: (required: {
+        lockPath: string;
+        waitMs: number;
+    }) => string;
+    messages?: PlatformMessages;
+    /** Durable stores historically ignored release failures to avoid masking their critical section. */
+    suppressReleaseErrors?: boolean;
+}
+export declare class FileLockTimeoutError extends Error {
+    readonly lockPath: string;
+    readonly holder: FileLockHolder | undefined;
+    readonly waitedMs: number;
+    constructor(required: {
+        lockPath: string;
+        holder: FileLockHolder | undefined;
+        waitedMs: number;
+    }, optional?: {
+        message?: string;
+        messages?: PlatformMessages;
+    });
+}
+export declare class FileLockLostError extends Error {
+    readonly lockPath: string;
+    constructor({ lockPath }: {
+        lockPath: string;
+    }, { messages }?: {
+        messages?: PlatformMessages;
+    });
+}
+/** Platform-specific contention classification retains the Windows exclusive-open behavior. */
+export declare function isContendedLockError({ code, platform }: {
+    code: string | undefined;
+    platform: NodeJS.Platform;
+}): boolean;
+/** One pure stale decision serves both I/O adapters. Invalid/foreign pids have unknown liveness,
+ * never false liveness; otherwise kill(0/negative, 0) would address a process group. */
+export declare function isLockStale(required: {
+    nowMs: number;
+    mtimeMs: number;
+    staleMs: number;
+    ownerAlive: boolean | undefined;
+    observedInode: number;
+    currentInode: number;
+    observedDevice: number;
+    currentDevice: number;
+}): boolean;
+/** Synchronous read-modify-write guard. Durable stores pass their former 5s/30s/10ms values.
+ * Release never evicts a later owner, even when the old owner reaches finally after a steal. */
+export declare function withFileLockSync<T>({ lockPath, run }: {
+    lockPath: string;
+    run: (lock: HeldFileLockSync) => T;
+}, options?: Omit<FileLockOptions, "sleep"> & {
+    sleep?: (required: {
+        durationMs: number;
+    }) => void;
+    filesystem?: FileLockSyncFilesystem;
+}): T;
+/** Async adapter of the same stale and ownership policy; polling yields to other writers. */
+export declare function withFileLock<T>({ lockPath, run }: {
+    lockPath: string;
+    run: (lock: HeldFileLock) => Promise<T> | T;
+}, options?: FileLockOptions & {
+    filesystem?: FileLockAsyncFilesystem;
+}): Promise<T>;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/fs/file-lock.js

@@ -0,0 +1,306 @@
+/**
+ * Atomic writes prevent tears but not lost updates between shared read-modify-writes. Plain readers
+ * need no lock. Deliberately non-reentrant: nesting times out rather than silently sharing an
+ * exclusive section; compose store operations from unlocked internals instead.
+ * Kernel exclusive create chooses the winner. A unique token AND inode identify that owner;
+ * pid alone cannot distinguish a later owner after a stale break. Signal-zero liveness probes
+ * treat only ESRCH as death: permission failure must never authorize evicting a live process.
+ * Stale removal rechecks inode, bytes and mtime immediately before unlink. There is still a residual
+ * check-to-unlink race on filesystems without conditional unlink; rename/restore chains create wider
+ * multi-process races and are deliberately avoided. Atomic file replacement independently prevents
+ * torn content. Hosts whose operations can legitimately exceed the stale budget use staleMs: Infinity.
+ */
+import fs from "node:fs";
+import * as asyncFs from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { hostname as nodeHostname } from "node:os";
+import path from "node:path";
+import { createSystemClock } from "@jini-ai/core/primitives";
+import { defaultPlatformMessages } from "../messages.js";
+export const DEFAULT_LOCK_TIMEOUT_MS = 15_000;
+export const DEFAULT_LOCK_STALE_AFTER_MS = 10_000;
+export class FileLockTimeoutError extends Error {
+    lockPath;
+    holder;
+    waitedMs;
+    constructor(required, optional = {}) {
+        super(optional.message ?? (optional.messages ?? defaultPlatformMessages).fileLockTimeout({ waitedMs: required.waitedMs }));
+        this.name = "FileLockTimeoutError";
+        this.lockPath = required.lockPath;
+        this.holder = required.holder;
+        this.waitedMs = required.waitedMs;
+    }
+}
+export class FileLockLostError extends Error {
+    lockPath;
+    constructor({ lockPath }, { messages = defaultPlatformMessages } = {}) {
+        super(messages.fileLockLost());
+        this.name = "FileLockLostError";
+        this.lockPath = lockPath;
+    }
+}
+/** Platform-specific contention classification retains the Windows exclusive-open behavior. */
+export function isContendedLockError({ code, platform }) {
+    return code === "EEXIST" || (code === "EPERM" && platform === "win32");
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+function validPid(pid) { return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0; }
+function parseHolder(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== "object" || value === null || !("pid" in value) || !validPid(value.pid) || !("hostname" in value) || typeof value.hostname !== "string" || !("token" in value) || typeof value.token !== "string" || !("acquiredAt" in value) || typeof value.acquiredAt !== "string")
+            return undefined;
+        return { pid: value.pid, hostname: value.hostname, token: value.token, acquiredAt: value.acquiredAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One pure stale decision serves both I/O adapters. Invalid/foreign pids have unknown liveness,
+ * never false liveness; otherwise kill(0/negative, 0) would address a process group. */
+export function isLockStale(required) {
+    return (required.ownerAlive === false || required.nowMs - required.mtimeMs > required.staleMs) && required.observedInode === required.currentInode && required.observedDevice === required.currentDevice;
+}
+function settings(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_AFTER_MS, pollMs = options.pollMs ?? 10;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || (!Number.isSafeInteger(staleMs) && staleMs !== Infinity) || staleMs <= 0 || !Number.isSafeInteger(pollMs) || pollMs <= 0)
+        throw new RangeError((options.messages ?? defaultPlatformMessages).fileLockIntervalsInvalid());
+    const processPort = options.process ?? { pid: process.pid, isAlive: ({ pid }) => { try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return errorCode(error) !== "ESRCH";
+        } } };
+    const clock = options.clock ?? createSystemClock();
+    const monotonicMs = options.monotonicMs ?? (() => clock.nowMs());
+    return { timeoutMs, staleMs, pollMs, processPort, clock, monotonicMs, hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
+}
+function ownership(s, options) {
+    return options.format === "token" ? `${s.processPort.pid}:${s.token}` : JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString() });
+}
+function ownerAlive(snapshot, s) {
+    const holder = snapshot.holder;
+    if (holder)
+        return holder.hostname === s.hostname ? s.processPort.isAlive({ pid: holder.pid }) : undefined;
+    // Legacy synchronous stores wrote pid:random rather than JSON. Malformed pids remain unknown.
+    if (!/^\d+:/.test(snapshot.raw))
+        return undefined;
+    const pid = Number(snapshot.raw.split(":", 1)[0]);
+    return validPid(pid) ? s.processPort.isAlive({ pid }) : undefined;
+}
+function unchanged(a, b) { return a.ino === b.ino && a.dev === b.dev && a.raw === b.raw && a.mtimeMs === b.mtimeMs; }
+function stale(observed, current, s) {
+    return unchanged(observed, current) && isLockStale({ nowMs: s.clock.nowMs(), mtimeMs: observed.mtimeMs, staleMs: s.staleMs, ownerAlive: ownerAlive(current, s), observedInode: observed.ino, currentInode: current.ino, observedDevice: observed.dev, currentDevice: current.dev });
+}
+function checkTimeout(lockPath, holder, start, s, options) {
+    const waitedMs = s.monotonicMs() - start;
+    if (waitedMs >= s.timeoutMs) {
+        const message = options.timeoutMessage?.({ lockPath, waitMs: s.timeoutMs });
+        throw new FileLockTimeoutError({ lockPath, holder, waitedMs }, { ...(options.messages ? { messages: options.messages } : {}), ...(message !== undefined ? { message } : {}) });
+    }
+}
+function inspectSync(lockPath, filesystem) {
+    let descriptor;
+    try {
+        descriptor = filesystem.openSync(lockPath, "r");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT" || isContendedLockError({ code: errorCode(error), platform: process.platform }))
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = filesystem.fstatSync(descriptor), raw = filesystem.readFileSync(descriptor, "utf8");
+        return { raw, holder: parseHolder(raw), mtimeMs: info.mtimeMs, ino: info.ino, dev: info.dev };
+    }
+    finally {
+        filesystem.closeSync(descriptor);
+    }
+}
+async function inspectAsync(lockPath, filesystem) {
+    let handle;
+    try {
+        handle = await filesystem.open(lockPath, "r");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT" || isContendedLockError({ code: errorCode(error), platform: process.platform }))
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = await handle.stat(), raw = await handle.readFile("utf8");
+        return { raw, holder: parseHolder(raw), mtimeMs: info.mtimeMs, ino: info.ino, dev: info.dev };
+    }
+    finally {
+        await handle.close();
+    }
+}
+const waitCell = new Int32Array(new SharedArrayBuffer(4));
+/** Synchronous read-modify-write guard. Durable stores pass their former 5s/30s/10ms values.
+ * Release never evicts a later owner, even when the old owner reaches finally after a steal. */
+export function withFileLockSync({ lockPath, run }, options = {}) {
+    const filesystem = options.filesystem ?? fs, s = settings(options), start = s.monotonicMs(), raw = ownership(s, options);
+    if (options.createParent)
+        filesystem.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    let identity;
+    for (;;) {
+        let descriptor;
+        try {
+            descriptor = filesystem.openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
+                throw error;
+        }
+        if (descriptor !== undefined) {
+            try {
+                identity = filesystem.fstatSync(descriptor);
+                // An unidentifiable lock would wedge writers until stale timeout; clean a failed creation
+                // only while its inode still matches, rather than deleting a replacement owner.
+                const bytes = Buffer.from(raw);
+                let offset = 0;
+                while (offset < bytes.length) {
+                    const written = filesystem.writeSync(descriptor, bytes, offset, bytes.length - offset);
+                    if (written === 0)
+                        throw new Error((options.messages ?? defaultPlatformMessages).fileLockWriteNoProgress());
+                    offset += written;
+                }
+            }
+            catch (error) {
+                try {
+                    const created = filesystem.fstatSync(descriptor), current = filesystem.statSync(lockPath);
+                    if (created.ino === current.ino && created.dev === current.dev)
+                        filesystem.rmSync(lockPath, { force: true });
+                }
+                catch { /* preserve creation failure */ }
+                throw error;
+            }
+            finally {
+                filesystem.closeSync(descriptor);
+            }
+            break;
+        }
+        const observed = inspectSync(lockPath, filesystem);
+        if (observed) {
+            const current = inspectSync(lockPath, filesystem);
+            if (current && stale(observed, current, s)) {
+                const last = filesystem.statSync(lockPath, { throwIfNoEntry: false });
+                if (last && last.ino === current.ino && last.dev === current.dev && last.mtimeMs === current.mtimeMs) {
+                    try {
+                        filesystem.rmSync(lockPath, { force: true });
+                        options.onStaleLockRemoved?.({ holder: current.holder });
+                    }
+                    catch (error) {
+                        if (errorCode(error) !== "ENOENT")
+                            throw error;
+                    }
+                }
+            }
+        }
+        // Every contention path, including repeated stale breaks and release races, is bounded.
+        checkTimeout(lockPath, observed?.holder, start, s, options);
+        (options.sleep ?? (({ durationMs }) => { Atomics.wait(waitCell, 0, 0, durationMs); }))({ durationMs: s.pollMs });
+    }
+    const held = () => { const current = inspectSync(lockPath, filesystem); return current && current.raw === raw && current.ino === identity.ino && current.dev === identity.dev; };
+    let completed = false;
+    try {
+        const value = run({ lockPath, assertHeld: (_required) => { if (!held())
+                throw new FileLockLostError({ lockPath }, options.messages ? { messages: options.messages } : {}); } });
+        completed = true;
+        return value;
+    }
+    finally {
+        try {
+            if (held())
+                filesystem.rmSync(lockPath, { force: true });
+        }
+        // A failed critical section keeps its original error; durable hosts also suppress release-only failures.
+        catch (error) {
+            if (completed && !options.suppressReleaseErrors && errorCode(error) !== "ENOENT")
+                throw error;
+        }
+    }
+}
+/** Async adapter of the same stale and ownership policy; polling yields to other writers. */
+export async function withFileLock({ lockPath, run }, options = {}) {
+    const filesystem = options.filesystem ?? asyncFs, s = settings(options), start = s.monotonicMs(), raw = ownership(s, options);
+    if (options.createParent)
+        await filesystem.mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    let identity;
+    for (;;) {
+        let handle;
+        try {
+            handle = await filesystem.open(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
+                throw error;
+        }
+        if (handle) {
+            try {
+                identity = await handle.stat();
+                await handle.writeFile(raw, "utf8");
+            }
+            catch (error) {
+                try {
+                    const created = await handle.stat(), current = await inspectAsync(lockPath, filesystem);
+                    if (current && created.ino === current.ino && created.dev === current.dev)
+                        await filesystem.rm(lockPath, { force: true });
+                }
+                catch { /* preserve creation failure */ }
+                throw error;
+            }
+            finally {
+                await handle.close();
+            }
+            break;
+        }
+        const observed = await inspectAsync(lockPath, filesystem);
+        if (observed) {
+            const current = await inspectAsync(lockPath, filesystem);
+            if (current && stale(observed, current, s)) {
+                const last = await inspectAsync(lockPath, filesystem);
+                if (last && unchanged(current, last)) {
+                    // Reading a descriptor pins an inode, not the pathname. Re-stat the pathname after the
+                    // final descriptor closes, so replacement during awaited inspection cannot be stolen.
+                    try {
+                        const atPath = await filesystem.stat(lockPath);
+                        if (atPath.ino === last.ino && atPath.dev === last.dev && atPath.mtimeMs === last.mtimeMs) {
+                            await filesystem.rm(lockPath, { force: true });
+                            options.onStaleLockRemoved?.({ holder: current.holder });
+                        }
+                    }
+                    catch (error) {
+                        if (errorCode(error) !== "ENOENT")
+                            throw error;
+                    }
+                }
+            }
+        }
+        checkTimeout(lockPath, observed?.holder, start, s, options);
+        await (options.sleep ?? (({ durationMs }) => new Promise(resolve => setTimeout(resolve, durationMs))))({ durationMs: s.pollMs });
+    }
+    const held = async () => { const current = await inspectAsync(lockPath, filesystem); return current && current.raw === raw && current.ino === identity.ino && current.dev === identity.dev; };
+    let completed = false;
+    try {
+        const value = await run({ lockPath, assertHeld: async (_required) => { if (!await held())
+                throw new FileLockLostError({ lockPath }, options.messages ? { messages: options.messages } : {}); } });
+        completed = true;
+        return value;
+    }
+    finally {
+        try {
+            if (await held())
+                await filesystem.rm(lockPath, { force: true });
+        }
+        // A failed critical section keeps its original error; durable hosts also suppress release-only failures.
+        catch (error) {
+            if (completed && !options.suppressReleaseErrors && errorCode(error) !== "ENOENT")
+                throw error;
+        }
+    }
+}
+//# sourceMappingURL=file-lock.js.map