Make atomic file replacement crash durable

docs/internal/fileops.md

@@ -0,0 +1,35 @@
+# Internal: File Operations
+
+`internal/fileops` owns the narrow mechanics for durable replacement of one
+byte file. Callers keep ownership of serialization, validation, cancellation,
+and destination-directory policy.
+
+## Replacement Contract
+
+`ReplaceFileAtomic` requires an existing destination directory. It creates a
+sibling temporary file, writes the complete byte sequence, applies the
+caller-supplied mode, syncs and closes the file, runs an optional pre-rename
+check, replaces the destination with a rename, then syncs the containing
+directory.
+
+The pre-rename check is the last point at which a caller can cancel without
+installing a new destination. A failure before the rename leaves the old
+destination unchanged and removes the temporary file; any cleanup failure is
+returned alongside the primary failure. A failure after the rename may leave
+the new file visible, but it is not reported as crash-durable.
+
+Replacement follows the operating system's same-filesystem rename semantics.
+If a platform cannot replace an existing destination, the operation returns an
+error and never removes the old file as an emulation step.
+
+## Directory-Sync Support
+
+Linux and macOS attempt to sync the destination directory. Windows opens the
+directory with backup semantics and flushes its buffers. If either operation
+is unavailable for the platform, directory handle, or filesystem,
+`ErrDirectorySyncUnsupported` is returned. Narratio does not treat that result
+as successful crash-durable replacement.
+
+`WriteFileAtomic`, copy helpers, and downloaded temporary-file installation
+retain their compatibility behavior of creating the destination parent with
+the repository's workspace permissions before using this contract.