Skip to main content

qualia_core_db/semantic_instruments/resolve/
resolver.rs

1//! Deterministic local dependency resolution (SI-05).
2//!
3//! Catalog records are the only source. No network is consulted.
4
5use crate::semantic_instruments::errors::InstrumentError;
6use crate::semantic_instruments::resolve::dependency::*;
7
8/// Plan a lock for `release_id` from `requirements` against a local `catalog`.
9///
10/// Requirements are cloned and sorted by `id`. Optional misses are omitted;
11/// required misses fail closed. Entries are sorted by `id` before return.
12pub fn plan_resolution(
13    release_id: &str,
14    requirements: &[DependencyReq],
15    catalog: &[CatalogRecord],
16) -> Result<DependencyLock, InstrumentError> {
17    let prepared = prepare_requirements(release_id, requirements)?;
18    let mut entries = Vec::with_capacity(prepared.len());
19    for req in &prepared {
20        if let Some(entry) = resolve_one(req, catalog)? {
21            entries.push(entry);
22        }
23    }
24    entries.sort_by(|a, b| a.id.cmp(&b.id));
25    Ok(DependencyLock {
26        release_id: release_id.to_string(),
27        entries,
28    })
29}
30
31fn prepare_requirements(
32    release_id: &str,
33    requirements: &[DependencyReq],
34) -> Result<Vec<DependencyReq>, InstrumentError> {
35    let mut working = requirements.to_vec();
36    working.sort_by(|a, b| a.id.cmp(&b.id));
37    let mut out: Vec<DependencyReq> = Vec::with_capacity(working.len());
38    for req in working {
39        if req.id == release_id {
40            return Err(InstrumentError::DependencyCycle);
41        }
42        if let Some(prev) = out.last() {
43            if prev.id == req.id {
44                if prev != &req {
45                    return Err(InstrumentError::DependencyCycle);
46                }
47                continue;
48            }
49        }
50        out.push(req);
51    }
52    Ok(out)
53}
54
55fn resolve_one(
56    req: &DependencyReq,
57    catalog: &[CatalogRecord],
58) -> Result<Option<LockEntry>, InstrumentError> {
59    let mut best: Option<&CatalogRecord> = None;
60    for rec in catalog {
61        if rec.id != req.id {
62            continue;
63        }
64        if !version_matches(&req.version_constraint, &rec.version) {
65            continue;
66        }
67        if !req.expected_digest.is_empty() && rec.digest != req.expected_digest {
68            continue;
69        }
70        if !rec.available_offline || rec.revoked {
71            continue;
72        }
73        match best {
74            None => best = Some(rec),
75            Some(cur) => {
76                if (&rec.version, &rec.locator) < (&cur.version, &cur.locator) {
77                    best = Some(rec);
78                }
79            }
80        }
81    }
82    if let Some(rec) = best {
83        require_digest(req, rec)?;
84        return Ok(Some(LockEntry {
85            id: rec.id.clone(),
86            version: rec.version.clone(),
87            digest: rec.digest.clone(),
88            locator: rec.locator.clone(),
89        }));
90    }
91    if !req.required {
92        return Ok(None);
93    }
94    Err(diagnose_required(req, catalog))
95}
96
97fn diagnose_required(req: &DependencyReq, catalog: &[CatalogRecord]) -> InstrumentError {
98    let mut any_id = false;
99    let mut any_online = false;
100    let mut all_revoked = true;
101    let mut version_hit = false;
102    let mut digest_hit = false;
103    let mut online_revoked = false;
104    let mut offline_live = false;
105
106    for rec in catalog {
107        if rec.id != req.id {
108            continue;
109        }
110        any_id = true;
111        if rec.available_offline {
112            any_online = true;
113        }
114        if !rec.revoked {
115            all_revoked = false;
116        }
117        if !version_matches(&req.version_constraint, &rec.version) {
118            continue;
119        }
120        version_hit = true;
121        if !req.expected_digest.is_empty() && rec.digest != req.expected_digest {
122            continue;
123        }
124        digest_hit = true;
125        match (rec.available_offline, rec.revoked) {
126            (true, true) => online_revoked = true,
127            (false, false) => offline_live = true,
128            _ => {}
129        }
130    }
131
132    if version_hit && !digest_hit && !req.expected_digest.is_empty() {
133        return InstrumentError::DigestMismatchDep;
134    }
135    if online_revoked {
136        return InstrumentError::RevokedDependency;
137    }
138    if digest_hit && offline_live {
139        return InstrumentError::OfflineHeld;
140    }
141    if digest_hit && all_revoked {
142        return InstrumentError::RevokedDependency;
143    }
144    if !any_id {
145        return InstrumentError::RequiredMissing;
146    }
147    if all_revoked {
148        return InstrumentError::RevokedDependency;
149    }
150    if !any_online {
151        return InstrumentError::OfflineHeld;
152    }
153    InstrumentError::RequiredMissing
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159
160    fn req(id: &str, constraint: &str, digest: &str, required: bool) -> DependencyReq {
161        DependencyReq {
162            id: id.into(),
163            kind: DependencyKind::Ontology,
164            version_constraint: constraint.into(),
165            expected_digest: digest.into(),
166            required,
167            purpose: "test".into(),
168        }
169    }
170
171    fn rec(
172        id: &str,
173        version: &str,
174        digest: &str,
175        locator: &str,
176        revoked: bool,
177        available_offline: bool,
178    ) -> CatalogRecord {
179        CatalogRecord {
180            id: id.into(),
181            version: version.into(),
182            digest: digest.into(),
183            locator: locator.into(),
184            revoked,
185            available_offline,
186        }
187    }
188
189    #[test]
190    fn exact_pin_resolves() {
191        let pin = req("ont", "1.0.0", "", true);
192        let catalog = [rec("ont", "1.0.0", "sha256:aa", "local:ont", false, true)];
193        let lock = plan_resolution("rel", &[pin.clone(), pin], &catalog).unwrap();
194        assert_eq!(lock.release_id, "rel");
195        assert_eq!(lock.entries.len(), 1);
196        assert_eq!(lock.entries[0].version, "1.0.0");
197        assert_eq!(lock.entries[0].digest, "sha256:aa");
198        assert_eq!(lock.entries[0].locator, "local:ont");
199    }
200
201    #[test]
202    fn compatible_caret_matches_patch() {
203        let requirements = [req("ont", "^1.0", "", true)];
204        let catalog = [rec("ont", "1.0.2", "sha256:aa", "local:ont", false, true)];
205        let lock = plan_resolution("rel", &requirements, &catalog).unwrap();
206        assert_eq!(lock.entries[0].version, "1.0.2");
207    }
208
209    #[test]
210    fn optional_missing_omitted_required_missing_errors() {
211        let optional = [req("ont", "1.0.0", "", false)];
212        let lock = plan_resolution("rel", &optional, &[]).unwrap();
213        assert!(lock.entries.is_empty());
214
215        let required = [req("ont", "1.0.0", "", true)];
216        let err = plan_resolution("rel", &required, &[]).unwrap_err();
217        assert_eq!(err, InstrumentError::RequiredMissing);
218    }
219
220    #[test]
221    fn digest_mismatch_is_digest_mismatch_dep() {
222        let requirements = [req("ont", "1.0.0", "sha256:aa", true)];
223        let catalog = [rec("ont", "1.0.0", "sha256:bb", "local:ont", false, true)];
224        let err = plan_resolution("rel", &requirements, &catalog).unwrap_err();
225        assert_eq!(err, InstrumentError::DigestMismatchDep);
226    }
227
228    #[test]
229    fn cycle_when_req_id_equals_release() {
230        let requirements = [req("rel", "1.0.0", "", true)];
231        let err = plan_resolution("rel", &requirements, &[]).unwrap_err();
232        assert_eq!(err, InstrumentError::DependencyCycle);
233    }
234
235    #[test]
236    fn revoked_required_is_revoked_dependency() {
237        let requirements = [req("ont", "1.0.0", "", true)];
238        let catalog = [rec("ont", "1.0.0", "sha256:aa", "local:ont", true, true)];
239        let err = plan_resolution("rel", &requirements, &catalog).unwrap_err();
240        assert_eq!(err, InstrumentError::RevokedDependency);
241    }
242
243    #[test]
244    fn offline_required_is_offline_held() {
245        let requirements = [req("ont", "1.0.0", "", true)];
246        let catalog = [rec("ont", "1.0.0", "sha256:aa", "local:ont", false, false)];
247        let err = plan_resolution("rel", &requirements, &catalog).unwrap_err();
248        assert_eq!(err, InstrumentError::OfflineHeld);
249    }
250
251    #[test]
252    fn lock_digest_stable_for_same_inputs() {
253        let requirements = [req("lex", "2.0.0", "", true), req("ont", "1.0.0", "", true)];
254        let catalog = [
255            rec("ont", "1.0.0", "sha256:aa", "local:ont", false, true),
256            rec("lex", "2.0.0", "sha256:bb", "local:lex", false, true),
257        ];
258        let a = plan_resolution("rel", &requirements, &catalog).unwrap();
259        let reversed = [requirements[1].clone(), requirements[0].clone()];
260        let b = plan_resolution("rel", &reversed, &catalog).unwrap();
261        assert_eq!(a.entries[0].id, "lex");
262        assert_eq!(a.entries[1].id, "ont");
263        assert_eq!(a.digest(), b.digest());
264    }
265}