tatara_process/

signal.rs

//! First-class CRD signals — Unix semantics over Kubernetes.
//!
//! Signals are delivered via annotation (`tatara.pleme.io/signal=SIGHUP`) or
//! via the MCP `signal_process` tool; the reconciler consumes them,
//! enqueues on `status.signalQueue`, and drains in phase order.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::phase::ProcessPhase;

/// The first-class signals the controller honors.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum ProcessSignal {
    /// Reconfigure — re-enter Execing without termination.
    /// Fires on spec change, drift detection, or manual invocation.
    Sighup,
    /// Graceful terminate — finalizer path with children draining first.
    Sigterm,
    /// Force terminate — `grace_period_seconds: 0` on all owned resources.
    Sigkill,
    /// Force re-attestation without spec change — recomputes three-pillar hash.
    Sigusr1,
    /// Force remediation — invokes kensa remediation hooks.
    Sigusr2,
    /// Pause reconciliation — fixed-point driver is suspended.
    Sigstop,
    /// Resume reconciliation after SIGSTOP.
    Sigcont,
}

impl ProcessSignal {
    /// The closed set of signals — single source of truth that
    /// drives `as_str` / `short_str` / `FromStr` so adding a variant
    /// updates every projection at once (and the
    /// `short_str_strips_sig_prefix` + `all_signals_roundtrip_*`
    /// tests pin the bridge).
    pub const ALL: [Self; 7] = [
        Self::Sighup,
        Self::Sigterm,
        Self::Sigkill,
        Self::Sigusr1,
        Self::Sigusr2,
        Self::Sigstop,
        Self::Sigcont,
    ];

    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Sighup => "SIGHUP",
            Self::Sigterm => "SIGTERM",
            Self::Sigkill => "SIGKILL",
            Self::Sigusr1 => "SIGUSR1",
            Self::Sigusr2 => "SIGUSR2",
            Self::Sigstop => "SIGSTOP",
            Self::Sigcont => "SIGCONT",
        }
    }

    /// The short alias accepted by `FromStr` — the canonical
    /// `as_str()` form with the leading `"SIG"` stripped (`"HUP"`,
    /// `"TERM"`, …). The `short_str_strips_sig_prefix` test asserts
    /// this contract structurally so the two projections cannot
    /// drift.
    pub const fn short_str(self) -> &'static str {
        match self {
            Self::Sighup => "HUP",
            Self::Sigterm => "TERM",
            Self::Sigkill => "KILL",
            Self::Sigusr1 => "USR1",
            Self::Sigusr2 => "USR2",
            Self::Sigstop => "STOP",
            Self::Sigcont => "CONT",
        }
    }
}

impl std::fmt::Display for ProcessSignal {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl std::str::FromStr for ProcessSignal {
    type Err = UnknownSignal;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let upper = s.to_ascii_uppercase();
        for sig in Self::ALL {
            if upper == sig.as_str() || upper == sig.short_str() {
                return Ok(sig);
            }
        }
        Err(UnknownSignal(upper))
    }
}

#[derive(Debug, thiserror::Error)]
#[error("unknown signal: {0}")]
pub struct UnknownSignal(pub String);

/// How a Process handles SIGHUP.
///
/// Sibling closed-set lifts on the same `ProcessSpec` axis:
/// [`ProcessSignal::ALL`] (parser triad), [`crate::phase::ProcessPhase::ALL`]
/// (target codomain), [`crate::spec::MustReachPhase::ALL`] (typed subset of
/// ProcessPhase).
#[derive(
    Clone,
    Copy,
    Debug,
    PartialEq,
    Eq,
    Hash,
    Serialize,
    Deserialize,
    JsonSchema,
    Default,
    tatara_closed_set::DeriveClosedSet,
)]
#[serde(rename_all = "PascalCase")]
#[closed_set(via = "as_str", generate_unknown, display)]
pub enum SighupStrategy {
    /// Running → Reconverging → Execing without tearing down resources.
    #[default]
    Reconverge,
    /// Running → Exiting → Reaped → Pending (full respawn).
    Restart,
    /// Ignore the signal.
    Noop,
}

impl SighupStrategy {
    /// The closed set of SIGHUP strategies — single source of truth that
    /// drives the `as_str` / Display / `FromStr` triad and the typed
    /// `sighup_target` projection. Adding a fourth strategy (e.g. a
    /// future `Suspend` that maps SIGHUP to `SignalEffect::Suspend`)
    /// lands at one `ALL` entry, one `as_str` arm, and one
    /// `sighup_target` arm — exhaustively checked by the compiler
    /// (the `[Self; 3]` array literal forces the arity).
    pub const ALL: [Self; 3] = [Self::Reconverge, Self::Restart, Self::Noop];

    /// Canonical PascalCase wire-format projection — matches the serde
    /// `rename_all = "PascalCase"` output verbatim. Used by Display
    /// (single source of truth), by `FromStr` to identify the variant
    /// from its annotation / status-field representation, and by
    /// operator-facing diagnostic strings without re-serializing
    /// through `serde_json`. Pinned by
    /// `sighup_strategy_as_str_matches_serde`.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Reconverge => "Reconverge",
            Self::Restart => "Restart",
            Self::Noop => "Noop",
        }
    }

    /// Typed projection: when this Process receives SIGHUP while in a
    /// `is_running()` phase, which `ProcessPhase` does the reconciler
    /// transition into? `None` means SIGHUP is a no-op (the `Noop`
    /// strategy). The phase guard lives at the call site (the strategy
    /// itself doesn't know about phase), so the codomain is purely a
    /// function of the strategy variant.
    ///
    /// Used by `tatara_reconciler::signals::apply` to lift the three
    /// SIGHUP arms (Reconverge / Restart / Noop) into one
    /// projection-driven arm. A future variant lands at one
    /// `sighup_target` arm; `apply` doesn't change.
    ///
    /// Pinned by `sighup_target_truth_table` (per-variant codomain)
    /// AND by `sighup_target_projects_only_to_legal_sighup_transitions`
    /// (every `Some(target)` must be reachable from `Running` /
    /// `Attested` via `ProcessPhase::can_transition_to`).
    pub const fn sighup_target(self) -> Option<ProcessPhase> {
        match self {
            Self::Reconverge => Some(ProcessPhase::Reconverging),
            Self::Restart => Some(ProcessPhase::Exiting),
            Self::Noop => None,
        }
    }

    /// Closed-set-driven presence probe on the derived
    /// [`Self::sighup_target`] projection — `true` iff this strategy's
    /// SIGHUP-target [`ProcessPhase`] (as read through
    /// [`Self::sighup_target`]) equals `phase`.
    ///
    /// # NEW representation-kind corner — required-parent × derived-Option-child
    ///
    /// The workspace-wide closed-set-driven presence-probe algebra
    /// grows a new corner here: the child projection returns an
    /// `Option<K>` (not a raw `K`), so the probe body reads
    /// `self.sighup_target() == Some(phase)` rather than the
    /// stored-scalar `self.<field> == kind` shape the sibling scalar-
    /// carrier probes ([`crate::spec::SignalPolicy::has_sighup_strategy`],
    /// [`crate::routing::RoutingSpec::has_form`],
    /// [`crate::classification::Classification::has_calm`], …) publish.
    /// The [`Self::Noop`] arm's `None` projection answers `false` for
    /// every `phase` query — the operator's `:requires
    /// (sighup-target-<phase>)` tag reads "does this Process's SIGHUP
    /// strategy transition INTO that phase," and `Noop` transitions
    /// into no phase at all, so the tag never matches on `Noop`.
    ///
    /// # Semantics — DERIVED sighup_target, not raw variant equality
    ///
    /// `has_target(ProcessPhase::Reconverging)` returns `true` iff
    /// `self == SighupStrategy::Reconverge` (via
    /// [`Self::sighup_target`] = `Some(Reconverging)`);
    /// `has_target(ProcessPhase::Exiting)` returns `true` iff
    /// `self == SighupStrategy::Restart`. The two probes coexist with
    /// the sibling stored-scalar `has_sighup_strategy` because they
    /// answer distinct operator questions: `has_sighup_strategy` asks
    /// "does this policy CARRY this strategy literal" (raw
    /// discriminator equality), while `has_target` asks "would SIGHUP
    /// TRANSITION this Process into that phase" (compound
    /// `sighup_target` projection). A future
    /// [`SighupStrategy`] variant that projects to a phase already
    /// reachable from an existing variant (a hypothetical `Refresh`
    /// mapping to `Reconverging`) would satisfy
    /// `has_target(Reconverging)` alongside `Reconverge` — distinct
    /// stored variants, same derived target — while
    /// `has_sighup_strategy(Reconverge)` stays keyed strictly on the
    /// stored variant.
    ///
    /// # Compounding
    ///
    /// The point-domain require-tag surface in
    /// `tatara-reconciler::bin::tatara-check` composes this primitive
    /// with the closed-set [`ProcessPhase`]'s autoderived `FromStr`
    /// through the `strip_and_classify_prefixed_kind` substrate to
    /// publish a `sighup-target-<phase>` prefix family byte-for-byte
    /// symmetrical with the sibling `sighup-<kind>` family that
    /// composes through [`crate::spec::SignalPolicy::has_sighup_strategy`].
    /// A future [`SighupStrategy`] variant reaches this probe through
    /// ONE `ALL` entry + one `as_str` arm + one `sighup_target` arm on
    /// the closed set — the require-tag classifier picks the new
    /// projection up mechanically without further per-consumer edits.
    ///
    /// A future [`ProcessPhase`] variant paired with a future
    /// [`SighupStrategy`] variant that targets it lands as a fresh
    /// `sighup_target` arm on this closed set — the probe body stays
    /// unchanged, and the ONE match inside [`Self::sighup_target`]
    /// serves as the arity gate that a compiler catches at the
    /// exhaustiveness check.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition
    /// preserves proofs; the derived-Option-child presence-probe body
    /// lives at ONE substrate site so every downstream (the future
    /// `sighup-target-<phase>` require-tag family in tatara-check,
    /// closed-set audit dispatchers walking [`ProcessPhase::ALL`],
    /// future variant additions on either closed set) binds through
    /// the SAME `has_target(phase)` shape rather than restating the
    /// `self.sighup_target() == Some(phase)` chain at each callsite.
    /// THEORY.md §VI.1 — generation over composition; the closed-set
    /// match in [`Self::sighup_target`] is the ONE per-variant edit
    /// site a future strategy variant reaches through.
    #[must_use]
    pub fn has_target(self, phase: ProcessPhase) -> bool {
        self.sighup_target() == Some(phase)
    }
}

// `impl FromStr for SighupStrategy` +
// `impl tatara_lisp::ClosedSet for SighupStrategy` +
// `impl std::fmt::Display for SighupStrategy` +
// `pub struct UnknownSighupStrategy(pub String)` are all generated
// by `#[derive(tatara_closed_set::DeriveClosedSet)]` + `#[closed_set(via =
// "as_str", generate_unknown, display)]` on the enum declaration
// above. `label` delegates to the inherent
// `SighupStrategy::as_str` — the PascalCase wire-vocabulary
// projection stays load-bearing (matches the serde
// `rename_all = "PascalCase"` projection verbatim), while generic
// `T: ClosedSet` consumers reach the STABLE workspace-wide name
// (`label`). The auto-derived carrier label "sighup strategy"
// matches the prior hand-rolled `#[error("unknown sighup strategy:
// {0}")]` annotation byte-for-byte.
//
// [`ProcessSignal`] is NOT a `ClosedSet` implementor — its
// `FromStr` keys on a compound projection (`as_str` || `short_str`)
// with case-insensitive uppercase normalization rather than a
// single canonical label, the same exemption pattern as
// [`tatara_lisp::CompilerSpecIoStage`]'s compound `(operation,
// label)` key. Only [`SighupStrategy`] (single PascalCase label, no
// normalization) plugs into the derive here.

#[cfg(test)]
mod tests {
    use super::{ProcessSignal, SighupStrategy, UnknownSighupStrategy};
    use crate::phase::ProcessPhase;
    use std::str::FromStr;

    #[test]
    fn all_signals_roundtrip_canonical() {
        for sig in ProcessSignal::ALL {
            assert_eq!(ProcessSignal::from_str(sig.as_str()).unwrap(), sig);
        }
    }

    #[test]
    fn all_signals_roundtrip_short() {
        for sig in ProcessSignal::ALL {
            assert_eq!(ProcessSignal::from_str(sig.short_str()).unwrap(), sig);
        }
    }

    /// The structural contract that lets `FromStr` parse off two
    /// projections without drift: `short_str()` is exactly
    /// `as_str()` minus the leading `"SIG"`. Any new variant whose
    /// canonical form doesn't follow the `SIG*` convention has to
    /// either rename or override this test deliberately.
    #[test]
    fn short_str_strips_sig_prefix() {
        for sig in ProcessSignal::ALL {
            assert_eq!(sig.as_str().strip_prefix("SIG"), Some(sig.short_str()));
        }
    }

    /// `ALL` is the source of truth for the parser table — pin its
    /// closure so a variant added without an `ALL` entry fails here
    /// (via the uniqueness check) before drifting `FromStr`.
    #[test]
    fn all_is_unique_and_complete() {
        let mut seen = std::collections::HashSet::new();
        for sig in ProcessSignal::ALL {
            assert!(seen.insert(sig), "duplicate variant in ALL: {sig:?}");
        }
        // The arity is asserted by the array type itself (`[Self; 7]`),
        // but the uniqueness check above + the const-array length is
        // what makes ALL a closed set rather than just a list.
        assert_eq!(seen.len(), ProcessSignal::ALL.len());
    }

    #[test]
    fn lowercase_short_form_accepted() {
        assert_eq!(
            ProcessSignal::from_str("hup").unwrap(),
            ProcessSignal::Sighup
        );
        assert_eq!(
            ProcessSignal::from_str("term").unwrap(),
            ProcessSignal::Sigterm
        );
    }

    #[test]
    fn unknown_errors() {
        let err = ProcessSignal::from_str("sigfoo").unwrap_err();
        // The error carries the uppercased input — preserves the
        // pre-refactor contract that `UnknownSignal` echoes the
        // normalized form, not the operator's casing.
        assert_eq!(err.0, "SIGFOO");
    }

    // ── closed-set algebra for SighupStrategy (ALL × as_str × FromStr ×
    //    sighup_target) ────────────────────────────────────────────────

    /// Structural well-formedness of [`SighupStrategy`] as a
    /// [`tatara_lisp::ClosedSet`] implementor — the workspace-wide
    /// testkit lift that pins all three structural invariants (`ALL`
    /// is non-empty, every variant round-trips through `label ↔
    /// parse_label`, labels are pairwise distinct, `""` is outside the
    /// closed set) at ONE call site. Replaces the hand-derived
    /// `sighup_strategy_all_is_unique_and_complete` +
    /// `sighup_strategy_roundtrip_via_as_str` + the empty-input arm of
    /// `unknown_sighup_strategy_errors`. `FromStr` delegates to
    /// `<Self as tatara_closed_set::ClosedSet>::parse_label`, so this helper
    /// exercises the same code path the reconciler hits when parsing a
    /// CRD `enum:`-validated value back to the typed strategy.
    #[test]
    fn sighup_strategy_is_well_formed_closed_set() {
        tatara_closed_set::assert_closed_set_well_formed::<SighupStrategy>();
    }

    /// CANONICAL-KEY CONTRACT: `as_str` matches serde's PascalCase
    /// output verbatim for every variant. A future variant rename (or
    /// an `as_str` arm typo) lands here at one site, not in a CRD
    /// `enum:` enumeration that quietly drifted away from the typed
    /// surface.
    #[test]
    fn sighup_strategy_as_str_matches_serde() {
        crate::tagged_union::assert_label_matches_serde_serialization::<SighupStrategy>();
    }

    /// The Display impl IS `as_str` — pinning this lets future callers
    /// reach for either projection without drift.
    #[test]
    fn sighup_strategy_display_matches_as_str() {
        crate::tagged_union::assert_display_matches_label::<SighupStrategy>();
    }

    /// `FromStr` rejects strings outside the canonical projection
    /// (lowercased / typo / unrelated) — and the error echoes the
    /// input verbatim so the operator-facing diagnostic carries the
    /// offending value, not a normalized form. The empty-input arm is
    /// pinned by [`sighup_strategy_is_well_formed_closed_set`] via the
    /// `tatara_lisp::ClosedSet` testkit; the cases here pin the
    /// verbatim-echo contract on the [`UnknownSighupStrategy`]
    /// newtype, which the trait's `make_unknown` can't see.
    #[test]
    fn unknown_sighup_strategy_errors() {
        for bad in ["reconverge", "RESTART", "Suspend", "noop "] {
            let err = SighupStrategy::from_str(bad).unwrap_err();
            let UnknownSighupStrategy(payload) = &err;
            assert_eq!(payload, bad, "error payload should echo input verbatim");
        }
    }

    /// PROJECTION TRUTH TABLE: pin the per-variant codomain of
    /// `sighup_target`. A future variant addition lands here at one
    /// arm — and the compiler's closed-set match in `sighup_target`
    /// catches the missing arm before this test runs.
    #[test]
    fn sighup_target_truth_table() {
        assert_eq!(
            SighupStrategy::Reconverge.sighup_target(),
            Some(ProcessPhase::Reconverging)
        );
        assert_eq!(
            SighupStrategy::Restart.sighup_target(),
            Some(ProcessPhase::Exiting)
        );
        assert_eq!(SighupStrategy::Noop.sighup_target(), None);
    }

    /// SEMANTIC SUBSET CONTRACT: every `Some(target)` produced by
    /// `sighup_target` must be reachable from a `is_running()` phase
    /// (`Running` or `Attested`) via `ProcessPhase::can_transition_to`.
    /// This pins the contract `tatara_reconciler::signals::apply`
    /// relies on: the typed projection produces only phases the
    /// reconciler is allowed to transition into from the SIGHUP
    /// reception sites. A future `SighupStrategy::Refresh` that
    /// projected to `ProcessPhase::Pending` would FAIL here (Pending
    /// is not a legal successor of Running/Attested), forcing the
    /// author to either pick a legal target phase or extend
    /// `ProcessPhase::can_transition_to` deliberately.
    #[test]
    fn sighup_target_projects_only_to_legal_sighup_transitions() {
        for strat in SighupStrategy::ALL {
            if let Some(target) = strat.sighup_target() {
                let reachable_from_running = ProcessPhase::Running.can_transition_to(target);
                let reachable_from_attested = ProcessPhase::Attested.can_transition_to(target);
                assert!(
                    reachable_from_running || reachable_from_attested,
                    "{strat:?}.sighup_target() = {target:?} must be reachable from \
                     Running or Attested via can_transition_to",
                );
            }
        }
    }

    /// PROJECTION INJECTIVITY: distinct variants that produce `Some`
    /// project to distinct `ProcessPhase`s. Pairing this with the
    /// reachability contract above forces a future SIGHUP strategy
    /// variant to land on a fresh legal SIGHUP-target phase (or to
    /// project to `None` and be a deliberate no-op).
    #[test]
    fn sighup_target_projection_is_injective() {
        let mut seen = std::collections::HashSet::new();
        for strat in SighupStrategy::ALL {
            if let Some(target) = strat.sighup_target() {
                assert!(
                    seen.insert(target),
                    "two variants project to the same ProcessPhase: {target:?}",
                );
            }
        }
    }

    // ── derived-Option-child presence probe on SighupStrategy ×
    //    ProcessPhase ──────────────────────────────────────────────────
    //
    // Fail-before-pass-after granularity: [`SighupStrategy::has_target`]
    // did not exist before this commit — every consumer of the
    // `(SighupStrategy, ProcessPhase) -> bool` derived-Option-child probe
    // shape restated the `strat.sighup_target() == Some(phase)` chain at
    // its own callsite. Post-lift the shape lives at ONE substrate owner
    // and every downstream (the `sighup-target-<phase>` require-tag
    // family in `tatara-check`, future audit dispatchers walking
    // [`ProcessPhase::ALL`] against SIGHUP transition semantics, any
    // future closed-set-discriminator projection whose codomain is
    // `Option<K>`) binds through the SAME `has_target(phase)` shape.

    /// DIAGONAL — for every [`SighupStrategy`] variant, `has_target`
    /// returns `true` on the phase [`SighupStrategy::sighup_target`]
    /// projects to (via `Some`) AND `false` on every other phase in
    /// [`ProcessPhase::ALL`]. Sweep the [`SighupStrategy::ALL`] ×
    /// [`ProcessPhase::ALL`] cross so a regression that hard-coded the
    /// arm to a single variant (silently returning `true` on every
    /// populated strategy regardless of query phase) or wired the
    /// projection to a fixed unrelated field fails HERE at the
    /// substrate primitive before landing at the operator-facing
    /// checks.lisp surface. The `Noop` arm's `None` projection is
    /// separately pinned by
    /// [`sighup_strategy_has_target_returns_false_on_noop_for_every_phase`].
    #[test]
    fn sighup_strategy_has_target_returns_true_iff_projection_matches() {
        for strat in SighupStrategy::ALL {
            let expected_target = strat.sighup_target();
            for phase in ProcessPhase::ALL {
                let expected = expected_target == Some(phase);
                assert_eq!(
                    strat.has_target(phase),
                    expected,
                    "strategy={strat:?}: query phase={phase:?} classification drifted \
                     from sighup_target() projection {expected_target:?}",
                );
            }
        }
    }

    /// NONE-ARM PIN — [`SighupStrategy::Noop`] projects to `None`
    /// through [`SighupStrategy::sighup_target`], so `has_target`
    /// returns `false` for every phase in [`ProcessPhase::ALL`].
    /// Distinct from the sibling stored-scalar
    /// [`crate::spec::SignalPolicy::has_sighup_strategy`], which
    /// returns `true` on the [`SighupStrategy::Noop`] variant when
    /// queried on `SighupStrategy::Noop` itself — pins the
    /// derived-Option-child vs stored-scalar semantic split at ONE
    /// narrow substrate site so a regression that projected `Noop`
    /// onto a "target Zombie" or "target Pending" arm fails HERE.
    #[test]
    fn sighup_strategy_has_target_returns_false_on_noop_for_every_phase() {
        assert_eq!(SighupStrategy::Noop.sighup_target(), None);
        for phase in ProcessPhase::ALL {
            assert!(
                !SighupStrategy::Noop.has_target(phase),
                "Noop must return false for phase {phase:?}",
            );
        }
    }
}