cadrumo.adapters.persistence.storage.custody.filesystem_primitives module

Identity-anchored directory primitives for profile custody storage.

class WindowsDirectoryAnchorErrors(cannot_open, cannot_verify, invalid_entry, empty_path)

Bases: object

Operator-facing refusals emitted while anchoring a Windows directory.

Parameters:

• cannot_open (str)

• cannot_verify (str)

• invalid_entry (str)

• empty_path (str)

cannot_open: str

cannot_verify: str

invalid_entry: str

empty_path: str

class ProfileCustodyPasswordReadOperation(operation, path)

Bases: object

One actual filesystem operation in the normal-password read set.

Parameters:

• operation (Literal['stat', 'open', 'read'])

• path (Path)

operation: Literal['stat', 'open', 'read']

path: Path

is_real_directory(path)

Return whether path is a real directory, never a symlink or reparse point.

Return type:

bool

Parameters:

path (Path)

ensure_real_directory(path)

Create path as a real directory, refusing an existing link or non-directory.

Return type:

None

Parameters:

path (Path)

anchor_directory(stack, path, *, final_access=0)

Keep a verified directory identity non-deletable for a path operation.

Return type:

int | None

Parameters:

• stack (ExitStack)

• path (Path)

• final_access (int)

ensure_profile_custody_local_directory(path)

Create one custody-owned directory while its parent identity is pinned.

The caller supplies a single child of an existing storage root. This is intentionally not a recursive convenience function: recursive path walks reintroduce a check-then-create window on Windows and POSIX alike.

Return type:

None

Parameters:

path (Path)

windows_file_information_type()

Return the one Win32 identity structure shared by custody operations.

Built once per process: the structure is a pure layout, and every anchored operation asked for it anew.

Return type:

type[Any]

windows_create_file_api()

Return configured CreateFileW bindings for identity-anchored calls.

Built once per process and shared. The binding is pure configuration, and every consumer that configures a further function on the returned library sets the same signature, so sharing cannot change a call’s conversion.

The sys.platform == "win32" block, rather than a guard at the call site or an early return, is what establishes the platform for the Windows API below: it is the only guard shape every checker this project runs narrows on, so those references resolve when the tree is analysed for a platform that does not ship them.

Return type:

tuple[Any, Any, Any, Any]

shared_directory_anchors()

Let the anchors of one operation share the component handles they hold.

An operation such as one capsule scan anchors the same ancestor chain again for every member it inspects – every component of the storage root, then the capsules directory – and each anchor re-opened all of them. Inside this scope an anchor reuses a component that another live anchor already holds with at least the access it needs, and opens only what is missing. A component stays held while ANY anchor relying on it is live, so no read runs under an ancestor that was released; a handle closes when its last user leaves. The scope holds nothing of its own, so nothing outlives the operation. Nested scopes share the outermost session.

Return type:

Generator[None]

windows_directory_anchor(path, *, final_access=0, errors=WindowsDirectoryAnchorErrors(cannot_open='profile capsule directory cannot be identity-anchored', cannot_verify='profile capsule directory identity cannot be verified', invalid_entry='profile capsule directory must not be a reparse point or non-directory', empty_path='profile capsule directory cannot be identity-anchored'))

Lock every real component against reparse and delete substitution.

Return type:

Generator[int]

Parameters:

• path (Path)

• final_access (int)

• errors (WindowsDirectoryAnchorErrors)

windows_component_paths(path)

Return the path of every component below the anchor, outermost first.

String-joined rather than built as successive Path objects: an anchor walks every component of a deep storage path, and rendering each intermediate Path was the largest cost of anchoring after the Win32 calls themselves.

Return type:

tuple[str, ...]

Parameters:

path (Path)

posix_directory_fd(path)

Walk an absolute directory a component at a time without following links.

Return type:

Generator[int]

Parameters:

path (Path)

posix_open_child_directory(parent_fd, name)

Open name below parent_fd without following links, or raise.

Return type:

int

Parameters:

• parent_fd (int)

• name (str)

posix_mkdir_child_directory(parent_fd, name)

Create directory name below parent_fd and return its open descriptor.

Return type:

int

Parameters:

• parent_fd (int)

• name (str)

is_reparse_metadata(metadata)

Return whether metadata describes a reparse-point entry.

Return type:

bool

Parameters:

metadata (stat_result)

write_exclusive_fsynced(path, payload)

Create and fsync one capsule staging record at an anchored path.

Return type:

None

Parameters:

• path (Path)

• payload (bytes)

write_exclusive_fsynced_fd(parent_fd, name, payload)

Create and fsync one capsule staging record below an anchored descriptor.

Return type:

None

Parameters:

• parent_fd (int)

• name (str)

• payload (bytes)