aeat.application.workflow._profile_bucket_scan module

Manifest-scan discovery for profile bucket pointers.

A profile bucket lives at <aeat-root>/buckets/<profile-id>/ where <profile-id> is the immutable UUIDv4 profile identity. The plaintext manifest.toml inside carries that bucket_id (the UUID) and a decoupled mutable label (the operator-chosen display name). The bucket directory name and the profile identity are one and the same; the operator never sees the UUID and addresses profiles by their label.

This module exposes the scanner that enumerates profile buckets by reading those plaintext manifests. It never opens the encrypted database engine. read_profile_bucket resolves an operator label to a bucket pointer (UUID + label); list_profile_buckets returns every registered pointer keyed by UUID.

The manifest carries a plaintext status lifecycle marker. The live-surface resolvers — read_profile_bucket and, by default, list_profile_buckets — exclude tombstoned profiles so a deleted profile never leaks into list / switch / name-uniqueness. The by-id resolver read_profile_bucket_by_id resolves a profile regardless of status: surfaces that legitimately inspect a tombstoned profile (show, diagnostics) address it by UUID.

See also

ProfileBucketPointer

Public pointer record returned by the manifest scanners.

application.workflow._profile_health

Consumes by-id manifest lookup to classify active-profile readiness.

BucketManifest

Plaintext manifest shape parsed from each profile bucket directory.

BucketLifecycleStatus

Lifecycle marker used to hide tombstoned profiles from live surfaces.

application.user_profile._orchestration

Owns profile creation, selection, and encrypted profile-record access around the same bucket identity.

class ProfileBucketScanIssue(bucket_id, reason)[source]

Bases: object

One bucket manifest skipped by the live profile scanner.

Parameters:

  • bucket_id (str)

  • reason (str)

bucket_id: str
reason: str
read_profile_bucket(label, *, root=None, include_tombstoned=False)[source]

Return the bucket pointer for the profile whose label is label.

Scans every <root>/buckets/*/manifest.toml and matches the manifest label against label case-insensitively. Returns a ProfileBucketPointer carrying the UUID bucket_id, the manifest label, and the lifecycle status when exactly one profile matches; returns None when no profile carries the label.

By default tombstoned profiles are excluded: a deleted profile is off the live surface, so its label resolves to None (re-usable) and it can never be switched into. The show inspect surface passes include_tombstoned=True so an operator can still inspect a deleted profile by name and see its tombstoned status; it then branches on the returned status.

Parameters:

  • label (str) – Operator-facing profile label. Must be non-empty.

  • root (Path | None) – Optional AEAT root override. When None, resolves Settings.aeat_local_storage_root via load_settings.

  • include_tombstoned (bool) – When True, a tombstoned profile is also a candidate; default False matches only live profiles.

Return type:

ProfileBucketPointer | None

Returns:

A ProfileBucketPointer for the matching profile, or None when no profile carries the label.

Raises:

ProfileLabelAmbiguousError – when two or more matching profiles share the label (an ambiguous resolution the name-uniqueness guard should have prevented among live profiles).

read_profile_bucket_by_id(profile_id, *, root=None)[source]

Return the ProfileBucketPointer for the profile whose UUID is profile_id.

Resolves <root>/buckets/<profile_id>/manifest.toml directly. Returns None when the manifest is absent. Resolves a profile regardless of lifecycle status - a tombstoned profile is still addressable by its UUID so show and diagnostics can inspect it; the returned pointer carries the manifest status so the caller can branch on it.

Return type:

ProfileBucketPointer | None

Parameters:

  • profile_id (str)

  • root (Path | None)

resolve_profile_bucket(identifier, *, root=None, include_tombstoned=False)[source]

Resolve a profile identifier that may be a UUID bucket id OR a display label.

The active-profile precedence chain (AEAT_ACTIVE_PROFILE env var, the active-profile pointer file) and operator input both carry whichever identifier the operator knows. An operator addresses a profile by the label they chose at profile create — they never see the immutable UUIDv4 bucket id — so AEAT_ACTIVE_PROFILE=<label> is a natural, intended operator action. Resolving the value as a UUID bucket directory only would hard-miss on a label (buckets/<label> does not exist), refusing every profile-scoped command with a “no manifest” error.

This resolver tries the UUID-direct lookup first (the canonical bucket directory key), then falls back to the manifest-scan-by-label. The same lifecycle filter applies to both paths: by default tombstoned profiles are hidden from live surfaces whether the operator supplies a UUID or a label. A label is unique among live profiles (the name-uniqueness guard), so the fallback is unambiguous. Returns None when the identifier matches neither a live bucket UUID nor a live profile label.

Parameters:

  • identifier (str) – A profile UUID bucket id or an operator display label.

  • root (Path | None) – Optional AEAT root override. When None, resolves Settings.aeat_local_storage_root via load_settings.

  • include_tombstoned (bool) – When True, inspect surfaces can resolve a deleted profile by UUID or name; default False matches only live profiles.

Return type:

ProfileBucketPointer | None

Returns:

A ProfileBucketPointer for the resolved profile, or None.

list_profile_buckets(*, root=None, include_tombstoned=False)[source]

Return registered profile-bucket pointers keyed by profile UUID.

Scans <root>/buckets/*/manifest.toml for every directory that carries a manifest file, parses each manifest, and returns a pointer carrying the manifest bucket_id (UUID), label (operator name), and status lifecycle marker. Directories without a manifest are treated as torn or pre-provisioned state and skipped.

By default only live (non-tombstoned) profiles are returned: a tombstoned profile has left the live operator surface. Pass include_tombstoned=True to enumerate every registered profile — used by repair / audit surfaces that must see deleted profiles.

Parameters:

  • root (Path | None) – Optional AEAT root override. When None, resolves Settings.aeat_local_storage_root via load_settings.

  • include_tombstoned (bool) – When True, tombstoned profiles are included; default False returns only live profiles.

Return type:

dict[str, ProfileBucketPointer]

Returns:

A dict mapping each profile UUID to its ProfileBucketPointer.

list_profile_bucket_scan_issues(*, root=None)[source]

Return non-sensitive manifest-scan issues found under the profile root.

Each element is a ProfileBucketScanIssue describing one structural problem found in the profile bucket directories.

Return type:

tuple[ProfileBucketScanIssue, ...]

Parameters:

root (Path | None)