cadrumo.adapters.persistence.storage.custody.label_head_models module

Canonical label-head records and their crash-recovery witness.

LABEL_HEAD_MAX_BYTES

Bounded durable head and pending-advance records share one strict budget.

class ProfileLabelHead(**data)[source]

Bases: CustodyDigestModel

Trusted current label witness, separate from the immutable commit marker.

Parameters:

self_digest (str)

schema_version: Literal[1]
profile_id: UUID
label_revision: int
label_content_digest: PrefixedContentDigest
label_self_digest: str
source_witness: str
previous_head_digest: str | None
self_digest: PrefixedContentDigest
classmethod create_initial(*, label, source_witness)[source]

Start a label-head chain from the label’s own first revision.

Refuses any label that is not itself revision 1 with no predecessor — the chain’s root must anchor to a label the label-record layer already proved is first, never to an arbitrary starting point a caller supplies.

Return type:

ProfileLabelHead

Parameters:
classmethod advance(*, current, label)[source]

Extend the trusted chain by exactly one label revision.

Refuses a label that does not continue current by revision number AND content lineage (previous_label_digest must equal the current head’s content digest) — a caller cannot skip a revision or splice in a label from a different chain, only ever advance one step from the head it already trusts.

Return type:

ProfileLabelHead

Parameters:
verifies(label)[source]

Return whether this head is the trusted head for exactly label.

The check every reader uses before trusting a label as current: a label is only “the” current one if a head record independently vouches for its identity AND digest, not merely because it happens to be the most recently written one on disk.

Return type:

bool

Parameters:

label (ProfileCustodyCapsuleLabel)

class ProfileLabelHeadPendingAdvance(**data)[source]

Bases: CustodyDigestModel

Crash-recovery witness for one label-record then head advance.

Parameters:

self_digest (str)

schema_version: Literal[1]
operation_id: UUID
profile_id: UUID
expected_head_digest: str
expected_label: ProfileCustodyCapsuleLabel
replacement_label: ProfileCustodyCapsuleLabel
replacement_head: ProfileLabelHead
self_digest: PrefixedContentDigest
classmethod create(*, expected_head, expected_label, replacement_label, replacement_head)[source]

Record intent to advance the label head, durably, before the advance is committed.

This is the crash-recovery witness the class docstring names: written BEFORE the actual label-then-head write lands, so a process that dies mid-advance leaves a record recovery can resume from, rather than an untraceable partial write. Refuses to start unless expected_head already verifies expected_label — recovery can only resume from a state that was itself trustworthy.

Return type:

ProfileLabelHeadPendingAdvance

Parameters: