aeat.core._bucket_pointer module

Strict pydantic v2 record for the active-profile pointer file.

The pointer file lives at <aeat-root>/active-profile and carries the canonical default for the active-profile precedence chain (flag > env > pointer). This record is the typed wrapper around the pointer file’s plaintext content: BucketPointer. The storage-layer term bucket is preserved on the record’s bucket_id field because the bucket is the encrypted storage slice the operator profile sits on; the file’s operator-visible name is active-profile to match the verb noun.

The on-disk representation is single-document TOML keyed by bucket_id and schema_version. An atomic write-then-rename helper, write_pointer(), materialises the pointer; the resolve_active_bucket_id() resolver consumes it at startup. Invalid TOML and pydantic validation failures are deliberate hard failures for read_pointer; they are not treated as “no active profile” because that would silently fall back to root storage.

This module is also distinct from the application-layer manifest scanners: ProfileBucketPointer records are derived from buckets/*/manifest.toml and prove registered profile metadata. A BucketPointer only names the intended active bucket; it does not prove the bucket exists, read a manifest, or validate lifecycle status. The companion core._bucket_pointer_io module owns the file boundary, while this module owns strict validation and deterministic serialisation only.

class BucketPointer(**data)[source]

Bases: BaseModel

Plaintext pointer to the active bucket id.

The value object carries only bucket_id and schema_version. It does not read settings, open storage, inspect manifests, or resolve precedence; those operations belong to read_pointer(), write_pointer(), and resolve_active_bucket_id().

Variables:

  • bucket_id – Encrypted profile bucket id selected by the pointer.

  • schema_version – Pointer document schema version. Values start at 1.

Parameters:

  • bucket_id (str)

  • schema_version (int)

bucket_id: str
schema_version: int
to_toml()[source]

Serialise the pointer to its single-document TOML representation.

Emits a deterministic two-line document keyed by bucket_id and schema_version. The output ends with a trailing newline so the atomic write-then-rename helper produces a POSIX-clean file. The inverse parser is from_toml().

Return type:

str

classmethod from_toml(text)[source]

Parse the single-document TOML representation back into a record.

The parser accepts the exact schema emitted by to_toml() and then delegates to pydantic validation, so unknown keys, blank bucket ids, and invalid schema versions fail before pointer IO can accept the file.

Parameters:

text (str) – Raw TOML string to parse, expected to carry bucket_id and schema_version scalar keys.

Return type:

BucketPointer

Returns:

A validated BucketPointer instance.

Raises:

  • tomllib.TOMLDecodeError – If text is not valid TOML.

  • pydantic.ValidationError – If the TOML payload violates the strict pointer schema.