Skip to main content

subc_daemon/config_gate/
mod.rs

1//! Immutable config planning and approval, independent of transport dispatch.
2//!
3//! The daemon owner captures files, validates schemas/bounds and runs module
4//! review before handing snapshots here. It serializes this engine with the
5//! store and supervisor commit locks, recaptures files at completion, and uses
6//! only the committed snapshot for delivery. No client text is approval input.
7
8mod anchor_retry;
9mod apply;
10mod approval;
11pub mod capture;
12pub(crate) mod program;
13pub(crate) mod review;
14mod reviewed_build;
15pub mod runtime;
16mod snapshot;
17mod strict_json;
18
19pub use approval::*;
20pub use snapshot::{CapturedInput, GateSnapshot, InputKey};
21
22use std::collections::{BTreeMap, BTreeSet};
23
24use subc_config::{Changeset, Digest, Generation, Plan};
25use subc_control::config::ConfigPlanView;
26
27use crate::config_store::{CommitKind, ConfigStore, HistoryEntry, StoreError, StoreState, Tuple};
28
29#[derive(Clone, Debug, PartialEq, Eq)]
30pub struct GateError {
31    pub code: String,
32    pub detail: String,
33}
34type Result<T> = std::result::Result<T, GateError>;
35
36impl GateError {
37    pub fn new(code: &str, detail: impl ToString) -> Self {
38        Self {
39            code: code.into(),
40            detail: detail.to_string(),
41        }
42    }
43    fn invalid(detail: impl ToString) -> Self {
44        Self::new("value_invalid", detail)
45    }
46    fn stale() -> Self {
47        Self::new(
48            "plan_stale",
49            "reviewed inputs or generation changed; plan again",
50        )
51    }
52
53    pub(crate) fn commit_timeout() -> Self {
54        Self::new("config_commit_timeout", "the post-answer commit window expired before durable publication; plan remains unapproved")
55    }
56}
57impl std::fmt::Display for GateError {
58    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
59        write!(f, "{}: {}", self.code, self.detail)
60    }
61}
62impl std::error::Error for GateError {}
63impl From<StoreError> for GateError {
64    fn from(error: StoreError) -> Self {
65        use crate::config_store::StoreErrorCode as Code;
66        let code = match error.code {
67            Code::StoreUnverified => "store_unverified",
68            Code::StoreMissing => "store_missing",
69            Code::StoreTampered => "store_tampered",
70            Code::StoreTooLarge => "store_too_large",
71            Code::AnchorPending => "anchor_pending",
72            Code::GenerationPruned => "generation_pruned",
73            Code::GenerationMissing => "generation_missing",
74            Code::RevisionExhausted => "revision_exhausted",
75            Code::InvalidState => "config_gated",
76            Code::Io => "config_store_io",
77        };
78        Self::new(code, error.detail)
79    }
80}
81
82/// The supervisor's program-admission adapter supplies this authority. A module
83/// registration and a schema declaration alone never admit its running code.
84pub trait ReviewAdmission: Send + Sync {
85    fn check(&self, registration: &crate::registry::ModuleRegistration) -> Result<()>;
86}
87
88pub(crate) struct MissingReviewAdmission;
89impl ReviewAdmission for MissingReviewAdmission {
90    fn check(&self, registration: &crate::registry::ModuleRegistration) -> Result<()> {
91        Err(GateError::new(
92            "program_admission_unavailable",
93            format!(
94                "{}: running program review admission is not connected",
95                registration.manifest.module_id
96            ),
97        ))
98    }
99}
100
101/// Which build each module's approved configuration was reviewed by, as a
102/// plan writes it into its generation.
103pub(crate) enum ReviewRecord<'a> {
104    /// Write no record. Later plans then treat every module this plan approves
105    /// as owing a re-review.
106    Absent,
107    /// These modules' admitted reviewers answered `config.review` for this
108    /// plan. Their builds are recorded; other modules keep their entries from
109    /// the newest approved generation.
110    Reviewed(&'a BTreeSet<String>),
111    /// Copy a record verbatim, for a rollback to a generation whose reviewers
112    /// are known. `None` (that generation had no record) writes none.
113    Copied(Option<serde_json::Value>),
114}
115
116#[derive(Clone, Copy, Debug, PartialEq, Eq)]
117pub enum PlanKind {
118    Change,
119    Stamp,
120    Unstamp,
121    Rollback(u64),
122}
123impl PlanKind {
124    fn commit_kind(self) -> CommitKind {
125        match self {
126            Self::Change => CommitKind::Approved,
127            Self::Stamp => CommitKind::Stamp,
128            Self::Unstamp => CommitKind::Unstamp,
129            Self::Rollback(_) => CommitKind::Rollback,
130        }
131    }
132}
133
134struct PendingPlan {
135    view: ConfigPlanView,
136    kind: PlanKind,
137    snapshot: GateSnapshot,
138    modules: BTreeSet<String>,
139    changed: BTreeSet<InputKey>,
140    callosum_entry_changed: bool,
141    recovery: bool,
142    delivery: Option<crate::config_store::DeliverySnapshot>,
143}
144
145/// Memory-only plans cannot be replayed across a daemon restart. A successful
146/// generation commit changes the base revision and consumes its approval once.
147pub struct ConfigGate {
148    incarnation: String,
149    plans: BTreeMap<Digest, PendingPlan>,
150    attempts: BTreeMap<u64, approval::Attempt>,
151    next_attempt: u64,
152}
153
154impl ConfigGate {
155    pub(crate) fn plan_modules(&self, digest: &Digest) -> Result<BTreeSet<String>> {
156        self.plans
157            .get(digest)
158            .map(|plan| plan.modules.clone())
159            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))
160    }
161
162    pub(crate) fn cancel_attempt(&mut self, attempt: u64) {
163        self.attempts.remove(&attempt);
164    }
165
166    pub(crate) fn expire_plan(&mut self, digest: &Digest) -> bool {
167        self.plans.remove(digest).is_some()
168    }
169    pub fn new(incarnation: String) -> Self {
170        Self {
171            incarnation,
172            plans: BTreeMap::new(),
173            attempts: BTreeMap::new(),
174            next_attempt: 0,
175        }
176    }
177
178    /// `review` enforces the approved schema and every affected project's bounds
179    /// before asking admitted module reviewers. Refusals produce no plan.
180    pub fn plan(
181        &mut self,
182        store: &mut ConfigStore,
183        kind: PlanKind,
184        candidate: GateSnapshot,
185        observed: &GateSnapshot,
186        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
187    ) -> Result<ConfigPlanView> {
188        self.plan_reviewed(
189            store,
190            kind,
191            candidate,
192            observed,
193            ReviewRecord::Absent,
194            review,
195        )
196    }
197
198    /// As [`Self::plan`], also writing the record of which build each module's
199    /// approved configuration was reviewed by. A generation planned without that
200    /// record vouches for no review, so later plans treat each module it
201    /// approved as needing re-review.
202    pub(crate) fn plan_reviewed(
203        &mut self,
204        store: &mut ConfigStore,
205        kind: PlanKind,
206        candidate: GateSnapshot,
207        observed: &GateSnapshot,
208        record: ReviewRecord<'_>,
209        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
210    ) -> Result<ConfigPlanView> {
211        let status = store.status();
212        let recovery = matches!(
213            status.state,
214            StoreState::StoreUnverified | StoreState::StoreMissing
215        );
216        if (recovery && !matches!(kind, PlanKind::Stamp | PlanKind::Unstamp))
217            || (status.state == StoreState::Unstamped && kind != PlanKind::Stamp)
218        {
219            return Err(GateError::new(
220                "config_gated",
221                "stamp is required before planning changes",
222            ));
223        }
224        if self.plans.len() >= 64 {
225            return Err(GateError::new("config_busy", "too many pending plans"));
226        }
227        let mut rollback_programs = Vec::new();
228        if let PlanKind::Rollback(id) = kind {
229            let target = GateSnapshot::from_store(&store.rollback_configuration(id)?)?;
230            if target
231                .inputs
232                .iter()
233                .filter(|(key, _)| !key.is_program())
234                .ne(candidate.inputs.iter().filter(|(key, _)| !key.is_program()))
235            {
236                return Err(GateError::invalid(
237                    "rollback must reverse the target configuration",
238                ));
239            }
240            for (key, now) in candidate.inputs.iter().filter(|(key, _)| key.is_program()) {
241                if target.inputs.get(key) != Some(now) {
242                    rollback_programs.push(serde_json::json!({
243                        "module_id":key.module(),
244                        "input":key,
245                        "reason":"program changed since that version",
246                        "approved_then":target.inputs.get(key),
247                        "on_disk_now":now,
248                    }));
249                }
250            }
251        }
252        let (base_revision, base_generation, approved, active) = if recovery {
253            (0, 0, GateSnapshot::default(), BTreeMap::new())
254        } else {
255            store.delivery_ready()?;
256            let body = store.body()?;
257            let active = body
258                .versions
259                .iter()
260                .filter_map(|(tuple, versions)| {
261                    versions
262                        .active
263                        .map(|id| (serde_json::to_string(tuple).expect("tuple"), id))
264                })
265                .collect();
266            (
267                body.base_revision,
268                body.last_generation,
269                GateSnapshot::from_store(&body.approved)?,
270                active,
271            )
272        };
273        let changed: BTreeSet<InputKey> = approved
274            .changed_keys(&candidate)
275            .into_iter()
276            .cloned()
277            .collect();
278        let callosum_entry_changed = if changed.contains(&InputKey::Daemon) {
279            match (
280                approved.inputs.get(&InputKey::Daemon),
281                candidate.inputs.get(&InputKey::Daemon),
282            ) {
283                (
284                    Some(CapturedInput {
285                        value: subc_config::RecordedValue::Value { value: old },
286                        ..
287                    }),
288                    Some(CapturedInput {
289                        value: subc_config::RecordedValue::Value { value: new },
290                        ..
291                    }),
292                ) => old.pointer("/modules/callosum") != new.pointer("/modules/callosum"),
293                _ => true,
294            }
295        } else {
296            false
297        };
298        let mut modules: BTreeSet<String> = changed
299            .iter()
300            .filter_map(|key| key.module().map(str::to_owned))
301            .collect();
302        let mut changeset = review(&approved, &candidate)?;
303        for difference in &rollback_programs {
304            if let Some(module) = difference["module_id"].as_str() {
305                modules.insert(module.to_owned());
306                changeset
307                    .launch_manifests
308                    .entry(module.to_owned())
309                    .or_insert_with(|| serde_json::json!({}))
310                    .as_object_mut()
311                    .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
312                    .insert(
313                        "program_changed_since_target".into(),
314                        serde_json::Value::Bool(true),
315                    );
316            }
317        }
318        modules.extend(changeset.fields.iter().map(|field| field.module_id.clone()));
319        modules.extend(changeset.launch_manifests.keys().cloned());
320        if matches!(kind, PlanKind::Stamp | PlanKind::Unstamp) {
321            modules.extend(observed.modules());
322            modules.extend(approved.modules());
323        }
324        // Bind the full retained view and operation, including identity-only and
325        // declaration-only changes a module's scalar diff would not describe.
326        changeset.apply_plan = serde_json::json!({
327            "operation": match kind { PlanKind::Change => "change", PlanKind::Stamp => "stamp", PlanKind::Unstamp => "unstamp", PlanKind::Rollback(_) => "rollback" },
328            "rollback_to": if let PlanKind::Rollback(id) = kind { Some(id) } else { None },
329            "review": changeset.apply_plan,
330            "previous": approved.to_store()?,
331            "snapshot": candidate.to_store()?,
332        });
333        if matches!(kind, PlanKind::Rollback(_)) {
334            changeset.apply_plan["rollback_programs"] = serde_json::Value::Array(rollback_programs);
335        }
336        let replaces_programs =
337            !recovery && matches!(kind, PlanKind::Change | PlanKind::Rollback(_));
338        if replaces_programs {
339            // A module whose active generation ran an older program than this
340            // plan's (an earlier program change not yet active, say) still has
341            // that older process running. It must not acknowledge this
342            // generation either, even though the program matches the last
343            // approval.
344            let body = store.body()?;
345            for module in &modules {
346                if reviewed_build::active(body, module)?
347                    .is_some_and(|active| active != reviewed_build::identity(&candidate, module))
348                {
349                    changeset
350                        .launch_manifests
351                        .entry(module.clone())
352                        .or_insert_with(|| serde_json::json!({}))
353                        .as_object_mut()
354                        .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
355                        .insert(
356                            "program_changed_since_active".into(),
357                            serde_json::Value::Bool(true),
358                        );
359                }
360            }
361        }
362        let reviewed = match record {
363            ReviewRecord::Absent | ReviewRecord::Copied(None) => None,
364            ReviewRecord::Copied(Some(copied)) => {
365                changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = copied;
366                None
367            }
368            ReviewRecord::Reviewed(reviewed) => Some(reviewed),
369        };
370        if let Some(reviewed) = reviewed {
371            let mut record = if replaces_programs {
372                reviewed_build::recorded(store.body()?)?
373            } else {
374                BTreeMap::new()
375            };
376            let present = candidate.modules();
377            record.retain(|module, _| present.contains(module));
378            for module in reviewed {
379                // A stamp records the programs already running. Otherwise the
380                // reviewer is the process that acknowledged the active
381                // generation, or one admitted from the last approval when the
382                // module has never acknowledged one.
383                let program = if replaces_programs {
384                    match reviewed_build::active(store.body()?, module)? {
385                        Some(active) => active,
386                        None => reviewed_build::identity(&approved, module),
387                    }
388                } else {
389                    reviewed_build::identity(&candidate, module)
390                };
391                if let Some(previous) = record.get(module).filter(|previous| **previous != program)
392                {
393                    changeset.policy_changes.push(serde_json::json!({
394                        "module_id": module,
395                        "path": "reviewed_program",
396                        "old": previous,
397                        "new": program,
398                        "reason": "approved configuration re-reviewed by the module's newly approved program",
399                    }));
400                }
401                record.insert(module.clone(), program);
402            }
403            changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = serde_json::json!(record);
404        }
405        apply::bind_plan(&mut changeset)?;
406        let mut plan = Plan::new(
407            base_revision,
408            base_generation,
409            &self.incarnation,
410            observed.read_set(&modules)?,
411            changeset,
412        );
413        plan.active_generations = active;
414        let view = ConfigPlanView::new(plan).map_err(GateError::invalid)?;
415        self.plans.insert(
416            view.digest.clone(),
417            PendingPlan {
418                view: view.clone(),
419                kind,
420                snapshot: candidate,
421                modules,
422                changed,
423                callosum_entry_changed,
424                recovery,
425                delivery: None,
426            },
427        );
428        Ok(view)
429    }
430
431    fn plan_program_keys(&self, digest: &Digest) -> Result<Vec<InputKey>> {
432        let plan = self
433            .plans
434            .get(digest)
435            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
436        Ok(plan
437            .snapshot
438            .inputs
439            .keys()
440            .filter(|key| {
441                key.is_program()
442                    && key
443                        .module()
444                        .is_some_and(|module| plan.modules.contains(module))
445            })
446            .cloned()
447            .collect())
448    }
449
450    /// Attach daemon-reviewed raw inputs without exposing them in diagnostic
451    /// plans. The saved file identities and byte digests still bind the bytes
452    /// captured for review.
453    pub(crate) fn bind_delivery(
454        &mut self,
455        digest: &Digest,
456        delivery: crate::config_store::DeliverySnapshot,
457    ) -> Result<()> {
458        self.plans
459            .get_mut(digest)
460            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?
461            .delivery = Some(delivery);
462        Ok(())
463    }
464
465    /// Capture program identities for the reverse configuration's launch specs
466    /// at the restored paths at plan time. No executable bytes or historical
467    /// identities are restored. The restored generation's reviewed-program
468    /// record is copied: its reviewers are known. If that generation has no
469    /// record, the rollback has none either, so its modules owe re-review.
470    pub fn rollback(
471        &mut self,
472        store: &mut ConfigStore,
473        generation: u64,
474        observed: &GateSnapshot,
475        current_programs: &GateSnapshot,
476        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
477    ) -> Result<ConfigPlanView> {
478        let mut target = GateSnapshot::from_store(&store.rollback_configuration(generation)?)?;
479        target.restore_programs_from(current_programs)?;
480        let copied = store
481            .body()?
482            .generations
483            .get(&generation)
484            .and_then(|entry| {
485                entry
486                    .generation
487                    .changeset
488                    .apply_plan
489                    .get(reviewed_build::REVIEWED_PROGRAMS)
490            })
491            .cloned();
492        self.plan_reviewed(
493            store,
494            PlanKind::Rollback(generation),
495            target,
496            observed,
497            ReviewRecord::Copied(copied),
498            review,
499        )
500    }
501
502    fn fresh(plan: &PendingPlan, store: &mut ConfigStore, current: &GateSnapshot) -> Result<()> {
503        let status = store.status();
504        let recovery = matches!(
505            status.state,
506            StoreState::StoreUnverified | StoreState::StoreMissing
507        );
508        if recovery != plan.recovery {
509            return Err(GateError::stale());
510        }
511        let base = if recovery {
512            0
513        } else {
514            store.delivery_ready()?;
515            store.body()?.base_revision
516        };
517        plan.view
518            .plan
519            .check_fresh(base, &current.read_set(&plan.modules)?)
520            .map_err(|_| GateError::stale())
521    }
522
523    #[allow(clippy::too_many_arguments)]
524    fn commit(
525        &mut self,
526        digest: &Digest,
527        approval_channel: subc_config::ApprovalChannel,
528        store: &mut ConfigStore,
529        current: &GateSnapshot,
530        now_ms: u64,
531        before_publication: impl FnOnce() -> Result<()>,
532    ) -> Result<u64> {
533        let plan = self
534            .plans
535            .get(digest)
536            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
537        Self::fresh(plan, store, current)?;
538        let mut generation = Generation::new(
539            0,
540            approval_channel,
541            digest.clone(),
542            plan.view.plan.input_vector.clone(),
543            plan.view.plan.changeset.clone(),
544        );
545        generation.active_generations = plan.view.plan.active_generations.clone();
546        for module in &plan.modules {
547            generation
548                .module_states
549                .insert(module.clone(), subc_config::GenerationState::Pending);
550            if let Some(CapturedInput {
551                state: subc_config::InputState::Present { digest },
552                ..
553            }) = plan
554                .snapshot
555                .inputs
556                .get(&InputKey::Declaration(module.clone()))
557            {
558                generation
559                    .declaration_digests
560                    .insert(module.clone(), digest.clone());
561            }
562        }
563        let tuples: BTreeSet<Tuple> = plan
564            .modules
565            .iter()
566            .map(|module| Tuple {
567                module: module.clone(),
568                project: None,
569            })
570            .chain(plan.view.plan.changeset.fields.iter().map(|field| Tuple {
571                module: field.module_id.clone(),
572                project: field.project_id.clone(),
573            }))
574            .chain(plan.modules.iter().flat_map(|module| {
575                plan.view
576                    .plan
577                    .changeset
578                    .affected_projects
579                    .iter()
580                    .map(move |project| Tuple {
581                        module: module.clone(),
582                        project: Some(project.clone()),
583                    })
584            }))
585            .collect();
586        let snapshot = plan.snapshot.to_store()?;
587        let entry = HistoryEntry {
588            generation,
589            kind: plan.kind.commit_kind(),
590            approval_id: digest.to_string(),
591            outcome: "approved".into(),
592            tuples,
593            configuration: snapshot.clone(),
594            delivery: plan.delivery.clone(),
595        };
596        let base_before = store.status().base_revision;
597        let observed = current.to_store()?;
598        before_publication()?;
599        let result = if plan.recovery {
600            store.recovery_exit(entry, snapshot, now_ms)
601        } else {
602            store.commit_generation(entry, snapshot, observed, now_ms)
603        };
604        // The sealed store's external revision/digest anchor may fail to update
605        // after a durable commit. The committed base makes the old plan stale;
606        // never repeat that generation while retrying the anchor update.
607        if result.is_ok() || store.status().base_revision != base_before {
608            self.plans.remove(digest);
609        }
610        let id = result?;
611        store.delivery_ready()?;
612        Ok(id)
613    }
614}
615
616mod registration;
617#[cfg(test)]
618mod tests;