import { fstatSync } from "node:fs";
export type OpenRegularFileFailureReason = "missing" | "exists" | "symlink" | "symlink-ancestor" | "not-regular" | "hardlink" | "outside-root" | "changed" | "unavailable";
export interface OpenRegularFileOptions {
    rejectHardlinks?: boolean;
    trustedRoot?: string;
}
export type OpenRegularFileResult = {
    ok: true;
    fd: number;
    stat: ReturnType<typeof fstatSync>;
} | {
    ok: false;
    reason: OpenRegularFileFailureReason;
};
/**
 * Open and bind a regular file without following its final symlink. The
 * nonblocking flag prevents FIFOs and similar special files from stalling
 * before descriptor-based validation can reject them. Callers writing
 * security-sensitive ledgers can also reject multiply-linked inodes.
 */
export declare function openRegularFile(filePath: string, flags: number, options?: OpenRegularFileOptions): OpenRegularFileResult;
export declare function writeAllSync(fd: number, content: string | Buffer): void;
export declare function ensureTrustedParentDirectory(filePath: string, trustedRoot: string): void;
export declare function atomicWriteTrustedFile(filePath: string, content: string | Buffer, options: OpenRegularFileOptions & {
    trustedRoot: string;
}): void;
/**
 * Atomically write content to a file using a temporary file + rename.
 * Ensures the target file is never left in a partially-written state.
 */
export declare function atomicWrite(path: string, content: string | Buffer): void;
/**
 * Ensure the directory for the given path exists, creating it recursively if needed.
 */
export declare function ensureDir(path: string): void;
/**
 * Read and parse JSON from a file, returning the fallback value if the file
 * doesn't exist or cannot be parsed.
 */
export declare function readJSON<T>(path: string, fallback: T): T;
/**
 * Read a bounded prefix and mtime from one opened file descriptor. Opening
 * before stat/read avoids path-based check-then-use races when files are
 * concurrently removed or replaced.
 */
export declare function readFilePrefixWithStat(path: string, maxBytes: number): {
    text: string;
    mtimeMs: number;
} | undefined;