subc-daemon 0.49.2

Embeddable subc daemon: bootstrap, module supervision, and opaque-byte splice routing.
Documentation
//! Reduce a module's field policies to one whole-generation transition.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};
use subc_config::{ApplyKind, Changeset};

use super::{GateError, Result};

/// Declaration order is the increasing transition strength. Every stronger
/// transition must still perform the route/readiness work of the weaker ones.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub(crate) enum Transition {
    Live,
    RouteRebind,
    NextSupervision,
    ModuleRestart,
    DaemonRestart,
}

impl Transition {
    fn from_apply(kind: ApplyKind) -> Result<Self> {
        match kind {
            ApplyKind::Live => Ok(Self::Live),
            ApplyKind::RouteRebind => Ok(Self::RouteRebind),
            ApplyKind::NextSupervision => Ok(Self::NextSupervision),
            ApplyKind::ModuleRestart => Ok(Self::ModuleRestart),
            ApplyKind::DaemonRestart => Ok(Self::DaemonRestart),
            _ => Err(GateError::new(
                "apply_kind_unsupported",
                "the daemon cannot enforce this field's apply policy",
            )),
        }
    }

    pub(crate) fn for_module(changeset: &Changeset, module: &str) -> Result<Self> {
        // Execution must use the digest-bound transition the person reviewed,
        // not the field rows, whose base may be a still-pending approval.
        let table = changeset
            .apply_plan
            .get("module_transitions")
            .and_then(serde_json::Value::as_object)
            .ok_or_else(|| {
                GateError::new("apply_plan_invalid", "bound module transitions are absent")
            })?;
        table.get(module).map_or(Ok(Self::Live), |entry| {
            serde_json::from_value(entry["transition"].clone()).map_err(GateError::invalid)
        })
    }

    pub(crate) fn requires_spawn(self) -> bool {
        self >= Self::NextSupervision
    }
}

/// Whether an ordinary change or rollback replaces the module's approved
/// program. The process already running was launched from the previous program,
/// so it must not acknowledge this generation: only a replacement child started
/// from the newly approved program, after warm-up, can make it active.
///
/// The daemon reviewer names each changed program file `program:<path>` in the
/// module's launch manifest. A rollback marks a program that differs from its
/// target with `program_changed_since_target`, and any change or rollback marks
/// a module whose active generation ran another program with
/// `program_changed_since_active`. A stamp or unstamp records the programs
/// already running rather than replacing them, so it is excluded.
fn changes_program(changeset: &Changeset, module: &str) -> bool {
    let replaces_programs = matches!(
        changeset
            .apply_plan
            .get("operation")
            .and_then(serde_json::Value::as_str),
        Some("change" | "rollback")
    );
    replaces_programs
        && changeset
            .launch_manifests
            .get(module)
            .and_then(serde_json::Value::as_object)
            .is_some_and(|manifest| {
                manifest.keys().any(|key| {
                    key.starts_with("program:")
                        || key == "program_changed_since_target"
                        || key == "program_changed_since_active"
                })
            })
}

/// The resulting transition is approval input, not an execution-time guess.
/// Preserve the existing apply plan alongside the module transition table.
pub(super) fn bind_plan(changeset: &mut Changeset) -> Result<()> {
    let mut policies: BTreeMap<String, (Transition, Vec<String>)> = BTreeMap::new();
    if let Some(table) = changeset.apply_plan.get("module_transitions") {
        // RuntimeOwner has already reduced active-to-candidate fields. Keep
        // that result while adding any program-replacement restart floor.
        let table = table
            .as_object()
            .ok_or_else(|| GateError::invalid("invalid module transitions"))?;
        for (module, entry) in table {
            policies.insert(
                module.clone(),
                (
                    serde_json::from_value(entry["transition"].clone())
                        .map_err(GateError::invalid)?,
                    serde_json::from_value(entry["deferred_live_fields"].clone())
                        .map_err(GateError::invalid)?,
                ),
            );
        }
    } else {
        for field in &changeset.fields {
            let (kind, live_fields) = policies
                .entry(field.module_id.clone())
                .or_insert((Transition::Live, vec![]));
            *kind = (*kind).max(Transition::from_apply(field.apply)?);
            if field.apply == ApplyKind::Live {
                live_fields.push(field.path.clone());
            }
        }
    }
    for module in changeset.launch_manifests.keys() {
        if changes_program(changeset, module) {
            let (kind, _) = policies
                .entry(module.clone())
                .or_insert((Transition::Live, vec![]));
            *kind = (*kind).max(Transition::ModuleRestart);
        }
    }
    let mut transitions = BTreeMap::new();
    for (module, (kind, live_fields)) in policies {
        let waits_for_next_start = kind == Transition::NextSupervision;
        let deferred_live_fields = if waits_for_next_start {
            live_fields
        } else {
            vec![]
        };
        transitions.insert(module, {
            serde_json::json!({
                "transition":kind,
                "whole_generation":true,
                "waits_for_next_start":waits_for_next_start,
                "waits_for_daemon_restart":kind == Transition::DaemonRestart,
                "deferred_live_fields":deferred_live_fields,
                "explanation":if kind == Transition::DaemonRestart {
                    "The complete generation takes effect when the daemon next restarts. Approval does not restart the daemon or interrupt running modules."
                } else if waits_for_next_start {
                    "The complete generation waits for the module's next start; fields that would apply live alone do not activate early."
                } else {
                    "The complete generation activates only after every required transition and readiness check finishes."
                },
            })
        });
    }
    let mut plan = match std::mem::take(&mut changeset.apply_plan) {
        serde_json::Value::Object(plan) => plan,
        serde_json::Value::Null => serde_json::Map::new(),
        review => serde_json::Map::from_iter([("review".into(), review)]),
    };
    plan.insert(
        "module_transitions".into(),
        serde_json::to_value(transitions).map_err(GateError::invalid)?,
    );
    changeset.apply_plan = serde_json::Value::Object(plan);
    Ok(())
}