Module runner_root 

Where disposable runner attempts are placed, and whether a configured location can actually hold them.

02-target-architecture.md separates three path concepts that used to share one directory. crate::paths::AppPaths owns the first — config, SQLite, logs, diagnostics and the verified package cache — and nothing here moves it. This module owns the other two: the host runner root under which ephemeral attempts are created, and the operational check every repository persistent root must also pass.

Two layers, and why the split is load-bearing

LocalAbsolutePath is the pure layer: it decides whether a string is a shape the product will persist, with no syscall and no ambient state, so opening the database never depends on a drive being mounted today. This module is the operational layer named in “Path validation”: it runs before a mutation is committed and before the daemon accepts new allocation, and it is the only one of the two allowed to ask the filesystem anything.

LocalAbsolutePath   absolute? non-root? native? no UNC, device or `..`?
RootPreflight       local volume? writable? a real directory? contained?

What this module will not do

It never creates, deletes, or re-permissions anything. Both writability probes are pure queries — access(2) on Unix, and on Windows a directory handle opened for FILE_ADD_SUBDIRECTORY, which runs the real access check against the real DACL and produces no file. That is deliberate: “validation performs no deletion or permission mutation” is then a property of the code rather than a convention, and a preflight that probed by writing a marker would be a preflight that can leave litter in an operator’s directory. Creating the validated leaf and applying the narrow default-root ACL are explicit steps their callers take after this returns Ok, in b2 and c1.

The Windows default

D1 is %SystemDrive%\rman, “normally C:\rman”. The drive letter is read from GetSystemDirectoryW, not from %SystemDrive%: an environment variable is writable by whatever launched the process, and this value decides where a recursive cleanup will later run. Nothing here assumes C: — default_runner_root_from takes the system directory as an argument, so the Linux and macOS CI legs test the Windows rule too.

Structs

FilesystemIdentity

The filesystem an existing directory sits on.

HostFilesystem

The real operating system.

PreflightedRoot

A root that passed the operational preflight.

RootPreflight

The operational check a configured or default runner root must pass.

Enums

Locality

What the host can prove about where a directory lives.

Overlap

How two paths sit relative to one another.

PlatformDefault

Where a platform default comes from.

RootOwner

Which setting a root came from.

RunnerRootError

Why a runner root cannot be resolved, or cannot be used.

Constants

WINDOWS_RUNNER_ROOT_NAME

The directory appended to the Windows system drive to form the default host runner root.

Traits

FilesystemProbe

The two questions the preflight asks the operating system.

Functions

default_runner_root

The platform default host runner root for this machine.

default_runner_root_from

Resolves a platform default from an explicit source.

derive_child

The path of one attempt directory or persistent slot below root.

is_on_privacy_gated_volume

Whether path sits on a volume macOS withholds from a background service.

verify_containment

Proves that child is below root, lexically and after resolution.