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        // Keep activation policy out of reviewer metadata. `small_prompt` in
328        // approval.rs offers the compact one-change prompt only when `review`
329        // is null, so leaving the transition table in it would deny that
330        // prompt to every one-field change.
331        let transitions = changeset
332            .apply_plan
333            .as_object_mut()
334            .and_then(|review| review.remove("module_transitions"));
335        if transitions.is_some()
336            && changeset
337                .apply_plan
338                .as_object()
339                .is_some_and(|review| review.is_empty())
340        {
341            changeset.apply_plan = serde_json::Value::Null;
342        }
343        changeset.apply_plan = serde_json::json!({
344            "operation": match kind { PlanKind::Change => "change", PlanKind::Stamp => "stamp", PlanKind::Unstamp => "unstamp", PlanKind::Rollback(_) => "rollback" },
345            "rollback_to": if let PlanKind::Rollback(id) = kind { Some(id) } else { None },
346            "review": changeset.apply_plan,
347            "previous": approved.to_store()?,
348            "snapshot": candidate.to_store()?,
349        });
350        if let Some(transitions) = transitions {
351            if let Some(table) = transitions.as_object() {
352                modules.extend(table.keys().cloned());
353            }
354            changeset.apply_plan["module_transitions"] = transitions;
355        }
356        if matches!(kind, PlanKind::Rollback(_)) {
357            changeset.apply_plan["rollback_programs"] = serde_json::Value::Array(rollback_programs);
358        }
359        let replaces_programs =
360            !recovery && matches!(kind, PlanKind::Change | PlanKind::Rollback(_));
361        if replaces_programs {
362            // A module whose active generation ran an older program than this
363            // plan's (an earlier program change not yet active, say) still has
364            // that older process running. It must not acknowledge this
365            // generation either, even though the program matches the last
366            // approval.
367            let body = store.body()?;
368            for module in &modules {
369                if reviewed_build::active(body, module)?
370                    .is_some_and(|active| active != reviewed_build::identity(&candidate, module))
371                {
372                    changeset
373                        .launch_manifests
374                        .entry(module.clone())
375                        .or_insert_with(|| serde_json::json!({}))
376                        .as_object_mut()
377                        .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
378                        .insert(
379                            "program_changed_since_active".into(),
380                            serde_json::Value::Bool(true),
381                        );
382                }
383            }
384        }
385        let reviewed = match record {
386            ReviewRecord::Absent | ReviewRecord::Copied(None) => None,
387            ReviewRecord::Copied(Some(copied)) => {
388                changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = copied;
389                None
390            }
391            ReviewRecord::Reviewed(reviewed) => Some(reviewed),
392        };
393        if let Some(reviewed) = reviewed {
394            let mut record = if replaces_programs {
395                reviewed_build::recorded(store.body()?)?
396            } else {
397                BTreeMap::new()
398            };
399            let present = candidate.modules();
400            record.retain(|module, _| present.contains(module));
401            for module in reviewed {
402                // A stamp records the programs already running. Otherwise the
403                // reviewer is the process that acknowledged the active
404                // generation, or one admitted from the last approval when the
405                // module has never acknowledged one.
406                let program = if replaces_programs {
407                    match reviewed_build::active(store.body()?, module)? {
408                        Some(active) => active,
409                        None => reviewed_build::identity(&approved, module),
410                    }
411                } else {
412                    reviewed_build::identity(&candidate, module)
413                };
414                if let Some(previous) = record.get(module).filter(|previous| **previous != program)
415                {
416                    changeset.policy_changes.push(serde_json::json!({
417                        "module_id": module,
418                        "path": "reviewed_program",
419                        "old": previous,
420                        "new": program,
421                        "reason": "approved configuration re-reviewed by the module's newly approved program",
422                    }));
423                }
424                record.insert(module.clone(), program);
425            }
426            changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = serde_json::json!(record);
427        }
428        apply::bind_plan(&mut changeset)?;
429        let mut plan = Plan::new(
430            base_revision,
431            base_generation,
432            &self.incarnation,
433            observed.read_set(&modules)?,
434            changeset,
435        );
436        plan.active_generations = active;
437        let view = ConfigPlanView::new(plan).map_err(GateError::invalid)?;
438        self.plans.insert(
439            view.digest.clone(),
440            PendingPlan {
441                development_approval: None,
442                view: view.clone(),
443                kind,
444                snapshot: candidate,
445                modules,
446                changed,
447                callosum_entry_changed,
448                recovery,
449                delivery: None,
450            },
451        );
452        Ok(view)
453    }
454
455    fn plan_program_keys(&self, digest: &Digest) -> Result<Vec<InputKey>> {
456        let plan = self
457            .plans
458            .get(digest)
459            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
460        Ok(plan
461            .snapshot
462            .inputs
463            .keys()
464            .filter(|key| {
465                key.is_program()
466                    && key
467                        .module()
468                        .is_some_and(|module| plan.modules.contains(module))
469            })
470            .cloned()
471            .collect())
472    }
473
474    /// Attach daemon-reviewed raw inputs without exposing them in diagnostic
475    /// plans. The saved file identities and byte digests still bind the bytes
476    /// captured for review.
477    pub(crate) fn bind_delivery(
478        &mut self,
479        digest: &Digest,
480        delivery: crate::config_store::DeliverySnapshot,
481    ) -> Result<()> {
482        self.plans
483            .get_mut(digest)
484            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?
485            .delivery = Some(delivery);
486        Ok(())
487    }
488
489    /// Capture program identities for the reverse configuration's launch specs
490    /// at the restored paths at plan time. No executable bytes or historical
491    /// identities are restored. The restored generation's reviewed-program
492    /// record is copied: its reviewers are known. If that generation has no
493    /// record, the rollback has none either, so its modules owe re-review.
494    pub fn rollback(
495        &mut self,
496        store: &mut ConfigStore,
497        generation: u64,
498        observed: &GateSnapshot,
499        current_programs: &GateSnapshot,
500        review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
501    ) -> Result<ConfigPlanView> {
502        let mut target = GateSnapshot::from_store(&store.rollback_configuration(generation)?)?;
503        target.restore_programs_from(current_programs)?;
504        let copied = store
505            .body()?
506            .generations
507            .get(&generation)
508            .and_then(|entry| {
509                entry
510                    .generation
511                    .changeset
512                    .apply_plan
513                    .get(reviewed_build::REVIEWED_PROGRAMS)
514            })
515            .cloned();
516        self.plan_reviewed(
517            store,
518            PlanKind::Rollback(generation),
519            target,
520            observed,
521            ReviewRecord::Copied(copied),
522            review,
523        )
524    }
525
526    fn fresh(plan: &PendingPlan, store: &mut ConfigStore, current: &GateSnapshot) -> Result<()> {
527        let status = store.status();
528        let recovery = matches!(
529            status.state,
530            StoreState::StoreUnverified | StoreState::StoreMissing
531        );
532        if recovery != plan.recovery {
533            return Err(GateError::stale());
534        }
535        let base = if recovery {
536            0
537        } else {
538            store.delivery_ready()?;
539            store.body()?.base_revision
540        };
541        plan.view
542            .plan
543            .check_fresh(base, &current.read_set(&plan.modules)?)
544            .map_err(|_| GateError::stale())
545    }
546
547    #[allow(clippy::too_many_arguments)]
548    fn commit(
549        &mut self,
550        digest: &Digest,
551        approval_channel: subc_config::ApprovalChannel,
552        store: &mut ConfigStore,
553        current: &GateSnapshot,
554        now_ms: u64,
555        before_publication: impl FnOnce() -> Result<()>,
556    ) -> Result<u64> {
557        let plan = self
558            .plans
559            .get(digest)
560            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
561        Self::fresh(plan, store, current)?;
562        let mut generation = Generation::new(
563            0,
564            approval_channel,
565            digest.clone(),
566            plan.view.plan.input_vector.clone(),
567            plan.view.plan.changeset.clone(),
568        );
569        let declarations_only = plan.development_approval.is_some();
570        generation.active_generations = plan.view.plan.active_generations.clone();
571        for module in plan.modules.iter().filter(|_| !declarations_only) {
572            generation
573                .module_states
574                .insert(module.clone(), subc_config::GenerationState::Pending);
575            if let Some(CapturedInput {
576                state: subc_config::InputState::Present { digest },
577                ..
578            }) = plan
579                .snapshot
580                .inputs
581                .get(&InputKey::Declaration(module.clone()))
582            {
583                generation
584                    .declaration_digests
585                    .insert(module.clone(), digest.clone());
586            }
587        }
588        let mut tuples: BTreeSet<Tuple> = plan
589            .modules
590            .iter()
591            .map(|module| Tuple {
592                module: module.clone(),
593                project: None,
594            })
595            .chain(plan.view.plan.changeset.fields.iter().map(|field| Tuple {
596                module: field.module_id.clone(),
597                project: field.project_id.clone(),
598            }))
599            .chain(plan.modules.iter().flat_map(|module| {
600                plan.view
601                    .plan
602                    .changeset
603                    .affected_projects
604                    .iter()
605                    .map(move |project| Tuple {
606                        module: module.clone(),
607                        project: Some(project.clone()),
608                    })
609            }))
610            .collect();
611        if declarations_only {
612            tuples.clear();
613        }
614        let snapshot = plan.snapshot.to_store()?;
615        let entry = HistoryEntry {
616            generation,
617            kind: if declarations_only {
618                CommitKind::DeclarationApproval
619            } else {
620                plan.kind.commit_kind()
621            },
622            approval_id: digest.to_string(),
623            outcome: "approved".into(),
624            tuples,
625            configuration: snapshot.clone(),
626            delivery: plan.delivery.clone(),
627        };
628        let base_before = store.status().base_revision;
629        let observed = current.to_store()?;
630        before_publication()?;
631        let result = if plan.recovery {
632            store.recovery_exit(entry, snapshot, now_ms)
633        } else {
634            store.commit_generation(entry, snapshot, observed, now_ms)
635        };
636        // The sealed store's external revision/digest anchor may fail to update
637        // after a durable commit. The committed base makes the old plan stale;
638        // never repeat that generation while retrying the anchor update.
639        if result.is_ok() || store.status().base_revision != base_before {
640            self.plans.remove(digest);
641        }
642        let id = result?;
643        store.delivery_ready()?;
644        Ok(id)
645    }
646}
647
648mod registration;
649#[cfg(test)]
650mod tests;