Module fsutil 

Cross-platform filesystem helpers.

sync_directory durably persists directory entries on platforms where the operating system supports it (Unix fsync on a directory file descriptor). On Windows there is no supported way to flush a directory handle (FlushFileBuffers requires a file, and opening a directory for File::open yields PermissionDenied), so this is a no-op there. These helpers do not establish an equivalent power-loss durability guarantee on Windows.

Structs

TempPathGuard

RAII guard that unlinks a temp path unless disarm is called. Used to prevent orphan .tmp files when an intermediate step between File::create and rename fails.

Constants

MAX_ATIF_BYTES

ATIF trajectories can carry long transcripts; 64 MiB is generous (a 200k-token GPT-4 context in ASCII fits in ~800 KiB).

MAX_CONTROL_BYTES

Small-file caps for control-plane files (config sidecars, journal metadata, marker files, ack files). 1 MiB is well above any real legitimate content but small enough that a hostile plant cannot materialize an OOM before the parser complains.

MAX_RECEIPT_BYTES

Receipts JCS-canonicalize to a few hundred bytes; even a huge tool-call summary stays well under 16 MiB. Shared between the CLI (avctl receipt-verify) and the harness reconciler.

Functions

basename

Return just the file name of path as a &str, suitable for path = %basename(&path) in tracing macros.

create_dir_all_synced

Create path and any missing ancestors, then confirm every parent entry in the resolved directory hierarchy with fsync. Existing directories need the same confirmation: they can remain visible after an earlier failed synchronization or a concurrent creator that has not synchronized yet. An empty path is a no-op. Symbolic links are resolved before synchronizing so the actual target hierarchy is confirmed, including relative paths.

read_capped

Read a file into memory subject to a hard byte cap, refusing non-regular files. The size check runs on the OPEN handle (not the path — closes the TOCTOU race where a symlink target is swapped between metadata() and read()), and the read itself uses Read::take so a target that grows after the metadata check still cannot exceed the cap.

read_capped_string

UTF-8 variant of read_capped. Used by the CLI for operator-supplied config / manifest / bearer token files where content is textual.

sweep_orphaned_tmp

Remove crash-orphaned *.tmp files under root, recursively.

sync_directory

Fsync a directory so its rename/create entries are durable after a crash.

sync_directory_ancestors

Confirm the parent entries of an existing directory without creating it. This includes every ancestor of the resolved target, highest parent first. The directory itself is not synchronized; callers persisting its contents must also call sync_directory(path). Missing or non-directory paths fail.

unix_o_nofollow

POSIX O_NOFOLLOW open-flag value for the target platform. Used alongside std::os::unix::fs::OpenOptionsExt::custom_flags to refuse to follow a symlink at the file path being opened — closes the symlink-plant confused-deputy class where a co-tenant with write access to a spool directory pre-plants a symlink at a deterministic file path so the harness’s authenticated append (running as the harness UID) is redirected to a file the attacker can then read or overwrite.

unix_o_nonblock

O_NONBLOCK for OpenOptions::custom_flags. Opening a FIFO read-only WITHOUT this flag blocks until a writer appears — a pre-planted FIFO (swapped in after any pathname precheck; pathname checks cannot close that race) would hang the caller forever before the post-open handle check could refuse it. With the flag, the open returns immediately and the handle check sees a non-regular file. Regular files ignore O_NONBLOCK entirely, so the flag is free on the happy path. Same per-arch caution as unix_o_nofollow above: Linux asm-generic uses 0o4000; the PowerPC layout swaps it; BSD/macOS use 0x4.

write_atomic

Durably write bytes to path via create-tmp + fsync + rename + parent fsync.