tatara-process 0.2.610

//! Substrate primitive over the K8s `metav1.Condition.type` wire-
//! form axis every writer + reader in this workspace hand-authored
//! as a bare `&'static str` literal on the `ProcessStatus.conditions[]`
//! wire. Sibling on the same wire-form axis-family to
//! [`crate::k8s_condition::K8sConditionStatus`] — that primitive
//! owns the closed set of the `status` slot (`"True"` / `"False"`
//! / `"Unknown"`); THIS primitive owns the closed set of the
//! `type` slot (`"Ready"` / `"Attested"`) every
//! [`crate::status::ProcessCondition`] carries.
//!
//! ## Why the substrate lives here
//!
//! Pre-lift the two `type` wire-form literals were hand-authored at
//! FOUR production sites across two crates past the ★★ PRIME-
//! DIRECTIVE ≥ 2 duplication threshold — each writer + reader pair
//! silently coupled by exact-case ASCII agreement on the `type` slot:
//!
//! * [`crate::status::ProcessCondition::ready`] — writer, `type_:
//!   "Ready".into()` on the `Ready` row emitted whenever the
//!   reconciler observes a Process running.
//! * [`crate::status::ProcessCondition::not_ready`] — writer, `type_:
//!   "Ready".into()` on the same row emitted with `status: "False"`
//!   whenever the reconciler observes a Process failing.
//! * [`crate::status::ProcessCondition::attested`] — writer, `type_:
//!   "Attested".into()` on the `Attested` row emitted whenever a
//!   three-pillar attestation lands.
//! * `tatara-reconciler::ssapply::ready_condition_value` — reader,
//!   `if typ != "Ready" { continue; }` filter that isolates the
//!   `Ready`-typed condition out of every FluxCD / Deployment /
//!   HelmRelease / Kustomization / StatefulSet resource's
//!   `status.conditions[]` list before classifying its `status` slot
//!   through [`crate::k8s_condition::K8sConditionStatus::from_wire_str`].
//!
//! Every site restated the SAME `&'static str` byte-literal
//! (`"Ready"` × 3 or `"Attested"` × 1). A copy-paste that lower-cased
//! one letter (`"ready"` — silently invalid; the K8s API server does
//! NOT case-normalize condition types, and every observer that
//! selects by exact case would silently miss the drifted row),
//! swapped the semantic slot (a writer that emitted `"Attested"` on
//! the `Ready` row would silently drift the reconciler's
//! `ready_condition_value` observer to always-Unknown on that
//! resource), or introduced an alternate spelling drifts the wire-
//! form at ONE end and leaves the other end unable to classify the
//! condition — the reader falls through to `ReadyState::Unknown` and
//! every Flux / Deployment readiness gate silently reports "not
//! observed" for the remainder of the resource's life. Post-lift
//! each writer composes with `ProcessConditionType::<V>.as_wire_str()`
//! and the reader binds through `ProcessConditionType::from_wire_str
//! (...)`; the wire-form literal lives at ONE substrate owner and a
//! drift at either end becomes unrepresentable at the closed-set
//! level.
//!
//! ## Closed-set completeness
//!
//! `ProcessCondition` is the crate-owned condition type — the K8s
//! API does NOT dictate the `type` slot's closed set (unlike the
//! `status` slot's three-value set at
//! [`crate::k8s_condition::K8sConditionStatus`]); each CRD owns its
//! own type alphabet. Every `ProcessCondition` constructor in
//! [`crate::status`] pre-lift wrote exactly one of the two literals
//! `"Ready"` or `"Attested"`; the enum below IS that closed set.
//! A future ProcessCondition constructor that adds a third condition
//! type (e.g. `"Reconverging"` for the SIGHUP re-convergence path,
//! `"Terminated"` for the Zombie/Reaped gate) would land as ONE new
//! variant at this ONE substrate owner AND ONE new
//! `ProcessCondition::<constructor>` at [`crate::status`] AND (if
//! the reader wants to classify it) ONE new arm at
//! `ssapply::ready_condition_value` — exhaustively checked by the
//! compiler at every downstream consumer that pattern-matches on
//! the closed set.
//!
//! ## Byte-shape parity
//!
//! `as_wire_str` returns the EXACT-CASE ASCII byte-shape every pre-
//! lift site restated inline — pinned bytewise at
//! [`tests::as_wire_str_matches_pre_lift_literals_bytewise`] against
//! a hand-authored fixture table of the pre-lift strings. A
//! regression that lower-cased a variant, added a whitespace prefix,
//! or reshaped the byte-form under a future `#[derive(Serialize)]`
//! `serde(rename = "…")` drift surfaces at the pin rather than as
//! silent operator-facing wire-form skew across every
//! `ProcessCondition` writer + `ready_condition_value` reader in the
//! workspace.
//!
//! `from_wire_str` is the invertible partner — a round-trip through
//! `from_wire_str(v.as_wire_str())` yields `Some(v)` for every
//! variant, pinned at
//! [`tests::wire_form_round_trip_holds_for_every_variant`]. Any
//! input outside the closed set (case-drift, whitespace, empty
//! string, unrelated K8s condition-type literals) returns `None`;
//! the closed-set nature is pinned at
//! [`tests::from_wire_str_rejects_case_drift_and_unknown`].
//!
//! ## Naming — `as_wire_str`, not `as_str`
//!
//! Same discipline as the [`crate::k8s_condition::K8sConditionStatus`]
//! sibling — the method signals that the returned `&'static str` is
//! the K8s WIRE FORM (the exact byte-shape the API server accepts on
//! the `type` slot of a `metav1.Condition`), not a debug-print or
//! `Display` projection. A caller that reads `.as_wire_str()`
//! immediately understands the return value is safe to write into a
//! JSON payload without any further normalization; a call spelled
//! `.as_str()` reads as a generic string projection and invites
//! callers to reach for `.to_lowercase()` / `.trim()` normalizations
//! that would break the wire form.
//!
//! ## `#[must_use]` on `as_wire_str`
//!
//! Every consumer feeds the returned `&'static str` into either a
//! `String::from(...)` composition (writer side, going into
//! `ProcessCondition.type_`) or a pattern-match / equality arm
//! (reader side, filtering `status.conditions[]`). Dropping the
//! return means the wire-form projection was computed for no
//! observable reason — the attribute surfaces that as a warning at
//! every consumer site.
//!
//! Theory anchor: THEORY.md §II.1 invariant 5 (composition preserves
//! proofs — the wire-form literal at ONE substrate owner means the
//! writer + reader sides of the K8s `status.conditions[].type` wire
//! agree bytewise by construction; a drift at either end becomes
//! unrepresentable at the closed-set level, not "detected at
//! runtime by a mismatched observer log line"). THEORY.md §III
//! (typescape — the ProcessCondition `type` slot's closed set is a
//! first-class Rust enum, not a stringly-typed wire-form).
//! THEORY.md §VI.1 (generation over composition — the two-literal
//! closed set recurred at FOUR hand-authored sites past the ★★
//! PRIME-DIRECTIVE ≥ 2 duplication trigger, and is lifted to ONE
//! substrate owner here on the K8s-Condition `type` wire-form axis).

use std::fmt;

/// The closed set of `metav1.Condition.type` values every
/// [`crate::status::ProcessCondition`] constructor emits and every
/// downstream `status.conditions[]` classifier filters against.
/// Wire-form is the exact-case ASCII literal (`"Ready"`,
/// `"Attested"`); a case-drifted variant would silently miss the
/// reader's byte-exact filter.
///
/// Substrate primitive over the `type`-slot wire-form literal every
/// writer + reader hand-authors on opposite sides of
/// `status.conditions[]`. Sibling on the same K8s-Condition wire-form
/// axis-family to [`crate::k8s_condition::K8sConditionStatus`] —
/// that primitive owns the `status`-slot closed set, this primitive
/// owns the `type`-slot closed set. See the module docs for the
/// pre-lift lift audit + closed-set completeness argument.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum ProcessConditionType {
    /// The `Ready`-typed condition — the reconciler's per-observation
    /// readiness row emitted by [`crate::status::ProcessCondition::
    /// ready`] (status = `True`) + [`crate::status::ProcessCondition::
    /// not_ready`] (status = `False`), and filtered by
    /// `tatara-reconciler::ssapply::ready_condition_value` on the
    /// reader side.
    Ready,
    /// The `Attested`-typed condition — the reconciler's post-
    /// three-pillar-attestation row emitted by
    /// [`crate::status::ProcessCondition::attested`] (status = `True`)
    /// once a `ProcessAttestation`'s `composed_root` is written into
    /// the `message` slot.
    Attested,
}

impl ProcessConditionType {
    /// The closed set of `metav1.Condition.type` values every
    /// [`crate::status::ProcessCondition`] constructor emits and every
    /// downstream reader classifies — single source of truth that drives
    /// every variant-sweep consumer (round-trip tests, Display parity
    /// tests, sibling-axis disjointness tests, and any future dashboard /
    /// tatara-check enumerator / typed-completion consumer that needs
    /// to iterate the closed set exhaustively).
    ///
    /// Adding a third variant (e.g. `Reconverging` for the SIGHUP
    /// re-convergence path, `Terminated` for the Zombie/Reaped gate)
    /// lands at ONE `ALL` entry + ONE `as_wire_str` arm + ONE
    /// `from_wire_str` arm — exhaustively checked by the compiler
    /// (the `[Self; 2]` array literal forces the arity, and the
    /// exhaustive-match on `as_wire_str` + `from_wire_str` covers the
    /// rest).
    ///
    /// Pre-lift the two-variant array literal was hand-authored at
    /// THREE test sites in this module past the ★★ PRIME-DIRECTIVE
    /// ≥ 2 duplication threshold — the round-trip test, the Display
    /// parity test, and the sibling-axis disjointness test. Post-lift
    /// each iterates `Self::ALL` and the closed-set enumeration lives
    /// at ONE substrate owner here.
    ///
    /// Sibling closed-set `ALL` slices across the crate's typescape:
    /// [`crate::k8s_condition::K8sConditionStatus::ALL`] (the sibling on
    /// the K8s-Condition wire-form axis-family — status-slot closed set,
    /// this owns the type-slot closed set); [`crate::boundary::ConditionKind::ALL`],
    /// [`crate::phase::ProcessPhase::ALL`], [`crate::signal::ProcessSignal::ALL`],
    /// [`crate::intent::IntentKind::ALL`], [`crate::lifetime::LifetimeKind::ALL`],
    /// [`crate::receipt::ReceiptKind::ALL`].
    pub const ALL: [Self; 2] = [Self::Ready, Self::Attested];

    /// The K8s wire-form literal for this variant — exact-case ASCII,
    /// safe to write directly into a `metav1.Condition.type` slot
    /// without further normalization. Byte-identical to the pre-lift
    /// hand-authored `"Ready"` / `"Attested"` literals every writer
    /// and reader restated inline.
    #[must_use = "a ProcessCondition type wire-form projection that isn't bound swallows the composition"]
    pub const fn as_wire_str(self) -> &'static str {
        match self {
            Self::Ready => "Ready",
            Self::Attested => "Attested",
        }
    }

    /// Parse a K8s wire-form ProcessCondition type literal into its
    /// typed variant. Returns `None` for any input outside the
    /// closed set — case-drift (`"ready"`), whitespace-wrapped
    /// variants (`" Ready"`), unrelated literals (`""`, `"True"`,
    /// `"KustomizationHealthy"`), all reject silently and the caller
    /// falls through to its own `_ => ...` arm.
    ///
    /// Invertible with [`Self::as_wire_str`]: a round-trip through
    /// `from_wire_str(v.as_wire_str())` yields `Some(v)` for every
    /// variant. Pinned at
    /// [`tests::wire_form_round_trip_holds_for_every_variant`].
    #[must_use = "a ProcessCondition type parse result that isn't bound swallows the classification"]
    pub fn from_wire_str(s: &str) -> Option<Self> {
        match s {
            "Ready" => Some(Self::Ready),
            "Attested" => Some(Self::Attested),
            _ => None,
        }
    }
}

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

#[cfg(test)]
mod tests {
    use super::ProcessConditionType;

    /// Fail-before-pass-after: the substrate's `as_wire_str`
    /// projection produces byte-identical output to the pre-lift
    /// hand-authored `"Ready"` / `"Attested"` literals every writer
    /// and reader restated inline. A regression that lower-cased
    /// one variant, added a whitespace prefix, or a future
    /// `#[derive(Serialize)]` `serde(rename)` drift on this type
    /// would surface HERE, not as silent operator-facing wire-form
    /// skew across every ProcessCondition writer and reader in the
    /// workspace.
    #[test]
    fn as_wire_str_matches_pre_lift_literals_bytewise() {
        assert_eq!(ProcessConditionType::Ready.as_wire_str(), "Ready");
        assert_eq!(ProcessConditionType::Attested.as_wire_str(), "Attested");
    }

    /// Round-trip through `from_wire_str(v.as_wire_str())` yields
    /// `Some(v)` for every variant. Pins the invariant that the
    /// writer + reader compose invertibly at the closed-set boundary
    /// — a writer's `as_wire_str` output is always accepted by the
    /// reader's `from_wire_str` on the SAME variant.
    #[test]
    fn wire_form_round_trip_holds_for_every_variant() {
        for v in ProcessConditionType::ALL {
            assert_eq!(
                ProcessConditionType::from_wire_str(v.as_wire_str()),
                Some(v),
            );
        }
    }

    /// Inputs outside the closed set — case-drift, whitespace-
    /// wrapped variants, empty string, unrelated K8s wire-form
    /// literals (K8s ConditionStatus values, K8s built-in condition
    /// types, ProcessCondition reason slot values) — all reject with
    /// `None`. Pins the closed-set nature: `from_wire_str` is a total
    /// function over the ProcessCondition type alphabet, not a
    /// permissive parser that accepts synonyms.
    #[test]
    fn from_wire_str_rejects_case_drift_and_unknown() {
        for bad in [
            "",
            "ready",
            "READY",
            "attested",
            "ATTESTED",
            " Ready",
            "Ready ",
            "Attested\n",
            "True",
            "False",
            "Unknown",
            "KustomizationHealthy",
            "HelmReleaseReleased",
            "ObservedRunning",
            "AttestationWritten",
            "1",
        ] {
            assert_eq!(
                ProcessConditionType::from_wire_str(bad),
                None,
                "expected `{bad:?}` outside the ProcessCondition type closed set, but from_wire_str accepted it",
            );
        }
    }

    /// `Display` composes through `as_wire_str` — the two
    /// projections are byte-identical so `format!("{v}")` and
    /// `v.as_wire_str()` are interchangeable at every consumer.
    /// Pins the invariant that a caller who reaches for the stdlib
    /// `Display` conversion path (via `.to_string()`,
    /// `format!("{v}")`, a `write!` macro) gets the same wire-form
    /// bytes as a direct `.as_wire_str()` call.
    #[test]
    fn display_composes_through_as_wire_str_bytewise() {
        for v in ProcessConditionType::ALL {
            assert_eq!(v.to_string(), v.as_wire_str());
            assert_eq!(format!("{v}"), v.as_wire_str());
        }
    }

    /// Closed-set completeness: the two variants exhaust the
    /// ProcessCondition type alphabet as of this crate's revision.
    /// A future ProcessCondition constructor that added a third
    /// condition type (e.g. `"Reconverging"` for the SIGHUP re-
    /// convergence path, `"Terminated"` for the Zombie/Reaped gate)
    /// would land as one new variant here, and every consumer that
    /// pattern-matched exhaustively against the closed set gets a
    /// compile-time error until it handles the new arm — the fifth
    /// invariant of the Rust+Lisp pattern. Compiler-verified below
    /// with an exhaustive match; a regression that added a
    /// `#[non_exhaustive]` attribute or a private constructor arm
    /// would break the exhaustiveness proof at this test.
    #[test]
    fn closed_set_exhausts_the_process_condition_type_alphabet() {
        fn describe(v: ProcessConditionType) -> &'static str {
            match v {
                ProcessConditionType::Ready => "Ready",
                ProcessConditionType::Attested => "Attested",
            }
        }
        assert_eq!(describe(ProcessConditionType::Ready), "Ready");
        assert_eq!(describe(ProcessConditionType::Attested), "Attested");
    }

    /// `Copy` + `Clone` + `Eq` + `Hash` — pins the trait derives at
    /// compile time so a regression that dropped one (a future
    /// `#[derive(Serialize, Deserialize)]` addition that reshaped
    /// the enum, a manual `impl Clone` that dropped `Copy`) surfaces
    /// here rather than at a downstream consumer that stored the
    /// value in a `HashMap` key or copied it across an `if` arm.
    #[test]
    fn value_semantics_hold_at_compile_time() {
        fn assert_copy<T: Copy>() {}
        fn assert_hash<T: std::hash::Hash>() {}
        fn assert_eq<T: Eq>() {}
        assert_copy::<ProcessConditionType>();
        assert_hash::<ProcessConditionType>();
        assert_eq::<ProcessConditionType>();
    }

    /// Sibling-axis coherence with [`crate::k8s_condition::
    /// K8sConditionStatus`] on the K8s-Condition wire-form axis-
    /// family — the two primitives partition the `metav1.Condition`
    /// wire alphabet by SLOT (`type` here, `status` at the sibling),
    /// so a caller that accidentally passed a ProcessConditionType
    /// wire-form to `K8sConditionStatus::from_wire_str` (or vice
    /// versa) MUST reject. Pins the invariant that the two closed
    /// sets are DISJOINT — a case-flip or a copy-paste that swapped
    /// the two `from_wire_str` calls surfaces HERE as a `None` at
    /// the wrong reader, not as silent classification skew.
    #[test]
    fn from_wire_str_rejects_sibling_axis_wire_forms() {
        use crate::k8s_condition::K8sConditionStatus;
        for s in K8sConditionStatus::ALL {
            let status_wire = s.as_wire_str();
            assert_eq!(
                ProcessConditionType::from_wire_str(status_wire),
                None,
                "ProcessConditionType::from_wire_str accepted the sibling-axis \
                 K8sConditionStatus wire-form `{status_wire:?}` — the two closed \
                 sets MUST stay disjoint",
            );
        }
        for t in ProcessConditionType::ALL {
            let type_wire = t.as_wire_str();
            assert_eq!(
                K8sConditionStatus::from_wire_str(type_wire),
                None,
                "K8sConditionStatus::from_wire_str accepted the sibling-axis \
                 ProcessConditionType wire-form `{type_wire:?}` — the two closed \
                 sets MUST stay disjoint",
            );
        }
    }

    /// Fail-before-pass-after: the `ALL` sweep MUST enumerate every
    /// variant of the closed set exactly once, with no duplicates and
    /// no omissions. Pinned three ways so any drift surfaces at ONE
    /// substrate pin rather than as silent skew at every consumer that
    /// iterates the sweep:
    ///
    /// 1. **Arity** — the array's length equals the variant count.
    ///    The `[Self; 2]` type-level arity already forces this at the
    ///    substrate; the test restates it as a runtime witness so a
    ///    regression that widened the type to `&[Self]` (a slice
    ///    literal) or a `Vec<Self>` builder would surface at the
    ///    substrate pin rather than as silent shape drift.
    /// 2. **No duplicates** — round-trip each entry through
    ///    `from_wire_str(as_wire_str)` and confirm the round-trip
    ///    yields distinct variants. A regression that stamped
    ///    `[Self::Ready, Self::Ready]` (a copy-paste at the sweep) or
    ///    `[Self::Ready, Self::Attested, Self::Ready]` (a paste that
    ///    also drifted the arity) surfaces at the collected-set
    ///    cardinality check.
    /// 3. **Cover** — an exhaustive match on each iterated variant
    ///    proves the compiler sees every arm at least once through the
    ///    sweep, so a future variant addition that landed at
    ///    `as_wire_str` + `from_wire_str` but was forgotten at `ALL`
    ///    surfaces at the sweep's compile-time exhaustive-match check.
    #[test]
    fn all_covers_the_process_condition_type_closed_set_exhaustively() {
        assert_eq!(
            ProcessConditionType::ALL.len(),
            2,
            "ALL must enumerate every variant of the closed set — a regression that \
             added a variant at `as_wire_str` but forgot to extend `ALL` surfaces here",
        );

        let seen: std::collections::HashSet<ProcessConditionType> =
            ProcessConditionType::ALL.iter().copied().collect();
        assert_eq!(
            seen.len(),
            ProcessConditionType::ALL.len(),
            "ALL must not stamp any variant twice — a copy-paste at the sweep surfaces here",
        );

        for v in ProcessConditionType::ALL {
            let _cover: &'static str = match v {
                ProcessConditionType::Ready => "Ready",
                ProcessConditionType::Attested => "Attested",
            };
        }
    }
}