Skip to main content

subc_daemon/config_gate/
runtime.rs

1//! Serialized production owner for the approval engine and durable authority.
2
3use std::{
4    collections::{BTreeMap, BTreeSet, HashMap, VecDeque},
5    sync::Mutex,
6    time::{Duration, Instant},
7};
8
9use subc_config::{Changeset, Digest};
10use subc_control::config::ConfigPlanView;
11use subc_protocol::config::{
12    ConfigDeclareRequest, ConfigLayer, ConfigLayerSnapshot, ConfigStatus, ConfigView,
13};
14
15use super::{
16    capture::{CapturedConfiguration, ConfigCapturer},
17    ApprovalChallenge, ApprovalFacts, ApprovalReply, ConfigGate, GateError, PlanKind, Result,
18};
19use crate::{
20    config_store::{ConfigStore, DeliverySnapshot, StoreActivity, StoreState},
21    ConnectionId,
22};
23
24pub struct RuntimeOwner {
25    #[cfg(test)]
26    config_park_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
27    #[cfg(test)]
28    pub(crate) content_kill_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
29    #[cfg(test)]
30    polled_capture_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
31    #[cfg(test)]
32    polled_capture_count: std::sync::atomic::AtomicUsize,
33    #[cfg(test)]
34    census_probe: Mutex<Option<std::sync::Arc<dyn Fn() + Send + Sync>>>,
35    #[cfg(test)]
36    agent_validation_window: Mutex<Option<Duration>>,
37    #[cfg(test)]
38    pub(crate) warm_restart_pause: Mutex<Option<WarmRestartPause>>,
39    #[cfg(test)]
40    pub(crate) warm_restart_busy: Mutex<Option<tokio::sync::oneshot::Sender<()>>>,
41    #[cfg(test)]
42    pub(crate) swap_preflight_attempts: std::sync::atomic::AtomicUsize,
43    #[cfg(feature = "test-support")]
44    test_hooks: Option<crate::config_store::testing::TestSupport>,
45    #[cfg(test)]
46    spawn_exec_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
47    published: std::sync::RwLock<std::sync::Arc<Published>>,
48    configured_modules: std::sync::RwLock<Option<admission::ConfiguredModuleSnapshot>>,
49    inner: Mutex<OwnerState>,
50    capturer: ConfigCapturer,
51    startup_overrides: Vec<String>,
52    module_gates: Mutex<HashMap<String, std::sync::Arc<tokio::sync::Mutex<()>>>>,
53    delivery_changed: std::sync::Arc<tokio::sync::Notify>,
54    route_policy_authority: std::sync::OnceLock<std::sync::Arc<dyn RoutePolicyAuthority>>,
55    binding_retirements: Mutex<BTreeMap<usize, Box<dyn Fn() + Send + Sync>>>,
56    canceled_approvals: Mutex<Vec<u64>>,
57    // Reader and Drop callbacks must not wait behind a keychain or disk check.
58    // These short queues/indexes never perform store I/O while locked.
59    approval_request_index: Mutex<HashMap<(ConnectionId, u64), std::sync::Arc<ApprovalRequest>>>,
60    disconnected_pending: Mutex<Vec<ConnectionId>>,
61    abandoned_spawns: Mutex<Vec<(DeliverySpawn, bool)>>,
62    phone_withdrawals: Mutex<phone::PhoneWithdrawals>,
63    #[cfg(any(test, feature = "test-support"))]
64    os_prompt_policy: std::sync::atomic::AtomicBool,
65    #[cfg(test)]
66    spawn_preflight_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
67    #[cfg(test)]
68    exit_record_attempts: std::sync::atomic::AtomicUsize,
69    #[cfg(test)]
70    phone_bind_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
71    #[cfg(test)]
72    begin_approval_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
73    #[cfg(test)]
74    begin_approval_completions: std::sync::atomic::AtomicUsize,
75    #[cfg(test)]
76    desktop_receipt_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
77    #[cfg(test)]
78    prepare_capture_hook: Mutex<Option<Box<dyn FnOnce() + Send>>>,
79    #[cfg(all(test, unix))]
80    approval_claim_pause: Mutex<Option<ApprovalClaimPause>>,
81}
82
83/// An in-memory cutover transaction. It is borrowed only for synchronous
84/// forwarding, registry and delivery-target publication under one module gate.
85pub(crate) struct SwapConfiguration<'a> {
86    owner: &'a RuntimeOwner,
87    state: OwnerGuard<'a>,
88}
89
90#[cfg(test)]
91pub(crate) struct WarmRestartPause {
92    pub(crate) reached: tokio::sync::oneshot::Sender<()>,
93    pub(crate) resume: tokio::sync::oneshot::Receiver<()>,
94}
95
96impl SwapConfiguration<'_> {
97    pub(crate) fn before_cutover(
98        &mut self,
99        module: &str,
100        connection: ConnectionId,
101        spawn: Option<&DeliverySpawn>,
102    ) -> Result<Option<u64>> {
103        match self.state.store.loaded_admission_state().0 {
104            StoreState::Unstamped => return Ok(None),
105            StoreState::Stamped => {}
106            _ => {
107                return Err(GateError::new(
108                    "config_gated",
109                    "configuration store is in recovery",
110                ))
111            }
112        }
113        let newer = RuntimeOwner::requires_fresher_spawn_loaded(&self.state, module, spawn)?;
114        if newer.is_none() {
115            self.owner.module_get_locked(
116                &mut self.state,
117                connection,
118                module,
119                subc_protocol::config::ConfigGetRequest::new(),
120                false,
121            )?;
122        }
123        Ok(newer)
124    }
125    pub(crate) fn promoted(
126        &mut self,
127        module: &str,
128        connection: ConnectionId,
129        at: tokio::time::Instant,
130    ) -> Result<()> {
131        RuntimeOwner::promote_loaded(&mut self.state, connection, module, at).map(|_| ())
132    }
133}
134
135#[cfg(all(test, unix))]
136struct ApprovalClaimPause {
137    reached: tokio::sync::oneshot::Sender<()>,
138    release: tokio::sync::oneshot::Receiver<()>,
139}
140
141/// The post-answer deadline can withdraw queued work, but never a publication
142/// that has crossed the final commit point while holding its owned gates.
143pub(crate) struct ApprovalCommitWindow {
144    pub deadline: tokio::time::Instant,
145    phase: std::sync::atomic::AtomicU8,
146}
147
148impl ApprovalCommitWindow {
149    pub(crate) fn new(deadline: tokio::time::Instant) -> Self {
150        Self {
151            deadline,
152            phase: std::sync::atomic::AtomicU8::new(0),
153        }
154    }
155
156    pub(crate) fn expire(&self) -> bool {
157        self.phase
158            .compare_exchange(
159                0,
160                2,
161                std::sync::atomic::Ordering::AcqRel,
162                std::sync::atomic::Ordering::Acquire,
163            )
164            .is_ok()
165    }
166
167    fn begin_publication(&self) -> Result<()> {
168        if tokio::time::Instant::now() >= self.deadline {
169            self.expire();
170            return Err(GateError::commit_timeout());
171        }
172        self.phase
173            .compare_exchange(
174                0,
175                1,
176                std::sync::atomic::Ordering::AcqRel,
177                std::sync::atomic::Ordering::Acquire,
178            )
179            .map(|_| ())
180            .map_err(|_| GateError::commit_timeout())
181    }
182}
183
184pub use route_policy::{
185    ApprovedRoutePolicy, RoutePolicyAuthority, RoutePolicyInstall, RoutePolicyInstallation,
186    RoutePolicyReceipt,
187};
188
189pub use delivery::{AppliedDisposition, DeliveryProbe, DeliverySpawn};
190
191/// Supervisor callbacks for the configuration delivery lifecycle. The caller
192/// supplies observed process events, never a module's claimed readiness.
193/// Target checks and promotion callbacks run under [`RuntimeOwner::module_gate`]
194/// across forwarding and registry changes. The spawn token binds a later
195/// registration to the approved generation and its original warm-up deadline.
196pub trait DeliveryObserver: Send + Sync {
197    fn spawned(
198        &self,
199        module: &str,
200        spawned_at: tokio::time::Instant,
201        register_timeout: std::time::Duration,
202        first_health_budget: std::time::Duration,
203    ) -> Result<Option<DeliverySpawn>>;
204    fn registered(&self, connection: ConnectionId, spawn: &DeliverySpawn) -> Result<()>;
205    fn health_probe(&self, connection: ConnectionId, module: &str)
206        -> Result<Option<DeliveryProbe>>;
207    fn health_result(
208        &self,
209        probe: DeliveryProbe,
210        healthy: bool,
211    ) -> Result<Option<AppliedDisposition>>;
212    fn promoted(
213        &self,
214        connection: ConnectionId,
215        module: &str,
216        cutover_at: tokio::time::Instant,
217    ) -> Result<Option<(u64, u64)>>;
218    /// Retry only the retained, non-interactive backend when its backoff is due.
219    /// `None` means there is no pending anchor and no timer should be armed.
220    fn retry_anchor(&self) -> Result<Option<tokio::time::Instant>>;
221}
222
223impl DeliveryObserver for RuntimeOwner {
224    fn spawned(
225        &self,
226        module: &str,
227        spawned_at: tokio::time::Instant,
228        register_timeout: std::time::Duration,
229        first_health_budget: std::time::Duration,
230    ) -> Result<Option<DeliverySpawn>> {
231        self.delivery_spawned(module, spawned_at, register_timeout, first_health_budget)
232    }
233
234    fn registered(&self, connection: ConnectionId, spawn: &DeliverySpawn) -> Result<()> {
235        self.delivery_child_registered(connection, spawn)
236    }
237
238    /// Capture before dispatching the ordinary health RPC. A later result must
239    /// use this witness, not look up whichever target is current on completion.
240    fn health_probe(
241        &self,
242        connection: ConnectionId,
243        module: &str,
244    ) -> Result<Option<DeliveryProbe>> {
245        self.delivery_health_probe(connection, module)
246    }
247
248    /// Complete under the module gate. A new target, attempt or policy install
249    /// invalidates an older witness rather than lending its health to new bytes.
250    fn health_result(
251        &self,
252        probe: DeliveryProbe,
253        healthy: bool,
254    ) -> Result<Option<AppliedDisposition>> {
255        self.delivery_health_result(probe, healthy)
256    }
257
258    fn promoted(
259        &self,
260        connection: ConnectionId,
261        module: &str,
262        cutover_at: tokio::time::Instant,
263    ) -> Result<Option<(u64, u64)>> {
264        self.delivery_promoted(connection, module, cutover_at)
265    }
266
267    fn retry_anchor(&self) -> Result<Option<tokio::time::Instant>> {
268        self.poll_anchor_retry()
269    }
270}
271
272/// Keep a reviewed plan for one idle hour so the operator can read the full diff.
273const PLAN_IDLE_TIMEOUT: Duration = Duration::from_secs(60 * 60);
274/// One shared sweep reclaims idle plans without allocating a timer per plan.
275pub(crate) const PLAN_SWEEP_INTERVAL: Duration = Duration::from_secs(60);
276/// Remember recent expirations by digest without retaining unbounded plan bodies.
277const EXPIRED_PLAN_IDS: usize = 64;
278
279pub(crate) fn daemon_review(
280    old: &super::GateSnapshot,
281    new: &super::GateSnapshot,
282) -> Result<Changeset> {
283    let mut changeset = Changeset::new();
284    for key in old.changed_keys(new) {
285        match key {
286            super::InputKey::Entry(module) | super::InputKey::Program { module, .. } => {
287                let field = match key {
288                    super::InputKey::Entry(_) => "entry".into(),
289                    super::InputKey::Program { path, .. } => format!("program:{path}"),
290                    _ => unreachable!(),
291                };
292                let manifest = changeset
293                    .launch_manifests
294                    .entry(module.clone())
295                    .or_insert_with(|| serde_json::json!({}));
296                manifest.as_object_mut().expect("launch manifest is an object").insert(field,serde_json::json!({"old":old.inputs.get(key).map(|v| &v.value),"new":new.inputs.get(key).map(|v| &v.value)}));
297            }
298            super::InputKey::Declaration(module) => {
299                changeset.policy_changes.push(serde_json::json!({"module_id":module,"path":"declaration","old":old.inputs.get(key).map(|v| &v.value),"new":new.inputs.get(key).map(|v| &v.value)}));
300            }
301            super::InputKey::Daemon => {
302                changeset.policy_changes.push(serde_json::json!({
303                    "path":"subc.jsonc",
304                    "old":old.inputs.get(key).map(|v| &v.value),
305                    "new":new.inputs.get(key).map(|v| &v.value),
306                }));
307                changeset.apply_plan = serde_json::json!({"supervisor_reconcile":true});
308            }
309            _ => {}
310        }
311    }
312    Ok(changeset)
313}
314
315struct OwnerState {
316    authority_incarnation: std::sync::Arc<()>,
317    observed_snapshot: Option<super::GateSnapshot>,
318    stamp_channel_cutover: bool,
319    gate: ConfigGate,
320    store: ConfigStore,
321    _writer_lock: Option<crate::config_store::StoreWriterLock>,
322    plan_deadlines: BTreeMap<Digest, Instant>,
323    // Only a successfully flushed complete plan on this connection can bind
324    // its desktop approval. A later view replaces the connection's old view.
325    desktop_views: BTreeMap<u64, (Digest, u64)>,
326    phone_waiters: BTreeMap<u64, tokio::sync::oneshot::Sender<()>>,
327    approval_requests: HashMap<(ConnectionId, u64), u64>,
328    delivery: delivery::DeliveryState,
329    anchor_retry: super::anchor_retry::AnchorRetry,
330    // Keep the original objects alive through approval so an unlinked file's
331    // inode/file id cannot be recycled to impersonate the reviewed input.
332    retained_plan_files: BTreeMap<Digest, Vec<std::fs::File>>,
333    expired_plans: VecDeque<Digest>,
334    declarations: HashMap<ConnectionId, (String, ConfigDeclareRequest)>,
335    active_declarations: BTreeMap<String, ConnectionId>,
336    activity: Option<crate::activity::ActivityLedger>,
337    refused_generations: BTreeMap<String, Digest>,
338    admission_holds: Vec<String>,
339    admission_releases: Vec<String>,
340    authority_exit: Option<u64>,
341    // Last reconciled daemon entries, independent of module-layer activation.
342    reconciled_entries: BTreeMap<String, crate::daemon_config::ConfiguredModule>,
343    recovery_exit_hold: bool,
344    unstamp_hints: std::collections::HashSet<ConnectionId>,
345    anchor_waiters: std::collections::HashSet<ConnectionId>,
346    anchor_hints: std::collections::HashSet<ConnectionId>,
347    anchor_notify: std::sync::Arc<tokio::sync::Notify>,
348    installed_route_policies: BTreeMap<String, u64>,
349    route_policy_receipts: BTreeMap<(String, u64), route_policy::PendingRoutePolicy>,
350    #[cfg(test)]
351    publication_hook: Option<Box<dyn FnOnce() + Send>>,
352    #[cfg(test)]
353    prepublication_hook: Option<Box<dyn FnOnce() + Send>>,
354    #[cfg(test)]
355    after_approval_drain_hook: Option<Box<dyn FnOnce() + Send>>,
356}
357
358impl OwnerState {
359    fn retry_anchor(&mut self, operator_command: bool) -> Option<tokio::time::Instant> {
360        let pending = self.store.status().anchor_pending;
361        let events = self.anchor_retry.poll(
362            pending,
363            tokio::time::Instant::now(),
364            operator_command,
365            || {
366                let error = self
367                    .store
368                    .retry_anchor()
369                    .err()
370                    .map(|error| error.to_string());
371                (self.store.status().anchor_pending, error)
372            },
373        );
374        for event in events {
375            match event {
376                super::anchor_retry::Event::Pending => {
377                    tracing::info!("configuration anchor became pending")
378                }
379                super::anchor_retry::Event::Failed(reason) => {
380                    tracing::warn!(%reason, "configuration anchor retry failed")
381                }
382                super::anchor_retry::Event::Recovered => {
383                    tracing::info!("configuration anchor recovered");
384                    self.queue_anchor_hints();
385                }
386            }
387        }
388        self.commit_anchored_route_policies();
389        self.anchor_retry.next()
390    }
391    fn with_desktop_view(&self, digest: &Digest, facts: &ApprovalFacts) -> ApprovalFacts {
392        let mut checked = facts.clone();
393        let bound = self
394            .desktop_views
395            .get(&facts.connection)
396            .is_some_and(|(shown, revision)| {
397                shown == digest
398                    && self
399                        .gate
400                        .plans
401                        .get(digest)
402                        .is_some_and(|plan| plan.view.base_revision == *revision)
403            });
404        if !bound {
405            checked.desktop_app = false;
406            checked.attested_operator_app = false;
407        }
408        checked
409    }
410    fn expire_idle(&mut self, now: Instant) {
411        let expired: Vec<_> = self
412            .plan_deadlines
413            .iter()
414            .filter(|(digest, deadline)| **deadline <= now && !self.gate.has_open_approval(digest))
415            .map(|(digest, _)| digest.clone())
416            .collect();
417        for digest in expired {
418            self.plan_deadlines.remove(&digest);
419            self.retained_plan_files.remove(&digest);
420            self.desktop_views.retain(|_, (shown, _)| shown != &digest);
421            if self.gate.expire_plan(&digest) {
422                self.expired_plans.push_back(digest);
423                if self.expired_plans.len() > EXPIRED_PLAN_IDS {
424                    self.expired_plans.pop_front();
425                }
426            }
427        }
428    }
429    fn reviewed(&mut self, digest: &Digest, now: Instant) {
430        self.plan_deadlines
431            .insert(digest.clone(), now + PLAN_IDLE_TIMEOUT);
432        self.expired_plans.retain(|expired| expired != digest);
433    }
434}
435
436struct OwnerGuard<'a>(
437    std::sync::MutexGuard<'a, OwnerState>,
438    &'a std::sync::RwLock<std::sync::Arc<Published>>,
439    &'a tokio::sync::Notify,
440    &'a Mutex<HashMap<String, std::sync::Arc<tokio::sync::Mutex<()>>>>,
441    &'a RuntimeOwner,
442);
443impl std::ops::Deref for OwnerGuard<'_> {
444    type Target = OwnerState;
445    fn deref(&self) -> &Self::Target {
446        &self.0
447    }
448}
449impl std::ops::DerefMut for OwnerGuard<'_> {
450    fn deref_mut(&mut self) -> &mut Self::Target {
451        &mut self.0
452    }
453}
454impl Drop for OwnerGuard<'_> {
455    fn drop(&mut self) {
456        // Project committed or invalidated authority before releasing its owner.
457        // Parse changed generations outside the cheap reader lock, then publish
458        // only the Arc; list polling never waits for store or keychain work.
459        let previous = self
460            .1
461            .read()
462            .map(|view| view.approved_daemon.clone())
463            .unwrap_or(ApprovedDaemonView::Unavailable);
464        let approved_daemon =
465            ApprovedDaemonView::from_store(&self.0.store, self.0.recovery_exit_hold, &previous);
466        // Volatile holds follow the same lifetime as their durable records.
467        // Approving another program identity retires the previous identity's
468        // volatile hold, even if that previous identity is later approved again.
469        let (_, body) = self.0.store.loaded_admission_state();
470        let valid: std::collections::BTreeSet<_> = body
471            .program_refusals
472            .iter()
473            .map(|refusal| (refusal.module.clone(), refusal.approved_base.clone()))
474            .collect();
475        self.0
476            .refused_generations
477            .retain(|module, base| valid.contains(&(module.clone(), base.clone())));
478        let next = admission::AdmissionCache::from_state(&self.0);
479        let observed = self.0.observed_snapshot.clone();
480        let projection = self.4.status_projection(&mut self.0, observed, &next);
481        if let Ok(mut cache) = self.1.write() {
482            let (holds, releases) = next.transitions_from(&cache);
483            let changed = next.is_recovering() != cache.is_recovering()
484                || !holds.is_empty()
485                || !releases.is_empty();
486            self.0.admission_holds.extend(holds);
487            self.0.admission_releases.extend(releases);
488            *cache = std::sync::Arc::new(Published {
489                admission: next,
490                approved_daemon,
491                projection,
492            });
493            if changed {
494                self.2.notify_one();
495            }
496        }
497        let Some(ledger) = self.0.activity.clone() else {
498            return;
499        };
500        let Ok(gates) = self.3.try_lock() else {
501            return;
502        };
503        let held: Vec<_> = gates
504            .values()
505            .filter(|gate| gate.try_lock().is_err())
506            .cloned()
507            .collect();
508        drop(gates);
509        if held.is_empty() {
510            for activity in self.0.store.take_activities() {
511                ledger.config_store_activity(activity);
512            }
513        } else if let Ok(runtime) = tokio::runtime::Handle::try_current() {
514            let activities = self.0.store.take_activities();
515            if !activities.is_empty() {
516                runtime.spawn(async move {
517                    // No store mutex follows the activity into this task. Drop
518                    // each gate before waiting for another, then publish the log.
519                    for gate in held {
520                        drop(gate.lock_owned().await);
521                    }
522                    for activity in activities {
523                        ledger.config_store_activity(activity);
524                    }
525                });
526            }
527        }
528    }
529}
530
531pub struct PreparedPlan {
532    pub candidate: CapturedConfiguration,
533    pub bases: BTreeMap<String, ConfigView>,
534    pub base_schemas: BTreeMap<String, subc_config::Schema>,
535    pub kind: PlanKind,
536    pub review_modules: std::collections::BTreeSet<String>,
537    /// Modules in `review_modules` only because their newly approved program
538    /// is active and has not yet reviewed their approved layers. A missing
539    /// reviewer drops such a module from this plan instead of failing it.
540    pub rereview_modules: std::collections::BTreeSet<String>,
541    base_revision: u64,
542    active_generations: BTreeMap<crate::config_store::Tuple, Option<u64>>,
543    touched_modules: BTreeSet<String>,
544    read_set: subc_config::InputVector,
545    program_keys: Vec<super::InputKey>,
546    observed_handles: Vec<std::fs::File>,
547}
548
549/// Immutable command inputs for the supervisor's approved rollback admission.
550pub struct ApprovedRollbackCommands {
551    pub generation: u64,
552    pub daemon: ConfigLayerSnapshot,
553    pub programs: BTreeMap<String, ApprovedRollbackProgram>,
554}
555
556/// A supervisor reconciliation witness minted only from a verified committed
557/// generation. Keeping the raw layer prevents a caller from substituting a
558/// freshly parsed live file for the approved command inputs.
559#[derive(Clone, Debug)]
560pub(crate) struct ApprovedDaemonConfiguration {
561    generation: u64,
562    approval_digest: Digest,
563    authority_incarnation: std::sync::Arc<()>,
564    daemon: std::sync::Arc<ConfigLayerSnapshot>,
565    changed_entries: BTreeSet<String>,
566}
567
568#[derive(Clone, Debug)]
569pub(crate) struct ApprovalIdentity {
570    generation: u64,
571    approval_digest: Digest,
572    // Rebuilding rejected store authority from unchanged files can repeat both
573    // generation and digest. Retain this token in ApprovedDaemonConfiguration and
574    // each actor's approved_start_failure so old failures cannot alias new authority.
575    authority_incarnation: std::sync::Arc<()>,
576}
577
578impl PartialEq for ApprovalIdentity {
579    fn eq(&self, other: &Self) -> bool {
580        self.generation == other.generation
581            && self.approval_digest == other.approval_digest
582            && std::sync::Arc::ptr_eq(&self.authority_incarnation, &other.authority_incarnation)
583    }
584}
585
586impl Eq for ApprovalIdentity {}
587
588pub struct ApprovedRollbackProgram {
589    pub path: String,
590    pub identity: super::CapturedInput,
591}
592
593#[cfg(test)]
594#[path = "runtime_tests.rs"]
595mod tests;
596
597#[cfg(test)]
598#[path = "commit_pause.rs"]
599pub(crate) mod commit_pause;
600
601#[path = "delivery.rs"]
602pub(crate) mod delivery;
603
604#[path = "admission.rs"]
605mod admission;
606#[path = "recovery.rs"]
607mod recovery;
608#[path = "route_policy.rs"]
609mod route_policy;
610pub(crate) use admission::SpawnAdmission;
611
612#[path = "approval_request.rs"]
613mod approval_request;
614#[path = "daemon_readers.rs"]
615mod daemon_readers;
616pub(crate) use daemon_readers::ApprovedDaemonView;
617#[path = "phone.rs"]
618mod phone;
619#[path = "placement.rs"]
620mod placement;
621#[path = "polled.rs"]
622mod polled;
623#[path = "published.rs"]
624mod published;
625pub(crate) use published::Published;
626#[path = "status_inputs.rs"]
627mod status_inputs;
628pub(crate) use approval_request::{ApprovalRequest, ApprovalRequestGuard, CancelApprovalRequest};
629
630impl RuntimeOwner {
631    /// Keep store I/O and waits for its synchronous owner lock off runtime threads.
632    pub(crate) async fn on_blocking<T: Send + 'static>(
633        self: &std::sync::Arc<Self>,
634        work: impl FnOnce(std::sync::Arc<Self>) -> Result<T> + Send + 'static,
635    ) -> Result<T> {
636        let owner = self.clone();
637        tokio::task::spawn_blocking(move || work(owner))
638            .await
639            .map_err(|_| GateError::new("config_unavailable", "configuration worker stopped"))?
640    }
641
642    #[cfg(feature = "test-support")]
643    pub(crate) fn pause_spawn_before_exec(&self) -> Result<()> {
644        if let Some(hooks) = &self.test_hooks {
645            hooks
646                .pause_spawn_before_exec()
647                .map_err(|error| GateError::new("config_test_pause", error.to_string()))?;
648        }
649        Ok(())
650    }
651
652    #[cfg(feature = "test-support")]
653    pub(crate) fn pause_swap_before_promotion(&self) -> Result<()> {
654        if let Some(hooks) = &self.test_hooks {
655            hooks
656                .pause_swap_before_promotion()
657                .map_err(|error| GateError::new("config_test_pause", error.to_string()))?;
658        }
659        Ok(())
660    }
661    /// Record the exact full response only after its writer flush succeeds and
662    /// the adapter revalidates the same live desktop connection.
663    #[cfg(test)]
664    pub(crate) fn desktop_view_delivered(
665        &self,
666        connection: ConnectionId,
667        view: &subc_control::config::ConfigPlanView,
668    ) -> Result<()> {
669        self.desktop_view_delivered_when(connection, view, || true)
670    }
671
672    pub(crate) fn desktop_view_delivered_when(
673        &self,
674        connection: ConnectionId,
675        view: &subc_control::config::ConfigPlanView,
676        is_live: impl FnOnce() -> bool,
677    ) -> Result<()> {
678        #[cfg(test)]
679        if let Some(hook) = self.desktop_receipt_hook.lock().unwrap().take() {
680            hook();
681        }
682        let mut state = self.lock()?;
683        // Check the live peer after acquiring the owner, without retaining the
684        // peer mutex during an owner wait or any configuration/store work.
685        if !is_live() {
686            return Ok(());
687        }
688        let plan = state
689            .gate
690            .plans
691            .get(&view.digest)
692            .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or expired"))?;
693        if plan.view != *view {
694            return Err(GateError::new(
695                "plan_stale",
696                "delivered view differs from the immutable plan",
697            ));
698        }
699        state
700            .desktop_views
701            .insert(connection.get(), (view.digest.clone(), view.base_revision));
702        Ok(())
703    }
704    pub fn new(incarnation: String, mut store: ConfigStore, capturer: ConfigCapturer) -> Self {
705        // Daemon-restart generations newer than the booted one stay deferred.
706        let initial_generation = match store.booted_generation() {
707            Some(booted) => booted,
708            None => store.body().map(|body| body.last_generation).unwrap_or(0),
709        };
710        let admission = admission::AdmissionCache::from_store(&store);
711        let approved_daemon =
712            ApprovedDaemonView::from_store(&store, false, &ApprovedDaemonView::Unavailable);
713        let reconciled_entries = match &approved_daemon {
714            ApprovedDaemonView::Approved { config, .. } => config
715                .modules
716                .iter()
717                .map(|module| (module.module_id.clone(), module.clone()))
718                .collect(),
719            _ => BTreeMap::new(),
720        };
721        let published = std::sync::RwLock::new(std::sync::Arc::new(Published {
722            admission,
723            approved_daemon,
724            projection: polled::Projection::default(),
725        }));
726        let delivery_changed = std::sync::Arc::new(tokio::sync::Notify::new());
727        let owner = Self {
728            #[cfg(test)]
729            polled_capture_hook: Mutex::new(None),
730            #[cfg(test)]
731            config_park_hook: Mutex::new(None),
732            #[cfg(test)]
733            content_kill_hook: Mutex::new(None),
734            #[cfg(test)]
735            polled_capture_count: std::sync::atomic::AtomicUsize::new(0),
736            #[cfg(test)]
737            census_probe: Mutex::new(None),
738            #[cfg(test)]
739            agent_validation_window: Mutex::new(None),
740            #[cfg(test)]
741            warm_restart_pause: Mutex::new(None),
742            #[cfg(test)]
743            warm_restart_busy: Mutex::new(None),
744            #[cfg(test)]
745            swap_preflight_attempts: std::sync::atomic::AtomicUsize::new(0),
746            #[cfg(feature = "test-support")]
747            test_hooks: store.test_support().cloned(),
748            #[cfg(test)]
749            spawn_exec_hook: Mutex::new(None),
750            published,
751            configured_modules: std::sync::RwLock::new(None),
752            inner: Mutex::new(OwnerState {
753                authority_incarnation: std::sync::Arc::new(()),
754                observed_snapshot: None,
755                stamp_channel_cutover: false,
756                gate: ConfigGate::new(incarnation),
757                store,
758                _writer_lock: None,
759                plan_deadlines: BTreeMap::new(),
760                desktop_views: BTreeMap::new(),
761                phone_waiters: BTreeMap::new(),
762                approval_requests: HashMap::new(),
763                delivery: delivery::DeliveryState::new(initial_generation),
764                anchor_retry: super::anchor_retry::AnchorRetry::default(),
765                retained_plan_files: BTreeMap::new(),
766                expired_plans: VecDeque::new(),
767                declarations: HashMap::new(),
768                active_declarations: BTreeMap::new(),
769                activity: None,
770                refused_generations: BTreeMap::new(),
771                admission_holds: Vec::new(),
772                admission_releases: Vec::new(),
773                authority_exit: None,
774                reconciled_entries,
775                recovery_exit_hold: false,
776                unstamp_hints: std::collections::HashSet::new(),
777                anchor_waiters: std::collections::HashSet::new(),
778                anchor_hints: std::collections::HashSet::new(),
779                anchor_notify: delivery_changed.clone(),
780                installed_route_policies: BTreeMap::new(),
781                route_policy_receipts: BTreeMap::new(),
782                #[cfg(test)]
783                publication_hook: None,
784                #[cfg(test)]
785                prepublication_hook: None,
786                #[cfg(test)]
787                after_approval_drain_hook: None,
788            }),
789            capturer,
790            startup_overrides: status_inputs::present_overrides(|name| {
791                std::env::var_os(name).is_some()
792            }),
793            module_gates: Mutex::new(HashMap::new()),
794            delivery_changed,
795            route_policy_authority: std::sync::OnceLock::new(),
796            binding_retirements: Mutex::new(BTreeMap::new()),
797            canceled_approvals: Mutex::new(Vec::new()),
798            approval_request_index: Mutex::new(HashMap::new()),
799            disconnected_pending: Mutex::new(Vec::new()),
800            abandoned_spawns: Mutex::new(Vec::new()),
801            phone_withdrawals: Mutex::new(phone::PhoneWithdrawals::default()),
802            #[cfg(any(test, feature = "test-support"))]
803            os_prompt_policy: std::sync::atomic::AtomicBool::new(false),
804            #[cfg(test)]
805            spawn_preflight_hook: Mutex::new(None),
806            #[cfg(test)]
807            exit_record_attempts: std::sync::atomic::AtomicUsize::new(0),
808            #[cfg(test)]
809            phone_bind_hook: Mutex::new(None),
810            #[cfg(test)]
811            begin_approval_hook: Mutex::new(None),
812            #[cfg(test)]
813            begin_approval_completions: std::sync::atomic::AtomicUsize::new(0),
814            #[cfg(test)]
815            desktop_receipt_hook: Mutex::new(None),
816            #[cfg(test)]
817            prepare_capture_hook: Mutex::new(None),
818            #[cfg(all(test, unix))]
819            approval_claim_pause: Mutex::new(None),
820        };
821        if let Ok(state) = owner.lock() {
822            drop(state);
823        }
824        owner
825    }
826
827    pub fn module_gate(&self, module: &str) -> Result<std::sync::Arc<tokio::sync::Mutex<()>>> {
828        let mut gates = self
829            .module_gates
830            .lock()
831            .map_err(|_| GateError::new("config_unavailable", "module gate lock is poisoned"))?;
832        Ok(gates.entry(module.into()).or_default().clone())
833    }
834
835    #[cfg(all(test, unix))]
836    pub(crate) fn set_agent_validation_window_for_test(&self, window: Duration) {
837        *self.agent_validation_window.lock().unwrap() = Some(window);
838    }
839
840    #[cfg(test)]
841    pub(crate) fn agent_validation_window_for_test(&self) -> Option<Duration> {
842        *self.agent_validation_window.lock().unwrap()
843    }
844
845    pub(crate) fn install_binding_retirement(
846        &self,
847        key: usize,
848        retire: impl Fn() + Send + Sync + 'static,
849    ) {
850        self.binding_retirements
851            .lock()
852            .unwrap_or_else(|poisoned| poisoned.into_inner())
853            .insert(key, Box::new(retire));
854    }
855
856    pub(crate) fn delivery_notifications(&self) -> std::sync::Arc<tokio::sync::Notify> {
857        self.delivery_changed.clone()
858    }
859
860    pub(crate) fn notify_delivery_changed(&self) {
861        self.delivery_changed.notify_one();
862    }
863
864    pub(crate) fn retain_writer_lock(
865        self,
866        lock: crate::config_store::StoreWriterLock,
867    ) -> Result<Self> {
868        self.lock()?._writer_lock = Some(lock);
869        Ok(self)
870    }
871
872    fn lock(&self) -> Result<OwnerGuard<'_>> {
873        let mut guard = self
874            .inner
875            .lock()
876            .map(|guard| {
877                OwnerGuard(
878                    guard,
879                    &self.published,
880                    &self.delivery_changed,
881                    &self.module_gates,
882                    self,
883                )
884            })
885            .map_err(|_| {
886                GateError::new("config_unavailable", "configuration owner lock is poisoned")
887            })?;
888        #[cfg(feature = "test-support")]
889        guard.store.refresh_test_anchor_failure();
890        self.drain_canceled_approvals(&mut guard);
891        self.drain_disconnections(&mut guard);
892        self.drain_abandoned_spawns(&mut guard);
893        guard.expire_idle(Instant::now());
894        Ok(guard)
895    }
896
897    pub(crate) fn try_swap_configuration(&self) -> Result<SwapConfiguration<'_>> {
898        let state = self.inner.try_lock().map_err(|_| {
899            GateError::new(
900                "config_delivery_deferred",
901                "configuration publication is busy or unavailable",
902            )
903        })?;
904        Ok(SwapConfiguration {
905            owner: self,
906            state: OwnerGuard(
907                state,
908                &self.published,
909                &self.delivery_changed,
910                &self.module_gates,
911                self,
912            ),
913        })
914    }
915
916    pub(crate) fn try_requires_fresher_spawn(
917        &self,
918        module: &str,
919        spawn: Option<&DeliverySpawn>,
920    ) -> Result<Option<u64>> {
921        let state = self.inner.try_lock().map_err(|_| {
922            GateError::new(
923                "config_delivery_deferred",
924                "configuration publication is busy or unavailable",
925            )
926        })?;
927        Self::requires_fresher_spawn_loaded(&state, module, spawn)
928    }
929
930    pub(crate) fn sweep_expired(&self) -> Result<()> {
931        drop(self.lock()?);
932        Ok(())
933    }
934
935    pub(crate) fn poll_anchor_retry(&self) -> Result<Option<tokio::time::Instant>> {
936        Ok(self.lock()?.retry_anchor(false))
937    }
938
939    pub(crate) fn set_activity(
940        &self,
941        ledger: Option<crate::activity::ActivityLedger>,
942    ) -> Result<()> {
943        self.lock()?.activity = ledger;
944        Ok(())
945    }
946
947    pub fn take_activities(&self) -> Vec<StoreActivity> {
948        self.inner
949            .lock()
950            .map(|mut state| state.store.take_activities())
951            .unwrap_or_default()
952    }
953
954    /// Declaration ownership comes from the registered transport connection.
955    /// A candidate's proposal is retained without replacing the incumbent's.
956    pub fn declare(
957        &self,
958        connection: ConnectionId,
959        module: &str,
960        declaration: ConfigDeclareRequest,
961        active: bool,
962    ) -> Result<()> {
963        subc_config::Schema::new(declaration.schema.clone())
964            .map_err(|r| GateError::new("schema_invalid", format!("{module}: {}", r.path)))?;
965        let mut state = self.lock()?;
966        if state.store.status().state == StoreState::StoreMissing
967            || state.store.status().state == StoreState::StoreUnverified
968        {
969            return Err(GateError::new(
970                "config_gated",
971                "configuration store is in recovery",
972            ));
973        }
974        if state.declarations.contains_key(&connection) {
975            return Err(GateError::new(
976                "declaration_order",
977                "configuration is declared once per connection",
978            ));
979        }
980        state
981            .declarations
982            .insert(connection, (module.into(), declaration));
983        state.delivery.declared(connection, module, active);
984        if active {
985            state.active_declarations.insert(module.into(), connection);
986        }
987        Ok(())
988    }
989
990    pub fn disconnected(&self, connection: ConnectionId) {
991        if let Ok(mut index) = self.approval_request_index.lock() {
992            index.retain(|(caller, _), request| {
993                if *caller == connection {
994                    request.cancel();
995                    false
996                } else {
997                    true
998                }
999            });
1000        }
1001        self.notify_delivery_changed();
1002        if let Ok(mut state) = self.inner.try_lock() {
1003            state.disconnected(connection);
1004        } else if let Ok(mut pending) = self.disconnected_pending.lock() {
1005            pending.push(connection);
1006        }
1007    }
1008
1009    pub fn module_get(
1010        &self,
1011        connection: ConnectionId,
1012        module: &str,
1013        request: subc_protocol::config::ConfigGetRequest,
1014    ) -> Result<subc_protocol::config::ConfigGetReply> {
1015        let mut state = self.lock()?;
1016        self.module_get_locked(&mut state, connection, module, request, true)
1017    }
1018
1019    fn module_get_locked(
1020        &self,
1021        state: &mut OwnerState,
1022        connection: ConnectionId,
1023        module: &str,
1024        request: subc_protocol::config::ConfigGetRequest,
1025        check_store: bool,
1026    ) -> Result<subc_protocol::config::ConfigGetReply> {
1027        let declaration = state
1028            .declarations
1029            .get(&connection)
1030            .filter(|(id, _)| id == module)
1031            .map(|(_, declaration)| declaration.clone())
1032            .ok_or_else(|| {
1033                GateError::new(
1034                    "declaration_order",
1035                    "config.declare must precede get or applied on this connection",
1036                )
1037            })?;
1038        if request.project_id.is_some() {
1039            return Err(GateError::new(
1040                "project_registry_unavailable",
1041                format!("{module}: project layer registry is not connected"),
1042            ));
1043        }
1044        if check_store {
1045            let checked = state.store.check();
1046            if matches!(
1047                state.store.loaded_admission_state().0,
1048                StoreState::StoreMissing | StoreState::StoreUnverified
1049            ) {
1050                return recovery::active_view(state, module, &declaration, &request);
1051            }
1052            checked?;
1053        }
1054        if state.store.loaded_admission_state().0 == StoreState::Unstamped {
1055            if request.generation.is_some() || request.attempt.is_some() {
1056                return Err(GateError::new(
1057                    "config_gated",
1058                    "unstamped reads have no assigned generation or delivery attempt",
1059                ));
1060            }
1061            let mut declarations = Self::declarations(state)?;
1062            declarations.insert(module.into(), declaration);
1063            let mut captured = self
1064                .capturer
1065                .capture_modules(&declarations, &BTreeSet::from([module.to_owned()]))?;
1066            let view = captured
1067                .modules
1068                .remove(module)
1069                .ok_or_else(|| GateError::new("config_gated", "module declaration is unavailable"))?
1070                .view;
1071            return Ok(subc_protocol::config::ConfigGetReply::new(Some(view), None));
1072        }
1073        if check_store {
1074            state.store.delivery_ready()?;
1075        }
1076        let body = if check_store {
1077            state.store.body()?
1078        } else {
1079            state.store.loaded_admission_state().1
1080        };
1081        let tuple = crate::config_store::Tuple {
1082            module: module.into(),
1083            project: None,
1084        };
1085        let versions = body
1086            .versions
1087            .iter()
1088            .find(|(entry, _)| entry == &tuple)
1089            .map(|(_, versions)| versions)
1090            .ok_or_else(|| {
1091                GateError::new("config_gated", "module is not in an approved generation")
1092            })?;
1093        let approved_declaration = [versions.pending, versions.active]
1094            .into_iter()
1095            .flatten()
1096            .any(|generation| {
1097                body.generations
1098                    .get(&generation)
1099                    .and_then(|entry| entry.delivery.as_ref())
1100                    .and_then(|snapshot| snapshot.declarations.get(module))
1101                    == Some(&declaration)
1102            });
1103        if !approved_declaration {
1104            return Err(GateError::new(
1105                "config_gated",
1106                "connection declaration differs from approved declaration",
1107            ));
1108        }
1109        let view = |generation: Option<u64>, status: ConfigStatus| -> Result<Option<ConfigView>> {
1110            let Some(generation) = generation else {
1111                return Ok(None);
1112            };
1113            let delivery = body
1114                .generations
1115                .get(&generation)
1116                .and_then(|entry| entry.delivery.as_ref())
1117                .ok_or_else(|| {
1118                    GateError::new("config_gated", "approved delivery bytes are absent")
1119                })?;
1120            let mut view =
1121                delivery.modules.get(module).cloned().ok_or_else(|| {
1122                    GateError::new("config_gated", "approved module view is absent")
1123                })?;
1124            view.generation = generation;
1125            view.status = status;
1126            Ok(Some(view))
1127        };
1128        let active = view(versions.active, ConfigStatus::Active)?;
1129        let pending = view(versions.pending, ConfigStatus::Pending)?;
1130        let transition = versions
1131            .pending
1132            .and_then(|id| body.generations.get(&id))
1133            .map(|entry| super::apply::Transition::for_module(&entry.generation.changeset, module))
1134            .transpose()?
1135            .unwrap_or(super::apply::Transition::Live);
1136        if active.is_none() && pending.is_none() {
1137            return Err(GateError::new(
1138                "config_gated",
1139                "module has no active or deliverable generation",
1140            ));
1141        }
1142        if !check_store {
1143            return delivery::visible_reply(
1144                state,
1145                connection,
1146                subc_protocol::config::ConfigGetReply::new(active, pending),
1147                transition,
1148            );
1149        }
1150        delivery::bind_get(
1151            state,
1152            connection,
1153            module,
1154            &request,
1155            subc_protocol::config::ConfigGetReply::new(active, pending),
1156            transition,
1157        )
1158    }
1159
1160    fn declarations(state: &mut OwnerState) -> Result<BTreeMap<String, ConfigDeclareRequest>> {
1161        let mut declarations = if state.store.status().state == StoreState::Stamped {
1162            state
1163                .store
1164                .body()?
1165                .generations
1166                .values()
1167                .next_back()
1168                .and_then(|entry| entry.delivery.as_ref())
1169                .map(|snapshot| snapshot.declarations.clone())
1170                .unwrap_or_default()
1171        } else {
1172            BTreeMap::new()
1173        };
1174        for (module, connection) in &state.active_declarations {
1175            if let Some((_, declaration)) = state.declarations.get(connection) {
1176                declarations.insert(module.clone(), declaration.clone());
1177            }
1178        }
1179        Ok(declarations)
1180    }
1181
1182    fn capture(&self, state: &mut OwnerState) -> Result<CapturedConfiguration> {
1183        let declarations = Self::declarations(state)?;
1184        let captured = self.capturer.capture(&declarations)?;
1185        state.observed_snapshot = Some(captured.diagnostic.clone());
1186        Ok(captured)
1187    }
1188
1189    fn capture_modules(
1190        &self,
1191        state: &mut OwnerState,
1192        modules: &BTreeSet<String>,
1193    ) -> Result<CapturedConfiguration> {
1194        self.capturer
1195            .capture_modules(&Self::declarations(state)?, modules)
1196    }
1197
1198    fn check_authority(state: &mut OwnerState, recovery: bool) -> Result<()> {
1199        if let Err(error) = state.store.check() {
1200            return if recovery
1201                && matches!(
1202                    state.store.loaded_admission_state().0,
1203                    StoreState::StoreUnverified | StoreState::StoreMissing
1204                ) {
1205                Ok(())
1206            } else {
1207                Err(error.into())
1208            };
1209        }
1210        state.retry_anchor(true);
1211        match state.store.check() {
1212            Ok(()) => Ok(()),
1213            Err(_)
1214                if recovery
1215                    && matches!(
1216                        state.store.status().state,
1217                        StoreState::StoreUnverified | StoreState::StoreMissing
1218                    ) =>
1219            {
1220                Ok(())
1221            }
1222            Err(error) => Err(error.into()),
1223        }
1224    }
1225
1226    /// Run from a blocking worker: capture and store publication may touch disk
1227    /// and the platform keychain. No transport wait takes place under this lock.
1228    /// Preflight may record the proposal observed on disk. Refusals for missing
1229    /// authoritative project membership, active-scope usage or approved-program
1230    /// launch selection happen before any plan, approval or generation is
1231    /// written. A proposal neither approves nor records the refused plan.
1232    pub fn prepare(&self, kind: PlanKind) -> Result<PreparedPlan> {
1233        let mut state = self.lock()?;
1234        Self::check_authority(
1235            &mut state,
1236            matches!(kind, PlanKind::Stamp | PlanKind::Unstamp),
1237        )?;
1238        #[cfg(test)]
1239        if let Some(hook) = self.prepare_capture_hook.lock().unwrap().take() {
1240            hook();
1241        }
1242        let observed = self.capture(&mut state)?;
1243        if observed.daemon.bytes.is_none() {
1244            return Err(GateError::new(
1245                "invalid_daemon_config",
1246                "subc.jsonc is absent; refusing to rescan",
1247            ));
1248        }
1249        if !state.recovery_exit_hold && state.store.status().state == StoreState::Stamped {
1250            state.store.observe(observed.diagnostic.to_store()?)?;
1251        }
1252        let rollback = if let PlanKind::Rollback(id) = kind {
1253            let target = super::GateSnapshot::from_store(&state.store.rollback_configuration(id)?)?;
1254            let delivery = state
1255                .store
1256                .body()?
1257                .generations
1258                .get(&id)
1259                .and_then(|entry| entry.delivery.as_ref())
1260                .ok_or_else(|| {
1261                    GateError::new(
1262                        "rollback_snapshot_unavailable",
1263                        "retained raw configuration is absent",
1264                    )
1265                })?;
1266            Some((self.capturer.capture_retained(&target, delivery)?, target))
1267        } else {
1268            None
1269        };
1270        let (candidate, mut observed, target) = if let Some((candidate, target)) = rollback {
1271            (candidate, Some(observed), Some(target))
1272        } else {
1273            (observed, None, None)
1274        };
1275        if kind == PlanKind::Stamp {
1276            super::registration::check_stamp(&candidate.diagnostic)?;
1277        }
1278        let base_revision = state.store.status().base_revision;
1279        let old = if state.store.status().state == StoreState::Stamped {
1280            super::GateSnapshot::from_store(&state.store.body()?.approved)?
1281        } else {
1282            super::GateSnapshot::default()
1283        };
1284        let mut touched_modules: BTreeSet<_> = candidate
1285            .diagnostic
1286            .changed_keys(&old)
1287            .iter()
1288            .filter_map(|key| key.module().map(str::to_owned))
1289            .collect();
1290        if matches!(kind, PlanKind::Stamp | PlanKind::Unstamp) {
1291            touched_modules.extend(candidate.diagnostic.modules());
1292            touched_modules.extend(old.modules());
1293        }
1294        if let Some(target) = target {
1295            touched_modules.extend(
1296                candidate
1297                    .diagnostic
1298                    .inputs
1299                    .iter()
1300                    .filter(|(key, value)| {
1301                        key.is_program() && target.inputs.get(*key) != Some(*value)
1302                    })
1303                    .filter_map(|(key, _)| key.module().map(str::to_owned)),
1304            );
1305        }
1306        let mut review_modules: BTreeSet<String> = touched_modules
1307            .iter()
1308            .filter(|module| candidate.modules.contains_key(*module))
1309            .filter(|module|matches!(kind,PlanKind::Stamp|PlanKind::Unstamp) || candidate.diagnostic.changed_keys(&old).iter().any(|key|matches!(key,super::InputKey::Layer {module:owner,..}|super::InputKey::Declaration(owner) if owner==*module)))
1310            .cloned()
1311            .collect();
1312        // A program change is approved launch-only: neither the build being
1313        // approved nor the one still running can review for it. Once the new
1314        // program is active, the next plan re-reviews the approved layers with
1315        // it. While it is not yet active the module waits, and the plan
1316        // carries its earlier reviewer forward.
1317        let mut rereview_modules = BTreeSet::new();
1318        if matches!(kind, PlanKind::Change | PlanKind::Rollback(_))
1319            && state.store.status().state == StoreState::Stamped
1320        {
1321            for (module, rereview) in
1322                super::reviewed_build::pending(state.store.body()?, candidate.modules.keys())?
1323            {
1324                if rereview == super::reviewed_build::Rereview::Ready
1325                    && !review_modules.contains(&module)
1326                {
1327                    touched_modules.insert(module.clone());
1328                    review_modules.insert(module.clone());
1329                    rereview_modules.insert(module);
1330                }
1331            }
1332        }
1333        let program_keys: Vec<_> = candidate
1334            .diagnostic
1335            .inputs
1336            .keys()
1337            .filter(|key| {
1338                key.is_program()
1339                    && key
1340                        .module()
1341                        .is_some_and(|module| touched_modules.contains(module))
1342            })
1343            .cloned()
1344            .collect();
1345        let read_set = if let Some(observed) = &mut observed {
1346            observed.capture_programs(&program_keys)?;
1347            if program_keys.iter().any(|key| {
1348                observed.diagnostic.inputs.get(key) != candidate.diagnostic.inputs.get(key)
1349            }) {
1350                return Err(GateError::stale());
1351            }
1352            observed.diagnostic.read_set(&touched_modules)?
1353        } else {
1354            candidate.diagnostic.read_set(&touched_modules)?
1355        };
1356        let observed_handles = observed
1357            .as_mut()
1358            .map(CapturedConfiguration::take_handles)
1359            .unwrap_or_default();
1360        let mut bases = BTreeMap::new();
1361        let mut base_schemas = BTreeMap::new();
1362        let mut active_generations = BTreeMap::new();
1363        if state.store.status().state == StoreState::Stamped {
1364            let body = state.store.body()?;
1365            for (tuple, versions) in &body.versions {
1366                if touched_modules.contains(&tuple.module) {
1367                    active_generations.insert(tuple.clone(), versions.active);
1368                }
1369                if tuple.project.is_some() || !review_modules.contains(&tuple.module) {
1370                    continue;
1371                }
1372                if let Some(id) = versions.active {
1373                    let snapshot = body
1374                        .generations
1375                        .get(&id)
1376                        .and_then(|entry| entry.delivery.as_ref())
1377                        .ok_or_else(|| {
1378                            GateError::new(
1379                                "approved_schema_unavailable",
1380                                format!(
1381                                    "{}: approved old schema is missing or damaged",
1382                                    tuple.module
1383                                ),
1384                            )
1385                        })?;
1386                    let schema = snapshot
1387                        .declarations
1388                        .get(&tuple.module)
1389                        .and_then(|declaration| {
1390                            subc_config::Schema::new(declaration.schema.clone()).ok()
1391                        })
1392                        .ok_or_else(|| {
1393                            GateError::new(
1394                                "approved_schema_unavailable",
1395                                format!(
1396                                    "{}: approved old schema is missing or damaged",
1397                                    tuple.module
1398                                ),
1399                            )
1400                        })?;
1401                    base_schemas.insert(tuple.module.clone(), schema);
1402                    let view = snapshot.modules.get(&tuple.module).ok_or_else(|| {
1403                        GateError::new(
1404                            "config_gated",
1405                            format!("{}: approved active view is absent", tuple.module),
1406                        )
1407                    })?;
1408                    let mut view = view.clone();
1409                    view.generation = id;
1410                    view.status = ConfigStatus::Active;
1411                    bases.insert(tuple.module.clone(), view);
1412                }
1413            }
1414        }
1415        Ok(PreparedPlan {
1416            candidate,
1417            bases,
1418            base_schemas,
1419            kind,
1420            review_modules,
1421            rereview_modules,
1422            base_revision,
1423            active_generations,
1424            touched_modules,
1425            read_set,
1426            program_keys,
1427            observed_handles,
1428        })
1429    }
1430
1431    pub fn finish_plan(
1432        &self,
1433        mut prepared: PreparedPlan,
1434        review: impl FnOnce(&super::GateSnapshot, &super::GateSnapshot) -> Result<Changeset>,
1435    ) -> Result<ConfigPlanView> {
1436        let mut state = self.lock()?;
1437        Self::check_authority(
1438            &mut state,
1439            matches!(prepared.kind, PlanKind::Stamp | PlanKind::Unstamp),
1440        )?;
1441        let active_generations = if state.store.status().state == StoreState::Stamped {
1442            state
1443                .store
1444                .body()?
1445                .versions
1446                .iter()
1447                .filter(|(tuple, _)| prepared.touched_modules.contains(&tuple.module))
1448                .map(|(tuple, versions)| (tuple.clone(), versions.active))
1449                .collect()
1450        } else {
1451            BTreeMap::new()
1452        };
1453        let mut current = self
1454            .capture_modules(&mut state, &prepared.touched_modules)
1455            .map_err(|_| GateError::stale())?;
1456        current
1457            .capture_programs(&prepared.program_keys)
1458            .map_err(|_| GateError::stale())?;
1459        if state.store.status().base_revision != prepared.base_revision
1460            || active_generations != prepared.active_generations
1461            || !prepared
1462                .read_set
1463                .matches(&current.diagnostic.read_set(&prepared.touched_modules)?)
1464        {
1465            return Err(GateError::stale());
1466        }
1467        let delivery = DeliverySnapshot {
1468            daemon: Some(ConfigLayerSnapshot::file(
1469                "subc",
1470                ConfigLayer::User,
1471                prepared.candidate.daemon.path.to_string_lossy(),
1472                prepared.candidate.daemon.bytes.clone(),
1473            )),
1474            modules: prepared
1475                .candidate
1476                .modules
1477                .iter()
1478                .map(|(module, captured)| (module.clone(), captured.view.clone()))
1479                .collect(),
1480            declarations: prepared
1481                .candidate
1482                .modules
1483                .iter()
1484                .map(|(module, captured)| (module.clone(), captured.declaration.clone()))
1485                .collect(),
1486        };
1487        let mut handles = prepared.candidate.take_handles();
1488        handles.append(&mut prepared.observed_handles);
1489        let OwnerState { gate, store, .. } = &mut *state;
1490        let view = gate.plan_reviewed(
1491            store,
1492            prepared.kind,
1493            prepared.candidate.diagnostic,
1494            &current.diagnostic,
1495            super::ReviewRecord::Reviewed(&prepared.review_modules),
1496            review,
1497        )?;
1498        if let Err(error) = self.check_route_policy_authority(&view.plan.changeset) {
1499            gate.expire_plan(&view.digest);
1500            return Err(error);
1501        }
1502        gate.bind_delivery(&view.digest, delivery)?;
1503        state.reviewed(&view.digest, Instant::now());
1504        state
1505            .retained_plan_files
1506            .insert(view.digest.clone(), handles);
1507        Ok(view)
1508    }
1509
1510    pub fn begin_approval(
1511        &self,
1512        digest: &Digest,
1513        facts: &ApprovalFacts,
1514    ) -> Result<ApprovalChallenge> {
1515        self.begin_approval_for_request(digest, facts, None)
1516    }
1517
1518    pub(crate) fn begin_approval_for_request(
1519        &self,
1520        digest: &Digest,
1521        facts: &ApprovalFacts,
1522        request: Option<&ApprovalRequest>,
1523    ) -> Result<ApprovalChallenge> {
1524        #[cfg(test)]
1525        struct Completion<'a>(&'a std::sync::atomic::AtomicUsize);
1526        #[cfg(test)]
1527        impl Drop for Completion<'_> {
1528            fn drop(&mut self) {
1529                self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
1530            }
1531        }
1532        #[cfg(test)]
1533        let _completed = Completion(&self.begin_approval_completions);
1534        #[cfg(test)]
1535        if let Some(hook) = self.begin_approval_hook.lock().unwrap().take() {
1536            hook();
1537        }
1538        let mut state = self.lock()?;
1539        if let Some(request) = request {
1540            request.ensure_live()?;
1541        }
1542        if state.expired_plans.contains(digest) {
1543            return Err(GateError::new(
1544                "plan_expired",
1545                "configuration plan exceeded its one-hour idle lifetime",
1546            ));
1547        }
1548        Self::check_authority(&mut state, true)?;
1549        let modules = state.gate.plan_modules(digest)?;
1550        let program_keys = state.gate.plan_program_keys(digest)?;
1551        let mut current = self
1552            .capture_modules(&mut state, &modules)
1553            .map_err(|_| GateError::stale())?;
1554        current
1555            .capture_programs(&program_keys)
1556            .map_err(|_| GateError::stale())?;
1557        let facts = state.with_desktop_view(digest, facts);
1558        let OwnerState { gate, store, .. } = &mut *state;
1559        if let Some(request) = request {
1560            request.ensure_live()?;
1561        }
1562        let challenge = gate.begin_approval(digest, store, &current.diagnostic, &facts)?;
1563        state.reviewed(digest, Instant::now());
1564        Ok(challenge)
1565    }
1566
1567    /// Acquire only after interactive approval. Sorted module locks serialize
1568    /// the final freshness check and publication with target changes at cutover.
1569    pub(crate) async fn approval_commit_gates(
1570        self: &std::sync::Arc<Self>,
1571        attempt: u64,
1572    ) -> Result<Vec<tokio::sync::OwnedMutexGuard<()>>> {
1573        let modules = self
1574            .on_blocking(move |owner| owner.lock()?.gate.approval_gate_modules(attempt))
1575            .await?;
1576        let mut guards = Vec::with_capacity(modules.len());
1577        for module in modules {
1578            guards.push(self.module_gate(&module)?.lock_owned().await);
1579        }
1580        Ok(guards)
1581    }
1582
1583    pub fn finish_approval(
1584        &self,
1585        attempt: u64,
1586        facts: &ApprovalFacts,
1587        reply: ApprovalReply,
1588        now_ms: u64,
1589    ) -> Result<u64> {
1590        // In-process approvals have no reader reservation. Wire approvals pass
1591        // their exact request token into the publication job instead.
1592        self.finish_approval_with_commit_window(
1593            attempt,
1594            facts,
1595            reply,
1596            now_ms,
1597            None,
1598            ApprovalRequest::for_attempt(attempt),
1599        )
1600    }
1601
1602    pub(crate) fn finish_approval_with_commit_window(
1603        &self,
1604        attempt: u64,
1605        facts: &ApprovalFacts,
1606        reply: ApprovalReply,
1607        now_ms: u64,
1608        window: Option<std::sync::Arc<ApprovalCommitWindow>>,
1609        cancellation: std::sync::Arc<ApprovalRequest>,
1610    ) -> Result<u64> {
1611        if cancellation.attempt() != attempt {
1612            return Err(GateError::new(
1613                "config_unavailable",
1614                "approval request witness does not match its attempt",
1615            ));
1616        }
1617        let mut state = self.lock()?;
1618        let digest = state.gate.approval_digest(attempt)?;
1619        state.reviewed(&digest, Instant::now());
1620        let modules = state.gate.approval_modules(attempt)?;
1621        let program_keys = state.gate.plan_program_keys(&digest)?;
1622        // Reopen inputs after the operator's interactive confirmation, immediately
1623        // before freshness checking and atomic publication of the saved plan.
1624        let current = match Self::check_authority(&mut state, true).and_then(|_| {
1625            let mut current = self
1626                .capture_modules(&mut state, &modules)
1627                .map_err(|_| GateError::stale())?;
1628            current
1629                .capture_programs(&program_keys)
1630                .map_err(|_| GateError::stale())?;
1631            Ok(current)
1632        }) {
1633            Ok(current) => current,
1634            Err(error) => {
1635                state.gate.cancel_attempt(attempt);
1636                return Err(error);
1637            }
1638        };
1639        let facts = state.with_desktop_view(&digest, facts);
1640        self.drain_canceled_approvals(&mut state);
1641        self.drain_disconnections(&mut state);
1642        #[cfg(test)]
1643        if let Some(hook) = state.after_approval_drain_hook.take() {
1644            hook();
1645        }
1646        let was_unstamped = state.store.status().state == StoreState::Unstamped;
1647        let was_recovery = state.recovery_exit_hold
1648            || matches!(
1649                state.store.status().state,
1650                StoreState::StoreMissing | StoreState::StoreUnverified
1651            );
1652        let unstamp_hints = recovery::changed_file_views(self, &mut state, &current);
1653        #[cfg(test)]
1654        let publication_hook = state.publication_hook.take();
1655        #[cfg(test)]
1656        let prepublication_hook = state.prepublication_hook.take();
1657        let publication_before = state.store.publication_sequence();
1658        let OwnerState {
1659            gate,
1660            store,
1661            route_policy_receipts,
1662            installed_route_policies,
1663            delivery,
1664            ..
1665        } = &mut *state;
1666        let result = gate.finish_approval_with_precommit(
1667            attempt,
1668            reply,
1669            store,
1670            &current.diagnostic,
1671            &facts,
1672            now_ms,
1673            || {
1674                #[cfg(test)]
1675                if let Some(hook) = prepublication_hook {
1676                    hook();
1677                }
1678                if let Some(window) = window {
1679                    window.begin_publication()?;
1680                }
1681                {
1682                    // Serialize the publication claim with cancellation-index
1683                    // health, then release the index before any store work.
1684                    let _index = self.approval_request_index.lock().map_err(|_| {
1685                        GateError::new(
1686                            "config_unavailable",
1687                            "approval cancellation index is poisoned",
1688                        )
1689                    })?;
1690                    cancellation.claim_publication()?;
1691                }
1692                route_policy::restore_superseded(
1693                    route_policy_receipts,
1694                    installed_route_policies,
1695                    &modules,
1696                    delivery,
1697                );
1698                #[cfg(test)]
1699                if let Some(hook) = publication_hook {
1700                    hook();
1701                }
1702                Ok(())
1703            },
1704        );
1705        let committed_this_call = state.store.publication_sequence() != publication_before;
1706        let stamped_files = committed_this_call
1707            && (was_unstamped || was_recovery)
1708            && state.store.body().is_ok_and(|body| {
1709                body.generations
1710                    .get(&body.last_generation)
1711                    .is_some_and(|entry| {
1712                        entry.generation.plan_digest == digest
1713                            && entry.kind == crate::config_store::CommitKind::Stamp
1714                    })
1715            });
1716        if result.is_ok() {
1717            state.plan_deadlines.remove(&digest);
1718            state.retained_plan_files.remove(&digest);
1719            state.desktop_views.retain(|_, (shown, _)| shown != &digest);
1720        }
1721        let unstamped = result.is_ok() && state.store.status().state == StoreState::Unstamped;
1722        let committed_exit = state
1723            .store
1724            .loaded_admission_state()
1725            .1
1726            .generations
1727            .iter()
1728            .next_back()
1729            .filter(|(_, entry)| {
1730                committed_this_call
1731                    && entry.generation.plan_digest == digest
1732                    && (was_recovery
1733                        || state.store.loaded_admission_state().1.stamped
1734                        || entry.kind == crate::config_store::CommitKind::Unstamp)
1735            })
1736            .map(|(generation, entry)| {
1737                (
1738                    *generation,
1739                    entry.kind == crate::config_store::CommitKind::Unstamp,
1740                )
1741            });
1742        if committed_this_call && was_recovery {
1743            state.authority_incarnation = std::sync::Arc::new(());
1744        }
1745        if let Some((generation, unstamp)) = committed_exit {
1746            state.authority_exit = Some(generation);
1747            state.recovery_exit_hold = was_recovery;
1748            if was_recovery || unstamp {
1749                state
1750                    .delivery
1751                    .reset_for_authority_exit(if unstamp { generation } else { 0 });
1752            }
1753            if unstamp {
1754                state.stamp_channel_cutover = false;
1755                state.reconciled_entries.clear();
1756                state.unstamp_hints.extend(unstamp_hints);
1757            }
1758        } else if committed_this_call {
1759            state.authority_exit = None;
1760        }
1761        if stamped_files {
1762            state.stamp_channel_cutover = true;
1763            let connections: Vec<_> = state.active_declarations.values().copied().collect();
1764            state.delivery.remember_stamp_connections(connections);
1765        }
1766        drop(state);
1767        if unstamped {
1768            self.retire_unstamped_bindings();
1769        }
1770        result
1771    }
1772
1773    #[cfg(all(test, unix))]
1774    pub(crate) fn set_publication_hook(&self, hook: impl FnOnce() + Send + 'static) {
1775        self.inner.lock().unwrap().publication_hook = Some(Box::new(hook));
1776    }
1777
1778    #[cfg(all(test, unix))]
1779    pub(crate) fn set_prepublication_hook(&self, hook: impl FnOnce() + Send + 'static) {
1780        self.inner.lock().unwrap().prepublication_hook = Some(Box::new(hook));
1781    }
1782
1783    #[cfg(all(test, unix))]
1784    pub(crate) fn set_after_approval_drain_hook(&self, hook: impl FnOnce() + Send + 'static) {
1785        self.inner.lock().unwrap().after_approval_drain_hook = Some(Box::new(hook));
1786    }
1787
1788    #[cfg(all(test, unix))]
1789    pub(crate) fn approval_request_count_for_test(&self) -> usize {
1790        self.approval_request_index.lock().unwrap().len()
1791    }
1792
1793    #[cfg(all(test, unix))]
1794    pub(crate) fn poison_approval_request_index_for_test(&self) {
1795        let poisoned = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
1796            let _guard = self.approval_request_index.lock().unwrap();
1797            panic!("injected approval index poison");
1798        }));
1799        assert!(poisoned.is_err());
1800    }
1801
1802    #[cfg(all(test, unix))]
1803    pub(crate) fn pause_next_approval_claim_for_test(
1804        &self,
1805    ) -> (
1806        tokio::sync::oneshot::Receiver<()>,
1807        tokio::sync::oneshot::Sender<()>,
1808    ) {
1809        let (reached, observed) = tokio::sync::oneshot::channel();
1810        let (release, wait) = tokio::sync::oneshot::channel();
1811        *self.approval_claim_pause.lock().unwrap() = Some(ApprovalClaimPause {
1812            reached,
1813            release: wait,
1814        });
1815        (observed, release)
1816    }
1817
1818    #[cfg(all(test, unix))]
1819    pub(crate) async fn pause_approval_claim_for_test(&self) {
1820        let pause = self.approval_claim_pause.lock().unwrap().take();
1821        if let Some(pause) = pause {
1822            let _ = pause.reached.send(());
1823            pause.release.await.unwrap();
1824        }
1825    }
1826
1827    // Flipping a flag is platform-neutral. Its callers are the unix-only phone
1828    // tests and, under test-support, the ckdev config test seam and its tests.
1829    #[cfg(any(all(test, unix), feature = "test-support"))]
1830    pub(crate) fn set_os_prompt_policy_for_tests(&self) {
1831        self.os_prompt_policy
1832            .store(true, std::sync::atomic::Ordering::Relaxed);
1833    }
1834
1835    #[cfg(any(test, feature = "test-support"))]
1836    pub(crate) fn os_prompt_policy_for_tests(&self) -> bool {
1837        self.os_prompt_policy
1838            .load(std::sync::atomic::Ordering::Relaxed)
1839    }
1840
1841    pub fn status(&self) -> Result<subc_control::config::ConfigStatus> {
1842        let mut state = self.lock()?;
1843        let mut current_snapshot = None;
1844        state.retry_anchor(true);
1845        let verified = state.store.check().is_ok();
1846        if verified
1847            && !state.recovery_exit_hold
1848            && !state.store.status().anchor_pending
1849            && matches!(
1850                state.store.status().state,
1851                StoreState::Stamped | StoreState::Unstamped
1852            )
1853        {
1854            let captured = self.capture(&mut state)?;
1855            current_snapshot = Some(captured.diagnostic.clone());
1856            state.store.observe(captured.diagnostic.to_store()?)?;
1857        }
1858        let store_status = state.store.status();
1859        let mut status = subc_control::config::ConfigStatus::default();
1860        status.state = match store_status.state {
1861            StoreState::Stamped => "stamped",
1862            StoreState::Unstamped => "unstamped",
1863            StoreState::StoreMissing => "store_missing",
1864            StoreState::StoreUnverified => "store_unverified",
1865        }
1866        .into();
1867        if state.recovery_exit_hold {
1868            if store_status.state != StoreState::Stamped {
1869                status.state = "store_unverified".into();
1870            }
1871            status
1872                .warnings
1873                .push("approved recovery exit is waiting for reconciliation".into());
1874        }
1875        status.integrity = match store_status.integrity {
1876            crate::config_store::IntegrityMode::DigestOnly => "digest_only",
1877            crate::config_store::IntegrityMode::Sealed => "sealed",
1878        }
1879        .into();
1880        status.revision = store_status.revision;
1881        status.base_revision = store_status.base_revision;
1882        status.anchor_pending = store_status.anchor_pending;
1883        status.ungated_inputs = self.startup_overrides.clone();
1884        #[cfg(feature = "test-support")]
1885        if state.store.uses_config_gate_test_seam() {
1886            status
1887                .development_switches
1888                .push("SUBC_TEST_CONFIG_GATE".into());
1889        }
1890        status.warnings.extend(store_status.warnings);
1891        if cfg!(feature = "dev-desktop-approval") {
1892            status
1893                .development_switches
1894                .push("dev-desktop-approval".into());
1895        }
1896        if cfg!(feature = "dev-placement") {
1897            status.development_switches.push("dev-placement".into());
1898        }
1899        let declared: Vec<String> = Self::declarations(&mut state)
1900            .map(|declarations| declarations.into_keys().collect())
1901            .unwrap_or_default();
1902        if let Ok(body) = state.store.body() {
1903            if body.stamped {
1904                for (module, rereview) in
1905                    super::reviewed_build::pending(body, &declared).unwrap_or_default()
1906                {
1907                    status.warnings.push(match rereview {
1908                        super::reviewed_build::Rereview::WaitingForProgram => format!(
1909                            "module {module}: needs configuration re-review: its approved program has not reviewed its approved layers; the re-review waits until that program is running and active"
1910                        ),
1911                        super::reviewed_build::Rereview::Ready => format!(
1912                            "module {module}: needs configuration re-review: its approved program has not reviewed its approved layers; the next configuration plan re-reviews them with the running program"
1913                        ),
1914                    });
1915                }
1916            }
1917            if body.stamped {
1918                current_snapshot = super::GateSnapshot::from_store(&body.approved).ok();
1919            }
1920            for entry in body
1921                .generations
1922                .values()
1923                .rev()
1924                .take_while(|entry| entry.kind == crate::config_store::CommitKind::Development)
1925            {
1926                status.warnings.push(format!(
1927                    "development generation {}: development placement (no approval)",
1928                    entry.generation.id
1929                ));
1930            }
1931            status.approval_channels = body
1932                .generations
1933                .iter()
1934                .map(|(id, entry)| {
1935                    subc_control::config::ConfigApprovalRecord::new(
1936                        *id,
1937                        entry.generation.approval_channel,
1938                    )
1939                })
1940                .chain(body.pruned.iter().map(|(id, entry)| {
1941                    subc_control::config::ConfigApprovalRecord::new(*id, entry.approval_channel)
1942                }))
1943                .collect();
1944            status
1945                .approval_channels
1946                .sort_by_key(|record| record.generation);
1947            status.pending_proposals = u64::from(body.proposal.is_some());
1948            for (tuple, versions) in &body.versions {
1949                if let Some(generation) = versions.pending {
1950                    let entry = body.generations.get(&generation);
1951                    let transition = entry.and_then(|entry| {
1952                        super::apply::Transition::for_module(
1953                            &entry.generation.changeset,
1954                            &tuple.module,
1955                        )
1956                        .ok()
1957                    });
1958                    status.approved_but_inactive.push(serde_json::json!({
1959                        "module_id":tuple.module,"project_id":tuple.project,"generation":generation,
1960                        "digest":entry.map(|entry| &entry.generation.plan_digest),
1961                        "waiting_for":match transition {
1962                            Some(super::apply::Transition::DaemonRestart) => "daemon_restart",
1963                            Some(super::apply::Transition::NextSupervision) => "next_supervision",
1964                            _ => "delivery",
1965                        },
1966                    }));
1967                }
1968            }
1969        }
1970        if let Some(snapshot) = current_snapshot {
1971            status_inputs::report_snapshot(&snapshot, &mut status);
1972        }
1973        status.gated_modules = admission::AdmissionCache::from_state(&state).held_modules();
1974        if state.store.loaded_admission_state().0 == StoreState::Stamped {
1975            let declarations: Vec<_> = state
1976                .declarations
1977                .iter()
1978                .map(|(connection, (module, _))| (*connection, module.clone()))
1979                .collect();
1980            for (connection, module) in declarations {
1981                // Use get's approved-declaration/view checks without opening the
1982                // store or binding a delivery attempt merely to display status.
1983                if self
1984                    .module_get_locked(
1985                        &mut state,
1986                        connection,
1987                        &module,
1988                        subc_protocol::config::ConfigGetRequest::new(),
1989                        false,
1990                    )
1991                    .is_err_and(|error| error.code == "config_gated")
1992                {
1993                    status.gated_modules.push(module);
1994                }
1995            }
1996            status.gated_modules.sort();
1997            status.gated_modules.dedup();
1998        }
1999        Ok(status)
2000    }
2001
2002    pub fn history(&self) -> Result<(Vec<subc_config::Generation>, Vec<serde_json::Value>)> {
2003        let mut state = self.lock()?;
2004        state.retry_anchor(true);
2005        state.store.check()?;
2006        let body = state.store.body()?;
2007        Ok((
2008            body.generations
2009                .values()
2010                .map(|entry| entry.generation.clone())
2011                .collect(),
2012            body.pruned
2013                .values()
2014                .map(serde_json::to_value)
2015                .collect::<std::result::Result<_, _>>()
2016                .map_err(GateError::invalid)?,
2017        ))
2018    }
2019
2020    /// Admission is owned by the supervisor adapter; until it is installed it
2021    /// must not infer executable authority from diagnostic snapshots.
2022    pub fn approved_snapshot(&self) -> Result<DeliverySnapshot> {
2023        let mut state = self.lock()?;
2024        state.store.delivery_ready()?;
2025        state
2026            .store
2027            .body()?
2028            .generations
2029            .values()
2030            .next_back()
2031            .and_then(|entry| entry.delivery.clone())
2032            .ok_or_else(|| GateError::new("config_gated", "approved delivery snapshot is absent"))
2033    }
2034
2035    /// Read the saved rollback, never today's edited files. This is not spawn
2036    /// authorization: admission must select an eligible module generation and
2037    /// launch exactly the returned identity under that module's gate lock.
2038    /// Re-check the file identity at spawn and refuse `plan_stale` if it changed
2039    /// since approval. Path-changing rollback plans remain refused until the
2040    /// supervisor uses these approved inputs to select and launch programs at
2041    /// the restored paths.
2042    pub fn approved_rollback_commands(&self, generation: u64) -> Result<ApprovedRollbackCommands> {
2043        let mut state = self.lock()?;
2044        state.store.delivery_ready()?;
2045        let configuration = state.store.rollback_configuration(generation)?;
2046        let entry = &state.store.body()?.generations[&generation];
2047        if entry.kind != crate::config_store::CommitKind::Rollback {
2048            return Err(GateError::new(
2049                "rollback_generation_required",
2050                "generation is not an approved rollback",
2051            ));
2052        }
2053        let daemon = entry
2054            .delivery
2055            .as_ref()
2056            .and_then(|snapshot| snapshot.daemon.clone())
2057            .ok_or_else(|| {
2058                GateError::new(
2059                    "rollback_snapshot_unavailable",
2060                    "approved rollback command input is absent",
2061                )
2062            })?;
2063        let snapshot = super::GateSnapshot::from_store(&configuration)?;
2064        let mut programs = BTreeMap::new();
2065        for (key, identity) in snapshot.inputs {
2066            if let super::InputKey::Program { module, path } = key {
2067                if programs
2068                    .insert(module, ApprovedRollbackProgram { path, identity })
2069                    .is_some()
2070                {
2071                    return Err(GateError::new(
2072                        "rollback_snapshot_unavailable",
2073                        "rollback contains conflicting program identities",
2074                    ));
2075                }
2076            }
2077        }
2078        Ok(ApprovedRollbackCommands {
2079            generation,
2080            daemon,
2081            programs,
2082        })
2083    }
2084}