#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VerificationKind {
Tests,
Compilation,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum UnknownReason {
Timeout,
Cancelled,
Signalled,
NoResultLine,
ZeroExecuted,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VerificationOutcome {
Passed,
Failed,
Unknown(UnknownReason),
}
impl VerificationOutcome {
pub fn is_passed(&self) -> bool {
matches!(self, Self::Passed)
}
pub fn unknown_reason(&self) -> Option<UnknownReason> {
match self {
Self::Unknown(reason) => Some(*reason),
Self::Passed | Self::Failed => None,
}
}
pub fn label(&self) -> &'static str {
match self {
Self::Passed => "passed",
Self::Failed => "failed",
Self::Unknown(_) => "unknown",
}
}
}
impl UnknownReason {
pub fn label(&self) -> &'static str {
match self {
Self::Timeout => "timeout",
Self::Cancelled => "cancelled",
Self::Signalled => "signalled",
Self::NoResultLine => "no_result_line",
Self::ZeroExecuted => "zero_executed",
}
}
}
impl VerificationKind {
pub fn label(&self) -> &'static str {
match self {
Self::Tests => "tests",
Self::Compilation => "compilation",
}
}
}
pub fn classify(
kind: VerificationKind,
timed_out: bool,
cancelled: bool,
code: Option<i32>,
results: usize,
executed: usize,
) -> VerificationOutcome {
if timed_out {
return VerificationOutcome::Unknown(UnknownReason::Timeout);
}
if cancelled {
return VerificationOutcome::Unknown(UnknownReason::Cancelled);
}
match code {
None => VerificationOutcome::Unknown(UnknownReason::Signalled),
Some(0) if kind == VerificationKind::Tests && results == 0 => {
VerificationOutcome::Unknown(UnknownReason::NoResultLine)
}
Some(0) if kind == VerificationKind::Tests && executed == 0 => {
VerificationOutcome::Unknown(UnknownReason::ZeroExecuted)
}
Some(0) => VerificationOutcome::Passed,
Some(_) => VerificationOutcome::Failed,
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Completion {
pub answered: bool,
pub applied: bool,
pub verified: Option<VerificationOutcome>,
pub accepted: bool,
}
impl Completion {
pub fn answered() -> Self {
Self {
answered: true,
applied: false,
verified: None,
accepted: false,
}
}
pub fn applied() -> Self {
Self {
answered: true,
applied: true,
verified: None,
accepted: false,
}
}
pub fn verified(outcome: VerificationOutcome) -> Self {
Self {
answered: true,
applied: false,
verified: Some(outcome),
accepted: false,
}
}
pub fn accepted() -> Self {
Self {
answered: true,
applied: false,
verified: None,
accepted: true,
}
}
pub fn verification_closes(&self) -> bool {
self.verified.is_some_and(|outcome| outcome.is_passed())
}
pub fn is_complete(&self, acceptance_required: bool) -> bool {
self.applied && self.verification_closes() && (!acceptance_required || self.accepted)
}
}
pub const EXECUTION_DIMENSIONS: &[&str] = &[
"candidate",
"toolchain",
"target",
"profile",
"features",
"no_default_features",
"selection",
"mode",
"checker",
"isolation",
];
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ExecutionIdentity {
fields: Vec<(String, String)>,
}
impl ExecutionIdentity {
pub fn of<I, K, V>(fields: I) -> Result<Self, String>
where
I: IntoIterator<Item = (K, V)>,
K: Into<String>,
V: Into<String>,
{
let mut bound: Vec<(String, String)> = Vec::new();
for (name, value) in fields {
let name = name.into();
let value = value.into();
if !EXECUTION_DIMENSIONS.contains(&name.as_str()) {
return Err(format!(
"`{name}` is not an execution dimension; the list is fixed so a new one cannot be forgotten silently"
));
}
if value.trim().is_empty() {
return Err(format!(
"execution dimension `{name}` has no value; record `unknown` explicitly instead of binding nothing"
));
}
bound.push((name, value));
}
bound.sort();
bound.dedup();
for dimension in EXECUTION_DIMENSIONS {
if !bound.iter().any(|(name, _)| name == dimension) {
return Err(format!(
"execution identity is missing the `{dimension}` dimension; binding fewer dimensions than the list would reuse evidence across a difference it never recorded"
));
}
}
if bound.len() != EXECUTION_DIMENSIONS.len() {
return Err(
"execution identity binds the same dimension twice; a duplicated dimension would hide the one it displaced"
.to_owned(),
);
}
Ok(Self { fields: bound })
}
pub fn fields(&self) -> &[(String, String)] {
&self.fields
}
pub fn digest(&self) -> String {
crate::sha256_hex(self.render_summary().as_bytes())
}
pub fn render_summary(&self) -> String {
self.fields
.iter()
.map(|(name, value)| format!("{name}={value}"))
.collect::<Vec<_>>()
.join("; ")
}
pub fn is_the_same_run_as(&self, other: &Self) -> bool {
self.fields == other.fields
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Receipt {
pub obligation: String,
pub execution: ExecutionIdentity,
pub input_manifest: String,
pub oracle_and_policy: String,
pub executed: usize,
pub outcome: VerificationOutcome,
pub coverage_confirmed: bool,
pub anomaly_undisposed: Witness,
pub scope_expanded: Witness,
pub published_form_changed: Witness,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Witness {
Known(bool),
Unknown(&'static str),
}
impl Witness {
fn refuses(&self, other: &Self) -> Option<String> {
for witness in [self, other] {
match witness {
Witness::Known(true) => {
return Some("the run recorded this dimension as changed".to_owned());
}
Witness::Unknown(why) => {
return Some(format!(
"nobody observed this dimension for the run ({why}), so reusing it would assume what was never looked for"
));
}
Witness::Known(false) => {}
}
}
None
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Reuse {
Allowed,
Refused(String),
}
impl Receipt {
pub fn reuse_against(&self, current: &Self) -> Reuse {
if self.obligation != current.obligation {
return Reuse::Refused(
"a different obligation's receipt cannot settle this one".to_owned(),
);
}
if self.execution != current.execution {
return Reuse::Refused(
"the execution identity differs: checker, toolchain, target, profile, features, mode, selection or isolation changed".to_owned(),
);
}
if self.input_manifest != current.input_manifest {
return Reuse::Refused(
"the input closure is not the one the run was made against".to_owned(),
);
}
if self.oracle_and_policy != current.oracle_and_policy {
return Reuse::Refused("the accepted oracle or policy changed".to_owned());
}
if self.executed == 0 {
return Reuse::Refused(
"the run executed no tests, so it establishes no behaviour".to_owned(),
);
}
if !matches!(self.outcome, VerificationOutcome::Passed) {
return Reuse::Refused("only a passed run is a receipt for this obligation".to_owned());
}
if !self.coverage_confirmed {
return Reuse::Refused(
"the run's coverage was assumed rather than confirmed".to_owned(),
);
}
for (name, stored, now) in [
(
"anomaly",
self.anomaly_undisposed,
current.anomaly_undisposed,
),
("scope", self.scope_expanded, current.scope_expanded),
(
"published form",
self.published_form_changed,
current.published_form_changed,
),
] {
if let Some(why) = stored.refuses(&now) {
return Reuse::Refused(match (name, why.as_str()) {
("anomaly", why) => format!(
"the anomaly dimension of this obligation is `{why}` — a flaky failure or an undisposed anomaly is attached to it"
),
_ => format!("{name} is not reusable: {why}"),
});
}
}
Reuse::Allowed
}
}
#[path = "rules.rs"]
mod rules;
pub use rules::*;
#[path = "decision.rs"]
mod decision;
pub use decision::*;
#[path = "grant.rs"]
mod grant;
pub use grant::*;
#[path = "task.rs"]
mod task;
pub use task::*;
#[cfg(test)]
#[path = "maintenance_tests.rs"]
mod maintenance_tests;