Guard Control

GuardDecision, RiskEnvelope, and NoGoPolicy are the shared policy contracts used by high-risk verifier adapters. They keep risk classification, calibrated thresholds, evidence references, and policy escalation separate from raw tenant payloads.

Irreversibility Forecasting

NoGoPolicy runs the irreversibility forecaster by default when both conditions hold:

• the upstream decision risk score is at or above risk_envelope.calibrated_threshold
• the decision carries a tenant-safe action label or action sequence

The policy blocks when the conservative lower confidence bound of the forecast crosses irreversible_threshold. This prevents a point estimate alone from blocking high-risk actions while still stopping action sequences whose irreversibility remains high under interval uncertainty.

For production high-risk paths, pass a ReviewedIrreversibilityThreshold. This represents a reviewed conformal threshold with source reference, reviewer identity, calibration size, coverage, and approval status. When a high-risk decision crosses the calibrated risk threshold and the forecast lower bound crosses the reviewed threshold, the policy returns no_go_reviewed_irreversibility_forecast.

from director_ai.core.guard_control import (
    GuardDecision,
    NoGoPolicy,
    ReviewedIrreversibilityThreshold,
    RiskEnvelope,
)

risk = RiskEnvelope(
    action_category="tool",
    reversibility="costly",
    domain="security",
    calibrated_threshold=0.7,
    no_go_threshold=0.95,
)

decision = GuardDecision(
    decision="warn",
    risk_score=0.78,
    confidence_low=0.69,
    confidence_high=0.86,
    policy_id="policy.ops",
    reason="operator_review",
    tenant_safe_explanation="The action needs operator review.",
    evidence_refs=("ops:change-7",),
    verifier_signals=(),
    risk_envelope=risk,
    attributes={"action_sequence": "preview deployment\ndelete production table"},
)

verdict = NoGoPolicy(
    irreversible_threshold=0.95,
    reviewed_irreversibility_threshold=ReviewedIrreversibilityThreshold(
        threshold=0.75,
        source_ref="calibration://irreversibility/2026-05-13",
        reviewer_id="reviewer-passport-a",
        calibration_size=256,
        coverage=0.95,
    ),
).evaluate(decision)
assert verdict.decision in {"warn", "block"}

Only tenant-safe action labels belong in action_sequence, action_description, proposed_action, tool_action, or physical_action. Raw prompts, credentials, private sensor packets, media payloads, and generated content remain outside the policy attributes and should be referenced by opaque evidence ids.

Consensus Wiring

CrossVerifierConsensus.decide() accepts the same tenant-safe action sequence and forwards it through the no-go policy path. Forecast metadata is preserved in decision attributes using numeric strings suitable for telemetry:

from director_ai.core.guard_control import NoGoPolicy, RiskEnvelope, VerifierSignal
from director_ai.core.scoring.consensus import CrossVerifierConsensus

signal = VerifierSignal(
    verifier="policy",
    modality="policy",
    score=0.61,
    verdict="uncertain",
    confidence_low=0.54,
    confidence_high=0.73,
    evidence_refs=("policy:change-risk",),
)

decision = CrossVerifierConsensus(no_go_policy=NoGoPolicy()).decide(
    (signal,),
    risk_envelope=RiskEnvelope(
        action_category="tool",
        reversibility="costly",
        domain="financial",
        calibrated_threshold=0.5,
        no_go_threshold=0.95,
    ),
    policy_id="policy.finance.ops",
    action_sequence=("stage plan", "transfer funds"),
)

When the no-go policy blocks from a forecast, decision.reason is "no_go_irreversibility_forecast" or "no_go_reviewed_irreversibility_forecast" and the attributes include irreversibility_forecast_p, irreversibility_forecast_ci_low, irreversibility_forecast_ci_high, and irreversibility_forecast_samples. Reviewed thresholds also add reviewed threshold provenance attributes.

Full API

director_ai.core.guard_control.GuardDecision dataclass

GuardDecision(decision: str, risk_score: float, confidence_low: float, confidence_high: float, policy_id: str, reason: str, tenant_safe_explanation: str, evidence_refs: Sequence[str], verifier_signals: Sequence[VerifierSignal], risk_envelope: RiskEnvelope, attributes: Mapping[str, str] = dict())

Normalized decision shared by future guard-control modules.

to_dict

to_dict() -> dict[str, Any]

Serialise without raw tenant payload fields.

to_safety_event

to_safety_event(*, hook_id: str, hook_scope: str, request_id: str = '', tenant_id: str = '', latency_ms: float | None = None) -> SafetyEvent

Convert this decision into the shared tenant-safe event schema.

director_ai.core.guard_control.RiskEnvelope dataclass

RiskEnvelope(action_category: str, reversibility: str, domain: str, calibrated_threshold: float, no_go_threshold: float)

Risk category and calibrated thresholds for one proposed action.

to_dict

to_dict() -> dict[str, Any]

Return a JSON-safe representation.

director_ai.core.guard_control.VerifierSignal dataclass

VerifierSignal(verifier: str, modality: str, score: float, verdict: str, confidence_low: float, confidence_high: float, evidence_refs: Sequence[str] = tuple(), latency_ms: float = 0.0, failure_mode: str = '')

One normalized signal emitted by a verifier or policy subsystem.

to_dict

to_dict() -> dict[str, Any]

Return a JSON-safe, tenant-safe representation.

director_ai.core.guard_control.NoGoPolicy

NoGoPolicy(*, default_threshold: float = 0.9, irreversible_threshold: float = 0.6, require_human_review_for_irreversible: bool = True, irreversibility_forecaster: _IrreversibilityForecasterLike | None = None, forecast_seed: int = 0, forecast_action_keys: Sequence[str] = ('action_sequence', 'action_description', 'proposed_action', 'tool_action', 'physical_action'), enable_irreversibility_forecast: bool = True, reviewed_irreversibility_threshold: ReviewedIrreversibilityThreshold | None = None)

Block irreversible or threshold-exceeding decisions deterministically.

The default path also evaluates tenant-safe action labels through the irreversibility forecaster once the upstream decision crosses the calibrated risk threshold. The policy blocks only on the conservative lower confidence bound, so uncertain forecasts escalate through review instead of being treated as proof.

evaluate

evaluate(decision: GuardDecision) -> NoGoVerdict

Return the final deterministic no-go verdict.

director_ai.core.guard_control.NoGoVerdict dataclass

NoGoVerdict(decision: str, reason: str, requires_human_review: bool, original_decision: GuardDecision, forecast: Forecast | None = None, reviewed_threshold: ReviewedIrreversibilityThreshold | None = None)

Result of applying :class:NoGoPolicy to a guard decision.

director_ai.core.guard_control.ReviewedIrreversibilityThreshold dataclass

ReviewedIrreversibilityThreshold(threshold: float, source_ref: str, reviewer_id: str, calibration_size: int, coverage: float, approved: bool = True)

Reviewed conformal threshold for forecast-based no-go blocking.

to_attributes

to_attributes() -> dict[str, str]

Return tenant-safe threshold provenance for telemetry.