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 bundles are not promoted by internal/fileops; extraction owns its validated Notarius bundle rename.

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.