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