Skip to content

symfonic.capabilities.governance.records

records

The verdict a stage returns and the record the pipeline keeps (T3.4.4).

Every decision carries its reason and its evidence. "Why was this turn refused?" and "why is this draft missing three sentences?" are answerable from the outcome alone, without re-running anything.

GovernanceOutcome dataclass 

GovernanceOutcome(subject: GovernanceSubject, trace: tuple[StageRecord, ...] = (), refusal: StageRecord | None = None)

The governed turn: the surviving subject and the whole trail.

StageRecord dataclass 

StageRecord(stage: str, phase: GovernancePhase, failure_mode: FailureMode, disposition: Disposition, reason: str = '', objection: str = '', findings: tuple[Finding, ...] = (), evidence: Mapping[str, Any] = dict(), degraded: bool = False, downgraded: bool = False)

What one stage did, including the stages that did nothing.

degraded means the stage failed and the declared failure mode decided the rest. downgraded means the stage worked and observe mode suppressed its terminal effect. Two flags because they are two different post-mortems.

StageVerdict dataclass 

StageVerdict(disposition: Disposition, reason: str = '', objection: str = '', subject: GovernanceSubject | None = None, findings: tuple[Finding, ...] = (), evidence: Mapping[str, Any] = dict())

One stage's answer. Built through the four constructors, not by hand.

allow classmethod 

allow(reason: str = '', *, evidence: Mapping[str, Any] | None = None, findings: Sequence[Finding] = ()) -> StageVerdict

Admit the subject, optionally saying what was noticed on the way.

findings on an allow is not a contradiction. A rule that repaired a call and raised no objection admitted it -- and still decided something an operator needs attributed. Without this the repair travelled anonymously, because only objections were recorded.

Source code in src/symfonic/capabilities/governance/records.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
@classmethod
def allow(
    cls,
    reason: str = "",
    *,
    evidence: Mapping[str, Any] | None = None,
    findings: Sequence[Finding] = (),
) -> StageVerdict:
    """Admit the subject, optionally saying what was noticed on the way.

    ``findings`` on an *allow* is not a contradiction. A rule that
    repaired a call and raised no objection admitted it -- and still
    decided something an operator needs attributed. Without this the
    repair travelled anonymously, because only objections were recorded.
    """
    return cls(
        Disposition.ALLOW,
        reason=reason,
        evidence=dict(evidence or {}),
        findings=tuple(findings),
    )