/**
 * Hard ceiling on `.corrupt-*` files kept per store directory, oldest reaped
 * first. A flapping writer that corrupts its file on every boot must not be
 * allowed to fill the disk with forensic copies, "a handful" is enough to
 * look at what went wrong without becoming a leak.
 */
export declare const CORRUPT_QUARANTINE_MAX_FILES = 5;
/**
 * How old a `<name>.tmp-*` file must be before the pre-write sweep will delete
 * it.
 *
 * The sweep cannot tell a crash leftover from another writer's work in
 * progress by name alone, so it uses age: a temp file written within the last
 * minute may still belong to a live write (another process, or this one on a
 * worker thread) and is left strictly alone. One minute is far longer than any
 * store here takes to serialize, open, write, fsync, chmod and rename, a few
 * hundred kilobytes of JSON at most, so a leftover from a process that really
 * did die becomes eligible on the next write a minute later, while a live
 * writer is never robbed of its temp file.
 */
export declare const STALE_TEMP_FILE_MIN_AGE_MS = 60000;
/**
 * Build the temp path for one atomic write of `filePath`.
 *
 * Unique per call, never per process: `<name>.tmp-<pid>-<seq>-<random>`. The
 * pid and sequence are there so a leftover file names the process and the
 * write that produced it when someone goes looking; the random suffix is what
 * guarantees two writers never collide even across pid reuse.
 *
 * Exported so a test can hold a second writer's temp file the way a real
 * concurrent writer does, and assert the sweep leaves it alone.
 */
export declare function createAtomicTempPath(filePath: string): string;
export interface AtomicWriteOptions {
    /**
     * Exact mode of the resulting file. Applied with an explicit `chmod` before
     * the rename, so the result does not vary with the process umask.
     * Defaults to `0o600`.
     */
    readonly mode?: number;
}
export interface AtomicJsonWriteOptions extends AtomicWriteOptions {
    /** `JSON.stringify` indent. `null` writes compact JSON. Defaults to `2`. */
    readonly indent?: number | null;
    /** Append a trailing newline to the serialized JSON. Defaults to `true`. */
    readonly trailingNewline?: boolean;
}
/**
 * Write `contents` to `filePath` atomically, creating parent directories as
 * needed. See the module docstring for the mechanics and why they matter.
 */
export declare function writeFileAtomic(filePath: string, contents: string, options?: AtomicWriteOptions): void;
/** Serialize `value` as JSON and write it atomically via {@link writeFileAtomic}. */
export declare function writeJsonFileAtomic(filePath: string, value: unknown, options?: AtomicJsonWriteOptions): void;
export interface AtomicJsonSafeWriteOptions extends AtomicJsonWriteOptions {
    /**
     * Short store name for the failure log, e.g. `'watchers/store'`. Rendered as
     * `[<label>]`. Defaults to `'atomic-json-store'`.
     */
    readonly label?: string;
}
/** What {@link writeJsonFileAtomicSafe} reports back instead of throwing. */
export interface AtomicWriteOutcome {
    /** True when the bytes are on disk under `filePath`. */
    readonly ok: boolean;
    /** The store file the write targeted. */
    readonly filePath: string;
    /** The failure, when `ok` is false. */
    readonly error?: Error;
    /** The errno string when the failure carried one, e.g. `'ENOENT'`, `'ENOSPC'`. */
    readonly code?: string;
    /** The failing syscall when the failure named one, e.g. `'chmod'`, `'rename'`. */
    readonly syscall?: string;
}
/**
 * {@link writeJsonFileAtomic} for callers whose failure policy is
 * log-and-continue: the failure is logged at error level with the store path,
 * the errno and the failing syscall, and returned as an
 * {@link AtomicWriteOutcome} rather than thrown.
 *
 * This exists because a periodic snapshot must never be able to kill its host.
 * A watcher-store write that failed inside a fleet tick propagated out of a
 * timer callback with nothing above it to catch it, and the whole agent
 * process died, from a store whose entire recovery story is "it rebuilds from
 * live registrations on the next load". Stores where a silent failure would be
 * a lie (settings, secrets, pairing tokens, anything a user just asked to
 * save) keep using {@link writeJsonFileAtomic} and keep throwing.
 */
export declare function writeJsonFileAtomicSafe(filePath: string, value: unknown, options?: AtomicJsonSafeWriteOptions): AtomicWriteOutcome;
export interface QuarantineLoadOptions<T> {
    /**
     * Short store name used in the log line and the `.why` receipt, e.g.
     * `'config/secrets'`. Rendered as `[<label>]` in logs.
     */
    readonly label: string;
    /**
     * Narrow the parsed JSON to the store's shape. Throw with a human-readable
     * reason when the content cannot be trusted, that reason is what lands in
     * the `.why` receipt and the error log.
     */
    readonly validate: (parsed: unknown) => T;
    /**
     * One sentence for the `.why` receipt describing what happens now that the
     * file is gone, i.e. how this store rebuilds. Written for a human reading
     * the receipt months later with no other context.
     */
    readonly recovery: string;
}
/**
 * Read and parse a JSON store file, never throwing on corrupt content.
 *
 * Returns `null` both when the file does not exist and when it existed but
 * could not be trusted, in the latter case the file is quarantined first (see
 * the module docstring). Callers treat `null` as "no store yet" and rebuild.
 *
 * A read failure (permissions, the file vanishing between the exists check and
 * the read) is deliberately NOT caught: there is no content to move aside, so
 * quarantine has nothing to do and the error propagates to the caller.
 */
export declare function readJsonFileOrQuarantine<T>(filePath: string, options: QuarantineLoadOptions<T>): T | null;
export interface QuarantineOptions {
    /** Short store name, e.g. `'config/secrets'`. */
    readonly label: string;
    /** Why the file could not be trusted. */
    readonly reason: string;
    /** What happens now that the file is gone, for the `.why` receipt. */
    readonly recovery: string;
}
/**
 * Move a corrupt store file aside, write a `.why` receipt beside it, log the
 * event loudly, and reap old quarantine files past the bound.
 *
 * Exported for stores that parse in stages and decide for themselves which
 * stage counts as container corruption (`config/secrets.ts` quarantines an
 * unreadable JSON envelope but must never quarantine a decrypt failure, which
 * means the file is intact and the key is wrong).
 */
export declare function quarantineCorruptFile(filePath: string, options: QuarantineOptions): void;
//# sourceMappingURL=atomic-json-store.d.ts.map