Skip to content

baldur.interfaces — Singleton Protocols & PRO-Boundary Markers

Protocol markers for the singletons resolved through ProviderRegistry — the governance and admin-identity contracts, plus the PRO-boundary service protocols (DLQ, emergency, error budget, bulkhead, canary, chaos, throttle, and others). OSS code consumes these via the registry; PRO ships the implementations.

Governance & admin identity

GovernanceChecker

Bases: Protocol

Protocol for governance gate evaluation.

Methods mirror baldur_pro.services.governance.checks exports that OSS code paths consume. PRO concrete adapter delegates to the real pipeline; the OSS NoOp default returns fail-open answers.

check_all_governance 

check_all_governance(
    check_kill_switch: bool = True,
    check_emergency: bool = True,
    emergency_min_level: int | None = None,
    check_error_budget: bool = True,
    operation_name: str = "unknown_operation",
    service_name: str | None = None,
    domain: str | None = None,
    audit_on_block: bool = True,
    tier_id: str | None = None,
    region: str | None = None,
    resource_context: dict[str, Any] | None = None,
) -> GovernanceCheckResult

Run all enabled governance gates; return aggregated result.

is_system_enabled 

is_system_enabled() -> bool

Return False when Kill Switch is active, True otherwise.

is_emergency_blocking 

is_emergency_blocking(
    min_level: int | None = None,
) -> tuple[bool, str]

Return (is_blocked, level_name) for the current emergency level.

is_error_budget_blocking 

is_error_budget_blocking(
    tier_id: str | None = None, region: str | None = None
) -> tuple[bool, float, float]

Return (is_blocked, current_pct, threshold_pct) for error budget.

invalidate_governance_cache 

invalidate_governance_cache() -> None

Invalidate the cached governance evaluation results.

Called by event-bus handlers when an underlying state transition (Kill Switch toggled, Emergency Level changed, Error Budget threshold crossed) must propagate immediately instead of waiting for TTL.

reset_governance_pipeline_cache 

reset_governance_pipeline_cache() -> None

Clear and rebuild the cached governance pipeline profiles.

Test-fixture utility — invoked by reset_protect_caches() so settings-mutating tests observe a fresh pipeline cache.

NoOpGovernanceChecker

Default OSS governance checker — fail-open for every check.

Registered as ProviderRegistry.governance default so OSS callers can invoke governance methods unconditionally. Returns "allowed" everywhere — the right behavior when PRO is absent (no governance pipeline to enforce).

AdminIdentityResolver

Bases: Protocol

Protocol for the PRO admin identity resolver.

OSS leaves ProviderRegistry.admin_identity_resolver empty; PRO ships the concrete resolver. The admin dispatch consumes any implementation via ProviderRegistry.admin_identity_resolver.safe_get().

Contract
  • trusted=False MUST return None — the forwarded identity header is never trusted from a direct (unproxied) caller (fail-closed on identity).
  • An absent / empty / whitespace-only header MUST return None (not a blank-username principal) so attribution degrades cleanly to "anonymous".

AdminPrincipal dataclass 

AdminPrincipal(username: str)

Authenticated admin operator identity.

Minimal principal satisfying the resolve_actor contract — it exposes username, the only attribute resolve_actor reads (getattr(user, "username", None)). Set onto RequestContext.user by the admin dispatch seam so audit records attribute control-plane actions to a real operator rather than "anonymous".

Frozen: a principal is an immutable per-request fact, never mutated after resolution.

Service singleton protocols

BlastRadiusManager

Bases: Protocol

Protocol for the PRO blast-radius manager singleton.

Bulkhead

Bases: Protocol

Protocol for an individual PRO bulkhead instance.

The structural return-type contract that PRO's bulkhead backends (SemaphoreBulkhead / ThreadPoolBulkhead) satisfy. OSS callers receive these instances from BulkheadRegistry.get() / get_or_create() and use them by duck typing; there is no OSS static-annotation consumer. @runtime_checkable plus the PRO contract test enforce conformance.

BulkheadRegistry

Bases: Protocol

Protocol for the PRO bulkhead registry singleton.

CanaryRollout

Bases: Protocol

Protocol for an individual PRO canary rollout instance.

Used as a TYPE_CHECKING-only annotation by OSS task wiring that holds a rollout reference but does not construct one — construction stays inside PRO via CanaryRolloutService.

state instance-attribute 

state: Any

Underlying CanaryState value — exposed as Any so OSS callers can compare with :class:baldur.models.canary.CanaryState without coupling to the PRO concrete attribute type.

created_at instance-attribute 

created_at: Any

datetime at PRO impl; Any here to keep this OSS Protocol free of a datetime import constraint.

paused_at instance-attribute 

paused_at: Any

datetime | None at PRO impl — when the rollout entered PAUSED. Watchdog anchor for the PAUSED stall clock (created_at fallback).

stage_started_at instance-attribute 

stage_started_at: Any

datetime | None at PRO impl — when the current stage's config was applied. Watchdog anchor for the per-stage observation window and the CANARY stall clock (created_at fallback for legacy rollouts).

CanaryRolloutService

Bases: Protocol

Protocol for the PRO canary rollout orchestration singleton.

ChaosScheduler

Bases: Protocol

Protocol for the PRO chaos experiment scheduler.

ReportGenerator

Bases: Protocol

Protocol for the PRO chaos report generator.

SafetyGuard

Bases: Protocol

Protocol for the PRO chaos safety guard.

DLQRepository

Bases: Protocol

Protocol for the PRO DLQ persistence layer.

DLQService

Bases: Protocol

Protocol for the PRO DLQ orchestrator.

EmergencyManager

Bases: Protocol

Protocol for the PRO emergency mode manager.

ErrorBudgetGate

Bases: Protocol

Protocol for the PRO error-budget gate singleton.

ErrorBudgetService

Bases: Protocol

Protocol for the PRO error-budget service singleton.

LearningServiceProtocol

Bases: Protocol

Protocol for the private-tier self-learning service singleton.

SelfhealerWatchdog

Bases: Protocol

Protocol for the PRO selfhealer watchdog singleton.

DistributedRecoveryLock

Bases: Protocol

Type marker for the PRO multi-backend recovery lock facade.

OSS code in the runbook executor holds a lock reference for type annotation but acquires/releases through PRO surface only.

IdempotencyRecord

Bases: Protocol

Type marker for the PRO idempotency record DTO.

Carries idempotency key + step lifecycle status. OSS code in the runbook executor reads identity/status fields for routing but does not construct records directly.

UnifiedNotificationManager

Bases: Protocol

Protocol for the PRO unified notification manager.

Used as a TYPE_CHECKING-only annotation by OSS modules that hold an injected manager reference (e.g., the runbook approval gate) and call its public dispatch method. The realized backend lives in :mod:baldur_pro.services.unified_notification.