Spectre.Governance.CandidateState (Spectre v0.3.0)

Immutable governance state attached to a Definition Candidate.

proposal_digest identifies the fixed proposal independently from later gate and approval receipts. Advancing the state creates a new outer Candidate.Ref, while every receipt remains bound to the same proposal. This avoids circular receipt identities without weakening content addressing.

Summary

Types

gate_class()

risk()

state()

t()

Functions

constitutional_gates(risk)

Returns the non-negotiable gate floor for a Candidate risk class.

gate_classes()

Returns the supported non-approval gate classes.

new(state)

Builds and verifies a Candidate governance state.

new!(attrs)

Builds governance state or raises with the stable validation reason.

proposal_digest(state)

Returns the immutable proposal digest from normalized core fields.

schema_version()

Returns the governance Candidate-state schema version.

to_data(state)

Returns portable governance state data.

transition(current, next, opts \\ [])

Advances mutable review state while preserving the proposal digest.

Types

gate_class()

@type gate_class() ::
  :structural
  | :authority
  | :closure
  | :prompt_budget
  | :applicability
  | :replay
  | :regression
  | :semantic_live
  | :evaluation_delta

risk()

@type risk() :: :low | :medium | :high | :critical

state()

@type state() :: :composed | :evaluated | :approved | :rejected

t()

@type t() :: %Spectre.Governance.CandidateState{
  applicability_ceilings: map(),
  approval_receipt_ref: String.t() | nil,
  base_activation_receipt: String.t(),
  base_candidate_ref: String.t(),
  candidate_case_ids: [String.t()],
  candidate_cases: [map()],
  candidate_definition_ref: String.t(),
  change_set_digest: String.t(),
  closure_digest: String.t(),
  evaluation_cases_digest: String.t(),
  gate_receipt_refs: [String.t()],
  lineage_refs: [String.t()],
  observed_authority_epoch: non_neg_integer(),
  observed_evidence_digest: String.t(),
  parent_definition_ref: String.t(),
  prompt_token_ceiling: number() | nil,
  proposal_digest: String.t(),
  protected_cases_digest: String.t(),
  report: Spectre.Projection.HumanReport.t() | nil,
  report_digest: String.t() | nil,
  required_gates: [gate_class()],
  risk: risk(),
  schema_version: pos_integer(),
  state: state(),
  state_migrations: [map()]
}

Functions

constitutional_gates(risk)

@spec constitutional_gates(risk()) :: [gate_class()]

Returns the non-negotiable gate floor for a Candidate risk class.

gate_classes()

@spec gate_classes() :: [gate_class()]

Returns the supported non-approval gate classes.

new(state)

@spec new(t() | map() | keyword()) :: {:ok, t()} | {:error, term()}

Builds and verifies a Candidate governance state.

new!(attrs)

@spec new!(map() | keyword()) :: t()

Builds governance state or raises with the stable validation reason.

proposal_digest(state)

@spec proposal_digest(t() | map()) :: String.t()

Returns the immutable proposal digest from normalized core fields.

schema_version()

@spec schema_version() :: pos_integer()

Returns the governance Candidate-state schema version.

to_data(state)

@spec to_data(t()) :: map()

Returns portable governance state data.

transition(current, next, opts \\ [])

@spec transition(t(), state(), keyword()) :: {:ok, t()} | {:error, term()}

Advances mutable review state while preserving the proposal digest.