Skip to main content

qualia_core_db/semantic_instruments/attestation/
award.rs

1//! Capability-award issuance as an unsigned attestation claim.
2//!
3//! This constructor records a learner/worker as the award subject of an
4//! assessment-instrument release. It does **not** run the instrument, and it
5//! does **not** treat evaluator success as sufficient grounds to issue.
6
7use crate::semantic_instruments::attestation::kinds::{AttestationKind, InstrumentAttestation};
8use crate::semantic_instruments::errors::InstrumentError;
9
10/// Cold-path inputs for a capability award. `capability` is the concept IRI.
11#[derive(Debug, Clone, PartialEq, Eq)]
12pub struct CapabilityAward {
13    pub learner: String,
14    pub assessment_release_id: String,
15    pub content_digest: String,
16    pub issuer: String,
17    /// Concept IRI of the awarded capability (adapters carry this; the unsigned
18    /// release claim binds learner + assessment release).
19    pub capability: String,
20    pub issued_at: u32,
21    pub valid_until: u32,
22}
23
24/// Construct a `CapabilityAward` attestation. Origin is recorded; origin is not
25/// substantive truth. Passing an evaluator is not a reason to call this.
26pub fn issue_capability_award(
27    award: CapabilityAward,
28) -> Result<InstrumentAttestation, InstrumentError> {
29    if award.learner == award.assessment_release_id {
30        return Err(InstrumentError::AwardIsInstrument);
31    }
32    let attestation = InstrumentAttestation {
33        kind: AttestationKind::CapabilityAward,
34        release_id: award.assessment_release_id.clone(),
35        content_digest: award.content_digest,
36        actor: award.issuer,
37        issued_at: award.issued_at,
38        valid_until: award.valid_until,
39        origin_is_not_truth: true,
40        award_subject: award.learner,
41        assessment_release_id: award.assessment_release_id,
42    };
43    attestation.validate()?;
44    Ok(attestation)
45}
46
47#[cfg(test)]
48mod tests {
49    use super::*;
50
51    const DIGEST: &str = "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
52
53    fn sample_award() -> CapabilityAward {
54        CapabilityAward {
55            learner: "did:example:learner".into(),
56            assessment_release_id: "https://ns.webizen.org/demo/unit-convert/releases/1.0.0".into(),
57            content_digest: DIGEST.into(),
58            issuer: "did:example:issuer".into(),
59            capability: "https://ns.webizen.org/demo/concepts/units".into(),
60            issued_at: 1_700_000_000,
61            valid_until: 1_800_000_000,
62        }
63    }
64
65    #[test]
66    fn happy_path_constructs_claim_without_running_instrument() {
67        let award = sample_award();
68        let issued = issue_capability_award(award.clone()).expect("issue");
69        issued.validate().expect("valid");
70        assert_eq!(issued.kind, AttestationKind::CapabilityAward);
71        assert_eq!(issued.release_id, award.assessment_release_id);
72        assert_eq!(issued.assessment_release_id, award.assessment_release_id);
73        assert_eq!(issued.award_subject, award.learner);
74        assert_eq!(issued.actor, award.issuer);
75        assert_eq!(issued.content_digest, award.content_digest);
76        assert_eq!(issued.issued_at, award.issued_at);
77        assert_eq!(issued.valid_until, award.valid_until);
78        assert!(issued.origin_is_not_truth);
79        assert_ne!(issued.award_subject, issued.assessment_release_id);
80    }
81
82    #[test]
83    fn learner_equal_to_instrument_is_award_is_instrument() {
84        let mut award = sample_award();
85        award.learner = award.assessment_release_id.clone();
86        let err = issue_capability_award(award).expect_err("must fail");
87        assert_eq!(err, InstrumentError::AwardIsInstrument);
88    }
89
90    #[test]
91    fn issued_claim_records_origin_is_not_truth() {
92        let issued = issue_capability_award(sample_award()).expect("issue");
93        assert!(issued.origin_is_not_truth);
94        assert_ne!(
95            issued.origin_is_not_truth, false,
96            "a signature/claim of origin is not substantive truth"
97        );
98    }
99}