/**
 * Write `data` to `path` atomically: write a sibling temp file, fsync-free
 * rename over the destination. A concurrent reader sees either the old file or
 * the new one, never a truncated mix. `mode` (e.g. 0o600) is applied to the
 * temp file so it carries over through the rename.
 */
export declare function atomicWriteFileSync(path: string, data: string, mode?: number): void;
export interface FileLockOptions {
    /** Give up acquiring the lock after this long. Default 10s. */
    timeoutMs?: number;
    /** A lock dir older than this is presumed abandoned by a crashed process. Default 30s. */
    staleMs?: number;
}
/**
 * Run `fn` while holding an exclusive advisory lock at `lockDir`. The lock is a
 * directory: `mkdir` fails atomically if it already exists, which is the
 * cross-process mutex. Retries with capped exponential backoff up to
 * `timeoutMs`; a lock dir older than `staleMs` is treated as abandoned (its
 * owner crashed without releasing) and forcibly broken. The lock is always
 * released in `finally`, including when `fn` throws.
 */
export declare function withFileLock<T>(lockDir: string, fn: () => T, opts?: FileLockOptions): T;
/**
 * Load and parse a JSON file, guarding against corruption. Returns `fallback`
 * when the file is absent. On a parse error — or a successfully-parsed value
 * that fails `isValid` (wrong shape, e.g. an object where an array was
 * expected) — the bad file is MOVED to `<path>.corrupt-<pid>-<ts>`, a loud
 * warning is written to stderr, and `fallback` is returned. It never silently
 * resets a corrupt store to empty.
 */
export declare function loadJsonGuarded<T>(path: string, isValid: (v: unknown) => boolean, fallback: T, label?: string): T;