narratio/docs/internal/fileops.md

Internal: File Operations

internal/fileops owns the narrow mechanics for atomically visible replacement of one byte file. Callers keep ownership of serialization, validation, cancellation, and destination-directory policy.

Destination Paths

Ordinary workspace replacement uses standard operating-system path semantics. Callers with a root-scoped safety contract own that validation at their boundary.

Remote object acquisition uses a writer supplied by the storage owner. The writer receives a fileops-owned, already-open sibling temporary file rather than a mutable destination path. Callers still own remote object selection, validation, conflict handling, and final mode.

Directory promotion keeps the verified destination parent open while it creates the temporary tree, copies regular source entries, and performs the platform no-replace rename. Platforms without a verified handle-relative atomic no-replace primitive reject promotion before writing a temporary tree.

Cleanup Contract

RemoveAllUnderRoot accepts an explicit root and a proper descendant, opens that root with os.OpenRoot, and removes the normalized root-relative target with Root.RemoveAll. It rejects root, traversal, and out-of-root targets; a missing target is successful. RemoveFileUnderRoot additionally requires an existing leaf to be regular. Command and post-publish policy remains owned by internal/app.

Bounded Reads

ReadFileBounded opens a normal path and reads at most its caller-supplied limit. Credential mode policy and environment precedence remain owned by internal/app.

Replacement Contract

ReplaceFileAtomic requires an existing destination directory. It creates a sibling temporary file, writes the complete byte sequence, applies the caller-supplied mode, closes the file, runs an optional pre-rename check, and replaces the destination with a rename.

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. Successful replacement provides atomic visibility; it makes no crash- or power-loss durability claim.

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.

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.