import type { z } from "zod";
/**
 * Durable file writes for the run directory: an append that reaches the disk
 * before it returns, and a validated whole-file replace that a reader can
 * never see half of. Annotation logs, statelogs, checklist revisions and
 * labeling drafts all go through here.
 */
/**
 * Append and flush to disk before returning.
 *
 * `appendFileSync` returns once the write reaches the OS page cache, not the
 * device. Without the fsync, a power loss can lose an annotation the tool
 * already told the person was recorded — and a run directory exists precisely
 * because those judgements cannot be regenerated.
 */
export declare function appendDurably(filePath: string, line: string): void;
/** Write each line and its newline through an open file, one line at a time,
 *  so no string ever holds more than one line. */
export declare function writeLines(handle: number, lines: readonly string[]): void;
/** `appendDurably` for many lines: one open, one line at a time, one flush to
 *  disk at the end. */
export declare function appendLinesDurably(filePath: string, lines: readonly string[]): void;
/**
 * Flush a directory entry, so a rename or creation survives a power loss.
 *
 * Renaming is atomic with respect to readers, but the directory entry itself
 * sits in cache until it is synced. Failures to open a directory for sync are
 * ignored: some platforms and filesystems refuse it, and that is not a reason
 * to fail a write that otherwise succeeded.
 */
export declare function syncDirectory(directoryPath: string): void;
export type AtomicWriteArgs<Value> = {
    targetPath: string;
    value: Value;
    schema: z.ZodType<Value>;
};
/**
 * Validate, then replace a whole file atomically.
 *
 * A plain write truncates before it writes, so a crash part-way leaves a file
 * that is neither the old content nor the new. Writing a uniquely named
 * temporary and renaming means a reader always sees one or the other. The temp
 * name is random and created exclusively, so two processes cannot collide on
 * it and nobody can plant a symlink at it ahead of time to redirect the write.
 */
export declare function atomicWriteValidated<Value>(args: AtomicWriteArgs<Value>): void;