cadrumo.application.workflow.profile_health module

Active-profile health projection shared by status, auth, and repair surfaces.

assess_active_profile_health() reads the persisted UserProfileRecord from the active bucket and returns an ActiveProfileHealth verdict used by every operator status surface. Confirmed pointer repairs coordinate mutation through the public active_profile_pointer_transaction() boundary.

See also

ProfileBucketPointer

Current committed-capsule projection resolved before secure profile records are loaded.

application.workflow.profile_bucket_scan

Resolves anchored current-capsule label projections without opening encrypted profile facts.

WorkflowState

Supplies the active profile record through the secure workflow-state repository when the active bucket is readable.

UserProfileRecord

Encrypted profile facts whose completeness determines the final health status.

ProjectionActiveProfile

Operator-state projection that carries this redacted health verdict to status and diagnostics surfaces.

class ProfileHealthStatus(*values)[source]

Bases: StrEnum

Closed set of active-profile health verdicts.

PROFILE_LOCKED is the ordinary benign member: the capsule is committed and its record is intact, and nobody has logged in, so the record is simply not knowable yet. It is deliberately distinct from MISSING_PROFILE_RECORD and PROFILE_RECORD_UNREADABLE, which both assert something is WRONG with the record. Collapsing the three told an operator whose profile was merely locked that their financial records were gone.

NONE
DANGLING_POINTER
PROFILE_LOCKED
MISSING_PROFILE_RECORD
PROFILE_RECORD_UNREADABLE
CAPSULE_UNREADABLE
INCOMPLETE
READY
ProfileHealthStatusValue

The same verdicts for a strict CLI payload field.

alias of Literal[NONE, DANGLING_POINTER, PROFILE_LOCKED, MISSING_PROFILE_RECORD, PROFILE_RECORD_UNREADABLE, CAPSULE_UNREADABLE, INCOMPLETE, READY]

RECORD_FAULT_STATUSES: Final[frozenset[ProfileHealthStatus]]

The verdicts asserting the active profile’s record is WRONG.

Exactly the two the docstring above warns must never absorb PROFILE_LOCKED. Written out at three sites before this existed, so that warning was carried by prose at one site and by three separate hand-written pairs everywhere else.

UNREADABLE_PROFILE_STATUSES: Final[frozenset[ProfileHealthStatus]]

Record faults plus a pointer that resolves to nothing.

Derived from RECORD_FAULT_STATUSES rather than restated, so the two sets cannot disagree about which record faults exist.

class ActiveProfileHealth(**data)[source]

Bases: BaseModel

Redacted active-profile health snapshot returned by assess_active_profile_health().

The active profile’s label is retained privately from the committed-capsule projection that this health assessment already resolved. Projection consumers use that snapshot value rather than re-reading discovery state after the health verdict has been computed. It is deliberately not a model field: repair payloads continue to expose only the redacted public health contract.

Parameters:

data (Any)

active_profile: str | None
source: ProfileSource
status: ProfileHealthStatusValue
registered_bucket: bool
profile_record_present: bool
profile_record_error: str
profile_present_keys: int
profile_total_keys: int
missing_required: tuple[str, ...]
repairable_by_clearing_pointer: bool
precondition_verdict: PreconditionVerdict | None
property active_profile_label: str | None

Return the committed-capsule label captured with this health assessment.

This is intentionally private to Pydantic serialisation. The label is an in-process snapshot witness for operator projections, not a new repair-result field.

with_active_profile_label(label)[source]

Attach the committed-capsule label captured during this health assessment.

Return type:

ActiveProfileHealth

Parameters:

label (str | None)

class ActiveProfileRepairResult(**data)[source]

Bases: BaseModel

Result of a safe active-profile pointer repair probe/action.

Parameters:

data (Any)

dry_run: bool
cleared_pointer: bool
before: ActiveProfileHealth
after: ActiveProfileHealth | None
unavailable_profile_record_verdict(*, status, source, repairable_by_clearing_pointer)[source]

Classify an unreadable or absent profile record without CLI recovery prose.

A pointer-backed broken active profile has one safe local recovery: clear that pointer after the operator supplies confirmation. An explicit profile override, or a non-active record being inspected, has no command we can honestly materialise from the observed facts, so it carries an explicit operator_decision outcome instead.

Return type:

PreconditionVerdict

Parameters:

  • status (Literal[ProfileHealthStatus.MISSING_PROFILE_RECORD, ProfileHealthStatus.PROFILE_RECORD_UNREADABLE])

  • source (ProfileSource)

  • repairable_by_clearing_pointer (bool)

assess_active_profile_health(state=None, *, operation)[source]

Return a redacted, non-secret projection from current authenticated state.

This is an observation boundary: it reads only the already-bound current profile-record or custody session; health assessment never unlocks a capsule or constructs a credential provider.

An absent session is reported as profile_locked and routed to the login action for the capsule’s own label. It is NOT an absent or unreadable record: the capsule is committed and the record is intact, and nothing about that record is knowable until someone logs in. Whether a record is genuinely gone is answered by the capsule projection above, which still refuses a selector with no committed capsule as dangling_pointer, so real data loss keeps its own verdict rather than hiding behind the benign one.

Return type:

ActiveProfileHealth

Parameters:
repair_active_profile_pointer(*, clear_active, confirmed, operation)[source]

Clear an eligible degraded pointer-file active profile after locked reassessment.

The preliminary best-effort probe keeps cold, unconfirmed, and ineligible calls read-only. A confirmed repair candidate acquires the bounded pointer transaction, then performs an authoritative locked reassessment whose repairable_by_clearing_pointer flag is the sole eligibility authority. The returned before is that locked reassessment, and after is measured before releasing the transaction. Lock contention propagates without pointer mutation.

Return type:

ActiveProfileRepairResult

Parameters: