Skip to main content

qualia_core_db/inference/conditioning/
registry.rs

1//! Profile registry with versioning, promotion/activation, and rollback (PP-081).
2//!
3//! Enforces reviewable lifecycle transitions, opaque version references,
4//! and fail-closed state tracking.
5
6use std::collections::BTreeMap;
7use std::sync::{OnceLock, RwLock};
8
9/// An immutable record of a registered profile version.
10#[derive(Clone, Debug, PartialEq, Eq)]
11pub struct ProfileVersionEntry {
12    pub profile_id: String,
13    pub version: u64,
14    pub spec_identity: u64,
15    pub approved_by: Option<String>,
16}
17
18/// Lifecycle state machine for a specific profile ID.
19#[derive(Clone, Debug, Default, PartialEq, Eq)]
20pub struct ProfileLifecycleState {
21    pub active_version: Option<u64>,
22    pub previous_version: Option<u64>,
23    pub versions: BTreeMap<u64, ProfileVersionEntry>,
24}
25
26/// Profile registry tracking versions and active promotion pointers.
27#[derive(Default, Debug)]
28pub struct ConditioningRegistry {
29    profiles: BTreeMap<String, ProfileLifecycleState>,
30}
31
32impl ConditioningRegistry {
33    /// Creates a default `ConditioningRegistry`.
34    pub fn new() -> Self {
35        Self::default()
36    }
37
38    /// Register a new profile version.
39    pub fn register(
40        &mut self,
41        profile_id: &str,
42        version: u64,
43        spec_identity: u64,
44        approved_by: Option<String>,
45    ) -> Result<(), &'static str> {
46        if profile_id.is_empty() || version == 0 {
47            return Err("invalid profile_id or version");
48        }
49        let state = self.profiles.entry(profile_id.to_string()).or_default();
50        if state.versions.contains_key(&version) {
51            return Err("version already registered");
52        }
53        state.versions.insert(
54            version,
55            ProfileVersionEntry {
56                profile_id: profile_id.to_string(),
57                version,
58                spec_identity,
59                approved_by,
60            },
61        );
62        Ok(())
63    }
64
65    /// Activate / promote a version to become the current active profile.
66    pub fn activate(
67        &mut self,
68        profile_id: &str,
69        version: u64,
70    ) -> Result<(Option<u64>, u64), &'static str> {
71        let state = self
72            .profiles
73            .get_mut(profile_id)
74            .ok_or("profile not found")?;
75        if !state.versions.contains_key(&version) {
76            return Err("version not found in registry");
77        }
78        let prev = state.active_version;
79        state.previous_version = prev;
80        state.active_version = Some(version);
81        Ok((prev, version))
82    }
83
84    /// Rollback active version to a target version or previous active version.
85    pub fn rollback(
86        &mut self,
87        profile_id: &str,
88        target_version: Option<u64>,
89    ) -> Result<(u64, u64), &'static str> {
90        let state = self
91            .profiles
92            .get_mut(profile_id)
93            .ok_or("profile not found")?;
94        let current = state
95            .active_version
96            .ok_or("no active version to rollback from")?;
97        let target = match target_version {
98            Some(t) => {
99                if !state.versions.contains_key(&t) {
100                    return Err("target rollback version not registered");
101                }
102                t
103            }
104            None => state
105                .previous_version
106                .ok_or("no previous active version available for rollback")?,
107        };
108        state.previous_version = Some(current);
109        state.active_version = Some(target);
110        Ok((current, target))
111    }
112
113    /// Query the currently active version for a profile.
114    pub fn active_version(&self, profile_id: &str) -> Option<u64> {
115        self.profiles.get(profile_id).and_then(|s| s.active_version)
116    }
117
118    /// Query the currently active version entry for a profile.
119    pub fn get_active(&self, profile_id: &str) -> Option<&ProfileVersionEntry> {
120        let v = self.active_version(profile_id)?;
121        self.get_version(profile_id, v)
122    }
123
124    /// Query entry details for a registered version.
125    pub fn get_version(&self, profile_id: &str, version: u64) -> Option<&ProfileVersionEntry> {
126        self.profiles
127            .get(profile_id)
128            .and_then(|s| s.versions.get(&version))
129    }
130
131    /// List all registered versions for a profile.
132    pub fn list_versions(&self, profile_id: &str) -> Vec<u64> {
133        self.profiles
134            .get(profile_id)
135            .map(|s| s.versions.keys().copied().collect())
136            .unwrap_or_default()
137    }
138}
139
140static GLOBAL_REGISTRY: OnceLock<RwLock<ConditioningRegistry>> = OnceLock::new();
141
142/// Global conditioning registry.
143pub fn global_registry() -> &'static RwLock<ConditioningRegistry> {
144    GLOBAL_REGISTRY.get_or_init(|| RwLock::new(ConditioningRegistry::new()))
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn test_registry_lifecycle_flow() {
153        let mut reg = ConditioningRegistry::new();
154        let pid = "urn:qualia:profile:rust-review:v1";
155
156        // Register versions 1 and 2
157        assert!(reg.register(pid, 1, 0x1111, Some("timothy".into())).is_ok());
158        assert!(reg.register(pid, 2, 0x2222, Some("timothy".into())).is_ok());
159
160        // Duplicate registration fails
161        assert!(reg.register(pid, 1, 0x1111, None).is_err());
162
163        // Initial active is None
164        assert_eq!(reg.active_version(pid), None);
165
166        // Activate version 1
167        let (prev, cur) = reg.activate(pid, 1).unwrap();
168        assert_eq!(prev, None);
169        assert_eq!(cur, 1);
170        assert_eq!(reg.active_version(pid), Some(1));
171
172        // Promote to version 2
173        let (prev, cur) = reg.activate(pid, 2).unwrap();
174        assert_eq!(prev, Some(1));
175        assert_eq!(cur, 2);
176        assert_eq!(reg.active_version(pid), Some(2));
177
178        // Rollback without target -> reverts to previous active (1)
179        let (from, to) = reg.rollback(pid, None).unwrap();
180        assert_eq!(from, 2);
181        assert_eq!(to, 1);
182        assert_eq!(reg.active_version(pid), Some(1));
183
184        // Rollback with explicit target 2
185        let (from, to) = reg.rollback(pid, Some(2)).unwrap();
186        assert_eq!(from, 1);
187        assert_eq!(to, 2);
188        assert_eq!(reg.active_version(pid), Some(2));
189    }
190}