Module private_storage 

Private, crash-safe file primitives shared by every durable record. What: Private, crash-safe file primitives shared by every durable record of the wrapper: exclusive no-follow creation with private modes, file and directory sync, and no-follow reads that refuse links and non-regular files. Why: Lock records, transaction journals and capture records must survive a crash in a readable state, must never be written through a planted link, and must be private to the account. The incumbent’s src/trust/registry-io.ts defines these semantics; both wrappers write and read the same files.

In TS you’d write (pseudocode):

await writePrivateFile({ path, bytes }); await syncDirectory(dirname(path));

Enums

ReadRefusal

What: Why a no-follow read refused a path. An enum is a closed set of alternatives. Why: A missing file is an expected answer for optional records; a link, a directory or an over-long file is unsafe or corrupt state that recovery must name, never follow.

Constants

PRIVATE_DIRECTORY_MODE

Mode of every private directory the wrapper creates: owner only.

PRIVATE_FILE_MODE

Mode of every private file the wrapper creates: owner read and write only.

Functions

create_private_directory

What: Create one directory with mode 0700; its parent must exist. Why: Lock candidates, transaction directories and stores are private to the account. Only the creation mode is applied, as the incumbent’s mkdir(path, { mode }).

protect_path

What: Set a path’s permission bits to mode, on Unix only. std::io::Result<()> is “nothing, or an operating-system error”. Why: The creation mode is filtered by the process umask; an explicit change makes the mode exactly private whatever the caller’s umask is, as the incumbent’s protectPath does. Windows keeps its inherited access rules (recorded under “Choices open to veto” in doc/handover/cli-git-native-transactions.md).

read_regular_file

What: Read a whole regular file without following links, up to limit bytes. u64 is an unsigned 64-bit size; Result<Vec<u8>, ReadRefusal> is “the bytes, or why not”. Why: Recovery reads untrusted state: a link or a directory must be named as unsafe, and a runaway file must not be read into memory.

remove_tree

What: Remove a directory tree, treating an already absent tree as removed. Why: Retired locks and transactions are removed by name after a rename; another process may have removed them first, which is the same end state (rm -rf with force).

sync_directory

What: Make a directory’s entries durable, where the platform supports directory handles. Why: A new or renamed entry survives a crash only after its directory is synced; Windows has no directory handle for this, as the incumbent’s syncDirectory notes.

write_exclusive_synced

What: Write one file exclusively with mode 0600, refusing links, and sync its bytes, without the explicit mode change. Why: Owner-lock candidates are written this way by the incumbent’s writeCandidate: the creation mode alone, then a sync before publication.

write_private_file

What: Write one private file exclusively, refusing links, then make its bytes durable. &[u8] borrows the exact bytes. Why: A journal state file is created once and never rewritten, so a crash leaves either no file or a complete one after the caller syncs the directory.