/**
 * AtomicWriter — crash-safe persistence helpers for OpenLife state files.
 *
 * Pattern:
 *   1. Write payload to `<filePath>.tmp.<pid>.<ts>`
 *   2. fsync the temp file (flush OS buffer to disk)
 *   3. Atomically rename temp → final (single syscall on POSIX, MoveFileEx on Windows)
 *   4. On any error: best-effort cleanup of temp file
 *
 * The rename step is atomic per the OS (POSIX rename(2), NTFS MoveFile), so a
 * `kill -9` mid-operation leaves either the old file intact, or the fully new
 * one. There is no partial-write window observable by other processes.
 *
 * Concurrency: each writer uses a unique temp suffix (`pid.ts.rand`), so
 * multiple processes writing the same final path do not collide on the temp.
 * The final rename is last-writer-wins, which is acceptable for our state
 * files (the loser's data is discarded, not corrupted).
 *
 * Feature flag: `OPENLIFE_ATOMIC_WRITES=off` disables atomicity and falls
 * back to plain writeFileSync / appendFileSync. Default is 'on'.
 *
 * Story 6.1 — OpenLife v1.2 Royal Stack.
 */
/**
 * Write a JSON-serializable object to `filePath` atomically.
 *
 * Writes pretty-printed JSON (2-space indent) followed by a trailing newline.
 * Parent directory is created recursively if it does not exist.
 */
export declare function writeJsonAtomic(filePath: string, obj: unknown): void;
/**
 * Write a raw string to `filePath` atomically. Used by writeJsonAtomic
 * internally; exported for callers that need control over serialization
 * (e.g. markdown templates).
 */
export declare function writeStringAtomic(filePath: string, content: string): void;
/**
 * Append one JSON object as a single line to a JSONL event log,
 * atomically with respect to crash.
 *
 * Implementation reads the existing file into memory, appends the new line,
 * and rewrites the whole file via the atomic temp+rename dance. This is
 * O(n) per append; suitable for event logs that stay under a few MB
 * (the typical case for `.openlife/*.jsonl` and `.artifacts/**\/events/*.jsonl`).
 *
 * For high-volume logs this becomes expensive; consider sharding or a
 * dedicated append-with-lock implementation if hot paths emerge.
 */
export declare function appendJsonlAtomic(filePath: string, obj: unknown): void;
/**
 * Append a raw string (already-terminated line, no JSON wrapping) atomically.
 * Used by callers that already control their own serialization format.
 */
export declare function appendStringAtomic(filePath: string, line: string): void;
/**
 * Remove orphaned `.tmp.<pid>.<ts>.<rand>` files older than `olderThanMs`.
 * Returns the count of files removed.
 *
 * Use during boot to clean up after a previous crash that left temp files
 * lingering. Safe to call even when atomic writes are disabled — it only
 * targets the `.tmp.<pid>.*` naming convention we control.
 */
export declare function purgeStaleTempFiles(dir: string, olderThanMs: number): number;
/** Internal — exposed for tests so they can assert the flag wiring. */
export declare function _isAtomicEnabled(): boolean;
