/** Options for {@link writeFileAtomicSync}. */
export interface AtomicWriteOptions {
    /**
     * Explicit permission bits for the written file. When provided, wins over
     * an existing target's preserved mode (the caller is stating intent — e.g.
     * a recovery artifact carrying its SOURCE file's mode). When omitted, an
     * existing target keeps its own bits and a new target gets the process
     * umask default. POSIX-only; ignored on win32 (the install-hooks chmod
     * convention).
     */
    mode?: number;
}
/**
 * Atomic user-file write — the shared helper the Tenet 4 User-File Mutation
 * Contract corollary mandates (mmnto-ai/totem#2620; canonical text:
 * `mmnto-ai/totem-strategy:design-tenets.md`). Observable state after any
 * outcome is the old bytes or the new bytes — never torn, metadata included.
 *
 * Ordering is contract, not implementation detail (author intent-read on the
 * #2620 Q2 consult): metadata lands on the TEMP file and the rename comes
 * last. Rename-then-repair would ship new-bytes-with-wrong-metadata on a
 * chmod/chown failure — a torn state in metadata clothing.
 *
 *   1. Resolve an existing symlink target to its real path — link identity
 *      survives (a bare rename would replace the link with a regular file).
 *      A dangling or cyclic link throws with the target untouched.
 *   2. Write to a unique same-volume temp (`<target>.<pid>-<uuid8>.tmp`):
 *      same-volume keeps the rename atomic (no EXDEV copy window); PID/time
 *      entropy alone collides under concurrency (lesson-bc2194f8), so the
 *      name carries UUID entropy and opens `wx` — a collision fails loud
 *      instead of two writers interleaving one temp path.
 *   3. fsync the temp fd. Declared boundary: no directory fsync (not
 *      portable on Windows), so crash durability of the rename itself is
 *      best-effort.
 *   4. Apply mode — and ownership, when the existing target's uid/gid differ
 *      from the process (POSIX) — to the temp. A chown failure throws: a
 *      silent ownership flip is metadata drift, never an "expected" condition
 *      under Tenet 4's boundary carve-out.
 *   5. Rename over the target.
 *
 * Throws on any failure with the temp cleaned up and the target's old bytes
 * intact. Callers running per-item best-effort loops catch per item and
 * account the failure (Tenet 4's licensed shape: failure accounting + a loud
 * backstop).
 *
 * Declared boundaries (falsification round, 2026-08-09):
 * - Windows: a rename over a target held open by another process fails
 *   EPERM/EACCES (old bytes remain); mode/ownership application is skipped;
 *   the temp suffix adds ~20 chars (`.<pid>-<uuid8>.tmp`), which can cross
 *   MAX_PATH on already-long target paths.
 * - HARD-link identity is NOT preserved: rename-over replaces the directory
 *   entry, so a target with nlink > 1 silently decouples from its other
 *   names (rule 1 names symlink identity only).
 * - Two behavior deltas vs the in-place writeFileSync this replaces: a
 *   cross-uid/gid target the process cannot chown now throws (previously an
 *   in-place write succeeded), and the parent DIRECTORY must be writable
 *   (in-place writes needed only the file writable).
 * - On a failure already in flight, temp cleanup is best-effort: if the
 *   cleanup itself fails — or the process is hard-killed mid-write — a
 *   `<target>.<pid>-<uuid8>.tmp` file can remain beside the target.
 */
export declare function writeFileAtomicSync(targetPath: string, data: string | Buffer, options?: AtomicWriteOptions): void;
//# sourceMappingURL=fs-atomic.d.ts.map