cadrumo.core.bucket_pointer module

Strict current-only record for the active-profile pointer.

The pointer is one durable, plaintext coordination record under the storage root. It names either a selected bucket or an explicit absence and carries the monotonic transition coordinate used by every pointer consumer. The record is not a profile manifest or a profile-lifecycle assertion: it only records the currently selected bucket.

class BucketPointer(**data)[source]

Bases: BaseModel

One strict active-profile selection and its durable transition revision.

selection is deliberately explicit because TOML has no null scalar. A selected record carries exactly one bucket id; an absent record is the persisted tombstone written by clear. The physically absent initial file observes as an absent record at revision zero and is never accepted as an on-disk compatibility format.

Parameters:

  • selection (Literal['absent', 'selected'])

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

  • transition_revision (int)

  • schema_version (Literal[2])

selection: Literal['absent', 'selected']
bucket_id: BucketId | None
transition_revision: int
schema_version: Literal[2]
classmethod absent(*, transition_revision)[source]

Construct the explicit absent-selection tombstone.

Return type:

BucketPointer

Parameters:

transition_revision (int)

classmethod selected(*, bucket_id, transition_revision)[source]

Construct one selected current-format record.

Return type:

BucketPointer

Parameters:

  • bucket_id (str)

  • transition_revision (int)

to_toml()[source]

Return the deterministic strict current-format TOML payload.

Return type:

str

classmethod from_toml(text)[source]

Strictly parse a current-format pointer record.

Return type:

BucketPointer

Parameters:

text (str)

pointer_path(root)[source]

Return the active-profile record path beneath root.

Return type:

Path

Parameters:

root (Path)

read_pointer(root)[source]

Observe the optional selection and durable current coordinate once.

Return type:

BucketPointer

Parameters:

root (Path)

write_pointer(root, pointer)[source]

Atomically replace the one strict pointer record under its owner lock.

Return type:

None

Parameters:
resolve_active_bucket_id()[source]

Resolve a process override or one current persisted selection.

Return type:

str | None

require_active_bucket_id()[source]

Return the selected bucket or raise the canonical no-profile refusal.

Return type:

str

resolve_repository_bucket_id(bucket_id, *, error_type)[source]

Resolve an explicit bucket or the current pointer selection.

Return type:

str

Parameters: