@jini-ai/platform 0.3.0 → 0.5.0

package/dist/fs/atomic-write.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { defaultPlatformMessages } from "../messages.js";
+/** Optional adapter wiring: no layout, env key, or application name is selected here. */
+export function createNodeAtomicFilesystem(_required, { filesystem = fs } = {}) {
+    return {
+        stat: ({ path }) => filesystem.statSync(path),
+        lstat: ({ path }) => filesystem.lstatSync(path),
+        open: ({ path, flags, mode }) => filesystem.openSync(path, flags, mode),
+        write: ({ descriptor, content }) => filesystem.writeFileSync(descriptor, content),
+        sync: ({ descriptor }) => filesystem.fsyncSync(descriptor),
+        close: ({ descriptor }) => filesystem.closeSync(descriptor),
+        chmod: ({ path, mode }) => filesystem.chmodSync(path, mode),
+        rename: ({ from, to }) => filesystem.renameSync(from, to),
+        remove: ({ path }) => filesystem.rmSync(path, { force: true }),
+    };
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function validateMode(mode, options) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o777)
+        throw new RangeError((options.messages ?? defaultPlatformMessages).atomicModeInvalid());
+    return mode;
+}
+function temporaryPath({ filePath }, options) {
+    const { tempName = () => `${process.pid}.${randomUUID()}` } = options;
+    if (options.tempPath) {
+        const temporary = options.tempPath({ filePath });
+        if (path.resolve(path.dirname(temporary)) !== path.resolve(path.dirname(filePath)) || path.resolve(temporary) === path.resolve(filePath) || temporary.includes("\0"))
+            throw new RangeError((options.messages ?? defaultPlatformMessages).atomicTempPathInvalid());
+        return temporary;
+    }
+    const token = tempName({ filePath });
+    if (!token || token === "." || token === ".." || /[/\\\x00]/.test(token))
+        throw new RangeError((options.messages ?? defaultPlatformMessages).atomicTempNameInvalid());
+    return path.join(path.dirname(filePath), `.${path.basename(filePath)}.${token}.tmp`);
+}
+function assertNotSymlink(info, options) {
+    if (info.isSymbolicLink())
+        throw new Error((options.messages ?? defaultPlatformMessages).atomicSymlinkRefused());
+}
+function assertOwnerOnly(mode, options) {
+    // Windows has no POSIX group/other bits; secret stores skip this verification there.
+    if (options.verifyOwnerOnly && (options.platform ?? process.platform) !== "win32" && (mode & 0o077) !== 0)
+        throw new Error((options.messages ?? defaultPlatformMessages).atomicPermissionsRefused());
+}
+/** Same-directory rename; preserve existing mode exactly, default new files to 0600.
+ * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
+ * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
+ * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+ */
+export function writeFileAtomic(required, options = {}) {
+    const { filePath, content, fs: filesystem } = required;
+    let existingMode;
+    try {
+        if (options.refuseSymlink) {
+            const info = filesystem.lstat({ path: filePath });
+            assertNotSymlink(info, options);
+            existingMode = info.mode & 0o777;
+        }
+        else {
+            existingMode = filesystem.stat({ path: filePath }).mode & 0o777;
+        }
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const mode = validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+    const temporary = temporaryPath(required, options);
+    // A failed exclusive create does not grant ownership of an existing temporary file.
+    let descriptor = filesystem.open({ path: temporary, flags: "wx", mode });
+    let renamed = false;
+    try {
+        filesystem.write({ descriptor, content });
+        filesystem.chmod({ path: temporary, mode });
+        assertOwnerOnly(filesystem.stat({ path: temporary }).mode, options);
+        filesystem.sync({ descriptor });
+        const fileDescriptor = descriptor;
+        descriptor = undefined;
+        filesystem.close({ descriptor: fileDescriptor });
+        if (options.refuseSymlink) {
+            try {
+                assertNotSymlink(filesystem.lstat({ path: filePath }), options);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        filesystem.rename({ from: temporary, to: filePath });
+        renamed = true;
+        const directory = filesystem.open({ path: path.dirname(filePath), flags: "r" });
+        try {
+            filesystem.sync({ descriptor: directory });
+        }
+        finally {
+            filesystem.close({ descriptor: directory });
+        }
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                filesystem.close({ descriptor });
+            }
+            catch { /* preserve the original failure */ }
+        }
+        if (!renamed) {
+            try {
+                filesystem.remove({ path: temporary });
+            }
+            catch { /* preserve the original failure */ }
+        }
+        throw error;
+    }
+}
+/** Pretty JSON delegates to the same mode-preserving atomic primitive. */
+export function writeJsonFileAtomic(required, options = {}) {
+    const { data, ...writer } = required;
+    const content = JSON.stringify(data, null, 2);
+    if (content === undefined)
+        throw new TypeError((options.messages ?? defaultPlatformMessages).atomicJsonUnserializable());
+    writeFileAtomic({ ...writer, content }, options);
+}
+/** Async counterpart with the same ownership, permission and durability guarantees.
+ * Parent creation supports runtime-state and secret stores without another writer implementation. */
+export async function writeFileAtomicAsync(required, options = {}) {
+    const { filePath, content } = required;
+    const filesystem = options.fs ?? fsPromises;
+    if (options.createParent)
+        await filesystem.mkdir(path.dirname(filePath), { recursive: true });
+    let existingMode;
+    try {
+        const info = options.refuseSymlink ? await filesystem.lstat(filePath) : await filesystem.stat(filePath);
+        if (options.refuseSymlink)
+            assertNotSymlink(info, options);
+        existingMode = info.mode & 0o777;
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const mode = validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+    const temporary = temporaryPath(required, options);
+    // Keep the exclusive create outside cleanup: EEXIST belongs to a different writer.
+    const handle = await filesystem.open(temporary, "wx", mode);
+    let closed = false, renamed = false;
+    try {
+        await handle.writeFile(content, "utf8");
+        await handle.chmod(mode);
+        assertOwnerOnly((await handle.stat()).mode, options);
+        await handle.sync();
+        await handle.close();
+        closed = true;
+        if (options.refuseSymlink) {
+            try {
+                assertNotSymlink(await filesystem.lstat(filePath), options);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        await filesystem.rename(temporary, filePath);
+        renamed = true;
+        const directory = await filesystem.open(path.dirname(filePath), "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    catch (error) {
+        if (!closed) {
+            try {
+                await handle.close();
+            }
+            catch { /* preserve the original failure */ }
+        }
+        if (!renamed) {
+            try {
+                await filesystem.rm(temporary, { force: true });
+            }
+            catch { /* preserve the original failure */ }
+        }
+        throw error;
+    }
+}
+/** Pretty JSON can retain a state-store's trailing newline without changing its serialization. */
+export async function writeJsonFileAtomicAsync(required, options = {}) {
+    const { data, ...writer } = required;
+    const content = JSON.stringify(data, null, 2);
+    if (content === undefined)
+        throw new TypeError((options.messages ?? defaultPlatformMessages).atomicJsonUnserializable());
+    await writeFileAtomicAsync({ ...writer, content: content + (options.trailingNewline ? "\n" : "") }, options);
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/fs/durable-json.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 type { Clock } from "@jini-ai/core/primitives";
+export type JsonFileRead = {
+    state: "ok";
+    value: unknown;
+} | {
+    state: "missing";
+} | {
+    state: "unreadable";
+    text?: string;
+};
+export interface QuarantineNotice {
+    label: string;
+    consequence: string;
+}
+export interface FileLockOptions {
+    waitMs?: number;
+}
+export interface DurableJsonPorts {
+    filesystem: Pick<typeof nodeFs, "readFileSync" | "mkdirSync" | "openSync" | "writeFileSync" | "fsyncSync" | "closeSync" | "renameSync" | "rmSync" | "writeSync" | "statSync" | "fstatSync" | "lstatSync" | "chmodSync">;
+    clock: Clock;
+    sleep: {
+        sleep(required: {
+            durationMs: number;
+        }): void;
+    };
+    process: {
+        pid: number;
+        isAlive(required: {
+            pid: number;
+        }): boolean;
+    };
+    random: {
+        token(_required: Record<string, never>): string;
+    };
+    report: {
+        error(required: {
+            message: string;
+        }): void;
+    };
+}
+export interface DurableJsonNotices {
+    prefix: string;
+    lockTimeout(required: {
+        lockPath: string;
+        waitMs: number;
+    }): string;
+}
+/** Native synchronous adapters. Liveness probes treat permission errors as alive. */
+export declare function createNodeDurableJsonPorts(_required: Record<string, never>): DurableJsonPorts;
+export interface DurableJsonFile {
+    read(required: Record<string, never>): JsonFileRead;
+    tempPath(required: Record<string, never>, optional?: {
+        pid?: number;
+    }): string;
+    write(required: {
+        value: unknown;
+    }): void;
+    quarantine(required: {
+        notice: QuarantineNotice;
+    }): boolean;
+    withLock<T>(required: {
+        critical: () => T;
+    }, optional?: FileLockOptions): T;
+}
+/** 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 declare function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }: DurableJsonPorts & {
+    filePath: string;
+    notices: DurableJsonNotices;
+}, { pollMs, staleMs }?: {
+    pollMs?: number;
+    staleMs?: number;
+}): DurableJsonFile;
+export declare function salvageJsonPrefix({ text }: {
+    text: string;
+}, { maxAttempts }?: {
+    maxAttempts?: number;
+}): unknown;
+//# sourceMappingURL=durable-json.d.ts.map

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