Skip to main content

qualia_core_db/semantic_instruments/resolve/
dependency.rs

1//! Dependency requirements and deterministic lock records (SI-05).
2//! Large Q42 volumes, lexicons and datasets are dependencies, not the instrument.
3
4use crate::semantic_instruments::canonical::sha256_prefixed;
5use crate::semantic_instruments::errors::InstrumentError;
6
7#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
8#[serde(rename_all = "kebab-case")]
9pub enum DependencyKind {
10    Ontology,
11    Lexicon,
12    Dataset,
13    LawPackage,
14    Instrument,
15    NativeModule,
16}
17
18#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
19pub struct DependencyReq {
20    pub id: String,
21    pub kind: DependencyKind,
22    pub version_constraint: String,
23    pub expected_digest: String,
24    pub required: bool,
25    pub purpose: String,
26}
27
28#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
29pub struct CatalogRecord {
30    pub id: String,
31    pub version: String,
32    pub digest: String,
33    pub locator: String,
34    pub revoked: bool,
35    pub available_offline: bool,
36}
37
38#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
39pub struct LockEntry {
40    pub id: String,
41    pub version: String,
42    pub digest: String,
43    pub locator: String,
44}
45
46#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
47pub struct DependencyLock {
48    pub release_id: String,
49    pub entries: Vec<LockEntry>,
50}
51
52impl DependencyLock {
53    /// Dependency digest.
54    pub fn digest(&self) -> String {
55        let mut buf = self.release_id.clone().into_bytes();
56        for e in &self.entries {
57            buf.extend_from_slice(e.id.as_bytes());
58            buf.extend_from_slice(e.version.as_bytes());
59            buf.extend_from_slice(e.digest.as_bytes());
60            buf.extend_from_slice(e.locator.as_bytes());
61        }
62        sha256_prefixed(&buf)
63    }
64
65    /// `true` when empty.
66    pub fn is_empty(&self) -> bool {
67        self.entries.is_empty()
68    }
69}
70
71/// Exact pin: constraint empty or equal to version. Compatible: constraint is a
72/// prefix of version followed by '.' or end (`1.0` matches `1.0.0`).
73pub fn version_matches(constraint: &str, version: &str) -> bool {
74    let c = constraint.trim();
75    if c.is_empty() || c == "*" {
76        return true;
77    }
78    if c == version {
79        return true;
80    }
81    let c = c
82        .trim_start_matches('^')
83        .trim_start_matches('~')
84        .trim_end_matches('*')
85        .trim_end_matches('.');
86    version == c || version.starts_with(&format!("{c}."))
87}
88
89/// `Ok(())` when the digest matches.
90pub fn require_digest(req: &DependencyReq, rec: &CatalogRecord) -> Result<(), InstrumentError> {
91    if req.expected_digest.is_empty() {
92        return Ok(());
93    }
94    if rec.digest == req.expected_digest {
95        Ok(())
96    } else {
97        Err(InstrumentError::DigestMismatchDep)
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104
105    #[test]
106    fn exact_and_compatible_versions() {
107        assert!(version_matches("1.0.0", "1.0.0"));
108        assert!(version_matches("1.0", "1.0.0"));
109        assert!(version_matches("^1.0", "1.0.2"));
110        assert!(!version_matches("1.0.0", "2.0.0"));
111        assert!(version_matches("*", "9.9.9"));
112    }
113
114    #[test]
115    fn lock_digest_is_stable_and_order_sensitive() {
116        let mut a = DependencyLock {
117            release_id: "r".into(),
118            entries: vec![LockEntry {
119                id: "ont".into(),
120                version: "1".into(),
121                digest: "sha256:aa".into(),
122                locator: "local:ont".into(),
123            }],
124        };
125        let b = a.clone();
126        assert_eq!(a.digest(), b.digest());
127        a.entries[0].digest = "sha256:bb".into();
128        assert_ne!(a.digest(), b.digest());
129    }
130}