tatara_process/

encapsulates.rs

//! `EncapsulatesSpec` — how a Process relates to pre-existing
//! in-cluster state.
//!
//! The substrate move: every long-running workload on a pleme-io
//! cluster — raw HelmReleases, Flux Kustomizations, bare Deployments
//! — becomes a Process without disruption. Three modes:
//!
//! * **Manage** (default) — Process IS the control loop. New
//!   HR/Kustomization emitted by the reconciler use ownerRefs
//!   pointing at the Process; cascade-delete on Reaped.
//!
//! * **Adopt** — Take over an existing HR/Kustomization in place.
//!   Reconciler emits a new HR with `releaseName` matching the
//!   running release; helm-controller adopts the existing release
//!   under new management. **No pod restart**; no values diff
//!   unless operator changes them. The original raw HR can be
//!   deleted from git after the takeover confirms.
//!
//! * **Observe** — Read-only awareness. Process watches the existing
//!   state for postcondition pillars + emits routing/exports/
//!   attestation, but does NOT modify or own the underlying
//!   HR/Kustomization. Useful for adding DNS + observability to
//!   legacy stacks without taking over.
//!
//! These compose progressively: Observe an HR first to confirm
//! shape, promote to Adopt for zero-downtime takeover, then to
//! Manage once the Process drives values.
//!
//! Lisp authoring:
//! ```lisp
//! :encapsulates (:kind (:existing-helm-release
//!                       :namespace    "demo-ns"
//!                       :name         "demo-app"
//!                       :release-name "demo-app-consolidated")
//!                :mode Adopt)
//! ```

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use tatara_lisp::DeriveTataraDomain;

/// How a Process wraps pre-existing in-cluster state.
///
/// Optional on `ProcessSpec` — None means the Process is greenfield
/// (Manage mode applied to nothing pre-existing). The render phase
/// branches on `kind` to decide whether to emit fresh resources or
/// reference/adopt running ones.
#[derive(DeriveTataraDomain, Clone, Debug, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[tatara(keyword = "defencapsulates")]
pub struct EncapsulatesSpec {
    /// What kind of pre-existing state.
    pub kind: EncapsulationKind,

    /// Reconciler's relationship to that state. Defaults to `Manage`
    /// (the operational default when `encapsulates` is set without
    /// an explicit mode).
    #[serde(default)]
    pub mode: EncapsulationMode,
}

impl EncapsulatesSpec {
    /// Closed-set-driven presence probe — does this [`EncapsulatesSpec`]
    /// carry the given [`EncapsulationMode`] discriminator on its
    /// [`Self::mode`] slot? The ONE substrate primitive that owns the
    /// `(EncapsulatesSpec, EncapsulationMode) -> bool` scalar-carrier walk
    /// shape.
    ///
    /// # Second scalar-carrier peer on the presence-probe axis
    ///
    /// Peer of [`crate::spec::SignalPolicy::has_sighup_strategy`] — both
    /// probe a scalar closed-set-discriminator field on an inner
    /// [`crate::crd::ProcessSpec`] struct via a one-line
    /// `self.<field> == kind` body. Together they close the SCALAR-CARRIER
    /// stratum of the workspace-wide closed-set-driven presence-probe
    /// algebra (the workspace-wide algebra spans three underlying
    /// representation kinds — Option-slot, slice, scalar — see the
    /// [`crate::spec::SignalPolicy::has_sighup_strategy`] docstring for
    /// the full-shape rundown; this method is the second scalar-carrier
    /// instance).
    ///
    /// # Semantics — VARIANT match, not POPULATED slot
    ///
    /// `has_mode(kind)` returns `true` iff `self.mode == kind`. On an
    /// [`EncapsulatesSpec`] whose `mode` slot is the substrate default
    /// ([`EncapsulationMode::default`] = [`EncapsulationMode::Manage`])
    /// the probe returns `true` for [`EncapsulationMode::Manage`] and
    /// `false` for every other variant — legitimate operator signal
    /// symmetric to [`crate::signal::SighupStrategy::default`]. An
    /// operator who opted `encapsulates` in (populating the parent
    /// `Option<EncapsulatesSpec>`) but left `:mode` unset IS configured
    /// for `Manage`, and a `:requires (encapsulation-mode-Manage)` check
    /// should pass on that spec.
    ///
    /// # Interaction with the parent `Option` gate
    ///
    /// The parent `Process.spec.encapsulates` field is an
    /// `Option<EncapsulatesSpec>` (greenfield Processes carry `None`);
    /// downstream consumers gate this probe on the parent presence via
    /// `spec.encapsulates.as_ref().is_some_and(|e| e.has_mode(kind))`.
    /// A permanent Process with `encapsulates: None` returns `false` for
    /// every kind — including the default `Manage` variant — because
    /// the operator DECLINED the encapsulation surface entirely rather
    /// than defaulting into it. Symmetric to the
    /// `resolved_ephemeral().is_some_and(…)` gate the
    /// `export-when-<kind>` / `channel-<kind>` / `report-format-<kind>` /
    /// `artifact-<kind>` slice-level probes compose on the ephemeral
    /// axis.
    ///
    /// # Compounding
    ///
    /// A future closed-set-discriminator scalar field on `EncapsulatesSpec`
    /// (a hypothetical `SubmodeKind` selecting a sub-strategy inside the
    /// Adopt/Manage modes; a `HandoffPhase` scalar selecting when the
    /// reconciler swaps ownership) lands as ONE peer inherent method
    /// with the same one-line `self.<field> == kind` body and routes
    /// through the same `strip_and_classify_prefixed_kind::<K, _>` shape
    /// in `tatara-check`. A future
    /// [`EncapsulationMode`] variant (a hypothetical `Observe` submode,
    /// a `Migrate` for scripted mode transitions) reaches every
    /// downstream through ONE `ALL` entry on the closed set with the
    /// probe body untouched.
    ///
    /// Theory anchor: THEORY.md §II.1 invariant 5 — composition preserves
    /// proofs; the scalar-carrier presence-probe body lives at ONE
    /// substrate site so every downstream (`encapsulation-mode-<kind>`
    /// require-tag family in `tatara-check`, closed-set audit
    /// dispatchers, future variant additions on [`EncapsulationMode`])
    /// binds through the SAME shape rather than restating the
    /// `encapsulates.mode == kind` closure body at each callsite.
    /// THEORY.md §VI.1 — generation over composition; a future
    /// [`EncapsulationMode`] variant lands at ONE `ALL` entry + ONE
    /// `as_str` arm on the closed set and the probe picks it up
    /// mechanically without further per-consumer edits.
    #[must_use]
    pub fn has_mode(&self, kind: EncapsulationMode) -> bool {
        self.mode == kind
    }
}

/// Three concrete kinds the substrate knows how to wrap. Exactly-
/// one-Option pattern matching `Intent` / `Lifetime` — additive on
/// the wire, every variant typed.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct EncapsulationKind {
    /// An existing FluxCD HelmRelease. The reconciler emits a new HR
    /// with the SAME `release_name` — helm-controller finds + adopts
    /// the in-cluster release without recreating Pods.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub existing_helm_release: Option<ExistingHelmRelease>,

    /// An existing FluxCD Kustomization. The reconciler stops emitting
    /// its own and instead references the existing one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub existing_kustomization: Option<ExistingKustomization>,

    /// Pre-existing in-cluster workload (Deployment/StatefulSet/etc)
    /// not Flux-managed. The reconciler adds ownerRefs + emits
    /// routing only. The workload stays where it is.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bare_workload: Option<BareWorkload>,
}

/// Resolved enum view used by the render phase.
#[derive(Clone, Debug)]
pub enum EncapsulationKindVariant<'a> {
    ExistingHelmRelease(&'a ExistingHelmRelease),
    ExistingKustomization(&'a ExistingKustomization),
    BareWorkload(&'a BareWorkload),
}

impl EncapsulationKindVariant<'_> {
    /// Reverse projection — every borrowed variant knows its
    /// [`EncapsulationTarget`] discriminator. Pairs with
    /// [`EncapsulationTarget::select`] so
    /// `EncapsulationTarget::select(kind).map(|v| v.target())`
    /// round-trips the closed set on the populated side; pinned by
    /// `encapsulation_target_round_trips_through_variant_target`.
    /// Future target-keyed consumers (metric labels like
    /// `tatara_encapsulations_total{target="existingHelmRelease"}`,
    /// status reason strings, audit-trail classifiers, LSP completion
    /// lists) reach through this projection instead of pattern-matching
    /// the payload-carrying view.
    pub fn target(&self) -> EncapsulationTarget {
        match self {
            Self::ExistingHelmRelease(_) => EncapsulationTarget::ExistingHelmRelease,
            Self::ExistingKustomization(_) => EncapsulationTarget::ExistingKustomization,
            Self::BareWorkload(_) => EncapsulationTarget::BareWorkload,
        }
    }
}

/// `EncapsulationKindVariant`'s [`crate::tagged_union::VariantKind`] impl
/// delegates to the inherent [`Self::target`] — the substrate trait names
/// the reverse projection uniformly across every borrowed-view enum on
/// `ProcessSpec`'s tagged-union axis, while the inherent method's
/// domain-specific name (`.target()`, matching `EncapsulationTarget`) stays
/// load-bearing at every consumer site. The one-line delegation IS the
/// only per-site restatement; the ground-truth arm-to-Kind mapping lives
/// at the inherent method above.
impl crate::tagged_union::VariantKind<EncapsulationTarget> for EncapsulationKindVariant<'_> {
    fn variant_kind(&self) -> EncapsulationTarget {
        self.target()
    }
}

/// Closed-set discriminator over `EncapsulationKind`'s three tagged-union
/// slots. Single source of truth that drives `EncapsulationKind::variant`'s
/// ambiguity + emptiness resolver, the `EncapsulationKindError::Empty`
/// diagnostic message, and the reverse `EncapsulationKindVariant::target`
/// projection. Adding a fourth encapsulation target (e.g., a future
/// `ExistingNamespace`, `ExistingDaemonSet`, or `ExistingService`) lands
/// at one `ALL` entry + one `as_str` arm + one `select` arm + one
/// `EncapsulationKindVariant::target` arm — exhaustively checked by the
/// compiler.
///
/// The (open authoring surface, closed typed discriminator) split mirrors
/// every other multi-Option tagged union on this `ProcessSpec` axis:
/// [`crate::intent::IntentKind`] discriminates [`crate::intent::Intent`];
/// [`crate::lifetime::LifetimeKind`] discriminates
/// [`crate::lifetime::Lifetime`];
/// [`crate::export::ArtifactKind`] discriminates
/// [`crate::export::ArtifactSource`];
/// [`crate::export::ChannelKind`] discriminates
/// [`crate::export::VectorChannel`]. The carrier here is named
/// `EncapsulationKind` (not `Encapsulation`) because it predates the
/// closed-set lift convention; `EncapsulationTarget` is the typed
/// discriminator the rest of the typescape projects through, named for
/// the semantic role each variant plays (a target of encapsulation).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, tatara_closed_set::DeriveClosedSet)]
#[closed_set(via = "as_str", generate_unknown, display)]
pub enum EncapsulationTarget {
    ExistingHelmRelease,
    ExistingKustomization,
    BareWorkload,
}

impl EncapsulationTarget {
    /// The closed set of encapsulation targets — single source of truth
    /// that drives `EncapsulationKind::variant`'s sweep so a variant
    /// added without an `ALL` entry never reaches the resolver. The
    /// `[Self; 3]` array literal forces the arity at compile time.
    pub const ALL: [Self; 3] = [
        Self::ExistingHelmRelease,
        Self::ExistingKustomization,
        Self::BareWorkload,
    ];

    /// Canonical camelCase wire-format key — matches the serde
    /// `rename_all = "camelCase"` field name on the corresponding
    /// `Option<…>` slot of `EncapsulationKind`. The
    /// `EncapsulationKindError::Empty` diagnostic composes the
    /// human-readable list from this projection so a new variant lands
    /// in the operator-facing diagnostic automatically via the `ALL`
    /// sweep, not via hand-maintained error-string drift. Pinned by
    /// `encapsulation_target_as_str_matches_field_name`.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::ExistingHelmRelease => "existingHelmRelease",
            Self::ExistingKustomization => "existingKustomization",
            Self::BareWorkload => "bareWorkload",
        }
    }

    /// Project an `EncapsulationKind` borrow into the optional typed
    /// variant view for this target. Returns `None` iff the matching
    /// slot is `None`. Composes the closed-set sweep
    /// `EncapsulationKind::variant` loops over. Mirrors
    /// [`crate::intent::IntentKind::select`],
    /// [`crate::lifetime::LifetimeKind::select`],
    /// [`crate::export::ArtifactKind::select`], and
    /// [`crate::export::ChannelKind::select`].
    pub fn select<'a>(self, kind: &'a EncapsulationKind) -> Option<EncapsulationKindVariant<'a>> {
        match self {
            Self::ExistingHelmRelease => kind
                .existing_helm_release
                .as_ref()
                .map(EncapsulationKindVariant::ExistingHelmRelease),
            Self::ExistingKustomization => kind
                .existing_kustomization
                .as_ref()
                .map(EncapsulationKindVariant::ExistingKustomization),
            Self::BareWorkload => kind
                .bare_workload
                .as_ref()
                .map(EncapsulationKindVariant::BareWorkload),
        }
    }
}

// `impl FromStr for EncapsulationTarget` + `impl tatara_lisp::ClosedSet for
// EncapsulationTarget` + `impl std::fmt::Display for EncapsulationTarget` are
// generated by `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum
// declaration above. `label` delegates to the inherent
// `EncapsulationTarget::as_str` via `#[closed_set(via = "as_str")]` so the
// camelCase wire-format projection stays load-bearing (matches the serde
// `rename_all = "camelCase"` field names on `EncapsulationKind` AND the
// `ENCAPSULATION_TARGET_LIST` slash-joined operator diagnostic verbatim)
// while generic `T: ClosedSet` consumers reach the STABLE workspace-wide
// name (`label`). The `display` flag emits the `f.write_str(self.as_str())`
// delegation block at the same proc-macro site rather than a hand-rolled
// `fmt::Display` block per implementor.

// `pub struct UnknownEncapsulationTarget(pub String)` is generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` + `#[closed_set(generate_unknown)]`
// on the enum declaration above. The auto-derived label `"encapsulation target"`
// matches the prior hand-rolled `#[error("unknown encapsulation target: {0}")]`
// verbatim — pinned generically by clause (5) of
// `tatara_closed_set::assert_closed_set_well_formed::<EncapsulationTarget>()` (called
// from `encapsulation_target_is_well_formed_closed_set` in the test module).
// Symmetric to [`UnknownEncapsulationMode`], [`crate::export::UnknownArtifactKind`],
// [`crate::export::UnknownChannelKind`], and
// [`crate::lifetime::UnknownTeardownPolicy`].

crate::declare_tagged_union_error! {
    pub EncapsulationKindError,
    empty = "encapsulation kind has no variant set (one of {0} required)",
    ambiguous = "encapsulation kind has multiple variants set; exactly one required",
}

/// Slash-joined list of every `EncapsulationTarget::as_str()` — composed
/// once at compile time so `EncapsulationKindError::Empty`'s diagnostic
/// carries the closed-set summary without per-variant string drift.
/// Mirrors [`crate::intent::INTENT_KIND_LIST`] /
/// [`crate::export::ARTIFACT_KIND_LIST`] in shape; pinned by
/// `encapsulation_kind_error_empty_lists_every_target_in_canonical_order`.
pub(crate) const ENCAPSULATION_TARGET_LIST: &str =
    "existingHelmRelease/existingKustomization/bareWorkload";

crate::declare_tagged_union_impls! {
    parent = EncapsulationKind,
    kind = EncapsulationTarget,
    variant = EncapsulationKindVariant,
    error = EncapsulationKindError,
    kind_list = ENCAPSULATION_TARGET_LIST,
}

/// Pointer to an existing FluxCD HelmRelease the Process wraps.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ExistingHelmRelease {
    /// Namespace of the HelmRelease CR.
    pub namespace: String,
    /// Name of the HelmRelease CR.
    pub name: String,
    /// The `spec.releaseName` Helm used for the actual chart install.
    /// For Adopt mode, the reconciler's emitted HR matches this so
    /// helm-controller adopts in-place. Required because the HR's
    /// `metadata.name` and `spec.releaseName` aren't always equal.
    pub release_name: String,
}

/// Pointer to an existing FluxCD Kustomization the Process wraps.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ExistingKustomization {
    pub namespace: String,
    pub name: String,
}

/// Pointer to a bare in-cluster workload (not Flux-managed). The
/// reconciler identifies the underlying Pods by `selector` and adds
/// ownerRefs / routing without emitting a new HR/Kustomization.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct BareWorkload {
    /// Namespace the workload lives in.
    pub namespace: String,
    /// Label selector. Must match a single Deployment/StatefulSet/
    /// DaemonSet; multiple matches are a config error.
    pub selector: BTreeMap<String, String>,
}

/// Three modes the reconciler dispatches on at render time.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    JsonSchema,
    PartialEq,
    Eq,
    Hash,
    tatara_closed_set::DeriveClosedSet,
)]
#[serde(rename_all = "PascalCase")]
#[closed_set(via = "as_str", generate_unknown, display)]
pub enum EncapsulationMode {
    /// **Default** — Process IS the control loop for whatever is
    /// inside. Emitted HR/Kustomization carry the Process's
    /// ownerRefs; cascade-delete on Reaped.
    #[default]
    Manage,

    /// **Adopt** — Take over the existing release/kustomization in
    /// place. New HR emitted matches the existing `releaseName`;
    /// pods don't restart. Used during migration from raw HR → Process.
    Adopt,

    /// **Observe** — Read-only. Emit routing/exports/attestation but
    /// don't modify the underlying HR/Kustomization. Used to add
    /// DNS + observability to legacy stacks without taking over.
    Observe,
}

impl EncapsulationMode {
    /// The closed set of encapsulation modes — single source of truth
    /// that drives the `as_str` / Display / `FromStr` triad and the
    /// typed `emits_workload` / `preserves_release_name` dispatch.
    /// Adding a fourth variant lands at one `ALL` entry + one `as_str`
    /// arm + one arm in each of the two boolean projections —
    /// exhaustively checked by the compiler (the `[Self; 3]` array
    /// literal forces the arity).
    ///
    /// Sibling closed-set lifts on the same `ProcessSpec` axis:
    /// [`crate::export::ExportTrigger::ALL`],
    /// [`crate::lifetime::TeardownPolicy::ALL`],
    /// [`crate::intent::IntentKind::ALL`],
    /// [`crate::lifetime::LifetimeKind::ALL`],
    /// [`crate::boundary::ConditionKind::ALL`],
    /// [`crate::phase::ProcessPhase::ALL`],
    /// [`crate::signal::ProcessSignal::ALL`].
    pub const ALL: [Self; 3] = [Self::Manage, Self::Adopt, Self::Observe];

    /// 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 reason strings without reaching for `{:?}` Debug
    /// formatting. Pinned by `mode_as_str_matches_serde`.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Manage => "Manage",
            Self::Adopt => "Adopt",
            Self::Observe => "Observe",
        }
    }

    /// True iff the reconciler should emit (or re-emit) the
    /// underlying HR/Kustomization at render time.
    /// Observe ⇒ false; Manage/Adopt ⇒ true.
    ///
    /// Closed-set match (not `matches!`) so adding a fourth variant
    /// triggers the compiler's exhaustiveness check at this site
    /// rather than silently defaulting to `false`. ONE typed dispatch
    /// over the closed set that replaces the
    /// `mode == EncapsulationMode::Observe` hand-rolled equality at
    /// the reconciler's render entry — the truth table for "should
    /// this mode emit a workload?" is now owned by the typed surface,
    /// not by a pattern fragment two crates have to keep coherent.
    pub const fn emits_workload(self) -> bool {
        match self {
            Self::Manage | Self::Adopt => true,
            Self::Observe => false,
        }
    }

    /// True iff the reconciler should preserve the existing release
    /// name (so helm-controller adopts in-place). Only Adopt.
    ///
    /// Closed-set match (not `matches!`) so adding a fourth variant
    /// triggers the compiler's exhaustiveness check at this site.
    /// ONE typed dispatch that replaces the
    /// `mode == EncapsulationMode::Adopt` hand-rolled equality at the
    /// reconciler's `render_aplicacao` adoption-annotation branch.
    pub const fn preserves_release_name(self) -> bool {
        match self {
            Self::Adopt => true,
            Self::Manage | Self::Observe => false,
        }
    }
}

// `impl FromStr for EncapsulationMode` + `impl tatara_lisp::ClosedSet for
// EncapsulationMode` + `impl std::fmt::Display for EncapsulationMode` are
// generated by `#[derive(tatara_closed_set::DeriveClosedSet)]` on the enum
// declaration above. `label` delegates to the inherent
// `EncapsulationMode::as_str` via `#[closed_set(via = "as_str")]` so the
// PascalCase wire-format projection stays load-bearing (matches the serde
// `rename_all = "PascalCase"` external-tag form on the wire AND the
// reconciler's `mode: {Manage,Adopt,Observe}` status-condition reason
// strings verbatim) while generic `T: ClosedSet` consumers reach the
// STABLE workspace-wide name (`label`). The `display` flag emits the
// `f.write_str(self.as_str())` delegation block at the same proc-macro
// site rather than a hand-rolled `fmt::Display` block per implementor.

// `pub struct UnknownEncapsulationMode(pub String)` is generated by
// `#[derive(tatara_closed_set::DeriveClosedSet)]` + `#[closed_set(generate_unknown)]`
// on the enum declaration above. The auto-derived label `"encapsulation mode"`
// matches the prior hand-rolled `#[error("unknown encapsulation mode: {0}")]`
// verbatim — pinned generically by clause (5) of
// `tatara_closed_set::assert_closed_set_well_formed::<EncapsulationMode>()` (called
// from `mode_is_well_formed_closed_set` in the test module).
// Symmetric to [`UnknownEncapsulationTarget`], [`crate::export::UnknownExportTrigger`],
// [`crate::lifetime::UnknownTeardownPolicy`],
// [`crate::boundary::UnknownConditionKind`], and
// [`crate::phase::UnknownPhase`].

/// Extension trait on `Option<EncapsulatesSpec>` — the ONE substrate
/// primitive that owns the "collapse the parent `encapsulates`
/// Option-carrier before probing the inner spec" shape shared by every
/// downstream require-tag family whose vocabulary reads through
/// [`crate::crd::ProcessSpec::encapsulates`].
///
/// # Why lift
///
/// The point-domain require-tag classifier in
/// `tatara-reconciler::bin::tatara-check` composed the SAME two-step
/// chain (`spec.encapsulates.as_ref().is_some_and(|e| e.<probe>(k))`)
/// at TWO consecutive rows in `evaluate_point_require_tag`'s prefix
/// table:
///
/// * `encapsulation-mode-<kind>` — projects onto the
///   [`EncapsulatesSpec::has_mode`] scalar-carrier probe.
/// * `encapsulation-target-<kind>` — projects onto the
///   [`crate::tagged_union::TaggedUnion::has`] presence probe over the
///   nested [`EncapsulationKind`] tagged union.
///
/// Two restatements of the ONE Option-carrier collapse past the
/// ★★ PRIME-DIRECTIVE ≥ 2 duplication threshold — post-lift ONE
/// substrate primitive owns the `(Option<EncapsulatesSpec>) → probe`
/// discipline, and every current + future presence probe threaded
/// through `spec.encapsulates` plugs into it through the SAME trait
/// shape without a bespoke Option-arm at the caller.
///
/// # Semantics vs. the pre-lift chain
///
/// `.as_ref().is_some_and(|e| e.has_mode(k))` returns `false` on the
/// "no encapsulation" outcome (`spec.encapsulates == None`, e.g., a
/// greenfield Process that declined the encapsulation surface entirely)
/// AND on the "encapsulation set but the probed axis doesn't match"
/// outcome. The lifted [`Self::has_mode`] projection returns `false` on
/// the "no encapsulation" outcome and delegates to the inner
/// [`EncapsulatesSpec::has_mode`] on the "encapsulation set" outcome —
/// observationally equivalent to the pre-lift chain at every callsite.
/// Symmetric shape for [`Self::has_target`] over the nested
/// [`EncapsulationKind`] tagged-union probe.
///
/// # Peer to [`crate::lifetime::Lifetime::ephemeral_exports`]
///
/// Both lifts collapse an Option-carrier at ONE substrate site so
/// downstream presence probes on the same nested carrier compose
/// through a uniform shape. `ephemeral_exports` returns `&[ExportSpec]`
/// (empty slice on the collapsed arm; slice methods return `false` on
/// empty via `.iter().any(...)`); this trait returns `bool` directly
/// because the two probes on `EncapsulatesSpec` are not slice-shaped
/// (a scalar-carrier equality and a tagged-union `.has()`). Both bind
/// their respective require-tag families' probes to a `spec.<field>
/// .<probe>(k)` shape without an `.as_ref().is_some_and(...)` chain at
/// the callsite.
///
/// # Compounding
///
/// A future third closed-set-driven presence probe reaching through
/// `spec.encapsulates` (a hypothetical `SubmodeKind` scalar on
/// [`EncapsulatesSpec`], a `HandoffPhase` closed-set on a new nested
/// carrier, a further tagged-union discriminator on
/// [`EncapsulationKind`]) lands as ONE more method on this trait +
/// ONE more `if let Some(res) = strip_and_classify_prefixed_kind::<K,
/// _>(tag, "prefix-", |k| spec.encapsulates.<new-probe>(k)) { return
/// res; }` branch in the require-tag classifier's prefix table — no
/// per-caller `.as_ref().is_some_and(...)` restatement, no per-caller
/// `spec.encapsulates.as_ref()` walk. A future diagnostic shift on the
/// Option-carrier collapse (surfacing "encapsulation declined" as a
/// distinct near-miss from "encapsulation set but axis absent") lands
/// at THIS ONE substrate owner and every current + future require-tag
/// family inherits the shift by construction.
///
/// Theory anchor: THEORY.md §II.1 invariant 5 (composition preserves
/// proofs — the Option-carrier collapse lives at ONE substrate site so
/// every downstream `encapsulation-<axis>` require-tag family binds
/// through the SAME shape). THEORY.md §VI.1 (generation over
/// composition — a new probe on `EncapsulatesSpec` reaches this trait
/// through a peer method without a bespoke Option-arm at the caller).
///
/// Pinned by
/// [`tests::encapsulates_option_ext_has_mode_returns_false_on_none_for_every_kind`],
/// [`tests::encapsulates_option_ext_has_mode_matches_inner_probe_when_present`],
/// [`tests::encapsulates_option_ext_has_target_returns_false_on_none_for_every_target`],
/// and
/// [`tests::encapsulates_option_ext_has_target_matches_inner_kind_probe_when_present`].
pub trait EncapsulatesSpecOptionExt {
    /// True iff this `Option<EncapsulatesSpec>` is `Some(e)` AND
    /// [`EncapsulatesSpec::has_mode`] on the inner spec answers `true`
    /// for the given [`EncapsulationMode`]. Returns `false` on `None`
    /// (a greenfield Process that declined encapsulation entirely) —
    /// including for the default [`EncapsulationMode::Manage`],
    /// because the operator DECLINED the encapsulation surface rather
    /// than defaulting into it.
    fn has_mode(&self, kind: EncapsulationMode) -> bool;

    /// True iff this `Option<EncapsulatesSpec>` is `Some(e)` AND the
    /// inner [`EncapsulatesSpec::kind`] tagged union carries a
    /// populated slot addressed by the given [`EncapsulationTarget`].
    /// Returns `false` on `None`.
    fn has_target(&self, kind: EncapsulationTarget) -> bool;
}

impl EncapsulatesSpecOptionExt for Option<EncapsulatesSpec> {
    fn has_mode(&self, kind: EncapsulationMode) -> bool {
        self.as_ref().is_some_and(|e| e.has_mode(kind))
    }

    fn has_target(&self, kind: EncapsulationTarget) -> bool {
        self.as_ref().is_some_and(|e| e.kind.has(kind))
    }
}

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

    fn demo_adopt() -> EncapsulatesSpec {
        EncapsulatesSpec {
            kind: EncapsulationKind {
                existing_helm_release: Some(ExistingHelmRelease {
                    namespace: "demo-ns".into(),
                    name: "demo-app".into(),
                    release_name: "demo-app-consolidated".into(),
                }),
                ..EncapsulationKind::default()
            },
            mode: EncapsulationMode::Adopt,
        }
    }

    #[test]
    fn kind_empty_errors() {
        let k = EncapsulationKind::default();
        assert_eq!(
            k.variant().unwrap_err(),
            EncapsulationKindError::Empty(ENCAPSULATION_TARGET_LIST)
        );
    }

    #[test]
    fn kind_existing_hr_resolves() {
        let s = demo_adopt();
        match s.kind.variant().unwrap() {
            EncapsulationKindVariant::ExistingHelmRelease(h) => {
                assert_eq!(h.namespace, "demo-ns");
                assert_eq!(h.release_name, "demo-app-consolidated");
            }
            other => panic!("expected ExistingHelmRelease, got {other:?}"),
        }
    }

    #[test]
    fn kind_two_variants_ambiguous() {
        let k = EncapsulationKind {
            existing_helm_release: Some(ExistingHelmRelease {
                namespace: "ns".into(),
                name: "n".into(),
                release_name: "r".into(),
            }),
            existing_kustomization: Some(ExistingKustomization {
                namespace: "ns".into(),
                name: "n".into(),
            }),
            ..EncapsulationKind::default()
        };
        assert_eq!(k.variant().unwrap_err(), EncapsulationKindError::Ambiguous);
    }

    #[test]
    fn mode_dispatch() {
        assert!(EncapsulationMode::Manage.emits_workload());
        assert!(EncapsulationMode::Adopt.emits_workload());
        assert!(!EncapsulationMode::Observe.emits_workload());

        assert!(!EncapsulationMode::Manage.preserves_release_name());
        assert!(EncapsulationMode::Adopt.preserves_release_name());
        assert!(!EncapsulationMode::Observe.preserves_release_name());
    }

    #[test]
    fn mode_default_is_manage() {
        assert_eq!(EncapsulationMode::default(), EncapsulationMode::Manage);
    }

    // ── scalar-carrier presence probe on EncapsulatesSpec × EncapsulationMode ─
    //
    // Fail-before-pass-after granularity: [`EncapsulatesSpec::has_mode`]
    // did not exist before this commit — every consumer of the
    // `(EncapsulatesSpec, EncapsulationMode) -> bool` scalar-carrier
    // probe shape restated the `encapsulates.mode == kind` closure body
    // at its own callsite. Post-lift the shape lives at ONE substrate
    // owner and every downstream (the `encapsulation-mode-<kind>`
    // require-tag family in `tatara-check`, future audit dispatchers
    // walking [`EncapsulationMode::ALL`], any future CRD-facing closed-
    // set discriminator on a scalar `EncapsulatesSpec` field) binds
    // through the SAME `has(kind)` shape the Option-slot (Intent::has,
    // Lifetime::has), slice-level (ConditionSliceExt::has_kind,
    // DependsOnSliceExt::has_must_reach, ComplianceBindingSliceExt::
    // has_verification_phase, ExportSpecSliceExt::{has_when,
    // has_channel_kind, has_report_format, has_artifact_kind}) and
    // sister scalar-carrier ([`crate::spec::SignalPolicy::has_sighup_strategy`])
    // primitives publish.

    /// DIAGONAL — for every [`EncapsulationMode`] variant, an
    /// [`EncapsulatesSpec`] whose `mode` field is set to that variant
    /// returns `true` from `has_mode` on that same variant AND `false`
    /// on every other variant. Sweep the [`EncapsulationMode::ALL`] ×
    /// ALL cross so a regression that hard-coded the arm to a single
    /// variant (silently returning `true` on every populated spec
    /// regardless of query kind) or wired the equality to a fixed
    /// unrelated field (a stray probe on `kind` — the tagged-union
    /// carrier — instead of `mode`) fails HERE at the substrate
    /// primitive before landing at the operator-facing checks.lisp
    /// surface.
    #[test]
    fn encapsulates_spec_has_mode_returns_true_iff_variant_matches() {
        for populated in EncapsulationMode::ALL {
            let spec = EncapsulatesSpec {
                kind: EncapsulationKind::default(),
                mode: populated,
            };
            for query in EncapsulationMode::ALL {
                assert_eq!(
                    spec.has_mode(query),
                    query == populated,
                    "mode={populated:?}: query {query:?} classification drifted",
                );
            }
        }
    }

    /// DEFAULT — an [`EncapsulatesSpec`] constructed with the
    /// [`EncapsulationMode::default`] variant carries
    /// `mode: EncapsulationMode::Manage`, so the scalar-carrier probe
    /// returns `true` on [`EncapsulationMode::Manage`] and `false` on
    /// every other variant. Symmetric to the
    /// [`crate::spec::SignalPolicy::has_sighup_strategy`] default pin —
    /// both scalar-carrier peers publish the SAME "default is a
    /// legitimate operator answer" contract at the substrate boundary,
    /// distinct from the Option-slot axis where a default carrier
    /// returns `false` for EVERY kind.
    #[test]
    fn encapsulates_spec_has_mode_default_probes_manage_only() {
        let spec = EncapsulatesSpec {
            kind: EncapsulationKind::default(),
            mode: EncapsulationMode::default(),
        };
        for kind in EncapsulationMode::ALL {
            let expected = kind == EncapsulationMode::Manage;
            assert_eq!(
                spec.has_mode(kind),
                expected,
                "default spec (mode=Manage) must return {expected} for {kind:?}",
            );
        }
    }

    // ── closed-set algebra for EncapsulationMode (ALL × as_str ×
    //    Display × FromStr × emits_workload × preserves_release_name) ─

    /// Structural well-formedness of [`EncapsulationMode`] 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 `mode_all_is_unique_and_complete` +
    /// `mode_roundtrip_via_as_str` + the empty-input arm of
    /// `unknown_encapsulation_mode_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 `mode` value back to the typed mode.
    #[test]
    fn mode_is_well_formed_closed_set() {
        tatara_closed_set::assert_closed_set_well_formed::<EncapsulationMode>();
    }

    /// 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, instead of
    /// drifting between the typed surface and the YAML wire format
    /// the reconciler / operator both read.
    #[test]
    fn mode_as_str_matches_serde() {
        crate::tagged_union::assert_label_matches_serde_serialization::<EncapsulationMode>();
    }

    /// The Display impl IS `as_str` — pinning this lets future callers
    /// reach for either projection without drift. If a reviewer
    /// accidentally re-introduces an inline match in Display, this
    /// test would fail the moment a variant rename touches one site
    /// but not the other.
    #[test]
    fn mode_display_matches_as_str() {
        crate::tagged_union::assert_display_matches_label::<EncapsulationMode>();
    }

    /// `FromStr` rejects strings that aren't in 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
    /// [`mode_is_well_formed_closed_set`] via the
    /// `tatara_lisp::ClosedSet` testkit; the cases here pin the
    /// verbatim-echo contract on the [`UnknownEncapsulationMode`]
    /// newtype, which the trait's `make_unknown` can't see.
    #[test]
    fn unknown_encapsulation_mode_errors() {
        use std::str::FromStr;
        for bad in ["manage", "ADOPT", "Observed", "Wrap"] {
            let err = EncapsulationMode::from_str(bad).unwrap_err();
            assert_eq!(err.0, bad, "error payload should echo input verbatim");
        }
    }

    /// TRUTH-TABLE CONTRACT: `emits_workload` / `preserves_release_name`
    /// agree with the documented (mode) -> (bool, bool) table for every
    /// variant. A new variant in `EncapsulationMode` without extending
    /// either projection's match is caught by the compiler (closed-set
    /// match in each method); adding a variant without extending its
    /// truth row is caught here.
    #[test]
    fn mode_projection_truth_table() {
        let table: &[(EncapsulationMode, bool, bool)] = &[
            // (mode, emits_workload, preserves_release_name)
            (EncapsulationMode::Manage, true, false),
            (EncapsulationMode::Adopt, true, true),
            (EncapsulationMode::Observe, false, false),
        ];
        assert_eq!(table.len(), EncapsulationMode::ALL.len());
        for (mode, emits, preserves) in table {
            assert_eq!(
                mode.emits_workload(),
                *emits,
                "emits_workload drift for {mode:?}"
            );
            assert_eq!(
                mode.preserves_release_name(),
                *preserves,
                "preserves_release_name drift for {mode:?}"
            );
        }
    }

    /// DRIFT-PROOF CONTRACT: the hand-rolled
    /// `mode == EncapsulationMode::Observe` and
    /// `mode == EncapsulationMode::Adopt` checks the reconciler's
    /// `render` function used pre-lift agree with the typed
    /// projections for every variant in `ALL`. A regression that
    /// re-introduces a raw `==` against a variant name fails here:
    /// `!emits_workload()` IS "Observe mode" and
    /// `preserves_release_name()` IS "Adopt mode", expressed as a
    /// property of the typed surface rather than a pattern fragment
    /// two crates have to keep coherent.
    #[test]
    fn mode_typed_projections_replace_raw_equality() {
        for mode in EncapsulationMode::ALL {
            assert_eq!(
                !mode.emits_workload(),
                mode == EncapsulationMode::Observe,
                "!emits_workload() drift for {mode:?}"
            );
            assert_eq!(
                mode.preserves_release_name(),
                mode == EncapsulationMode::Adopt,
                "preserves_release_name() drift for {mode:?}"
            );
        }
    }

    #[test]
    fn serde_round_trip_via_yaml() {
        let s = demo_adopt();
        let yaml = serde_yaml::to_string(&s).unwrap();
        assert!(yaml.contains("existingHelmRelease:"));
        assert!(yaml.contains("releaseName: demo-app-consolidated"));
        assert!(yaml.contains("mode: Adopt"));
        let back: EncapsulatesSpec = serde_yaml::from_str(&yaml).unwrap();
        assert!(back.kind.existing_helm_release.is_some());
        assert_eq!(back.mode, EncapsulationMode::Adopt);
    }

    #[test]
    fn bare_workload_selector_round_trips() {
        let mut sel = BTreeMap::new();
        sel.insert("app".into(), "demo-app".into());
        sel.insert("tier".into(), "prod".into());
        let s = EncapsulatesSpec {
            kind: EncapsulationKind {
                bare_workload: Some(BareWorkload {
                    namespace: "legacy".into(),
                    selector: sel,
                }),
                ..EncapsulationKind::default()
            },
            mode: EncapsulationMode::Observe,
        };
        let yaml = serde_yaml::to_string(&s).unwrap();
        assert!(yaml.contains("bareWorkload:"));
        assert!(yaml.contains("app: demo-app"));
        assert!(yaml.contains("mode: Observe"));
        let back: EncapsulatesSpec = serde_yaml::from_str(&yaml).unwrap();
        match back.kind.variant().unwrap() {
            EncapsulationKindVariant::BareWorkload(b) => {
                assert_eq!(b.selector.len(), 2);
                assert_eq!(b.selector.get("app").map(String::as_str), Some("demo-app"));
            }
            other => panic!("expected BareWorkload, got {other:?}"),
        }
    }

    #[test]
    fn lisp_round_trip_existing_hr() {
        let src = r#"
            (defencapsulates demo-adopt
              :kind (:existing-helm-release
                     (:namespace    "demo-ns"
                      :name         "demo-app"
                      :release-name "demo-app-consolidated"))
              :mode Adopt)
        "#;
        let defs: Vec<tatara_lisp::NamedDefinition<EncapsulatesSpec>> =
            tatara_lisp::compile_named::<EncapsulatesSpec>(src).expect("compile");
        let d = &defs[0];
        assert_eq!(d.name, "demo-adopt");
        assert_eq!(d.spec.mode, EncapsulationMode::Adopt);
        let h = d.spec.kind.existing_helm_release.as_ref().unwrap();
        assert_eq!(h.namespace, "demo-ns");
        assert_eq!(h.release_name, "demo-app-consolidated");
    }

    #[test]
    fn lisp_default_mode_is_manage() {
        // `:mode` omitted ⇒ Manage (Default derive).
        let src = r#"
            (defencapsulates greenfield
              :kind (:existing-kustomization
                     (:namespace "flux-system"
                      :name      "openclaw")))
        "#;
        let defs: Vec<tatara_lisp::NamedDefinition<EncapsulatesSpec>> =
            tatara_lisp::compile_named::<EncapsulatesSpec>(src).expect("compile");
        let d = &defs[0];
        assert_eq!(d.spec.mode, EncapsulationMode::Manage);
    }

    // ── closed-set algebra for EncapsulationTarget (ALL × as_str ×
    //    Display × FromStr × select × EncapsulationKindVariant::target) ─

    /// Construct an `EncapsulationKind` with one slot populated — the
    /// composable construction table the closed-set property tests
    /// loop over. Mirrors `single_slot_source` in
    /// [`crate::export`] in shape.
    fn single_slot_kind(target: EncapsulationTarget) -> EncapsulationKind {
        match target {
            EncapsulationTarget::ExistingHelmRelease => EncapsulationKind {
                existing_helm_release: Some(ExistingHelmRelease {
                    namespace: "ns".into(),
                    name: "hr".into(),
                    release_name: "rel".into(),
                }),
                ..EncapsulationKind::default()
            },
            EncapsulationTarget::ExistingKustomization => EncapsulationKind {
                existing_kustomization: Some(ExistingKustomization {
                    namespace: "ns".into(),
                    name: "ks".into(),
                }),
                ..EncapsulationKind::default()
            },
            EncapsulationTarget::BareWorkload => {
                let mut sel = BTreeMap::new();
                sel.insert("app".into(), "x".into());
                EncapsulationKind {
                    bare_workload: Some(BareWorkload {
                        namespace: "ns".into(),
                        selector: sel,
                    }),
                    ..EncapsulationKind::default()
                }
            }
        }
    }

    /// Construct an `EncapsulationKind` with two slots populated — drives
    /// the pairwise `Ambiguous` sweep. Composes the single-slot
    /// constructor on top of itself to keep one source of truth for
    /// per-variant inner payloads.
    fn two_slot_kind(a: EncapsulationTarget, b: EncapsulationTarget) -> EncapsulationKind {
        let ka = single_slot_kind(a);
        let kb = single_slot_kind(b);
        EncapsulationKind {
            existing_helm_release: ka.existing_helm_release.or(kb.existing_helm_release),
            existing_kustomization: ka.existing_kustomization.or(kb.existing_kustomization),
            bare_workload: ka.bare_workload.or(kb.bare_workload),
        }
    }

    /// Structural well-formedness of [`EncapsulationTarget`] 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 `encapsulation_target_all_is_unique_and_complete` +
    /// `encapsulation_target_roundtrip_via_as_str` + the empty-input
    /// arm of `unknown_encapsulation_target_errors`. `FromStr`
    /// delegates to `<Self as tatara_closed_set::ClosedSet>::parse_label`, so
    /// this helper exercises the same code path the
    /// `EncapsulationKind::variant` resolver hits when keying on a
    /// camelCase target name back to the typed target.
    #[test]
    fn encapsulation_target_is_well_formed_closed_set() {
        tatara_closed_set::assert_closed_set_well_formed::<EncapsulationTarget>();
    }

    /// CANONICAL-KEY CONTRACT: every `EncapsulationTarget::as_str()`
    /// matches the serde `rename_all = "camelCase"` field name on the
    /// corresponding `Option<…>` slot of `EncapsulationKind`. A future
    /// rename of either the struct field OR the `as_str` arm lands here
    /// at one site, instead of drifting between the typed surface, the
    /// wire format, and the `EncapsulationKindError::Empty` diagnostic.
    ///
    /// Routes through the substrate primitive
    /// [`crate::tagged_union::assert_single_slot_key_matches_label`],
    /// which pins the exactly-one-key + name-equality projection
    /// byte-identically for every `<T: TaggedUnion + Serialize>`
    /// implementor — the wire-alignment testkit shared with the sibling
    /// `intent_kind_as_str_matches_intent_field_name` /
    /// `artifact_kind_as_str_matches_field_name` /
    /// `channel_kind_as_str_matches_field_name` sites. Pre-lift this
    /// site restated a weaker YAML-substring check (`yaml.contains(&format!("{key}:"))`)
    /// which would silently pass on drift where a non-tagged-union
    /// field was added to `EncapsulationKind`; post-lift the primitive's
    /// JSON exactly-one form catches that drift too — at ONE substrate
    /// site.
    #[test]
    fn encapsulation_target_as_str_matches_field_name() {
        crate::tagged_union::assert_single_slot_key_matches_label::<EncapsulationKind, _>(
            single_slot_kind,
        );
    }

    /// CANONICAL-NAMES PIN: byte-exact camelCase wire-format pin —
    /// renaming any of these strings IS a wire-format break that fails
    /// this test FIRST so the rename stays a deliberate decision, not a
    /// typo. Locks the (variant → operator-facing key) table.
    #[test]
    fn encapsulation_target_canonical_names_pinned() {
        assert_eq!(
            EncapsulationTarget::ExistingHelmRelease.as_str(),
            "existingHelmRelease"
        );
        assert_eq!(
            EncapsulationTarget::ExistingKustomization.as_str(),
            "existingKustomization"
        );
        assert_eq!(EncapsulationTarget::BareWorkload.as_str(), "bareWorkload");
    }

    /// The Display impl IS `as_str` — pinning this lets future callers
    /// reach for either projection without drift. If a reviewer
    /// accidentally re-introduces an inline match in Display, this test
    /// would fail the moment a variant rename touches one site but not
    /// the other.
    #[test]
    fn encapsulation_target_display_matches_as_str() {
        crate::tagged_union::assert_display_matches_label::<EncapsulationTarget>();
    }

    /// `FromStr` rejects strings that aren't in the canonical projection
    /// — PascalCased / typo / cross-axis-leaked inputs from sibling
    /// closed-set enums on the same `ProcessSpec` axis (`Manage`,
    /// `Adopt`, `Observe`, `OnAttested`, …) — and the error echoes the
    /// input verbatim so the operator-facing diagnostic carries the
    /// offending value, not a normalized form. `EncapsulationTarget`
    /// is its own axis, NOT a transparent reflection of any sibling.
    /// The empty-input arm is pinned by
    /// [`encapsulation_target_is_well_formed_closed_set`] via the
    /// `tatara_lisp::ClosedSet` testkit; the cases here pin the
    /// verbatim-echo contract on the [`UnknownEncapsulationTarget`]
    /// newtype, which the trait's `make_unknown` can't see.
    #[test]
    fn unknown_encapsulation_target_errors() {
        use std::str::FromStr;
        for bad in [
            "ExistingHelmRelease",
            "existing_helm_release",
            "EXISTINGHELMRELEASE",
            "helmRelease",
            "kustomization",
            "Manage",
            "Adopt",
            "Observe",
            "OnAttested",
        ] {
            let err = EncapsulationTarget::from_str(bad).unwrap_err();
            assert_eq!(err.0, bad, "error payload should echo input verbatim");
        }
    }

    /// ROUND-TRIP CONTRACT: every target reaches its borrowed-variant
    /// view via `select`, and that variant projects back to the same
    /// target via `EncapsulationKindVariant::target`. A regression that
    /// misroutes a `select` arm (e.g.
    /// `Self::ExistingHelmRelease => kind.existing_kustomization
    /// .as_ref()...`) fails loudly here. Also pins that the resolver
    /// lands on the same target.
    ///
    /// Routes through the substrate primitive
    /// [`crate::tagged_union::assert_variant_round_trip`] shared with
    /// the sibling `intent_kind_round_trips_through_variant_kind` /
    /// `artifact_kind_round_trips_through_variant_kind` /
    /// `channel_kind_round_trips_through_variant_kind` sites — the
    /// projection lives at ONE substrate primitive and every site
    /// binds through a single call. The `target()` inherent method
    /// (semantic-specific to `EncapsulationTarget`) stays load-bearing
    /// on the callsite convention while the trait projection carries
    /// the round-trip check uniformly.
    #[test]
    fn encapsulation_target_round_trips_through_variant_target() {
        crate::tagged_union::assert_variant_round_trip::<EncapsulationKind, _>(single_slot_kind);
    }

    /// SELECT-EMPTY CONTRACT: an unpopulated slot returns `None` from
    /// `select`, for every target. Pairs with the resolver's `Empty`
    /// path so a future target's slot defaulting wrong (e.g.
    /// accidentally `Some(Default::default())` instead of `None`) is
    /// caught here.
    #[test]
    fn encapsulation_target_select_returns_none_for_unset_slot() {
        let empty = EncapsulationKind::default();
        for t in EncapsulationTarget::ALL {
            assert!(
                t.select(&empty).is_none(),
                "{t:?} reported populated on a default EncapsulationKind"
            );
        }
    }

    /// EMPTY-DIAGNOSTIC CONTRACT: the closed-set target list embedded
    /// in `EncapsulationKindError::Empty` echoes the canonical join of
    /// every `EncapsulationTarget::as_str()` projection. A variant
    /// added without updating `ENCAPSULATION_TARGET_LIST` (or a renamed
    /// variant) shows up here as a mismatch. Routes through the
    /// substrate primitive
    /// [`crate::tagged_union::assert_kind_list_matches_closed_set`]
    /// shared with the sibling `intent_error_empty_lists_every_kind_in_canonical_order`
    /// / `artifact_error_empty_lists_every_kind_in_canonical_order`
    /// / `channel_error_empty_lists_every_kind_in_canonical_order`
    /// sites — the projection lives at ONE substrate primitive and
    /// every site binds through a single call. The paired assertion
    /// that the diagnostic reaches operator-facing output verbatim
    /// stays local because the empty-arm construction differs per
    /// carrier.
    #[test]
    fn encapsulation_kind_error_empty_lists_every_target_in_canonical_order() {
        crate::tagged_union::assert_kind_list_matches_closed_set::<EncapsulationKind>();
        // And the diagnostic carries that exact list.
        let err = EncapsulationKind::default().variant().unwrap_err();
        assert_eq!(
            err,
            EncapsulationKindError::Empty(ENCAPSULATION_TARGET_LIST)
        );
    }

    /// AMBIGUOUS-PATH CONTRACT: when two slots are populated the
    /// resolver yields `Ambiguous`, exhaustively across every pair in
    /// `ALL × ALL` (excluding the diagonal). A future asymmetry where
    /// one slot would silently shadow another (e.g. an `if-let` chain
    /// re-introducing first-wins ordering) is caught here. Routes
    /// through the substrate primitive
    /// [`crate::tagged_union::assert_two_slots_ambiguous`] shared with
    /// the sibling `artifact_source_two_slots_is_ambiguous_across_every_pair`
    /// / `vector_channel_two_slots_is_ambiguous_across_every_pair`
    /// / `intent_two_slots_is_ambiguous_across_every_pair` sites — the
    /// nested-`for a in K::ALL { for b in K::ALL { … } }` sweep lives
    /// at ONE substrate site.
    #[test]
    fn encapsulation_kind_two_slots_is_ambiguous_across_every_pair() {
        crate::tagged_union::assert_two_slots_ambiguous::<EncapsulationKind, _>(two_slot_kind);
    }

    // ── EncapsulatesSpecOptionExt — Option-carrier collapse contract ──

    /// COLLAPSED-NONE CONTRACT (mode axis): a `None` outer Option
    /// carries no encapsulation surface, so
    /// [`EncapsulatesSpecOptionExt::has_mode`] returns `false` for
    /// every [`EncapsulationMode`] — INCLUDING the substrate default
    /// [`EncapsulationMode::Manage`]. An operator who declined the
    /// encapsulation surface entirely is NOT configured for `Manage`;
    /// the default only fires when the parent Option is `Some(_)` and
    /// the inner `mode` slot is unset. Pre-lift the require-tag
    /// classifier restated `spec.encapsulates.as_ref().is_some_and(|e|
    /// e.has_mode(k))` inline; post-lift the collapse is a peer to
    /// [`crate::lifetime::Lifetime::ephemeral_exports`] (both own the
    /// Option-carrier arm at ONE substrate site).
    #[test]
    fn encapsulates_option_ext_has_mode_returns_false_on_none_for_every_kind() {
        let opt: Option<EncapsulatesSpec> = None;
        for m in EncapsulationMode::ALL {
            assert!(
                !opt.has_mode(m),
                "None carrier reported has_mode({m:?}) = true; \
                 the Option-carrier collapse arm must return false \
                 for every EncapsulationMode kind, including the \
                 substrate default"
            );
        }
    }

    /// DELEGATED-SOME CONTRACT (mode axis): a `Some(e)` outer Option
    /// forwards to [`EncapsulatesSpec::has_mode`] byte-identically.
    /// This test pins that the extension trait's projection on the
    /// populated arm equals the inner-spec probe's answer for every
    /// [`EncapsulationMode`] kind on a spec whose `mode` slot is set
    /// to a specific variant — so the collapse-arm's `false` on `None`
    /// is the ONLY behavioral change introduced by the lift.
    #[test]
    fn encapsulates_option_ext_has_mode_matches_inner_probe_when_present() {
        for set_mode in EncapsulationMode::ALL {
            let inner = EncapsulatesSpec {
                kind: single_slot_kind(EncapsulationTarget::ExistingHelmRelease),
                mode: set_mode,
            };
            let opt: Option<EncapsulatesSpec> = Some(inner.clone());
            for probe in EncapsulationMode::ALL {
                assert_eq!(
                    opt.has_mode(probe),
                    inner.has_mode(probe),
                    "Some-arm projection diverged from inner probe: \
                     set_mode={set_mode:?} probe={probe:?}"
                );
            }
        }
    }

    /// COLLAPSED-NONE CONTRACT (target axis): a `None` outer Option
    /// carries no encapsulation surface, so
    /// [`EncapsulatesSpecOptionExt::has_target`] returns `false` for
    /// every [`EncapsulationTarget`]. Symmetric to the mode-axis
    /// collapse; the two axes route through the SAME Option-carrier
    /// arm so this test AND the mode-axis peer must both stay `false`
    /// on `None` — a regression that leaked `true` on one axis would
    /// diverge the two require-tag families' truth tables.
    #[test]
    fn encapsulates_option_ext_has_target_returns_false_on_none_for_every_target() {
        let opt: Option<EncapsulatesSpec> = None;
        for t in EncapsulationTarget::ALL {
            assert!(
                !opt.has_target(t),
                "None carrier reported has_target({t:?}) = true; \
                 the Option-carrier collapse arm must return false \
                 for every EncapsulationTarget"
            );
        }
    }

    /// DELEGATED-SOME CONTRACT (target axis): a `Some(e)` outer Option
    /// forwards to the inner
    /// [`crate::tagged_union::TaggedUnion::has`] presence probe over
    /// [`EncapsulatesSpec::kind`] byte-identically. Pins that populated
    /// slots answer `true` on their own target and `false` on the
    /// other two — the `select`-populated arm of the closed-set sweep
    /// is what the collapsed-`Some` path delegates to.
    #[test]
    fn encapsulates_option_ext_has_target_matches_inner_kind_probe_when_present() {
        for set_target in EncapsulationTarget::ALL {
            let inner = EncapsulatesSpec {
                kind: single_slot_kind(set_target),
                mode: EncapsulationMode::default(),
            };
            let opt: Option<EncapsulatesSpec> = Some(inner.clone());
            for probe in EncapsulationTarget::ALL {
                let expected = probe == set_target;
                assert_eq!(
                    opt.has_target(probe),
                    expected,
                    "Some-arm target projection wrong: \
                     set_target={set_target:?} probe={probe:?}"
                );
                assert_eq!(
                    opt.has_target(probe),
                    inner.kind.has(probe),
                    "Some-arm target projection diverged from inner \
                     tagged-union probe: set_target={set_target:?} \
                     probe={probe:?}"
                );
            }
        }
    }

    // Per-implementor `unknown_X_message_matches_substrate_convention`
    // tests removed — clause (5) of
    // `tatara_closed_set::assert_closed_set_well_formed::<T>()` now verifies
    // the substrate-wide `"unknown {SET_LABEL}: {input}"` carrier shape
    // generically (called above on `EncapsulationTarget` /
    // `EncapsulationMode` through their `*_is_well_formed_closed_set`
    // sites). The `SET_LABEL` projection is pinned independently by
    // `tatara_lisp_derive::pascal_to_spaced_lowercase_tests` —
    // together the two contracts guarantee the operator-facing
    // diagnostic without needing per-enum literal pins.
}