Skip to main content

stateknot_testkit/
report.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4use crate::{
5    environment::{EnvironmentError, QualificationEnvironment, ReferenceEnvironmentViolation},
6    fault::{FaultCaseId, FaultError, FaultResult},
7    run::QualificationWindow,
8};
9use serde::{Deserialize, Serialize};
10use sha2::{Digest as _, Sha256};
11use std::{collections::BTreeSet, fmt::Write as _};
12use thiserror::Error;
13
14const REPORT_SCHEMA_VERSION: u16 = 1;
15const ENVELOPE_SCHEMA_VERSION: u16 = 1;
16const MAX_ENVELOPE_BYTES: usize = 8 * 1_024 * 1_024;
17const MAX_BUCKETS: usize = 16_384;
18
19/// Qualification execution profile.
20#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum QualificationProfile {
23    /// A small correctness-oriented CI or developer profile.
24    CiReduced,
25    /// The full reference-environment release candidate profile.
26    ReleaseCandidate,
27}
28
29/// Closed qualification scenario identifier.
30#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
31#[serde(rename_all = "snake_case")]
32pub enum QualificationScenario {
33    /// Concrete Agent host control-plane admission, execution and recovery.
34    AgentHostControlPlaneV1,
35}
36
37/// Shared latency signal with a version-one objective.
38#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
39#[serde(rename_all = "snake_case")]
40pub enum LatencySignal {
41    /// Client request start through durable admission response.
42    AdmissionCommit,
43    /// Runnable durable work through a fenced Worker claim.
44    RunnableClaim,
45    /// Durable event commit through client receipt on an established SSE stream.
46    SseDelivery,
47    /// Reconnect request through the first replayed event.
48    SseReconnect,
49}
50
51impl LatencySignal {
52    /// Every shared latency signal required for valid evidence.
53    pub const ALL: [Self; 4] = [
54        Self::AdmissionCommit,
55        Self::RunnableClaim,
56        Self::SseDelivery,
57        Self::SseReconnect,
58    ];
59}
60
61/// One non-empty HDR histogram bucket.
62#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
63#[serde(deny_unknown_fields)]
64pub struct LatencyBucket {
65    /// Inclusive upper value represented by this bucket, in microseconds.
66    pub upper_bound_micros: u64,
67    /// Observations represented since the previous recorded bucket.
68    pub count: u64,
69}
70
71/// Bounded latency distribution emitted by the recorder.
72#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
73#[serde(deny_unknown_fields)]
74pub struct LatencyDistribution {
75    /// Signal measured by this distribution.
76    pub signal: LatencySignal,
77    /// Calls made by the driver before coordinated-omission correction.
78    pub observed_samples: u64,
79    /// Samples stored in the HDR histogram after correction.
80    pub histogram_samples: u64,
81    /// 50th percentile in microseconds.
82    pub p50_micros: u64,
83    /// 95th percentile in microseconds.
84    pub p95_micros: u64,
85    /// 99th percentile in microseconds.
86    pub p99_micros: u64,
87    /// Maximum value in microseconds.
88    pub max_micros: u64,
89    /// Non-empty recorded histogram buckets.
90    pub buckets: Vec<LatencyBucket>,
91}
92
93impl LatencyDistribution {
94    pub(crate) fn validate(&self) -> Result<(), ReportError> {
95        if self.observed_samples == 0
96            || self.histogram_samples < self.observed_samples
97            || self.buckets.is_empty()
98            || self.buckets.len() > MAX_BUCKETS
99            || self.buckets.iter().any(|bucket| bucket.count == 0)
100            || self
101                .buckets
102                .windows(2)
103                .any(|pair| pair[0].upper_bound_micros >= pair[1].upper_bound_micros)
104            || self
105                .buckets
106                .iter()
107                .try_fold(0_u64, |sum, bucket| sum.checked_add(bucket.count))
108                != Some(self.histogram_samples)
109            || !(self.p50_micros <= self.p95_micros
110                && self.p95_micros <= self.p99_micros
111                && self.p99_micros <= self.max_micros)
112        {
113            return Err(ReportError::InvalidReport("invalid latency distribution"));
114        }
115        Ok(())
116    }
117}
118
119/// Counter selected by a driver for an exceptional correctness observation.
120#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
121pub enum QualificationCounter {
122    /// An acknowledged durable record could not be recovered.
123    LostAcknowledgedRecords,
124    /// A stale-fence mutation was accepted.
125    AcceptedStaleWrites,
126    /// Data crossed a tenant authorization boundary.
127    CrossTenantDisclosures,
128    /// An externally visible effect was duplicated.
129    DuplicateExternalEffects,
130}
131
132/// Exact operation and correctness counters.
133#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
134#[serde(deny_unknown_fields)]
135pub struct QualificationCounters {
136    /// Operations offered during the measurement phase.
137    pub offered: u64,
138    /// Offered operations accepted by the target.
139    pub accepted: u64,
140    /// Accepted operations completed successfully.
141    pub completed: u64,
142    /// Offered operations rejected by the target or harness ceiling.
143    pub rejected: u64,
144    /// Rejections caused by the explicit harness in-flight ceiling.
145    pub harness_capacity_rejections: u64,
146    /// Accepted operations ending in an intentionally injected failure.
147    pub expected_injected_failures: u64,
148    /// Accepted operations ending in any unexpected failure.
149    pub unexpected_failures: u64,
150    /// Acknowledged records that could not be recovered.
151    pub lost_acknowledged_records: u64,
152    /// Stale-fence writes accepted by a durable authority.
153    pub accepted_stale_writes: u64,
154    /// Data disclosed across a tenant boundary.
155    pub cross_tenant_disclosures: u64,
156    /// Duplicate externally visible effects.
157    pub duplicate_external_effects: u64,
158}
159
160impl QualificationCounters {
161    pub(crate) fn checked_add(
162        &mut self,
163        counter: QualificationCounter,
164        amount: u64,
165    ) -> Result<(), ReportError> {
166        let target = match counter {
167            QualificationCounter::LostAcknowledgedRecords => &mut self.lost_acknowledged_records,
168            QualificationCounter::AcceptedStaleWrites => &mut self.accepted_stale_writes,
169            QualificationCounter::CrossTenantDisclosures => &mut self.cross_tenant_disclosures,
170            QualificationCounter::DuplicateExternalEffects => &mut self.duplicate_external_effects,
171        };
172        *target = target
173            .checked_add(amount)
174            .ok_or(ReportError::CounterOverflow)?;
175        Ok(())
176    }
177
178    pub(crate) fn validate(&self) -> Result<(), ReportError> {
179        if self.accepted.checked_add(self.rejected) != Some(self.offered)
180            || self.harness_capacity_rejections > self.rejected
181            || self
182                .completed
183                .checked_add(self.expected_injected_failures)
184                .and_then(|value| value.checked_add(self.unexpected_failures))
185                != Some(self.accepted)
186        {
187            return Err(ReportError::InvalidReport(
188                "inconsistent operation counters",
189            ));
190        }
191        Ok(())
192    }
193}
194
195/// Noisy-neighbour fairness evidence.
196#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
197#[serde(deny_unknown_fields)]
198pub struct FairnessEvidence {
199    /// Uncontended in-quota p95 queue delay.
200    pub uncontended_p95_queue_micros: u64,
201    /// Contended in-quota p95 queue delay.
202    pub contended_p95_queue_micros: u64,
203    /// Longest continuously runnable-but-unclaimed interval.
204    pub max_runnable_unclaimed_micros: u64,
205}
206
207impl FairnessEvidence {
208    /// Creates non-zero bounded fairness evidence.
209    pub fn new(
210        uncontended_p95_queue_micros: u64,
211        contended_p95_queue_micros: u64,
212        max_runnable_unclaimed_micros: u64,
213    ) -> Result<Self, ReportError> {
214        let value = Self {
215            uncontended_p95_queue_micros,
216            contended_p95_queue_micros,
217            max_runnable_unclaimed_micros,
218        };
219        value.validate()?;
220        Ok(value)
221    }
222
223    fn validate(&self) -> Result<(), ReportError> {
224        if self.uncontended_p95_queue_micros == 0
225            || self.contended_p95_queue_micros == 0
226            || self.max_runnable_unclaimed_micros == 0
227            || self.uncontended_p95_queue_micros > 3_600_000_000
228            || self.contended_p95_queue_micros > 3_600_000_000
229            || self.max_runnable_unclaimed_micros > 3_600_000_000
230        {
231            return Err(ReportError::InvalidReport("invalid fairness evidence"));
232        }
233        Ok(())
234    }
235}
236
237/// Stable objective identifier.
238#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
239#[serde(rename_all = "snake_case")]
240pub enum ObjectiveId {
241    /// Admission p95 is at most 150 ms.
242    AdmissionP95,
243    /// Admission p99 is at most 300 ms.
244    AdmissionP99,
245    /// Runnable-to-claim p95 is at most 500 ms.
246    RunnableClaimP95,
247    /// Runnable-to-claim p99 is at most 2 s.
248    RunnableClaimP99,
249    /// Event-to-SSE p95 is at most 250 ms.
250    SseDeliveryP95,
251    /// Event-to-SSE p99 is at most 1 s.
252    SseDeliveryP99,
253    /// SSE reconnect p95 is at most 1 s.
254    SseReconnectP95,
255    /// Unexpected errors remain strictly below 0.1 percent.
256    UnexpectedErrorRate,
257    /// Shared saturation remains strictly below 70 percent.
258    Saturation,
259    /// Contended in-quota queue delay remains strictly below twice baseline.
260    NoisyNeighbourFairness,
261    /// No runnable tenant waits continuously for more than 5 s.
262    RunnableWait,
263    /// No acknowledged record is lost.
264    LostAcknowledgedRecords,
265    /// No stale-fence write is accepted.
266    AcceptedStaleWrites,
267    /// No cross-tenant disclosure occurs.
268    CrossTenantDisclosures,
269    /// No external effect is duplicated.
270    DuplicateExternalEffects,
271    /// Every planned fault completes injection, recovery and invariant checks.
272    FaultMatrix,
273}
274
275/// Evaluation status for one objective.
276#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
277#[serde(rename_all = "snake_case")]
278pub enum ObjectiveStatus {
279    /// A mandatory objective passed.
280    Pass,
281    /// A mandatory objective failed.
282    Fail,
283    /// A reduced-profile diagnostic threshold passed.
284    InformationalPass,
285    /// A reduced-profile diagnostic threshold failed.
286    InformationalFail,
287    /// A reduced profile explicitly did not collect this release-only signal.
288    InformationalMissing,
289}
290
291/// Deterministic integer evaluation of one objective.
292#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
293#[serde(deny_unknown_fields)]
294pub struct ObjectiveResult {
295    /// Stable objective identifier.
296    pub objective: ObjectiveId,
297    /// Mandatory or informational result.
298    pub status: ObjectiveStatus,
299    /// Observed integer value, or `None` when a reduced profile did not measure it.
300    pub observed: Option<u64>,
301    /// Threshold in the same unit.
302    pub threshold: u64,
303}
304
305/// Monotonic elapsed time for each completed phase.
306#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
307#[serde(deny_unknown_fields)]
308pub struct PhaseDurations {
309    /// Warm-up elapsed microseconds.
310    pub warmup_micros: u64,
311    /// Measurement elapsed microseconds.
312    pub measurement_micros: u64,
313    /// Drain elapsed microseconds.
314    pub drain_micros: u64,
315}
316
317/// Explicit reason the evidence cannot establish a release qualification.
318#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
319#[serde(rename_all = "snake_case")]
320pub enum EvidenceLimitation {
321    /// This was intentionally a reduced CI or developer run.
322    ReducedProfile,
323    /// The environment does not match the documented reference profile.
324    NonReferenceEnvironment,
325    /// The complete version-one release fault matrix was not planned.
326    IncompleteReleaseFaultMatrix,
327}
328
329/// Immutable evaluated qualification report.
330#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
331#[serde(deny_unknown_fields)]
332pub struct QualificationReport {
333    schema_version: u16,
334    profile: QualificationProfile,
335    scenario: QualificationScenario,
336    release_qualified: bool,
337    evidence_valid: bool,
338    environment: QualificationEnvironment,
339    reference_environment_violations: Vec<ReferenceEnvironmentViolation>,
340    window: QualificationWindow,
341    phase_durations: PhaseDurations,
342    started_at_unix_millis: u64,
343    finished_at_unix_millis: u64,
344    latencies: Vec<LatencyDistribution>,
345    counters: QualificationCounters,
346    max_saturation_basis_points: Option<u16>,
347    fairness: Option<FairnessEvidence>,
348    faults: Vec<FaultResult>,
349    objectives: Vec<ObjectiveResult>,
350    limitations: Vec<EvidenceLimitation>,
351}
352
353impl QualificationReport {
354    /// Returns whether the evidence is internally complete and free of mandatory failures.
355    pub const fn evidence_valid(&self) -> bool {
356        self.evidence_valid
357    }
358
359    /// Returns whether this exact report satisfies the release profile.
360    pub const fn release_qualified(&self) -> bool {
361        self.release_qualified
362    }
363
364    /// Returns the exact source and environment record.
365    pub const fn environment(&self) -> &QualificationEnvironment {
366        &self.environment
367    }
368
369    /// Returns evaluated objectives in stable identifier order.
370    pub fn objectives(&self) -> &[ObjectiveResult] {
371        &self.objectives
372    }
373
374    /// Returns latency distributions in stable signal order.
375    pub fn latencies(&self) -> &[LatencyDistribution] {
376        &self.latencies
377    }
378
379    /// Returns exact operation and safety counters.
380    pub const fn counters(&self) -> &QualificationCounters {
381        &self.counters
382    }
383
384    /// Returns explicit reasons this report cannot establish release qualification.
385    pub fn limitations(&self) -> &[EvidenceLimitation] {
386        &self.limitations
387    }
388
389    /// Returns the executed fault matrix.
390    pub fn faults(&self) -> &[FaultResult] {
391        &self.faults
392    }
393
394    /// Wraps this report in a canonical SHA-256 integrity envelope.
395    pub fn to_integrity_envelope(&self) -> Result<IntegrityEnvelope, ReportError> {
396        IntegrityEnvelope::new(self.clone())
397    }
398
399    #[allow(clippy::too_many_arguments)]
400    pub(crate) fn build(
401        profile: QualificationProfile,
402        scenario: QualificationScenario,
403        environment: QualificationEnvironment,
404        window: QualificationWindow,
405        phase_durations: PhaseDurations,
406        started_at_unix_millis: u64,
407        finished_at_unix_millis: u64,
408        mut latencies: Vec<LatencyDistribution>,
409        counters: QualificationCounters,
410        max_saturation_basis_points: Option<u16>,
411        fairness: Option<FairnessEvidence>,
412        mut faults: Vec<FaultResult>,
413        release_fault_plan_complete: bool,
414    ) -> Result<Self, ReportError> {
415        latencies.sort_by_key(|entry| entry.signal);
416        faults.sort_by_key(FaultResult::case);
417        let reference_environment_violations = environment.reference_violations();
418        let objectives = evaluate_objectives(
419            profile,
420            &latencies,
421            &counters,
422            max_saturation_basis_points,
423            fairness.as_ref(),
424            &faults,
425        )?;
426        let evidence_valid = objectives
427            .iter()
428            .all(|result| result.status != ObjectiveStatus::Fail)
429            && counters.unexpected_failures == 0;
430        let mut limitations = Vec::new();
431        if profile == QualificationProfile::CiReduced {
432            limitations.push(EvidenceLimitation::ReducedProfile);
433        }
434        if !reference_environment_violations.is_empty() {
435            limitations.push(EvidenceLimitation::NonReferenceEnvironment);
436        }
437        if !release_fault_plan_complete {
438            limitations.push(EvidenceLimitation::IncompleteReleaseFaultMatrix);
439        }
440        let release_qualified = profile == QualificationProfile::ReleaseCandidate
441            && limitations.is_empty()
442            && evidence_valid
443            && objectives
444                .iter()
445                .all(|result| result.status == ObjectiveStatus::Pass);
446        let report = Self {
447            schema_version: REPORT_SCHEMA_VERSION,
448            profile,
449            scenario,
450            release_qualified,
451            evidence_valid,
452            environment,
453            reference_environment_violations,
454            window,
455            phase_durations,
456            started_at_unix_millis,
457            finished_at_unix_millis,
458            latencies,
459            counters,
460            max_saturation_basis_points,
461            fairness,
462            faults,
463            objectives,
464            limitations,
465        };
466        report.validate()?;
467        Ok(report)
468    }
469
470    fn validate(&self) -> Result<(), ReportError> {
471        if self.schema_version != REPORT_SCHEMA_VERSION {
472            return Err(ReportError::UnsupportedReportVersion(self.schema_version));
473        }
474        self.environment.validate()?;
475        if self.window.validate(self.profile).is_err() {
476            return Err(ReportError::InvalidReport("invalid qualification window"));
477        }
478        self.counters.validate()?;
479        if let Some(fairness) = &self.fairness {
480            fairness.validate()?;
481        }
482        if self.started_at_unix_millis > self.finished_at_unix_millis
483            || self
484                .max_saturation_basis_points
485                .is_some_and(|value| value > 10_000)
486        {
487            return Err(ReportError::InvalidReport(
488                "invalid report timing or saturation",
489            ));
490        }
491        let expected_reference = self.environment.reference_violations();
492        if self.reference_environment_violations != expected_reference {
493            return Err(ReportError::InvalidReport(
494                "reference-environment evaluation mismatch",
495            ));
496        }
497        let expected_micros = self.window.minimum_micros();
498        if self.phase_durations.warmup_micros < expected_micros.warmup_micros
499            || self.phase_durations.measurement_micros < expected_micros.measurement_micros
500            || self.phase_durations.drain_micros < expected_micros.drain_micros
501        {
502            return Err(ReportError::InvalidReport(
503                "phase shorter than declared window",
504            ));
505        }
506        let latency_ids = self
507            .latencies
508            .iter()
509            .map(|entry| {
510                entry.validate()?;
511                Ok(entry.signal)
512            })
513            .collect::<Result<BTreeSet<_>, ReportError>>()?;
514        if self.latencies.len() != LatencySignal::ALL.len()
515            || !LatencySignal::ALL.iter().all(|id| latency_ids.contains(id))
516        {
517            return Err(ReportError::InvalidReport(
518                "missing or duplicate latency evidence",
519            ));
520        }
521        let mut fault_ids = BTreeSet::new();
522        for fault in &self.faults {
523            fault.validate()?;
524            if !fault_ids.insert(fault.case()) {
525                return Err(ReportError::InvalidReport("duplicate fault result"));
526            }
527        }
528        let release_fault_plan_complete = fault_ids.len() == FaultCaseId::ALL.len()
529            && FaultCaseId::ALL.iter().all(|case| fault_ids.contains(case));
530        let objectives = evaluate_objectives(
531            self.profile,
532            &self.latencies,
533            &self.counters,
534            self.max_saturation_basis_points,
535            self.fairness.as_ref(),
536            &self.faults,
537        )?;
538        if self.objectives != objectives {
539            return Err(ReportError::InvalidReport("objective evaluation mismatch"));
540        }
541        let evidence_valid = objectives
542            .iter()
543            .all(|result| result.status != ObjectiveStatus::Fail)
544            && self.counters.unexpected_failures == 0;
545        let mut limitations = Vec::new();
546        if self.profile == QualificationProfile::CiReduced {
547            limitations.push(EvidenceLimitation::ReducedProfile);
548        }
549        if !expected_reference.is_empty() {
550            limitations.push(EvidenceLimitation::NonReferenceEnvironment);
551        }
552        if !release_fault_plan_complete {
553            limitations.push(EvidenceLimitation::IncompleteReleaseFaultMatrix);
554        }
555        let release_qualified = self.profile == QualificationProfile::ReleaseCandidate
556            && limitations.is_empty()
557            && evidence_valid
558            && objectives
559                .iter()
560                .all(|result| result.status == ObjectiveStatus::Pass);
561        if self.evidence_valid != evidence_valid
562            || self.limitations != limitations
563            || self.release_qualified != release_qualified
564        {
565            return Err(ReportError::InvalidReport("derived report field mismatch"));
566        }
567        Ok(())
568    }
569}
570
571/// Canonical report plus a tamper-evident, non-authenticating digest.
572#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
573#[serde(deny_unknown_fields)]
574pub struct IntegrityEnvelope {
575    schema_version: u16,
576    report: QualificationReport,
577    report_sha256: String,
578}
579
580impl IntegrityEnvelope {
581    fn new(report: QualificationReport) -> Result<Self, ReportError> {
582        report.validate()?;
583        let report_sha256 = digest(&canonical(&report)?);
584        let value = Self {
585            schema_version: ENVELOPE_SCHEMA_VERSION,
586            report,
587            report_sha256,
588        };
589        value.enforce_size()?;
590        Ok(value)
591    }
592
593    /// Parses bounded JSON, verifies the digest and validates every derived field.
594    pub fn from_json(bytes: &[u8]) -> Result<Self, ReportError> {
595        if bytes.len() > MAX_ENVELOPE_BYTES {
596            return Err(ReportError::EnvelopeTooLarge);
597        }
598        let value: Self = serde_json::from_slice(bytes).map_err(|_| ReportError::InvalidJson)?;
599        value.verify()?;
600        Ok(value)
601    }
602
603    /// Returns canonical JSON bytes for storage or external attestation.
604    pub fn canonical_bytes(&self) -> Result<Vec<u8>, ReportError> {
605        self.verify()?;
606        let bytes = canonical(self)?;
607        if bytes.len() > MAX_ENVELOPE_BYTES {
608            return Err(ReportError::EnvelopeTooLarge);
609        }
610        Ok(bytes)
611    }
612
613    /// Returns the verified immutable report.
614    pub fn report(&self) -> &QualificationReport {
615        &self.report
616    }
617
618    /// Recomputes integrity and all report evaluations.
619    pub fn verify(&self) -> Result<(), ReportError> {
620        if self.schema_version != ENVELOPE_SCHEMA_VERSION {
621            return Err(ReportError::UnsupportedEnvelopeVersion(self.schema_version));
622        }
623        self.report.validate()?;
624        if self.report_sha256 != digest(&canonical(&self.report)?) {
625            return Err(ReportError::DigestMismatch);
626        }
627        self.enforce_size()
628    }
629
630    fn enforce_size(&self) -> Result<(), ReportError> {
631        if canonical(self)?.len() > MAX_ENVELOPE_BYTES {
632            return Err(ReportError::EnvelopeTooLarge);
633        }
634        Ok(())
635    }
636}
637
638/// Qualification report construction or verification failure.
639#[derive(Clone, Debug, Eq, Error, PartialEq)]
640pub enum ReportError {
641    /// Environment metadata is invalid.
642    #[error(transparent)]
643    Environment(#[from] EnvironmentError),
644    /// Fault evidence is invalid.
645    #[error(transparent)]
646    Fault(#[from] FaultError),
647    /// A counter overflowed.
648    #[error("qualification counter overflowed")]
649    CounterOverflow,
650    /// The serialized envelope exceeds the hard input ceiling.
651    #[error("qualification envelope exceeds the byte ceiling")]
652    EnvelopeTooLarge,
653    /// JSON is malformed, non-conforming or contains unknown fields.
654    #[error("invalid qualification JSON")]
655    InvalidJson,
656    /// Canonical serialization failed.
657    #[error("qualification canonicalization failed")]
658    Canonicalization,
659    /// The report digest does not match the canonical report.
660    #[error("qualification report digest mismatch")]
661    DigestMismatch,
662    /// The report schema version is unsupported.
663    #[error("unsupported qualification report schema version {0}")]
664    UnsupportedReportVersion(u16),
665    /// The envelope schema version is unsupported.
666    #[error("unsupported qualification envelope schema version {0}")]
667    UnsupportedEnvelopeVersion(u16),
668    /// A derived or bounded report invariant is invalid.
669    #[error("invalid qualification report: {0}")]
670    InvalidReport(&'static str),
671}
672
673fn canonical(value: &impl Serialize) -> Result<Vec<u8>, ReportError> {
674    serde_json_canonicalizer::to_vec(value).map_err(|_| ReportError::Canonicalization)
675}
676
677fn digest(bytes: &[u8]) -> String {
678    Sha256::digest(bytes)
679        .iter()
680        .fold(String::with_capacity(64), |mut output, byte| {
681            write!(output, "{byte:02x}").expect("writing to String is infallible");
682            output
683        })
684}
685
686fn evaluate_objectives(
687    profile: QualificationProfile,
688    latencies: &[LatencyDistribution],
689    counters: &QualificationCounters,
690    saturation: Option<u16>,
691    fairness: Option<&FairnessEvidence>,
692    faults: &[FaultResult],
693) -> Result<Vec<ObjectiveResult>, ReportError> {
694    let mandatory_latency = profile == QualificationProfile::ReleaseCandidate;
695    let mut values = Vec::with_capacity(16);
696    add_latency_objectives(latencies, mandatory_latency, &mut values)?;
697
698    let error_bps = if counters.offered == 0 {
699        return Err(ReportError::InvalidReport("no offered operations"));
700    } else {
701        ratio_basis_points(counters.unexpected_failures, counters.offered)?
702    };
703    values.push(objective_result(
704        ObjectiveId::UnexpectedErrorRate,
705        error_bps,
706        10,
707        counters
708            .unexpected_failures
709            .checked_mul(10_000)
710            .is_some_and(|left| {
711                counters
712                    .offered
713                    .checked_mul(10)
714                    .is_some_and(|right| left < right)
715            }),
716        true,
717    ));
718    if let Some(saturation) = saturation {
719        values.push(objective_result(
720            ObjectiveId::Saturation,
721            u64::from(saturation),
722            7_000,
723            saturation < 7_000,
724            mandatory_latency,
725        ));
726    } else {
727        values.push(missing_objective(
728            ObjectiveId::Saturation,
729            7_000,
730            mandatory_latency,
731        ));
732    }
733    if let Some(fairness) = fairness {
734        let fairness_bps = ratio_basis_points(
735            fairness.contended_p95_queue_micros,
736            fairness.uncontended_p95_queue_micros,
737        )?;
738        values.push(objective_result(
739            ObjectiveId::NoisyNeighbourFairness,
740            fairness_bps,
741            20_000,
742            fairness
743                .uncontended_p95_queue_micros
744                .checked_mul(2)
745                .is_some_and(|right| fairness.contended_p95_queue_micros < right),
746            mandatory_latency,
747        ));
748        values.push(objective_result(
749            ObjectiveId::RunnableWait,
750            fairness.max_runnable_unclaimed_micros,
751            5_000_000,
752            fairness.max_runnable_unclaimed_micros <= 5_000_000,
753            mandatory_latency,
754        ));
755    } else {
756        values.push(missing_objective(
757            ObjectiveId::NoisyNeighbourFairness,
758            20_000,
759            mandatory_latency,
760        ));
761        values.push(missing_objective(
762            ObjectiveId::RunnableWait,
763            5_000_000,
764            mandatory_latency,
765        ));
766    }
767    add_safety_objectives(counters, &mut values);
768    let incomplete = faults.iter().filter(|fault| !fault.is_complete()).count() as u64;
769    values.push(objective_result(
770        ObjectiveId::FaultMatrix,
771        incomplete,
772        0,
773        incomplete == 0,
774        true,
775    ));
776    values.sort_by_key(|result| result.objective);
777    Ok(values)
778}
779
780fn add_latency_objectives(
781    latencies: &[LatencyDistribution],
782    mandatory: bool,
783    values: &mut Vec<ObjectiveResult>,
784) -> Result<(), ReportError> {
785    let latency = |signal| {
786        latencies
787            .iter()
788            .find(|entry| entry.signal == signal)
789            .ok_or(ReportError::InvalidReport("missing latency evidence"))
790    };
791    let mut add_latency = |objective, observed, threshold| {
792        values.push(objective_result(
793            objective,
794            observed,
795            threshold,
796            observed <= threshold,
797            mandatory,
798        ));
799    };
800    let admission = latency(LatencySignal::AdmissionCommit)?;
801    add_latency(ObjectiveId::AdmissionP95, admission.p95_micros, 150_000);
802    add_latency(ObjectiveId::AdmissionP99, admission.p99_micros, 300_000);
803    let claim = latency(LatencySignal::RunnableClaim)?;
804    add_latency(ObjectiveId::RunnableClaimP95, claim.p95_micros, 500_000);
805    add_latency(ObjectiveId::RunnableClaimP99, claim.p99_micros, 2_000_000);
806    let delivery = latency(LatencySignal::SseDelivery)?;
807    add_latency(ObjectiveId::SseDeliveryP95, delivery.p95_micros, 250_000);
808    add_latency(ObjectiveId::SseDeliveryP99, delivery.p99_micros, 1_000_000);
809    let reconnect = latency(LatencySignal::SseReconnect)?;
810    add_latency(
811        ObjectiveId::SseReconnectP95,
812        reconnect.p95_micros,
813        1_000_000,
814    );
815    Ok(())
816}
817
818fn add_safety_objectives(counters: &QualificationCounters, values: &mut Vec<ObjectiveResult>) {
819    for (objective, observed) in [
820        (
821            ObjectiveId::LostAcknowledgedRecords,
822            counters.lost_acknowledged_records,
823        ),
824        (
825            ObjectiveId::AcceptedStaleWrites,
826            counters.accepted_stale_writes,
827        ),
828        (
829            ObjectiveId::CrossTenantDisclosures,
830            counters.cross_tenant_disclosures,
831        ),
832        (
833            ObjectiveId::DuplicateExternalEffects,
834            counters.duplicate_external_effects,
835        ),
836    ] {
837        values.push(objective_result(
838            objective,
839            observed,
840            0,
841            observed == 0,
842            true,
843        ));
844    }
845}
846
847fn objective_result(
848    objective: ObjectiveId,
849    observed: u64,
850    threshold: u64,
851    met: bool,
852    mandatory: bool,
853) -> ObjectiveResult {
854    let status = match (mandatory, met) {
855        (true, true) => ObjectiveStatus::Pass,
856        (true, false) => ObjectiveStatus::Fail,
857        (false, true) => ObjectiveStatus::InformationalPass,
858        (false, false) => ObjectiveStatus::InformationalFail,
859    };
860    ObjectiveResult {
861        objective,
862        status,
863        observed: Some(observed),
864        threshold,
865    }
866}
867
868fn missing_objective(objective: ObjectiveId, threshold: u64, mandatory: bool) -> ObjectiveResult {
869    ObjectiveResult {
870        objective,
871        status: if mandatory {
872            ObjectiveStatus::Fail
873        } else {
874            ObjectiveStatus::InformationalMissing
875        },
876        observed: None,
877        threshold,
878    }
879}
880
881fn ratio_basis_points(numerator: u64, denominator: u64) -> Result<u64, ReportError> {
882    if denominator == 0 {
883        return Err(ReportError::InvalidReport("zero ratio denominator"));
884    }
885    let scaled = u128::from(numerator) * 10_000;
886    let denominator = u128::from(denominator);
887    let rounded_up = scaled.div_ceil(denominator);
888    u64::try_from(rounded_up).map_err(|_| ReportError::InvalidReport("ratio overflow"))
889}