use crate::{
Artifact, ContractError, artifact_shape, from_json, hex, identifier, nonempty, relative_path,
require, sha256,
};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;
pub const MAX_PLAN_CHECKS: usize = 1024;
pub const MAX_PLAN_DURATION_MS: u64 = 86_400_000;
pub const MAX_PLAN_OUTPUT_BYTES: u64 = 1_073_741_824;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Subject {
pub repository: String,
pub revision: String,
pub configuration: String,
pub dirty: bool,
pub working_tree: Option<Artifact>,
pub inputs: Vec<Artifact>,
}
impl Subject {
pub fn validate(&self) -> Result<(), ContractError> {
require(nonempty(&self.repository), "subject.repository is required")?;
require(
hex(&self.revision, &[40, 64]),
"subject.revision must be a full Git id",
)?;
require(
nonempty(&self.configuration),
"subject.configuration is required",
)?;
require(
self.dirty == self.working_tree.is_some(),
"dirty subject must have exactly one working-tree snapshot",
)?;
if let Some(a) = &self.working_tree {
artifact_shape(a)?;
}
validate_inputs(&self.inputs)
}
}
pub(crate) fn validate_inputs(inputs: &[Artifact]) -> Result<(), ContractError> {
require(!inputs.is_empty(), "subject inputs cannot be empty")?;
validate_input_paths(inputs)
}
pub(crate) fn validate_input_paths(inputs: &[Artifact]) -> Result<(), ContractError> {
let mut paths = BTreeSet::new();
for a in inputs {
artifact_shape(a)?;
require(paths.insert(&a.path), "duplicate input path")?;
}
Ok(())
}
pub(crate) fn same_inputs(a: &[Artifact], b: &[Artifact]) -> bool {
let values = |items: &[Artifact]| {
items
.iter()
.map(|x| (x.path.clone(), x.sha256.clone()))
.collect::<BTreeSet<_>>()
};
a.len() == b.len() && values(a) == values(b)
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Invocation {
pub program: String,
pub args: Vec<String>,
pub cwd: String,
pub env: Vec<String>,
pub timeout_ms: u64,
pub max_output_bytes: u64,
}
impl Invocation {
pub fn validate(&self) -> Result<(), ContractError> {
require(nonempty(&self.program), "invocation.program is required")?;
require(
self.args.iter().all(|x| !x.contains('\0')),
"argv cannot contain NUL",
)?;
require(
self.cwd == "." || relative_path(&self.cwd),
"cwd must be a confined relative path",
)?;
let mut names = BTreeSet::new();
for name in &self.env {
require(
name.as_bytes()
.first()
.is_some_and(|b| b.is_ascii_alphabetic() || *b == b'_')
&& name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_'),
"invalid environment name",
)?;
require(names.insert(name), "duplicate environment name")?;
}
require(
(1..=86_400_000).contains(&self.timeout_ms),
"timeout_ms outside 1..=86400000",
)?;
require(
(1..=1_073_741_824).contains(&self.max_output_bytes),
"max_output_bytes outside 1..=1073741824",
)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum Evaluator {
ExitCode {
success_codes: Vec<i32>,
},
Reported {
adapter: String,
},
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CheckSpec {
pub id: String,
pub required: bool,
pub invocation: Invocation,
pub evaluator: Evaluator,
pub scope: Vec<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum EvidenceCategory {
Executable,
PartiallyVerifiable,
Manual,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Stabilizer {
pub check_id: String,
pub test_id: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Expectation {
pub id: String,
pub claim: String,
pub required: bool,
pub category: EvidenceCategory,
pub checks: Vec<String>,
pub regression_critical: bool,
pub stabilizer: Option<Stabilizer>,
pub positive_control: Option<String>,
pub independent_audit: bool,
pub limitation: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GatePolicy {
pub max_age_ms: Option<u64>,
pub require_observed_scope: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct QualityPlan {
pub version: u32,
pub id: String,
pub subject: Subject,
pub checks: Vec<CheckSpec>,
pub expectations: Vec<Expectation>,
pub policy: GatePolicy,
}
impl QualityPlan {
pub fn parse(bytes: &[u8]) -> Result<Self, ContractError> {
let plan: Self = from_json(bytes)?;
plan.validate()?;
Ok(plan)
}
pub fn validate(&self) -> Result<(), ContractError> {
require(self.version == 1, "unsupported plan version")?;
require(
self.checks.len() <= MAX_PLAN_CHECKS,
"plan check count exceeds admission ceiling",
)?;
require(identifier(&self.id), "invalid plan id")?;
self.subject.validate()?;
require(
!self.checks.is_empty() && self.checks.iter().any(|c| c.required),
"a gate requires at least one required check",
)?;
require(
self.policy.max_age_ms != Some(0),
"max_age_ms must be positive when present",
)?;
let inputs: BTreeSet<_> = self.subject.inputs.iter().map(|x| &x.path).collect();
let mut ids = BTreeSet::new();
let mut duration = 0_u64;
let mut output_bytes = 0_u64;
for c in &self.checks {
require(
identifier(&c.id) && ids.insert(&c.id),
"invalid or duplicate check id",
)?;
c.invocation.validate()?;
duration = duration
.checked_add(c.invocation.timeout_ms)
.ok_or_else(|| ContractError::Invalid("aggregate deadline overflow".into()))?;
output_bytes = output_bytes
.checked_add(c.invocation.max_output_bytes)
.ok_or_else(|| ContractError::Invalid("aggregate capture overflow".into()))?;
require(
duration <= MAX_PLAN_DURATION_MS,
"aggregate declared deadlines exceed one day",
)?;
require(
output_bytes <= MAX_PLAN_OUTPUT_BYTES,
"aggregate declared captures exceed one GiB",
)?;
require(!c.scope.is_empty(), "check scope cannot be empty")?;
let mut scope = BTreeSet::new();
for p in &c.scope {
require(
inputs.contains(p) && scope.insert(p),
"scope must uniquely reference subject inputs",
)?;
}
match &c.evaluator {
Evaluator::ExitCode { success_codes } => {
let codes: BTreeSet<_> = success_codes.iter().collect();
require(
!codes.is_empty()
&& codes.len() == success_codes.len()
&& success_codes.iter().all(|c| (0..=255).contains(c)),
"success_codes must be unique portable exit codes",
)?;
}
Evaluator::Reported { adapter } => require(
identifier(adapter),
"reported evaluator requires an adapter id",
)?,
}
}
let mut expectations = BTreeSet::new();
for e in &self.expectations {
require(
identifier(&e.id) && expectations.insert(&e.id),
"invalid or duplicate expectation id",
)?;
require(nonempty(&e.claim), "expectation claim is required")?;
let checks: BTreeSet<_> = e.checks.iter().collect();
require(
(!checks.is_empty()
|| (e.category == EvidenceCategory::Manual && !e.independent_audit))
&& checks.len() == e.checks.len()
&& checks.iter().all(|c| ids.contains(c)),
"expectation must uniquely reference declared checks",
)?;
require(
!e.regression_critical || e.stabilizer.is_some(),
"regression-critical expectation requires a stabilizer",
)?;
if let Some(s) = &e.stabilizer {
require(
ids.contains(&s.check_id) && nonempty(&s.test_id),
"invalid stabilizer reference",
)?;
}
if let Some(c) = &e.positive_control {
require(
ids.contains(c) && !checks.contains(c),
"positive control must be a distinct declared check",
)?;
}
if e.category != EvidenceCategory::Executable {
require(
e.limitation.as_deref().is_some_and(nonempty),
"partial/manual evidence requires a limitation",
)?;
}
}
Ok(())
}
pub fn digest(&self) -> Result<String, ContractError> {
self.validate()?;
let bytes = serde_json::to_vec(self)
.map_err(|_| ContractError::Invalid("plan serialization failed".into()))?;
Ok(sha256(&bytes))
}
}