SPDX-License-Identifier: AGPL-3.0-or-later

Commercial license available

© Concepts 1996–2026 Miroslav Šotek. All rights reserved.

© Code 2020–2026 Miroslav Šotek. All rights reserved.

ORCID: 0009-0009-3560-0851

Contact: www.anulum.li | protoscience@anulum.li

SCPN Phase Orchestrator — Autotune candidate safety certificate API reference

Autotune Candidate Safety Certificate

A reward report and a per-knob attribution say whether a candidate is good and why. They do not say whether it is safe. Before a candidate goes anywhere near a plant, a reviewer needs the safety question answered with evidence rather than a clamp: did the system stay inside the safe set under this candidate, with what margin, and is that margin a measured replay outcome or a proven forward-invariant one?

certify_candidate_safety produces that evidence by combining three sources into one content-addressed certificate:

• Barrier margin — the worst value of a control-barrier function h(x) over the states the candidate visited in replay. A non-negative worst margin means the system never left the safe set {x : h(x) >= 0}; the number of violating states is reported alongside it. Replay states must be finite numeric vectors, and every barrier evaluation must return a finite margin; malformed evidence is rejected instead of being interpreted as safe.
• Constraint margins — the worst Lyapunov-exponent, STL-robustness, and safety-cost margins over the replay observations against the bounds in a SafetyConstraintConfig, with the proposal gate's require-evidence semantics: a required constraint whose evidence is missing fails closed.
• Forward invariance — an optional BarrierCertificate from a forward-invariance verification. When it is present, verified, and the replay stayed within its certified shell, the certificate's evidence is reported as formally proven; otherwise it is a measured replay margin. The certificate also carries filter_digest and verification_digest fields so a runtime CBF caller can reject stale or mismatched neural-barrier evidence.

import numpy as np

from scpn_phase_orchestrator.actuation.control_barrier import NeuralBarrier
from scpn_phase_orchestrator.autotune import (
    KnobPolicyCandidate,
    RewardObservation,
    SafetyConstraintConfig,
    certify_candidate_safety,
)

candidate = KnobPolicyCandidate(alpha=0.1, zeta=0.05)
# h(x) = x[0]; the safe set is {x : x[0] >= 0}.
barrier = NeuralBarrier(weights=(np.array([[1.0]]),), biases=(np.array([0.0]),))

certificate = certify_candidate_safety(
    candidate,
    [
        RewardObservation(coherence=0.82, lyapunov_exponent=-0.02, safety_cost=0.01),
        RewardObservation(coherence=0.85, lyapunov_exponent=-0.03, safety_cost=0.02),
    ],
    SafetyConstraintConfig(max_lyapunov_exponent=0.0, max_safety_cost=0.1),
    barrier=barrier,
    replay_states=np.array([[0.5], [0.7]]),
)

assert certificate.safe is True
assert certificate.evidence_kind == "measured"  # no forward-invariance supplied
record = certificate.to_audit_record()
assert record["digest"] == certificate.digest

Why a certificate, not a clamp

A control-barrier filter keeps a single live action safe by projecting it onto the admissible set. That is the right tool at run time, but it leaves no reviewable statement about a candidate: a reviewer cannot tell, from a clamp, whether the candidate was already safe or was silently corrected on every step. The certificate is the complementary artefact — it records the margin the candidate actually held over a replay and, where a forward-invariance proof covers that replay, upgrades the claim from measured to formally proven. That distinction is deliberately preserved: a proven margin and a measured one are different modalities of evidence, not different grades of the same number.

The certificate also fails closed on numeric evidence: empty observations, missing barrier states, non-finite replay states, and non-finite barrier margins raise ValueError before a certificate is emitted. This prevents NaN barrier values from bypassing the violation count.

Where this sits in the autotune track

The certificate consumes the same candidate surface as Reward Evaluation and Per-Knob Attribution. Together they answer a reviewer's three questions about a candidate — is it good, why, and is it safe — as evidence rather than action: the function actuates nothing and only emits a sealed record.

candidate_safety_certificate

Bind an autotune candidate to a safety certificate over a replay.

A reward report and a per-knob attribution say whether a candidate is good and why. They do not say whether it is safe. Before a candidate is allowed near a plant a reviewer needs the safety question answered with evidence, not a clamp: did the system stay inside the safe set under this candidate, with what margin, and is that margin a measured replay outcome or a proven forward-invariant one?

:func:certify_candidate_safety answers that by combining three sources:

• Barrier margin — the worst value of a control-barrier function h(x) over the states the candidate visited in replay. A non-negative worst margin means the system never left the safe set {x : h(x) >= 0}; the count of violating states is reported alongside it.
• Constraint margins — the worst Lyapunov-exponent, STL-robustness, and safety-cost margins over the replay observations against the bounds in a :class:~scpn_phase_orchestrator.autotune.reward.SafetyConstraintConfig, with the same require-evidence semantics as the proposal gate: a required constraint whose evidence is missing fails closed.
• Forward invariance — an optional :class:~scpn_phase_orchestrator.actuation.control_barrier.BarrierCertificate from a forward-invariance verification. When it is present, verified, and the replay stayed within its certified shell, the certificate's evidence is formally proven; otherwise it is a measured replay margin.

The certificate is content-addressed (a canonical-JSON SHA-256 seal) and the function performs no control actuation.

Classes

CandidateSafetyCertificate dataclass

CandidateSafetyCertificate(
    candidate: KnobPolicyCandidate,
    barrier_worst_margin: float | None,
    barrier_violations: int,
    lyapunov_margin: float | None,
    stl_margin: float | None,
    safety_cost_margin: float | None,
    constraint_verdicts: Mapping[str, bool],
    forward_invariance_verified: bool | None,
    evidence_kind: str,
    safe: bool,
    digest: str,
)

A safety certificate for one candidate over a replay window.

Parameters

candidate : KnobPolicyCandidate The certified candidate. barrier_worst_margin : float | None The smallest barrier value h(x) over the replay states, or None when no barrier was supplied. Non-negative means the safe set was never left. barrier_violations : int The number of replay states with a negative barrier value. lyapunov_margin : float | None max_lyapunov_exponent minus the worst (largest) replay Lyapunov exponent, or None when the constraint is not configured. stl_margin : float | None The worst (smallest) replay STL robustness minus min_stl_robustness, or None when the constraint is not configured. safety_cost_margin : float | None max_safety_cost minus the worst (largest) replay safety cost, or None when the constraint is not configured. constraint_verdicts : Mapping[str, bool] Pass/fail verdict for each of "lyapunov", "stl" and "safety_cost"; a constraint that is not configured passes. forward_invariance_verified : bool | None The verification flag of a supplied forward-invariance certificate, or None when none was supplied. evidence_kind : str "formally-proven" when a verified forward-invariance certificate covers the replay, otherwise "measured". safe : bool True when there are no barrier violations and every constraint verdict passes. digest : str Canonical-JSON SHA-256 content address of the certificate body.

Methods:

to_audit_record

to_audit_record() -> dict[str, object]

Return a JSON-ready, deterministic record of the certificate.

Returns

dict[str, object] A mapping with the margins, per-constraint verdicts, evidence kind, overall safety verdict, and the content-address digest.

Source code in src/scpn_phase_orchestrator/autotune/candidate_safety_certificate.py

def to_audit_record(self) -> dict[str, object]:
    """Return a JSON-ready, deterministic record of the certificate.

    Returns
    -------
    dict[str, object]
        A mapping with the margins, per-constraint verdicts, evidence kind,
        overall safety verdict, and the content-address digest.
    """
    body = _certificate_body(
        barrier_worst_margin=self.barrier_worst_margin,
        barrier_violations=self.barrier_violations,
        lyapunov_margin=self.lyapunov_margin,
        stl_margin=self.stl_margin,
        safety_cost_margin=self.safety_cost_margin,
        constraint_verdicts=self.constraint_verdicts,
        forward_invariance_verified=self.forward_invariance_verified,
        evidence_kind=self.evidence_kind,
        safe=self.safe,
    )
    return {**body, "digest": self.digest}

Functions:

certify_candidate_safety

certify_candidate_safety(
    candidate: KnobPolicyCandidate,
    observations: Sequence[RewardObservation],
    constraints: SafetyConstraintConfig,
    *,
    barrier: NeuralBarrier | None = None,
    replay_states: Sequence[FloatArray]
    | FloatArray
    | None = None,
    forward_invariance: BarrierCertificate | None = None,
) -> CandidateSafetyCertificate

Certify a candidate's safety over a replay window.

The candidate is certified against a control-barrier function over the states it visited, against the Lyapunov, STL, and safety-cost bounds over the replay observations, and against an optional forward-invariance certificate. The result is content-addressed and carries no control action.

Parameters

candidate : KnobPolicyCandidate The candidate being certified. observations : Sequence[RewardObservation] The per-step replay observations carrying the Lyapunov exponent, STL robustness, and safety cost. Must be non-empty. constraints : SafetyConstraintConfig The Lyapunov/STL/safety-cost bounds and their require-evidence flags. barrier : NeuralBarrier | None A control-barrier function h(x). When supplied, replay_states is required and the worst margin over those states is certified. replay_states : Sequence[FloatArray] | FloatArray | None The states the candidate visited, as a 2-D array or a sequence of state vectors. Required when barrier is supplied. forward_invariance : BarrierCertificate | None An optional forward-invariance certificate for the barrier. When it is verified and the replay stayed within its certified shell, the evidence is reported as formally proven.

Returns

CandidateSafetyCertificate The sealed certificate.

Raises

ValueError If observations is empty, or if barrier is supplied without replay_states (or with empty/non-finite states or margins).

Source code in src/scpn_phase_orchestrator/autotune/candidate_safety_certificate.py

def certify_candidate_safety(
    candidate: KnobPolicyCandidate,
    observations: Sequence[RewardObservation],
    constraints: SafetyConstraintConfig,
    *,
    barrier: NeuralBarrier | None = None,
    replay_states: Sequence[FloatArray] | FloatArray | None = None,
    forward_invariance: BarrierCertificate | None = None,
) -> CandidateSafetyCertificate:
    """Certify a candidate's safety over a replay window.

    The candidate is certified against a control-barrier function over the states
    it visited, against the Lyapunov, STL, and safety-cost bounds over the replay
    observations, and against an optional forward-invariance certificate. The
    result is content-addressed and carries no control action.

    Parameters
    ----------
    candidate : KnobPolicyCandidate
        The candidate being certified.
    observations : Sequence[RewardObservation]
        The per-step replay observations carrying the Lyapunov exponent, STL
        robustness, and safety cost. Must be non-empty.
    constraints : SafetyConstraintConfig
        The Lyapunov/STL/safety-cost bounds and their require-evidence flags.
    barrier : NeuralBarrier | None
        A control-barrier function ``h(x)``. When supplied, ``replay_states`` is
        required and the worst margin over those states is certified.
    replay_states : Sequence[FloatArray] | FloatArray | None
        The states the candidate visited, as a 2-D array or a sequence of state
        vectors. Required when ``barrier`` is supplied.
    forward_invariance : BarrierCertificate | None
        An optional forward-invariance certificate for the barrier. When it is
        verified and the replay stayed within its certified shell, the evidence
        is reported as formally proven.

    Returns
    -------
    CandidateSafetyCertificate
        The sealed certificate.

    Raises
    ------
    ValueError
        If ``observations`` is empty, or if ``barrier`` is supplied without
        ``replay_states`` (or with empty/non-finite states or margins).
    """
    if len(observations) == 0:
        raise ValueError("observations must be non-empty")

    barrier_worst_margin, barrier_violations = _barrier_margins(barrier, replay_states)

    lyapunov_margin, lyapunov_ok = _bounded_constraint(
        constraints.max_lyapunov_exponent,
        required=constraints.require_lyapunov,
        values=[obs.lyapunov_exponent for obs in observations],
        higher_is_safe=False,
    )
    stl_margin, stl_ok = _bounded_constraint(
        constraints.min_stl_robustness,
        required=constraints.require_stl,
        values=[obs.stl_robustness for obs in observations],
        higher_is_safe=True,
    )
    safety_cost_margin, safety_cost_ok = _bounded_constraint(
        constraints.max_safety_cost,
        required=constraints.require_safety_cost,
        values=[obs.safety_cost for obs in observations],
        higher_is_safe=False,
    )
    constraint_verdicts = {
        "lyapunov": lyapunov_ok,
        "stl": stl_ok,
        "safety_cost": safety_cost_ok,
    }

    forward_invariance_verified = (
        None if forward_invariance is None else forward_invariance.verified
    )
    within_shell = (
        forward_invariance is not None
        and forward_invariance.verified
        and barrier_worst_margin is not None
        and barrier_worst_margin >= forward_invariance.boundary_shell
    )
    evidence_kind = _FORMALLY_PROVEN if within_shell else _MEASURED

    safe = barrier_violations == 0 and all(constraint_verdicts.values())

    body = _certificate_body(
        barrier_worst_margin=barrier_worst_margin,
        barrier_violations=barrier_violations,
        lyapunov_margin=lyapunov_margin,
        stl_margin=stl_margin,
        safety_cost_margin=safety_cost_margin,
        constraint_verdicts=constraint_verdicts,
        forward_invariance_verified=forward_invariance_verified,
        evidence_kind=evidence_kind,
        safe=safe,
    )
    return CandidateSafetyCertificate(
        candidate=candidate,
        barrier_worst_margin=barrier_worst_margin,
        barrier_violations=barrier_violations,
        lyapunov_margin=lyapunov_margin,
        stl_margin=stl_margin,
        safety_cost_margin=safety_cost_margin,
        constraint_verdicts=constraint_verdicts,
        forward_invariance_verified=forward_invariance_verified,
        evidence_kind=evidence_kind,
        safe=safe,
        digest=_seal(body),
    )