cadrumo.application.user_profile.capabilities module¶

Profile-linked service-capability resolution.

A capability is the operator’s opt-in/opt-out of an external service, stored as a boolean fact under the profile schema capabilities section of the UserProfileRecord. This module resolves the effective posture by overlaying that profile fact onto the global Settings default and the global safety floor, returning a typed CapabilityDecision with the reason.

The load-bearing invariant: a capability may only NARROW the global safety floor, never widen it. The resolver is the single place this is computed; every gate routes through it.

cloud_evidence_upload is the one capability carrying an absolute safety-floor bar: gestor mode refuses it regardless of any profile opt-in, because a gestor never transmits a client’s document. It is also the standing ELIGIBILITY bar for the off-host evidence read — a layer above the per-invocation acknowledgement — and cloud_evidence_upload_eligible_for_active_profile() is the single production reading of it that every consent-offering surface must route through. While the bar is off, mint_evidence_consent_token() refuses, so no surface can offer a gate that could succeed.

GESTOR_BARRED_CAPABILITIES¶: Capabilities the global safety floor bars outright, whatever the profile fact says. Derived membership rather than an inline literal so the bar is one declaration the resolver and its gate both read: a member added here is gestor-barred everywhere the resolver runs, and there is no second list to forget.

class CapabilitySource(*values)[source]¶

Bases: StrEnum

Why a capability resolved the way it did.

PROFILE¶

DEFAULT¶

GLOBAL_SETTING¶

SAFETY_FLOOR¶

class CapabilityDecision(**data)[source]¶

Bases: BaseModel

The resolved posture of one service capability for a profile.

Parameters:: data (Any)

capability: ServiceCapability¶

enabled: bool¶

source: CapabilitySource¶

reason: str¶

resolve_capability(capability, *, profile_record, settings)[source]¶

Resolve capability for a UserProfileRecord against the global posture.

Pure: no I/O. Reads the profile’s capability fact (when present), falls back to the conservative capability default, and applies the global safety floor on top. The safety floor can only DISABLE, never enable.

Return type:

CapabilityDecision

Returns:

The resolved CapabilityDecision carrying the posture and reason.

Parameters:

capability (ServiceCapability)
profile_record (UserProfileRecord | None)
settings (Settings)

resolve_active_capability(capability, *, settings=None)[source]¶

Resolve capability for the active profile (or the global default when none).

Loads the active-profile record through a pure read of workflow state (no mutation, no bucket events), mirroring the output-language resolver. With no active profile, profile_record is None and the resolver falls back to the global default — so the posture is well-defined even before a profile is selected.

Return type:

CapabilityDecision

Returns:

The resolved CapabilityDecision for the active profile.

Parameters:

capability (ServiceCapability)
settings (Settings | None)

cloud_evidence_upload_eligible_for_active_profile(*, settings=None)[source]¶

Whether the active profile is eligible to be OFFERED the off-host consent gate.

The standing per-profile bar, distinct from the per-invocation acknowledgement it sits above: eligibility asks “may this profile ever be asked”, the acknowledgement asks “does the operator agree to this one read”. Default off (CLOUD_EVIDENCE_UPLOAD is the one capability defaulting off) and gestor-barred outright, so the answer here is False on an untouched deployment.

This is the SINGLE production reading of the bar. Every surface that would offer the operator an off-host acknowledgement passes this function’s result into mint_evidence_consent_token(), which refuses when it is False — so “the gate is never offered while the bar is off” is a property of the minting path rather than of each surface remembering to hide a prompt. A surface that skipped the check would still be unable to obtain a token.

Parameters:: settings (Settings | None) – Optional resolved settings override; loaded when omitted.
Return type:: bool
Returns:: True only when the profile’s resolved capability posture permits it.