cadrumo.adapters.persistence.storage.custody._filesystem_records module

Atomic local custody-record transitions.

The public filesystem facade retains the custody locks, bounded primitive read/write operations, and the public API names. This module owns the compare-and-swap transition state machines so their Windows and POSIX publication paths stay together.

compare_and_replace_profile_custody_local_record(path, *, expected, replacement, maximum_bytes)

Atomically replace path only when its exact anchored bytes match.

The comparison and mutation belong to one custody-owner operation. A sibling that substitutes a different regular, canonical record after the comparison is detected at the exchange boundary; its bytes are restored before this function refuses. expected=None is the one no-replace initial publication case.

Return type:

None

Parameters:

• path (Path)

• expected (bytes | None)

• replacement (bytes)

• maximum_bytes (int)

compare_and_replace_same_or_predecessor_profile_custody_local_record(path, *, current, predecessor, maximum_bytes)

Idempotently publish current from only its exact predecessor.

A durable retry whose requested bytes are already current is successful and performs no mutation. Otherwise, one anchored compare-and-replace accepts only the exact predecessor (or a proven-absent first receipt); every other leaf is preserved and refused.

Return type:

None

Parameters:

• path (Path)

• current (bytes)

• predecessor (bytes | None)

• maximum_bytes (int)

compare_and_clear_profile_custody_local_record(path, *, expected, maximum_bytes)

Remove path only when its exact anchored bytes still match.

Unlike a read followed by unlink, this keeps the verified leaf pinned through the delete decision and refuses without deleting a substituted canonical record.

Return type:

None

Parameters:

• path (Path)

• expected (bytes)

• maximum_bytes (int)