cadrumo.adapters.persistence.storage.custody.label_head_repository module

Durable persistence and recovery operations for the label head.

class ProfileLabelHeadRepository(*, root=None)[source]

Bases: object

Read, verify, CAS-advance, and deterministically recover label heads.

Parameters:

root (Path | None)

head_path(profile_id)[source]

Return the durable head file’s path, without reading or asserting it exists.

Return type:

Path

Parameters:

profile_id (UUID)

pending_path(profile_id)[source]

Return the crash-recovery pending-advance file’s path.

The leading dot matches the filesystem convention for a hidden, in-progress artefact — a directory listing of head files should not surface a pending advance as if it were a committed head.

Return type:

Path

Parameters:

profile_id (UUID)

load_current(profile_id)[source]

Return the exact durable head for an already-verified current capsule.

Return type:

ProfileLabelHead

Parameters:

profile_id (UUID)

verify(*, label)[source]

Read and verify the durable head without publishing or repairing it.

Return type:

ProfileLabelHead | None

Parameters:

label (ProfileCustodyCapsuleLabel)

publish_initial(*, label, source_witness)[source]

Publish exactly the initial head a verified caller has decided is absent.

Return type:

ProfileLabelHead

Parameters:
begin_advance(*, current_head, current_label, replacement_label)[source]

Durably record intent to advance the head before writing the new head itself.

This is the write-ahead half of the crash-recovery protocol recover_pending() completes on the other side: the pending record lands on disk FIRST, so a crash between here and the eventual head write leaves a resumable trail instead of an ambiguous half-advanced state.

Return type:

ProfileLabelHeadPendingAdvance

Parameters:
recover_pending(*, profile_id, current_label)[source]

Repair one durable pending advance; verification remains a separate read.

Return type:

None

Parameters: