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