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    development_approval: Option<crate::program_origin::DevelopmentApproval>,
136    view: ConfigPlanView,
137    kind: PlanKind,
138    snapshot: GateSnapshot,
139    modules: BTreeSet<String>,
140    changed: BTreeSet<InputKey>,
141    callosum_entry_changed: bool,
142    recovery: bool,
143    delivery: Option<crate::config_store::DeliverySnapshot>,
144}
145
146/// Memory-only plans cannot be replayed across a daemon restart. A successful
147/// generation commit changes the base revision and consumes its approval once.
148pub struct ConfigGate {
149    incarnation: String,
150    plans: BTreeMap<Digest, PendingPlan>,
151    attempts: BTreeMap<u64, approval::Attempt>,
152    next_attempt: u64,
153}
154
155impl ConfigGate {
156    pub(crate) fn plan_modules(&self, digest: &Digest) -> Result<BTreeSet<String>> {
157        self.plans
158            .get(digest)
159            .map(|plan| plan.modules.clone())
160            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))
161    }
162
163    pub(crate) fn cancel_attempt(&mut self, attempt: u64) {
164        self.attempts.remove(&attempt);
165    }
166
167    pub(crate) fn expire_plan(&mut self, digest: &Digest) -> bool {
168        self.plans.remove(digest).is_some()
169    }
170    pub fn new(incarnation: String) -> Self {
171        Self {
172            incarnation,
173            plans: BTreeMap::new(),
174            attempts: BTreeMap::new(),
175            next_attempt: 0,
176        }
177    }
178
179    /// `review` enforces the approved schema and every affected project's bounds
180    /// before asking admitted module reviewers. Refusals produce no plan.
181    pub fn plan(
182        &mut self,
183        store: &mut ConfigStore,
184        kind: PlanKind,
185        candidate: GateSnapshot,
186        observed: &GateSnapshot,
187        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
188    ) -> Result<ConfigPlanView> {
189        self.plan_reviewed(
190            store,
191            kind,
192            candidate,
193            observed,
194            ReviewRecord::Absent,
195            review,
196        )
197    }
198
199    /// As [`Self::plan`], also writing the record of which build each module's
200    /// approved configuration was reviewed by. A generation planned without that
201    /// record vouches for no review, so later plans treat each module it
202    /// approved as needing re-review.
203    pub(crate) fn plan_reviewed(
204        &mut self,
205        store: &mut ConfigStore,
206        kind: PlanKind,
207        candidate: GateSnapshot,
208        observed: &GateSnapshot,
209        record: ReviewRecord<'_>,
210        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
211    ) -> Result<ConfigPlanView> {
212        let status = store.status();
213        let recovery = matches!(
214            status.state,
215            StoreState::StoreUnverified | StoreState::StoreMissing
216        );
217        if (recovery && !matches!(kind, PlanKind::Stamp | PlanKind::Unstamp))
218            || (status.state == StoreState::Unstamped && kind != PlanKind::Stamp)
219        {
220            return Err(GateError::new(
221                "config_gated",
222                "stamp is required before planning changes",
223            ));
224        }
225        if self.plans.len() >= 64 {
226            return Err(GateError::new("config_busy", "too many pending plans"));
227        }
228        let mut rollback_programs = Vec::new();
229        if let PlanKind::Rollback(id) = kind {
230            let target = GateSnapshot::from_store(&store.rollback_configuration(id)?)?;
231            if target
232                .inputs
233                .iter()
234                .filter(|(key, _)| !key.is_program())
235                .ne(candidate.inputs.iter().filter(|(key, _)| !key.is_program()))
236            {
237                return Err(GateError::invalid(
238                    "rollback must reverse the target configuration",
239                ));
240            }
241            for (key, now) in candidate.inputs.iter().filter(|(key, _)| key.is_program()) {
242                if target.inputs.get(key) != Some(now) {
243                    rollback_programs.push(serde_json::json!({
244                        "module_id":key.module(),
245                        "input":key,
246                        "reason":"program changed since that version",
247                        "approved_then":target.inputs.get(key),
248                        "on_disk_now":now,
249                    }));
250                }
251            }
252        }
253        let (base_revision, base_generation, approved, active) = if recovery {
254            (0, 0, GateSnapshot::default(), BTreeMap::new())
255        } else {
256            store.delivery_ready()?;
257            let body = store.body()?;
258            let active = body
259                .versions
260                .iter()
261                .filter_map(|(tuple, versions)| {
262                    versions
263                        .active
264                        .map(|id| (serde_json::to_string(tuple).expect("tuple"), id))
265                })
266                .collect();
267            (
268                body.base_revision,
269                body.last_generation,
270                GateSnapshot::from_store(&body.approved)?,
271                active,
272            )
273        };
274        let changed: BTreeSet<InputKey> = approved
275            .changed_keys(&candidate)
276            .into_iter()
277            .cloned()
278            .collect();
279        let callosum_entry_changed = if changed.contains(&InputKey::Daemon) {
280            match (
281                approved.inputs.get(&InputKey::Daemon),
282                candidate.inputs.get(&InputKey::Daemon),
283            ) {
284                (
285                    Some(CapturedInput {
286                        value: subc_config::RecordedValue::Value { value: old },
287                        ..
288                    }),
289                    Some(CapturedInput {
290                        value: subc_config::RecordedValue::Value { value: new },
291                        ..
292                    }),
293                ) => old.pointer("/modules/callosum") != new.pointer("/modules/callosum"),
294                _ => true,
295            }
296        } else {
297            false
298        };
299        let mut modules: BTreeSet<String> = changed
300            .iter()
301            .filter_map(|key| key.module().map(str::to_owned))
302            .collect();
303        let mut changeset = review(&approved, &candidate)?;
304        for difference in &rollback_programs {
305            if let Some(module) = difference["module_id"].as_str() {
306                modules.insert(module.to_owned());
307                changeset
308                    .launch_manifests
309                    .entry(module.to_owned())
310                    .or_insert_with(|| serde_json::json!({}))
311                    .as_object_mut()
312                    .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
313                    .insert(
314                        "program_changed_since_target".into(),
315                        serde_json::Value::Bool(true),
316                    );
317            }
318        }
319        modules.extend(changeset.fields.iter().map(|field| field.module_id.clone()));
320        modules.extend(changeset.launch_manifests.keys().cloned());
321        if matches!(kind, PlanKind::Stamp | PlanKind::Unstamp) {
322            modules.extend(observed.modules());
323            modules.extend(approved.modules());
324        }
325        // Bind the full retained view and operation, including identity-only and
326        // declaration-only changes a module's scalar diff would not describe.
327        changeset.apply_plan = serde_json::json!({
328            "operation": match kind { PlanKind::Change => "change", PlanKind::Stamp => "stamp", PlanKind::Unstamp => "unstamp", PlanKind::Rollback(_) => "rollback" },
329            "rollback_to": if let PlanKind::Rollback(id) = kind { Some(id) } else { None },
330            "review": changeset.apply_plan,
331            "previous": approved.to_store()?,
332            "snapshot": candidate.to_store()?,
333        });
334        if matches!(kind, PlanKind::Rollback(_)) {
335            changeset.apply_plan["rollback_programs"] = serde_json::Value::Array(rollback_programs);
336        }
337        let replaces_programs =
338            !recovery && matches!(kind, PlanKind::Change | PlanKind::Rollback(_));
339        if replaces_programs {
340            // A module whose active generation ran an older program than this
341            // plan's (an earlier program change not yet active, say) still has
342            // that older process running. It must not acknowledge this
343            // generation either, even though the program matches the last
344            // approval.
345            let body = store.body()?;
346            for module in &modules {
347                if reviewed_build::active(body, module)?
348                    .is_some_and(|active| active != reviewed_build::identity(&candidate, module))
349                {
350                    changeset
351                        .launch_manifests
352                        .entry(module.clone())
353                        .or_insert_with(|| serde_json::json!({}))
354                        .as_object_mut()
355                        .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
356                        .insert(
357                            "program_changed_since_active".into(),
358                            serde_json::Value::Bool(true),
359                        );
360                }
361            }
362        }
363        let reviewed = match record {
364            ReviewRecord::Absent | ReviewRecord::Copied(None) => None,
365            ReviewRecord::Copied(Some(copied)) => {
366                changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = copied;
367                None
368            }
369            ReviewRecord::Reviewed(reviewed) => Some(reviewed),
370        };
371        if let Some(reviewed) = reviewed {
372            let mut record = if replaces_programs {
373                reviewed_build::recorded(store.body()?)?
374            } else {
375                BTreeMap::new()
376            };
377            let present = candidate.modules();
378            record.retain(|module, _| present.contains(module));
379            for module in reviewed {
380                // A stamp records the programs already running. Otherwise the
381                // reviewer is the process that acknowledged the active
382                // generation, or one admitted from the last approval when the
383                // module has never acknowledged one.
384                let program = if replaces_programs {
385                    match reviewed_build::active(store.body()?, module)? {
386                        Some(active) => active,
387                        None => reviewed_build::identity(&approved, module),
388                    }
389                } else {
390                    reviewed_build::identity(&candidate, module)
391                };
392                if let Some(previous) = record.get(module).filter(|previous| **previous != program)
393                {
394                    changeset.policy_changes.push(serde_json::json!({
395                        "module_id": module,
396                        "path": "reviewed_program",
397                        "old": previous,
398                        "new": program,
399                        "reason": "approved configuration re-reviewed by the module's newly approved program",
400                    }));
401                }
402                record.insert(module.clone(), program);
403            }
404            changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = serde_json::json!(record);
405        }
406        apply::bind_plan(&mut changeset)?;
407        let mut plan = Plan::new(
408            base_revision,
409            base_generation,
410            &self.incarnation,
411            observed.read_set(&modules)?,
412            changeset,
413        );
414        plan.active_generations = active;
415        let view = ConfigPlanView::new(plan).map_err(GateError::invalid)?;
416        self.plans.insert(
417            view.digest.clone(),
418            PendingPlan {
419                development_approval: None,
420                view: view.clone(),
421                kind,
422                snapshot: candidate,
423                modules,
424                changed,
425                callosum_entry_changed,
426                recovery,
427                delivery: None,
428            },
429        );
430        Ok(view)
431    }
432
433    fn plan_program_keys(&self, digest: &Digest) -> Result<Vec<InputKey>> {
434        let plan = self
435            .plans
436            .get(digest)
437            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
438        Ok(plan
439            .snapshot
440            .inputs
441            .keys()
442            .filter(|key| {
443                key.is_program()
444                    && key
445                        .module()
446                        .is_some_and(|module| plan.modules.contains(module))
447            })
448            .cloned()
449            .collect())
450    }
451
452    /// Attach daemon-reviewed raw inputs without exposing them in diagnostic
453    /// plans. The saved file identities and byte digests still bind the bytes
454    /// captured for review.
455    pub(crate) fn bind_delivery(
456        &mut self,
457        digest: &Digest,
458        delivery: crate::config_store::DeliverySnapshot,
459    ) -> Result<()> {
460        self.plans
461            .get_mut(digest)
462            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?
463            .delivery = Some(delivery);
464        Ok(())
465    }
466
467    /// Capture program identities for the reverse configuration's launch specs
468    /// at the restored paths at plan time. No executable bytes or historical
469    /// identities are restored. The restored generation's reviewed-program
470    /// record is copied: its reviewers are known. If that generation has no
471    /// record, the rollback has none either, so its modules owe re-review.
472    pub fn rollback(
473        &mut self,
474        store: &mut ConfigStore,
475        generation: u64,
476        observed: &GateSnapshot,
477        current_programs: &GateSnapshot,
478        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
479    ) -> Result<ConfigPlanView> {
480        let mut target = GateSnapshot::from_store(&store.rollback_configuration(generation)?)?;
481        target.restore_programs_from(current_programs)?;
482        let copied = store
483            .body()?
484            .generations
485            .get(&generation)
486            .and_then(|entry| {
487                entry
488                    .generation
489                    .changeset
490                    .apply_plan
491                    .get(reviewed_build::REVIEWED_PROGRAMS)
492            })
493            .cloned();
494        self.plan_reviewed(
495            store,
496            PlanKind::Rollback(generation),
497            target,
498            observed,
499            ReviewRecord::Copied(copied),
500            review,
501        )
502    }
503
504    fn fresh(plan: &PendingPlan, store: &mut ConfigStore, current: &GateSnapshot) -> Result<()> {
505        let status = store.status();
506        let recovery = matches!(
507            status.state,
508            StoreState::StoreUnverified | StoreState::StoreMissing
509        );
510        if recovery != plan.recovery {
511            return Err(GateError::stale());
512        }
513        let base = if recovery {
514            0
515        } else {
516            store.delivery_ready()?;
517            store.body()?.base_revision
518        };
519        plan.view
520            .plan
521            .check_fresh(base, &current.read_set(&plan.modules)?)
522            .map_err(|_| GateError::stale())
523    }
524
525    #[allow(clippy::too_many_arguments)]
526    fn commit(
527        &mut self,
528        digest: &Digest,
529        approval_channel: subc_config::ApprovalChannel,
530        store: &mut ConfigStore,
531        current: &GateSnapshot,
532        now_ms: u64,
533        before_publication: impl FnOnce() -> Result<()>,
534    ) -> Result<u64> {
535        let plan = self
536            .plans
537            .get(digest)
538            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
539        Self::fresh(plan, store, current)?;
540        let mut generation = Generation::new(
541            0,
542            approval_channel,
543            digest.clone(),
544            plan.view.plan.input_vector.clone(),
545            plan.view.plan.changeset.clone(),
546        );
547        let declarations_only = plan.development_approval.is_some();
548        generation.active_generations = plan.view.plan.active_generations.clone();
549        for module in plan.modules.iter().filter(|_| !declarations_only) {
550            generation
551                .module_states
552                .insert(module.clone(), subc_config::GenerationState::Pending);
553            if let Some(CapturedInput {
554                state: subc_config::InputState::Present { digest },
555                ..
556            }) = plan
557                .snapshot
558                .inputs
559                .get(&InputKey::Declaration(module.clone()))
560            {
561                generation
562                    .declaration_digests
563                    .insert(module.clone(), digest.clone());
564            }
565        }
566        let mut tuples: BTreeSet<Tuple> = plan
567            .modules
568            .iter()
569            .map(|module| Tuple {
570                module: module.clone(),
571                project: None,
572            })
573            .chain(plan.view.plan.changeset.fields.iter().map(|field| Tuple {
574                module: field.module_id.clone(),
575                project: field.project_id.clone(),
576            }))
577            .chain(plan.modules.iter().flat_map(|module| {
578                plan.view
579                    .plan
580                    .changeset
581                    .affected_projects
582                    .iter()
583                    .map(move |project| Tuple {
584                        module: module.clone(),
585                        project: Some(project.clone()),
586                    })
587            }))
588            .collect();
589        if declarations_only {
590            tuples.clear();
591        }
592        let snapshot = plan.snapshot.to_store()?;
593        let entry = HistoryEntry {
594            generation,
595            kind: if declarations_only {
596                CommitKind::DeclarationApproval
597            } else {
598                plan.kind.commit_kind()
599            },
600            approval_id: digest.to_string(),
601            outcome: "approved".into(),
602            tuples,
603            configuration: snapshot.clone(),
604            delivery: plan.delivery.clone(),
605        };
606        let base_before = store.status().base_revision;
607        let observed = current.to_store()?;
608        before_publication()?;
609        let result = if plan.recovery {
610            store.recovery_exit(entry, snapshot, now_ms)
611        } else {
612            store.commit_generation(entry, snapshot, observed, now_ms)
613        };
614        // The sealed store's external revision/digest anchor may fail to update
615        // after a durable commit. The committed base makes the old plan stale;
616        // never repeat that generation while retrying the anchor update.
617        if result.is_ok() || store.status().base_revision != base_before {
618            self.plans.remove(digest);
619        }
620        let id = result?;
621        store.delivery_ready()?;
622        Ok(id)
623    }
624}
625
626mod registration;
627#[cfg(test)]
628mod tests;