cadrumo.adapters.persistence.storage.custody.filesystem module¶
Identity-anchored local filesystem substrate for profile custody.
- profile_custody_local_lock(path, *, timeout_seconds=30.0)[source]¶
Hold a no-follow, parent-anchored cross-process custody lock.
On POSIX the descriptor is opened relative to a pinned parent and locked with
flock. Windows opens the exact no-reparse leaf with no sharing; the kernel releases that exclusion when a process dies. Neither platform relies on a stale lock-file convention.
- profile_custody_root_lock(root, *, timeout_seconds=30.0)[source]¶
Hold the single re-entrant root lock for every current custody pointer mutation.
This is deliberately a separate primitive from leaf locks: both the application active-pointer transaction and custody compare-and-swap use this exact root lock identity. Re-entry is limited to the same process, thread, and effective root; sibling processes retain kernel-enforced exclusion through
profile_custody_local_lock().
- read_profile_custody_local_record(path, *, maximum_bytes)[source]¶
Read an auxiliary local custody record through the same anchored no-follow primitive.
- read_optional_profile_custody_local_record(path, *, maximum_bytes)[source]¶
Read a local record or prove its absence through the anchored primitive.
Callers that need an absent-vs-corrupt distinction must not first inspect a pathname and then reopen it. This keeps that distinction inside the same no-follow, identity-anchored operation as the bounded read.
- write_profile_custody_local_record(path, payload, *, publish_once)[source]¶
Durably write an auxiliary local custody record under pinned ancestry.
publish_onceuses a no-replace publication; mutable journals are first read through the paired no-follow primitive and then atomically replaced.
- compare_and_replace_profile_custody_local_record(path, *, expected, replacement, maximum_bytes)[source]¶
Atomically replace a local custody record through the transition engine.
- compare_and_replace_same_or_predecessor_profile_custody_local_record(path, *, current, predecessor, maximum_bytes)[source]¶
Publish a current custody record only from its exact predecessor.
- compare_and_clear_profile_custody_local_record(path, *, expected, maximum_bytes)[source]¶
Remove a local custody record only when its anchored bytes still match.
- clear_profile_custody_local_record(path)[source]¶
Remove one local record through an anchored verified leaf handle.
The operation opens and verifies the leaf before any unlink/delete action; it never performs a
lexists/unlinkpath sequence. The caller’s custody root lock serializes cooperating writers, while the pinned parent and non-delete-shared Windows handle prevent ancestry or leaf substitution during this operation.
- lexists(path, *, trace)¶
- Return type:
- Parameters:
path (Path)
trace (list[ProfileCustodyPasswordReadOperation] | None)
- posix_child_exists(parent_fd, name, *, trace, display_path)¶
- read_regular_file(path, *, maximum_bytes, trace=None, missing_ok=False)¶
- read_regular_file_fd(parent_fd, name, *, display_path, maximum_bytes, trace)¶
- read_regular_file_open(path, *, maximum_bytes, trace, parent_fd=None, missing_ok=False)¶
- windows_regular_file_anchor(path, *, missing_ok=False)¶
Reject a final reparse point, then lock the verified leaf against replacement.
- write_descriptor_fsynced(descriptor, payload)¶
- windows_replace_file(*, target, replacement, backup)¶
Replace one custody record through
ReplaceFileW.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.
- windows_read_handle_bounded(*, handle, info, maximum_bytes)¶
Read a bounded record from an already-verified Windows handle.
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.