grafos_core/

policy_vocab.rs

//! Cross-phase shared vocabulary for phases 218–222.
//!
//! This module is the home for typed surfaces that are referenced by
//! multiple phases: preemption reasons (218), audit event kinds and
//! evidence labels (219), and workload identity (220). It exists so
//! that the five upstream phases compose a single layered story
//! rather than each forking its own enum.
//!
//! ## What lives here
//!
//! - `PreemptionReason` — Phase 218's typed enum for "why was this
//!   work preempted." Used by scheduler admission, audit emit, runtime
//!   events, and the DRA driver's typed failure path.
//! - `EvidenceLabel` — Phase 219's evidence-label vocabulary, reused
//!   without translation by Phase 220 assurance posture, Phase 221
//!   HCL status, and Phase 222 DRA claim provenance. The same docs
//!   lint enforces all four.
//! - `AuditEventKind` — Phase 219's typed audit event names. The set
//!   here is intentionally minimal at slice 1; new variants land
//!   alongside the code paths that emit them.
//! - `WorkloadIdentity` — Phase 220's canonical workload-identity
//!   tuple. Single shape across scheduler, audit, attestation,
//!   Kubernetes/DRA. No phase invents a parallel record.
//!
//! ## What does NOT live here
//!
//! - Anything that `fabricbios-core` would import. These types are
//!   policy vocabulary; they MUST NOT cross the TCB boundary into
//!   `fabricbios-core`. A CI guard at `scripts/check-fabricbios-core-tcb.sh`
//!   asserts this structurally by reading the manifest.
//! - Implementation logic. This file is types and small helpers
//!   (Display, FromStr) only. Emit code, validation, persistence,
//!   docs lint — all elsewhere.
//! - Phase-internal records. Per-phase concrete records (admission
//!   record, audit-chain entry, HCL row) live in their owning crate
//!   and embed these vocabulary types as fields.

use core::fmt;

// ---------------------------------------------------------------------------
// Phase 218 — PreemptionReason
// ---------------------------------------------------------------------------

/// Typed reasons for which an admission was rejected or an existing
/// lease was preempted. Phase 218 enumerates these up front so the
/// admission, audit, and DRA layers all agree on the vocabulary.
///
/// The reason MUST be present on every preemption emit. There is no
/// `Other(String)` variant on purpose: a generic kill path is exactly
/// what the typed-lifecycle rule rejects.
///
/// New reasons require a design-doc update plus a typed regression
/// test that asserts the reason fires in the case it names. Adding
/// a reason is a vocabulary change, not a runtime config knob.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum PreemptionReason {
    /// Higher-priority admitted work is allowed to reclaim resources
    /// from lower-priority preemptible work.
    #[cfg_attr(feature = "serde", serde(alias = "PriorityPreemption"))]
    PriorityPreemption,
    /// Tenant or project usage must be moved back inside its configured
    /// fair-share/quota envelope. Distinct from `BurstCreditExhausted`:
    /// a `QuotaRebalance` typically admitted a different tenant.
    #[cfg_attr(feature = "serde", serde(alias = "QuotaRebalance"))]
    QuotaRebalance,
    /// The tenant's token-bucket burst credit reached zero while the
    /// request required burst capacity beyond hard quota. No other
    /// tenant was admitted; the workload was rejected for exceeding
    /// its own configured burst envelope.
    #[cfg_attr(feature = "serde", serde(alias = "BurstCreditExhausted"))]
    BurstCreditExhausted,
    /// Tenant budget or spend policy is exhausted and the work is
    /// configured as preemptible on budget exhaustion.
    #[cfg_attr(feature = "serde", serde(alias = "BudgetExhausted"))]
    BudgetExhausted,
    /// Phase 216 economics policy requires eviction because a hard
    /// cost cap can no longer be satisfied.
    #[cfg_attr(feature = "serde", serde(alias = "CostCapEviction"))]
    CostCapEviction,
    /// An operator initiated node/cell drain.
    #[cfg_attr(feature = "serde", serde(alias = "OperatorDrain"))]
    OperatorDrain,
    /// An operator initiated GPU MIG profile recompose. Shared with
    /// Phase 221 dynamic MIG profile recompose so audit logs
    /// distinguish operator-driven GPU repartitioning from ordinary
    /// priority preemption.
    #[cfg_attr(feature = "serde", serde(alias = "OperatorMigProfileChange"))]
    OperatorMigProfileChange,
    /// A scheduled maintenance policy requires the resource to be
    /// cleared.
    #[cfg_attr(feature = "serde", serde(alias = "MaintenanceWindow"))]
    MaintenanceWindow,
    /// The system detected a previously admitted lease no longer
    /// satisfies a mandatory policy and must fail closed or recover.
    /// Emit MUST carry a typed `policy_id` naming the violated policy
    /// — emit without policy_id is a typed error, not a string default.
    #[cfg_attr(feature = "serde", serde(alias = "PolicyViolationRecovery"))]
    PolicyViolationRecovery,
}

impl PreemptionReason {
    /// Stable wire / log identifier. Used by audit emit, DRA failure
    /// types, and Phase 219 docs lint. MUST be stable across minor
    /// versions: external collectors group on this string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::PriorityPreemption => "priority_preemption",
            Self::QuotaRebalance => "quota_rebalance",
            Self::BurstCreditExhausted => "burst_credit_exhausted",
            Self::BudgetExhausted => "budget_exhausted",
            Self::CostCapEviction => "cost_cap_eviction",
            Self::OperatorDrain => "operator_drain",
            Self::OperatorMigProfileChange => "operator_mig_profile_change",
            Self::MaintenanceWindow => "maintenance_window",
            Self::PolicyViolationRecovery => "policy_violation_recovery",
        }
    }

    /// Tooltip-grade operator-readable phrase for this preemption
    /// reason. Mirrors the [`RejectionReason::human_summary`] shape
    /// so dashboard / CLI surfaces can render typed preemption
    /// reasons without re-deriving the prose.
    ///
    /// `as_str()` remains the wire-format-grade snake_case label
    /// SIEM rules and audit collectors group on; `human_summary()`
    /// is the rendering helper. They are NOT interchangeable.
    ///
    /// The string is intentionally short (one line, no terminal
    /// punctuation) so a renderer can compose it inline. The
    /// runbook at `docs/runbooks/preemption-explanations.md` is
    /// the long-form operator-action prose; this helper is the
    /// tooltip-grade sibling.
    ///
    /// Slice 73 lands the helper without dashboard wiring — there
    /// is no preemption panel yet. When that surface lands it
    /// can read this method directly.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::PriorityPreemption => "reclaimed for higher-priority work that outranked it",
            Self::QuotaRebalance => {
                "reclaimed because tenant fair-share moved a different tenant in"
            }
            Self::BurstCreditExhausted => {
                "reclaimed because the tenant's burst-bucket envelope was exceeded"
            }
            Self::BudgetExhausted => "reclaimed because the tenant's spend budget was exhausted",
            Self::CostCapEviction => {
                "reclaimed because the global cost cap could no longer be satisfied"
            }
            Self::OperatorDrain => "reclaimed because an operator drained the host node",
            Self::OperatorMigProfileChange => {
                "reclaimed because an operator recomposed the GPU MIG profile"
            }
            Self::MaintenanceWindow => "reclaimed by a scheduled maintenance window",
            Self::PolicyViolationRecovery => {
                "reclaimed because the workload no longer satisfied a mandatory policy"
            }
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 218.2 — Priority (slice 85)
// ---------------------------------------------------------------------------

/// Phase 218.2 — Scheduling priority class for a tenant's workloads.
///
/// Three classes that compose with the rest of the typed policy
/// vocabulary. Ordering is `Guaranteed > Standard > Scavenger`;
/// discriminants are arranged so the derived `Ord` yields this
/// ordering directly. Slice 85 relocated this enum from
/// `grafos-scheduler::tenant` to `grafos-core::policy_vocab`
/// alongside the other cross-crate typed surfaces (`PreemptionReason`,
/// `RejectionReason`, `FairShareWindow`, `EvidenceLabel`,
/// `AuditEventKind`, `WorkloadIdentity`) so every consumer agrees on
/// the same shape and the same docs-lint discipline applies.
///
/// `as_str()` is the wire-format-grade snake_case label (SIEM rules,
/// dashboard panel JSONPath selectors, audit-chain markers all alert
/// off this exact string). `human_summary()` is the operator-readable
/// rendering string used by CLI status pages and dashboard tooltips.
/// They are NOT interchangeable surfaces.
///
/// Adding a variant is wire-compatibility-grade — coordinate with
/// whoever owns the SIEM rules + a coordinated docs/tests/rules
/// update. Renaming a label is forbidden once shipped.
///
/// Historical: was renamed from `BestEffort` to `Standard` in Phase
/// 48.5 hygiene to avoid confusion with `CpuIsolationClass::BestEffort`
/// (an orthogonal per-lease CPU isolation policy).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum Priority {
    /// Lowest priority — preempted first.
    #[cfg_attr(feature = "serde", serde(alias = "Scavenger"))]
    Scavenger = 0,
    /// Uses unreserved capacity, preemptible by guaranteed work.
    #[cfg_attr(feature = "serde", serde(alias = "Standard"))]
    Standard = 1,
    /// Reserved capacity, never preempted by ordinary scheduling.
    #[cfg_attr(feature = "serde", serde(alias = "Guaranteed"))]
    Guaranteed = 2,
}

impl Priority {
    /// Stable wire / log identifier (snake_case). Wire-format-grade —
    /// SIEM rules, dashboard panel selectors, and audit-chain markers
    /// all alert off this exact string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Scavenger => "scavenger",
            Self::Standard => "standard",
            Self::Guaranteed => "guaranteed",
        }
    }

    /// Operator-readable one-line summary. Distinct surface from
    /// `as_str()`: this is what a CLI status page or dashboard
    /// tooltip renders so an operator can read the priority class
    /// without consulting documentation. Not localized, not
    /// terminated with punctuation, intentionally short so a
    /// renderer can compose it inline.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::Scavenger => "uses leftover capacity; preempted first when contention rises",
            Self::Standard => "uses unreserved capacity; preemptible by guaranteed work",
            Self::Guaranteed => "reserved capacity; never preempted by ordinary scheduling",
        }
    }
}

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

impl PartialOrd for Priority {
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Priority {
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        (*self as u8).cmp(&(*other as u8))
    }
}

/// Phase 218.2 slice 87 — typed parse error returned by
/// `Priority::from_str` for an unrecognized label. The carried
/// `String` is the offending input so the surface (clap value
/// parser, dashboard label table, scheduler request validator)
/// can echo it back to the operator without losing the original
/// spelling. The error message lists the canonical set so a
/// typo at the CLI fails closed at parse time with operator
/// guidance instead of silently propagating a free-form
/// `priority` string downstream.
///
/// SIEM rules and audit emit alert off `Priority::as_str()`
/// values; a `--priority bogus` invocation that quietly fell
/// through to the wire would shift those rules into the typed
/// vocabulary without operator intent. Fail-closed at the CLI
/// arg-parsing layer is the discipline boundary.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ParsePriorityError(pub String);

impl fmt::Display for ParsePriorityError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid priority {:?} — valid values: scavenger | standard | guaranteed",
            self.0
        )
    }
}

impl std::error::Error for ParsePriorityError {}

impl core::str::FromStr for Priority {
    type Err = ParsePriorityError;

    /// Parse a snake_case priority label.
    ///
    /// Accepted labels:
    /// - `scavenger` → [`Priority::Scavenger`]
    /// - `standard` → [`Priority::Standard`]
    /// - `guaranteed` → [`Priority::Guaranteed`]
    /// - `best_effort` → [`Priority::Standard`] (deprecation alias)
    ///
    /// ## Deprecation alias rationale
    ///
    /// The Phase 48.5 hygiene rename (`BestEffort -> Standard`)
    /// avoided a name collision with the orthogonal
    /// `CpuIsolationClass::BestEffort` per-lease policy. The
    /// CLI surfaces (`grafos deploy run --priority …`,
    /// `cloud/doctor.rs` probe, `run.rs` lease body) and the
    /// dashboard JS label table never received the rename;
    /// they still emit and accept `best_effort`. Slice 87 lands
    /// the CLI/dashboard typed migration but the migration
    /// window is real — operators have CLI invocations,
    /// shell scripts, and dashboard cookies in flight that pass
    /// `best_effort`.
    ///
    /// We pick fail-closed-with-a-named-alias rather than
    /// silently accept any free-form string: unknown labels
    /// (`bogus`, `besteffort`, `Best Effort`) return a typed
    /// error naming the canonical set; only the one named
    /// historical spelling is accepted.
    ///
    /// Retiring the alias (typed error on `best_effort`
    /// instead of `Standard`) is tracked as a separate sub-bullet
    /// in TODO.md Phase 218.2; the migration must complete first.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "scavenger" => Ok(Self::Scavenger),
            "standard" => Ok(Self::Standard),
            "guaranteed" => Ok(Self::Guaranteed),
            // Deprecation alias — see method docs.
            "best_effort" => Ok(Self::Standard),
            _ => Err(ParsePriorityError(s.to_string())),
        }
    }
}

// ---------------------------------------------------------------------------
// Phase 219 — EvidenceLabel
// ---------------------------------------------------------------------------

/// Evidence labels classify the strength of a public claim. Phase 219
/// defines these; Phase 220 (assurance posture), Phase 221 (HCL status),
/// and Phase 222 (DRA claim provenance) reuse them unchanged. The same
/// docs lint enforces all four.
///
/// A claim may not carry a stronger label than its backing artifact.
/// The lint executes in CI: any public docs page using a label
/// stronger than `DesignTarget` must link to a named artifact, report,
/// test, or drill record. Phase 221 HCL labels reuse this enum
/// directly; an HCL row at `LabSupported` is the same kind of evidence
/// as a public docs claim labeled `LabEvidence`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum EvidenceLabel {
    /// Intended architecture; not yet implemented.
    #[cfg_attr(feature = "serde", serde(alias = "DesignTarget"))]
    DesignTarget,
    /// Local deterministic tests (unit/integration).
    #[cfg_attr(feature = "serde", serde(alias = "UnitIntegrationEvidence"))]
    UnitIntegrationEvidence,
    /// Validated in our local lab environment with a recorded artifact.
    #[cfg_attr(feature = "serde", serde(alias = "LabEvidence"))]
    LabEvidence,
    /// Validated in a real cloud or provider cell drill with a captured
    /// artifact.
    #[cfg_attr(feature = "serde", serde(alias = "StagedProviderEvidence"))]
    StagedProviderEvidence,
    /// Measured in a partner environment, anonymized as agreed.
    #[cfg_attr(feature = "serde", serde(alias = "DesignPartnerEvidence"))]
    DesignPartnerEvidence,
    /// Measured in production with a customer support process.
    #[cfg_attr(feature = "serde", serde(alias = "ProductionEvidence"))]
    ProductionEvidence,
}

impl EvidenceLabel {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::DesignTarget => "design target",
            Self::UnitIntegrationEvidence => "unit/integration evidence",
            Self::LabEvidence => "lab evidence",
            Self::StagedProviderEvidence => "staged provider evidence",
            Self::DesignPartnerEvidence => "design-partner evidence",
            Self::ProductionEvidence => "production evidence",
        }
    }

    /// True when the label requires a backing artifact under the
    /// Phase 219 docs-lint rule. `DesignTarget` does not (it's
    /// roadmap); everything stronger does.
    pub fn requires_artifact(self) -> bool {
        !matches!(self, Self::DesignTarget)
    }
}

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

// ---------------------------------------------------------------------------
// Phase 219.2 — RejectionReason
// ---------------------------------------------------------------------------

/// Typed vocabulary for admission / placement / preemption-victim-selection
/// rejection reasons surfaced through operator-facing explanation APIs
/// (CLI, dashboard JSON, audit-chain marker labels).
///
/// Design constraints (from Phase 219 cross-phase invariants and the
/// Phase 219.2 standardize-explanation-fields task):
///
///   - Each variant maps to a stable snake_case label via
///     [`RejectionReason::as_str`]. The label appears verbatim in the
///     audit-chain `instance_id` markers (see slice 26's
///     `admission_denied_reason_label`) AND in the JSON of operator-
///     facing endpoints. SIEM rules and dashboard panels alert off
///     these labels.
///   - Adding a variant is wire-compatibility-grade — a SIEM rule
///     keying off the label must keep matching, so a rename is a
///     coordinated change requiring docs and rules updates.
///   - Removing a variant is forbidden once the label has shipped.
///   - Free-form `reason: String` rejection paths are NOT replaced
///     wholesale; the typed reason lands alongside the human-readable
///     string so operators see both. The wire contract is: the typed
///     reason is the load-bearing API field; the prose is for human
///     consumption.
///
/// Coverage matches the rejection paths surfaced by
/// `grafos_scheduler::AdmissionDenied` (slice 26) and
/// `grafos_scheduler::QuotaDenied`. Adding new failure modes requires
/// a new variant rather than a new free-form string.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum RejectionReason {
    /// Free pool has insufficient bytes across all eligible nodes.
    /// Maps to `AdmissionDenied::InsufficientCapacity`.
    #[cfg_attr(feature = "serde", serde(alias = "InsufficientCapacity"))]
    InsufficientCapacity,
    /// Placement constraint matches no node (the constraint excluded
    /// every fenced/healthy/non-fenced candidate). Maps to
    /// `AdmissionDenied::NoEligibleNodes`.
    #[cfg_attr(feature = "serde", serde(alias = "NoEligibleNodes"))]
    NoEligibleNodes,
    /// Hard quota cap reached for the tenant. Maps to
    /// `QuotaDenied::HardLimitExceeded`.
    #[cfg_attr(feature = "serde", serde(alias = "QuotaHardLimitExceeded"))]
    QuotaHardLimitExceeded,
    /// Burst quota cap reached for the tenant (the soft limit allows
    /// bursting up to the burst cap; this fires when the burst cap is
    /// also reached). Maps to `QuotaDenied::BurstExceeded`.
    #[cfg_attr(feature = "serde", serde(alias = "QuotaBurstExceeded"))]
    QuotaBurstExceeded,
    /// Per-tenant lease count limit reached. Maps to
    /// `QuotaDenied::LeaseCountExceeded`.
    #[cfg_attr(feature = "serde", serde(alias = "QuotaLeaseCountExceeded"))]
    QuotaLeaseCountExceeded,
    /// Per-tenant per-node capacity limit reached. Maps to
    /// `QuotaDenied::PerNodeLimitExceeded`.
    #[cfg_attr(feature = "serde", serde(alias = "QuotaPerNodeLimitExceeded"))]
    QuotaPerNodeLimitExceeded,
    /// Tenant id not registered in the tenant store. Maps to
    /// `QuotaDenied::TenantNotFound` and to the early-exit branch of
    /// `AdmissionGate::check_admission` when the gate's TenantStore
    /// lookup fails.
    #[cfg_attr(feature = "serde", serde(alias = "TenantNotFound"))]
    TenantNotFound,
    /// Selected node is fenced for the requested resource type. Maps
    /// to `AdmissionDenied::NodeFenced`.
    #[cfg_attr(feature = "serde", serde(alias = "NodeFenced"))]
    NodeFenced,
    /// Power / cost budget cap exceeded. Maps to
    /// `AdmissionDenied::BudgetDenied`.
    #[cfg_attr(feature = "serde", serde(alias = "BudgetExhausted"))]
    BudgetExhausted,
    /// Reservation found but does not have enough remaining capacity.
    /// Maps to `AdmissionDenied::ReservationExhausted`.
    #[cfg_attr(feature = "serde", serde(alias = "ReservationExhausted"))]
    ReservationExhausted,
    /// Phase 219.2 slice 36 — placement layer rejected this
    /// candidate by policy (top-level placement authorization,
    /// active-degradation set exclusion, or explicit `Pinned`
    /// strategy mismatch). The prose `reasons` field on the
    /// `NodePlacementCandidateExplanation` carries the specific
    /// sub-reason for human consumption; the typed enum is the
    /// SIEM-rule / dashboard-panel hook that fires on any
    /// policy-driven exclusion.
    #[cfg_attr(feature = "serde", serde(alias = "PlacementPolicyExcluded"))]
    PlacementPolicyExcluded,
    /// Phase 219.2 slice 36 — the scheduler does not have a
    /// control-plane address for the node, so a candidate that
    /// would otherwise have been considered cannot be reached.
    /// Operational state, not a policy decision; SIEM should
    /// alert on this distinct from policy exclusions.
    #[cfg_attr(feature = "serde", serde(alias = "NodeAddressUnknown"))]
    NodeAddressUnknown,
    /// Target node was drained by the operator via
    /// `/api/v1/admin/manage-node`. The node sits in a
    /// non-admitting drain/maintenance mode (`Draining`,
    /// `Drained`, `Maintenance`, `Returning`, or `FenceLost`) and
    /// `filter_schedulable_nodes` excludes it from new workload
    /// admission. Distinct from `NodeFenced` (a real fence-epoch
    /// transition under fence-epoch authority) — `NodeDrained` is
    /// operator-initiated maintenance, and admission resumes only
    /// after the node returns to `Accepting` mode. Distinct from
    /// `NoEligibleNodes` (no node fits the placement
    /// constraint) — `NodeDrained` is a cause-erasure-free
    /// label so operators reading the audit chain or running
    /// `grafos admissions --reason node_drained` see the
    /// drain-skipped path as its own line item.
    #[cfg_attr(feature = "serde", serde(alias = "NodeDrained"))]
    NodeDrained,
    /// Phase 218.5 slice 118 — bundle admission request had zero
    /// requirements. Mirrors `BundleAdmissionFailure::EmptyBundle`
    /// on the flat admissions query surface.
    #[cfg_attr(feature = "serde", serde(alias = "EmptyBundle"))]
    EmptyBundle,
    /// Phase 218.5 slice 118 — at least one requirement in a
    /// bundle could not be satisfied with available capacity.
    #[cfg_attr(feature = "serde", serde(alias = "InsufficientBundleCapacity"))]
    InsufficientBundleCapacity,
    /// Phase 218.5 slice 118 — bundle-level placement constraints
    /// excluded every viable fan-out or colocated plan.
    #[cfg_attr(feature = "serde", serde(alias = "BundleConstraintViolation"))]
    BundleConstraintViolation,
    /// Phase 218.5 slice 118 — requested hardware generation had
    /// no matching inventory.
    #[cfg_attr(feature = "serde", serde(alias = "HardwareGenerationUnavailable"))]
    HardwareGenerationUnavailable,
    /// Phase 218.5 slice 118 — closed-vocabulary catch-all for
    /// bundle admission failures not yet split into a more specific
    /// rejection reason.
    #[cfg_attr(feature = "serde", serde(alias = "OtherBundleFailure"))]
    OtherBundleFailure,
}

impl RejectionReason {
    /// Stable snake_case label. Wire-format-grade — SIEM rules,
    /// dashboard panel JSONPath selectors, and audit-chain
    /// `instance_id` markers all alert off this exact string. Pinned
    /// per-variant in the `rejection_reason_labels_are_stable` test.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::InsufficientCapacity => "insufficient_capacity",
            Self::NoEligibleNodes => "no_eligible_nodes",
            Self::QuotaHardLimitExceeded => "quota_hard_limit_exceeded",
            Self::QuotaBurstExceeded => "quota_burst_exceeded",
            Self::QuotaLeaseCountExceeded => "quota_lease_count_exceeded",
            Self::QuotaPerNodeLimitExceeded => "quota_per_node_limit_exceeded",
            Self::TenantNotFound => "tenant_not_found",
            Self::NodeFenced => "node_fenced",
            Self::BudgetExhausted => "budget_exhausted",
            Self::ReservationExhausted => "reservation_exhausted",
            Self::PlacementPolicyExcluded => "placement_policy_excluded",
            Self::NodeAddressUnknown => "node_address_unknown",
            Self::NodeDrained => "node_drained",
            Self::EmptyBundle => "empty_bundle",
            Self::InsufficientBundleCapacity => "insufficient_bundle_capacity",
            Self::BundleConstraintViolation => "bundle_constraint_violation",
            Self::HardwareGenerationUnavailable => "hardware_generation_unavailable",
            Self::OtherBundleFailure => "other_bundle_failure",
        }
    }

    /// Phase 219.2 slice 37 — operator-friendly prose for one
    /// rejection. CLI status pages, dashboard panels, and the
    /// `grafos admissions`/`grafos placements` rendering paths
    /// (forthcoming) consume this so each surface presents the
    /// same prose for the same typed reason — no per-surface
    /// drift.
    ///
    /// The string is intentionally short (one line, no
    /// punctuation at the end) so a renderer can compose it
    /// inline: `"{} (at {})"`, `"reason={}, requested={}"`, etc.
    /// Operator-readable but not user-localized; localization
    /// is a future concern handled by the consuming surface.
    ///
    /// `as_str()` remains the wire-format-grade label SIEM
    /// rules alert off; `human_summary()` is the rendering
    /// helper. They are NOT interchangeable.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::InsufficientCapacity => "insufficient free capacity across all eligible nodes",
            Self::NoEligibleNodes => "no nodes match the placement constraint",
            Self::QuotaHardLimitExceeded => "tenant quota hard limit reached",
            Self::QuotaBurstExceeded => "tenant burst quota cap reached",
            Self::QuotaLeaseCountExceeded => "tenant lease count limit reached",
            Self::QuotaPerNodeLimitExceeded => "tenant per-node capacity limit reached",
            Self::TenantNotFound => "tenant id not registered with the scheduler",
            Self::NodeFenced => "selected node is fenced for the requested resource type",
            Self::BudgetExhausted => "power or cost budget cap reached",
            Self::ReservationExhausted => "reservation has insufficient remaining capacity",
            Self::PlacementPolicyExcluded => "placement policy excluded this candidate",
            Self::NodeAddressUnknown => {
                "scheduler does not have a control-plane address for this node"
            }
            Self::NodeDrained => {
                "target node is drained for maintenance; admission resumes after the node returns to accepting mode"
            }
            Self::EmptyBundle => "bundle had zero requirements; nothing to admit",
            Self::InsufficientBundleCapacity => {
                "insufficient capacity for at least one bundle requirement"
            }
            Self::BundleConstraintViolation => {
                "bundle placement constraint excludes every viable candidate plan"
            }
            Self::HardwareGenerationUnavailable => {
                "requested bundle hardware generation has no matching inventory"
            }
            Self::OtherBundleFailure => "other bundle admission failure",
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 220.2 — Egress enforcement vocabulary
// ---------------------------------------------------------------------------

/// Typed classification of the enforcement boundary that
/// applies to a tasklet/program target's outbound network
/// access.
///
/// Phase 220.2 design rule: the scheduler MUST classify each
/// target with one of these labels so it does not advertise a
/// mode as fabric-enforced when the runtime cannot observe the
/// outbound path. See the egress matrix in
/// [`docs/design/220-security-trust-egress-assurance.md`](../../../docs/design/220-security-trust-egress-assurance.md).
///
/// SIEM rules and dashboard panels alert off the snake_case
/// label from `as_str()`. Adding a variant is wire-compatibility-
/// grade — coordinate with whoever owns the SIEM rules.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum EgressEnforcement {
    /// fabricBIOS / its runtime fully owns the path. Deny-all
    /// is enforceable in the runtime and audit events for
    /// denied attempts can be emitted. Today: wasm tasklets
    /// under the wasmi executor, which has no ambient network
    /// surface.
    #[cfg_attr(feature = "serde", serde(alias = "FabricEnforced"))]
    FabricEnforced,
    /// A host integration point (kernel module, eBPF program,
    /// systemd network policy, DPU NIC) enforces egress on
    /// behalf of the fabric. The fabric supplies policy; the
    /// host enforces. Audit events flow through the
    /// integration's own logging path.
    #[cfg_attr(feature = "serde", serde(alias = "HostRuntimeIntegration"))]
    HostRuntimeIntegration,
    /// The operator's external network policy enforces egress
    /// — the fabric does not own this path. Today: native
    /// host processes, container-adjacent workloads,
    /// Kubernetes/DRA workloads. Operators run iptables /
    /// eBPF / CNI / NetworkPolicy outside the fabric.
    #[cfg_attr(feature = "serde", serde(alias = "OperatorControlled"))]
    OperatorControlled,
    /// Egress enforcement is not currently available for this
    /// target on any deployment. Distinct from
    /// `OperatorControlled` (which has a clear external
    /// enforcement story) — this label means "we have nothing
    /// today, period". A scheduler must refuse to admit a
    /// workload that requires fabric-enforced egress against
    /// an `Unsupported` target.
    #[cfg_attr(feature = "serde", serde(alias = "Unsupported"))]
    Unsupported,
}

impl EgressEnforcement {
    /// Stable snake_case label. Wire-format-grade — SIEM
    /// rules, dashboard panel JSONPath selectors, and operator
    /// CLI tools alert off this exact string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::FabricEnforced => "fabric_enforced",
            Self::HostRuntimeIntegration => "host_runtime_integration",
            Self::OperatorControlled => "operator_controlled",
            Self::Unsupported => "unsupported",
        }
    }
}

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

/// Typed target classes for tasklet / program runtime
/// environments. Each variant maps to exactly one
/// `EgressEnforcement` class today via
/// [`EgressTarget::enforcement`]; that mapping is the
/// canonical policy table the scheduler consults.
///
/// The set is intentionally narrow — adding a target requires
/// committing its enforcement class in the same change. A
/// scheduler that synthesizes a target name without going
/// through this enum can drift away from the matrix.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum EgressTarget {
    /// wasm tasklet running in a wasmi executor. No ambient
    /// network surface; deny-all is enforced by absence.
    #[cfg_attr(feature = "serde", serde(alias = "WasmTasklet"))]
    WasmTasklet,
    /// Native host process — `grafos-jobs`, `grafos-posix`,
    /// or any code running outside a wasm sandbox. The host
    /// kernel owns the network stack.
    #[cfg_attr(feature = "serde", serde(alias = "NativeProgram"))]
    NativeProgram,
    /// Container-adjacent workload (e.g. a sidecar process
    /// running in the same network namespace as a tenant
    /// container). Container runtime owns the network.
    #[cfg_attr(feature = "serde", serde(alias = "ContainerAdjacent"))]
    ContainerAdjacent,
    /// Kubernetes / DRA workload. The Kubernetes
    /// NetworkPolicy / Cilium / Calico stack owns egress.
    /// The DRA driver records workload identity for audit
    /// but does not enforce egress.
    #[cfg_attr(feature = "serde", serde(alias = "KubernetesDra"))]
    KubernetesDra,
    /// Bare-metal target. Where the firmware owns the NIC,
    /// fabric enforcement is possible; where the host kernel
    /// owns the NIC, it falls back to operator control. The
    /// HCL entry per node names which path applies.
    #[cfg_attr(feature = "serde", serde(alias = "BareMetal"))]
    BareMetal,
}

impl EgressTarget {
    /// Stable snake_case label.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::WasmTasklet => "wasm_tasklet",
            Self::NativeProgram => "native_program",
            Self::ContainerAdjacent => "container_adjacent",
            Self::KubernetesDra => "kubernetes_dra",
            Self::BareMetal => "bare_metal",
        }
    }

    /// Canonical enforcement class for this target per the
    /// Phase 220.2 design-doc matrix. The scheduler MUST use
    /// this function rather than constructing
    /// `EgressEnforcement` values directly so the matrix
    /// stays the single source of truth.
    ///
    /// Bare-metal returns `HostRuntimeIntegration` as the
    /// canonical class — when the firmware owns the NIC the
    /// fabric supplies policy and the firmware enforces;
    /// where the host kernel owns the NIC, the per-HCL entry
    /// can override to `OperatorControlled` at a higher
    /// layer. The HCL override is Phase 221 work; this enum
    /// commits the design-doc default.
    pub fn enforcement(self) -> EgressEnforcement {
        match self {
            Self::WasmTasklet => EgressEnforcement::FabricEnforced,
            Self::NativeProgram => EgressEnforcement::OperatorControlled,
            Self::ContainerAdjacent => EgressEnforcement::OperatorControlled,
            Self::KubernetesDra => EgressEnforcement::OperatorControlled,
            Self::BareMetal => EgressEnforcement::HostRuntimeIntegration,
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 216 — Economics observation vocabulary
// ---------------------------------------------------------------------------

/// Provenance class for an economics observation (cost,
/// energy, carbon, egress weight, latency). The scheduler
/// uses the source to decide what confidence to apply and
/// whether the observation is fresh enough for a required
/// admission decision.
///
/// Spec context:
/// [`docs/design/216-cost-carbon-aware-placement.md`](../../../docs/design/216-cost-carbon-aware-placement.md)
/// "Authority and Freshness" section.
///
/// Adding a variant is wire-compatibility-grade —
/// scheduler-side admission rules may filter on source
/// strings, and committed economics-generation records
/// store the source.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum EconomicsSource {
    /// Operator-supplied configuration (rate cards, regional
    /// carbon defaults). Authoritative for admission
    /// estimates within the operator's deployment.
    #[cfg_attr(feature = "serde", serde(alias = "OperatorStaticConfig"))]
    OperatorStaticConfig,
    /// Cloud provider's price sheet (AWS pricing API, GCP
    /// SKU catalog, Azure rate card). Authoritative when
    /// the operator authorizes its use.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderPriceSheet"))]
    ProviderPriceSheet,
    /// Provider's actual usage / billing export
    /// (CloudTrail/billing CSV equivalents). Higher
    /// confidence than the price sheet because it reflects
    /// realized cost, not list price.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderUsageExport"))]
    ProviderUsageExport,
    /// Power telemetry measured at the node or accelerator.
    /// Highest-confidence source for energy values when
    /// available.
    #[cfg_attr(feature = "serde", serde(alias = "MeasuredPowerTelemetry"))]
    MeasuredPowerTelemetry,
    /// Third-party carbon-intensity feed authorized by the
    /// operator (e.g. WattTime, ElectricityMaps).
    #[cfg_attr(feature = "serde", serde(alias = "ThirdPartyCarbonFeed"))]
    ThirdPartyCarbonFeed,
    /// Estimate computed from other sources (e.g. carbon =
    /// energy × regional intensity). Lowest-confidence
    /// source by default.
    #[cfg_attr(feature = "serde", serde(alias = "DerivedEstimate"))]
    DerivedEstimate,
}

impl EconomicsSource {
    /// Stable snake_case label.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::OperatorStaticConfig => "operator_static_config",
            Self::ProviderPriceSheet => "provider_price_sheet",
            Self::ProviderUsageExport => "provider_usage_export",
            Self::MeasuredPowerTelemetry => "measured_power_telemetry",
            Self::ThirdPartyCarbonFeed => "third_party_carbon_feed",
            Self::DerivedEstimate => "derived_estimate",
        }
    }
}

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

/// Confidence band for an economics observation. The
/// scheduler's `EconomicConstraints::min_confidence` field
/// uses this to filter observations that fall below a
/// tenant-required floor.
///
/// Bands are ordinal — `Low < Medium < High`. The
/// `PartialOrd` / `Ord` derives make filter queries like
/// `obs.confidence >= constraints.min_confidence` work
/// directly.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum ObservationConfidence {
    /// Low confidence — derived estimate, stale data, or
    /// minimal corroboration. Acceptable for non-required
    /// preferences (PreferLowerCost, PreferLowerCarbon) but
    /// rejected for required admission caps.
    #[cfg_attr(feature = "serde", serde(alias = "Low"))]
    Low,
    /// Medium confidence — operator-authorized provider
    /// price sheet, third-party feed within freshness
    /// window. The default floor for tenant-policy required
    /// economics decisions unless explicitly overridden.
    #[cfg_attr(feature = "serde", serde(alias = "Medium"))]
    Medium,
    /// High confidence — measured telemetry or provider
    /// usage export. Required for `production evidence`
    /// utilization claims and for tenants explicitly
    /// requesting `min_confidence = High`.
    #[cfg_attr(feature = "serde", serde(alias = "High"))]
    High,
}

impl ObservationConfidence {
    /// Stable snake_case label.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Low => "low",
            Self::Medium => "medium",
            Self::High => "high",
        }
    }
}

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

/// Monotonic generation counter for committed economics
/// views. Phase 216 design rule: this is a FRESHNESS
/// counter, not an authority epoch. It identifies WHICH
/// version of the rate cards / carbon feeds / egress
/// weights was used for a placement decision so admission
/// records and post-run accounting can be reproduced.
///
/// It does NOT gate writes, fence resources, or substitute
/// for the Phase 215 fence-epoch check. Phase 215's
/// epoch/generation vocabulary names fence epoch as the
/// only counter that gates write authority.
///
/// Wraparound is not a real concern: a u64 incremented
/// once per economics commit lasts longer than the universe.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct EconomicsGeneration(pub u64);

impl EconomicsGeneration {
    /// The unanchored sentinel — a scheduler that has not
    /// yet committed any economics view starts here.
    pub const UNANCHORED: Self = Self(0);

    /// Next generation. `next()` is the canonical
    /// monotonic-step API; the scheduler MUST NOT add a
    /// constant or jump generations to make a view "look
    /// fresher."
    pub fn next(self) -> Self {
        Self(self.0.saturating_add(1))
    }
}

impl fmt::Display for EconomicsGeneration {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "gen={}", self.0)
    }
}

/// Phase 216 slice 59 — typed envelope for any economics
/// observation. Carries the value plus the provenance,
/// confidence, freshness window, and generation the scheduler
/// uses for required-decision admission rules.
///
/// Generic over the value type `T` so the eventual concrete
/// observations (domain rate cards, carbon intensity, energy
/// vectors, egress weights) can fit without new envelope
/// types. The envelope is what the scheduler stores; the
/// inner value is what's measured.
///
/// `observed_at` and `valid_until` are unix seconds (u64),
/// matching the audit-chain `timestamp_unix` convention so
/// observations and audit records are correlatable on time.
///
/// Phase 216 design rule: a scheduler that requires a
/// specific economics input for an admission decision MUST
/// reject when the observation is missing, stale (now >=
/// `valid_until`), or below the tenant's
/// `min_confidence` floor. The scheduler MUST NOT silently
/// substitute a default.
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct EconomicsObservation<T> {
    pub value: T,
    pub source: EconomicsSource,
    pub confidence: ObservationConfidence,
    /// Unix seconds at which the underlying measurement was
    /// taken (or — for static config — committed).
    pub observed_at: u64,
    /// Unix seconds at which this observation expires. The
    /// scheduler MUST treat `now >= valid_until` as stale and
    /// fail closed for required decisions.
    pub valid_until: u64,
    pub generation: EconomicsGeneration,
}

impl<T> EconomicsObservation<T> {
    /// True when `now` falls within the observation's
    /// freshness window: `observed_at <= now < valid_until`.
    /// `observed_at == now` is fresh; `now == valid_until`
    /// is stale (boundary is exclusive on the upper end).
    pub fn is_fresh(&self, now: u64) -> bool {
        self.observed_at <= now && now < self.valid_until
    }

    /// True when the observation's confidence band is at or
    /// above `min`. Uses the slice-53 ordinal contract on
    /// `ObservationConfidence`.
    pub fn meets_floor(&self, min: ObservationConfidence) -> bool {
        self.confidence >= min
    }

    /// True when the observation is acceptable for a required
    /// admission decision: fresh AND meets the confidence
    /// floor. Convenience for the common scheduler-side check.
    pub fn admissible(&self, now: u64, min: ObservationConfidence) -> bool {
        self.is_fresh(now) && self.meets_floor(min)
    }
}

/// Phase 218 — typed fair-share window descriptor for tenants,
/// projects, and priority classes. Carries the window length,
/// the dimensionless priority-class weight, and the lower /
/// upper resource-second bounds the scheduler will eventually
/// enforce over a rolling window.
///
/// This landing is vocabulary-only — a docs target. There is
/// no scheduler integration today; the production wiring
/// (capacity-ledger window accounting, admission-side weight
/// resolution, eviction selection on share overshoot) lands in
/// a follow-on slice. Pinning the typed shape first lets the
/// scheduler, audit, and dashboard layers compose against a
/// single record rather than each forking their own envelope.
///
/// `priority_class_weight` is dimensionless. Operator policy
/// decides what `100` means relative to `50`: it could be
/// proportional fair share, lexicographic priority, or any
/// other interpretation the scheduler chooses at compute time.
/// The value is just the typed input; the policy layer does
/// the conversion to a share fraction.
///
/// `min_share_secs` and `max_share_secs` are resource-seconds
/// over the rolling `window_secs`. `min_share_secs` is the
/// guaranteed floor (the tenant cannot fall below this when
/// it has work pending); `max_share_secs` is the ceiling per
/// window (the tenant cannot consume above this even if the
/// fabric is idle).
///
/// `generation` is the slice-53 [`EconomicsGeneration`]
/// committed-config freshness counter — it identifies WHICH
/// version of the fair-share table was used when an admission
/// decision was made so admission records and post-run
/// accounting can be reproduced. Per the same Phase 218 design
/// rule that gates [`EconomicsGeneration`], this is NOT an
/// authority epoch: the scheduler MUST NOT gate writes on the
/// share number or the generation. Write authority is gated
/// by the Phase 215 fence epoch and nothing else.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct FairShareWindow {
    /// Tenant identifier the window applies to.
    pub tenant_id: u128,
    /// Dimensionless priority-class weight. The scheduler
    /// converts this to a share fraction at compute time;
    /// operator policy decides what the relative magnitudes
    /// mean. MUST be > 0; a zero weight is rejected by
    /// [`Self::is_valid`].
    pub priority_class_weight: u32,
    /// Rolling window length in seconds. MUST be > 0; a zero
    /// window is rejected by [`Self::is_valid`].
    pub window_secs: u64,
    /// Lower bound: minimum guaranteed share over the window
    /// in resource-seconds.
    pub min_share_secs: u64,
    /// Upper bound: ceiling per window in resource-seconds.
    /// MUST be >= `min_share_secs`.
    pub max_share_secs: u64,
    /// Committed-config freshness counter — which version of
    /// the fair-share table this descriptor came from. Not an
    /// authority epoch; see the type-level doc comment.
    pub generation: EconomicsGeneration,
}

impl FairShareWindow {
    /// Returns true iff the descriptor is internally
    /// consistent: `min_share_secs <= max_share_secs`,
    /// `priority_class_weight > 0`, and `window_secs > 0`.
    /// Returns false for any violation. Callers handle the
    /// typed reject — this never panics, matching the
    /// fail-closed-without-panic discipline used elsewhere in
    /// this module.
    pub fn is_valid(&self) -> bool {
        self.min_share_secs <= self.max_share_secs
            && self.priority_class_weight > 0
            && self.window_secs > 0
    }
}

/// Scope that participates in fair-share accounting.
///
/// Phase 218.1 needs the scheduler to reason about shares at three
/// levels without conflating them: a tenant, a project within a
/// tenant, or a priority class. The scope is policy vocabulary only;
/// it does not grant authority and it must not cross into
/// `fabricbios-core`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum FairShareScope {
    /// Share for all work owned by a tenant.
    #[cfg_attr(feature = "serde", serde(alias = "Tenant"))]
    Tenant { tenant_id: u128 },
    /// Share for a project or account namespace within a tenant.
    #[cfg_attr(feature = "serde", serde(alias = "Project"))]
    Project { project_id: u128 },
    /// Share for all work in a priority class.
    #[cfg_attr(feature = "serde", serde(alias = "PriorityClass"))]
    PriorityClass { priority: Priority },
}

impl FairShareScope {
    /// Stable scope-kind label. The identifiers inside the scope are
    /// fields, not part of this grouping label.
    pub fn kind(self) -> &'static str {
        match self {
            Self::Tenant { .. } => "tenant",
            Self::Project { .. } => "project",
            Self::PriorityClass { .. } => "priority_class",
        }
    }
}

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

/// Weighted fair-share entry for one scope.
///
/// `weight` is dimensionless and must be positive. `min_share_secs`
/// and `max_share_secs` are resource-seconds over the containing
/// [`WeightedFairSharePolicy::window_secs`] rolling window.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct FairShareWeight {
    pub scope: FairShareScope,
    pub weight: u32,
    pub min_share_secs: u64,
    pub max_share_secs: u64,
}

impl FairShareWeight {
    /// Returns true iff the entry is internally consistent.
    pub fn is_valid(&self) -> bool {
        self.weight > 0 && self.min_share_secs <= self.max_share_secs
    }
}

/// Committed fair-share table for a scheduler policy generation.
///
/// This is the typed input a scheduler can use to compute fair-share
/// ordering across tenants, projects, and priority classes. It is not
/// an admission decision by itself; admission code still evaluates
/// concrete usage, placement, quota, and preemption state.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct WeightedFairSharePolicy {
    /// Rolling accounting window in seconds.
    pub window_secs: u64,
    /// Committed-config freshness counter. Not an authority epoch.
    pub generation: EconomicsGeneration,
    /// One entry per fair-share scope. Duplicate scopes are invalid:
    /// callers must update a scope's single entry rather than relying
    /// on last-writer-wins behavior.
    pub entries: Vec<FairShareWeight>,
}

impl WeightedFairSharePolicy {
    /// Validate the table without panicking. Returns false when the
    /// policy has no entries, a zero window, an invalid entry, or a
    /// duplicate scope.
    pub fn is_valid(&self) -> bool {
        if self.window_secs == 0 || self.entries.is_empty() {
            return false;
        }
        for (idx, entry) in self.entries.iter().enumerate() {
            if !entry.is_valid() {
                return false;
            }
            if self.entries[..idx]
                .iter()
                .any(|prior| prior.scope == entry.scope)
            {
                return false;
            }
        }
        true
    }

    /// Sum of all positive weights. Invalid entries are deliberately
    /// ignored here; callers should check [`Self::is_valid`] before
    /// using the table for admission or preemption policy.
    pub fn total_weight(&self) -> u64 {
        self.entries
            .iter()
            .filter(|entry| entry.weight > 0)
            .map(|entry| u64::from(entry.weight))
            .sum()
    }
}

// ---------------------------------------------------------------------------
// Phase 218.3 — RevokeState (slice 86)
// ---------------------------------------------------------------------------

/// Phase 218.3 — Typed revoke lifecycle states.
///
/// A workload that holds a lease can observe the revoke transitions
/// described in `docs/design/218-tenant-policy-and-lifecycle.md`
/// § "Revoke State Machine". The 9 states form a deterministic
/// state machine: a lease enters via `Active`, optionally transits
/// through warning → grace → either cooperative checkpoint or
/// forced teardown, and lands in one of three terminal states
/// (`Torndown`, `Fenced`, `FailedClosed`) plus the TTL-driven
/// `Expired` (which itself is non-terminal — the spec routes
/// `expired -> failed-closed`).
///
/// A typed primitive in `policy_vocab` (not split across leasekit /
/// runtime / scheduler) so SIEM rules, audit emit, dashboard
/// renderers, and the operator-facing revoke runbook all use the
/// same vocabulary. Same discipline as Phase 218.2 `Priority` /
/// 219.2 `RejectionReason` / 219 `AuditEventKind`.
///
/// `as_str()` is the wire-format-grade snake_case label (SIEM rules,
/// dashboard panel JSONPath selectors, audit-chain markers all alert
/// off this exact string). `human_summary()` is the operator-readable
/// rendering string used by CLI status pages and dashboard tooltips.
/// They are NOT interchangeable surfaces.
///
/// `legal_transition_to(next)` pins the spec-allowed transition set.
/// Slice 86 does NOT wire this primitive into the existing revoke
/// pathway — that integration spans `grafos-leasekit`,
/// `grafos-runtime`, `grafos-scheduler-service`, and `fabricbiosd`
/// and is captured as TODO carry-overs. Slice 86 lands the typed
/// primitive + discipline methods + legal-transition pin only,
/// matching the slice-62 / slice-73 / slice-85 "land primitive,
/// defer integration" pattern.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum RevokeState {
    /// Pre-revoke normal state. Lease is active, no revoke pending.
    #[cfg_attr(feature = "serde", serde(alias = "Active"))]
    Active,
    /// Revoke initiated. Workload has been notified; grace timer started.
    #[cfg_attr(feature = "serde", serde(alias = "RevokeWarning"))]
    RevokeWarning,
    /// Grace period running. Workload has time to checkpoint
    /// cooperatively before forced teardown.
    #[cfg_attr(feature = "serde", serde(alias = "GraceRunning"))]
    GraceRunning,
    /// Workload reported checkpoint complete during grace. Cooperative
    /// teardown can proceed.
    #[cfg_attr(feature = "serde", serde(alias = "CheckpointReported"))]
    CheckpointReported,
    /// Forced teardown initiated. Reachable directly from `Active` for
    /// hard revokes (no grace) per the spec's
    /// `active -> forced-teardown -> torn-down` arrow.
    #[cfg_attr(feature = "serde", serde(alias = "ForcedTeardown"))]
    ForcedTeardown,
    /// Teardown completed successfully (cooperative or forced path).
    /// Terminal.
    #[cfg_attr(feature = "serde", serde(alias = "Torndown"))]
    Torndown,
    /// Lease TTL aged out without operator/tenant-initiated revoke.
    /// Distinct from `RevokeWarning`. Per the spec's
    /// `active -> expired -> failed-closed` arrow this is a
    /// transitional state, not a terminal one.
    #[cfg_attr(feature = "serde", serde(alias = "Expired"))]
    Expired,
    /// Teardown failed; resource is fenced. No further leases until
    /// operator forensic clearing. Terminal.
    #[cfg_attr(feature = "serde", serde(alias = "Fenced"))]
    Fenced,
    /// Explicit fail-closed terminal. Reachable from `Expired` per
    /// the spec, and from any non-terminal state when the state
    /// machine encounters an invariant violation (a transition the
    /// legal set rejects). Terminal.
    #[cfg_attr(feature = "serde", serde(alias = "FailedClosed"))]
    FailedClosed,
}

impl RevokeState {
    /// Stable wire / log identifier (snake_case). Wire-format-grade —
    /// SIEM rules, dashboard panel selectors, and audit-chain markers
    /// all alert off this exact string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Active => "active",
            Self::RevokeWarning => "revoke_warning",
            Self::GraceRunning => "grace_running",
            Self::CheckpointReported => "checkpoint_reported",
            Self::ForcedTeardown => "forced_teardown",
            Self::Torndown => "torndown",
            Self::Expired => "expired",
            Self::Fenced => "fenced",
            Self::FailedClosed => "failed_closed",
        }
    }

    /// Operator-readable one-line summary. Distinct surface from
    /// `as_str()`: this is what a CLI status page or dashboard
    /// tooltip renders so an operator can read the lifecycle
    /// position without consulting documentation. Not localized,
    /// not terminated with punctuation, intentionally short so a
    /// renderer can compose it inline.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::Active => "lease is active; no revoke pending",
            Self::RevokeWarning => "revoke initiated; workload has been notified",
            Self::GraceRunning => "grace period running; workload may checkpoint",
            Self::CheckpointReported => "workload reported checkpoint; cooperative teardown",
            Self::ForcedTeardown => "forced teardown in progress; no grace or grace exceeded",
            Self::Torndown => "teardown complete; lease released",
            Self::Expired => "lease TTL aged out without revoke",
            Self::Fenced => "teardown failed; resource fenced for forensic clearing",
            Self::FailedClosed => "fail-closed terminal; lease invariant violated",
        }
    }

    /// Returns `true` for the four terminal states. `Torndown`,
    /// `Fenced`, and `FailedClosed` are explicit terminals. `Expired`
    /// is included here because once a lease has aged out it cannot
    /// re-enter `Active` — the spec routes it through
    /// `failed-closed`, but observers treating `Expired` as a
    /// terminal-for-display purpose stay correct. The typed legal
    /// transition set still allows `Expired -> FailedClosed`.
    pub fn is_terminal(self) -> bool {
        matches!(
            self,
            Self::Torndown | Self::Fenced | Self::FailedClosed | Self::Expired
        )
    }

    /// Returns `true` if a direct transition from `self` to `next`
    /// is allowed by the spec. The legal set is derived from
    /// `docs/design/218-tenant-policy-and-lifecycle.md` § "Revoke
    /// State Machine":
    ///
    /// ```text
    /// active -> revoke-warning -> grace-running
    ///   -> checkpoint-reported -> torn-down
    ///   -> forced-teardown -> torn-down
    /// active -> forced-teardown -> torn-down
    /// active -> expired -> failed-closed
    /// active -> fenced
    /// ```
    ///
    /// In addition to the spec arrows, this implementation allows:
    ///
    /// - `CheckpointReported -> Fenced` and
    ///   `ForcedTeardown -> Fenced`: a teardown attempt that fails
    ///   fences the resource, matching the existing `LeaseFenced`
    ///   audit-event kind ("Lease teardown failed; the resource is
    ///   fenced").
    /// - `_ -> FailedClosed` from any non-terminal state: the spec's
    ///   `expired -> failed-closed` arrow is one path; the
    ///   FailedClosed sink is also the explicit landing for any
    ///   invariant violation, so that an unexpected transition
    ///   request can be rejected fail-closed without inventing a
    ///   string default.
    ///
    /// Any transition not in this set is either an invariant
    /// violation (use `FailedClosed` as the landing state) or a
    /// multi-step path (model intermediate transitions explicitly).
    pub fn legal_transition_to(self, next: Self) -> bool {
        use RevokeState::*;
        matches!(
            (self, next),
            // Spec arrows from `active`.
            (Active, RevokeWarning)
                | (Active, ForcedTeardown)
                | (Active, Expired)
                | (Active, Fenced)
                // Spec: revoke-warning -> grace-running.
                | (RevokeWarning, GraceRunning)
                // Spec: grace-running -> checkpoint-reported.
                | (GraceRunning, CheckpointReported)
                // Spec: checkpoint-reported -> torn-down.
                | (CheckpointReported, Torndown)
                // Spec: forced-teardown -> torn-down.
                | (ForcedTeardown, Torndown)
                // Spec: expired -> failed-closed.
                | (Expired, FailedClosed)
                // Teardown-failure routes to Fenced (matches
                // LeaseFenced audit-event kind semantics).
                | (CheckpointReported, Fenced)
                | (ForcedTeardown, Fenced)
                // Invariant-violation sink: any non-terminal state
                // can be forced to FailedClosed.
                | (Active, FailedClosed)
                | (RevokeWarning, FailedClosed)
                | (GraceRunning, FailedClosed)
                | (CheckpointReported, FailedClosed)
                | (ForcedTeardown, FailedClosed)
        )
    }
}

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

/// Policy-bounded grace window for cooperative lease revoke.
///
/// `RevokeGracePolicy` is deliberately small: it answers whether a
/// revoke is hard (`grace_secs == 0`) or cooperative, what the maximum
/// permitted grace is, and whether checkpoint hooks may report
/// committed progress during that window. It does not choose victims
/// and it does not extend lease TTLs; scheduler/runtime integration
/// must enforce the policy before emitting `RevokeWarning` /
/// `GraceRunning`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub struct RevokeGracePolicy {
    /// Requested cooperative grace window in seconds. `0` means hard
    /// revoke: no warning/grace path and no checkpoint hooks.
    pub grace_secs: u64,
    /// Maximum grace this policy allows. `grace_secs` must be less
    /// than or equal to this value.
    pub max_grace_secs: u64,
    /// Whether checkpoint hooks are allowed to report committed
    /// progress during the grace window.
    pub checkpoint_hooks_allowed: bool,
}

impl RevokeGracePolicy {
    pub const fn hard_revoke() -> Self {
        Self {
            grace_secs: 0,
            max_grace_secs: 0,
            checkpoint_hooks_allowed: false,
        }
    }

    pub fn bounded(
        grace_secs: u64,
        max_grace_secs: u64,
        checkpoint_hooks_allowed: bool,
    ) -> Result<Self, RevokeGracePolicyError> {
        let policy = Self {
            grace_secs,
            max_grace_secs,
            checkpoint_hooks_allowed,
        };
        policy.validate()?;
        Ok(policy)
    }

    pub fn validate(self) -> Result<(), RevokeGracePolicyError> {
        if self.grace_secs > self.max_grace_secs {
            return Err(RevokeGracePolicyError::GraceExceedsMaximum);
        }
        if self.grace_secs == 0 && self.checkpoint_hooks_allowed {
            return Err(RevokeGracePolicyError::CheckpointHooksRequireGrace);
        }
        Ok(())
    }

    pub fn is_hard_revoke(self) -> bool {
        self.grace_secs == 0
    }

    pub fn checkpoint_hooks_allowed(self) -> bool {
        self.checkpoint_hooks_allowed && !self.is_hard_revoke()
    }

    pub fn grace_deadline_unix_secs(
        self,
        start_unix_secs: u64,
    ) -> Result<Option<u64>, RevokeGracePolicyError> {
        self.validate()?;
        if self.is_hard_revoke() {
            return Ok(None);
        }
        start_unix_secs
            .checked_add(self.grace_secs)
            .map(Some)
            .ok_or(RevokeGracePolicyError::DeadlineOverflow)
    }
}

impl Default for RevokeGracePolicy {
    fn default() -> Self {
        Self::hard_revoke()
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum RevokeGracePolicyError {
    GraceExceedsMaximum,
    CheckpointHooksRequireGrace,
    DeadlineOverflow,
}

impl RevokeGracePolicyError {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::GraceExceedsMaximum => "grace_exceeds_maximum",
            Self::CheckpointHooksRequireGrace => "checkpoint_hooks_require_grace",
            Self::DeadlineOverflow => "deadline_overflow",
        }
    }

    pub fn human_summary(self) -> &'static str {
        match self {
            Self::GraceExceedsMaximum => "requested grace exceeds policy maximum",
            Self::CheckpointHooksRequireGrace => "checkpoint hooks require a nonzero grace window",
            Self::DeadlineOverflow => "grace deadline overflowed unix timestamp range",
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 218.2 — Preemptibility (slice 88)
// ---------------------------------------------------------------------------

/// Phase 218.2 — Whether a workload accepts preemption.
///
/// Orthogonal to `Priority`: a `Priority::Standard` workload that
/// declares `Preemptibility::Protected` overrides the priority-based
/// preemption rules and cannot be preempted by ordinary scheduling.
/// Operators use this to mark real-time / latency-sensitive work
/// where the preemption cost outweighs the rebalance benefit.
///
/// `Preemptibility` is the WORKLOAD-SCOPE policy. The lease-scope
/// override is `NonPreemptibleReason` below — a workload may be
/// `Preemptible` overall but a specific lease (e.g. one currently
/// flushing a checkpoint) carries a typed non-preemptible marker.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum Preemptibility {
    /// Default. Workload accepts preemption per priority rules.
    #[cfg_attr(feature = "serde", serde(alias = "Preemptible"))]
    Preemptible,
    /// Workload is explicitly non-preemptible. Cannot be preempted by
    /// ordinary scheduling regardless of priority pressure. Operators
    /// use this for real-time / latency-sensitive work where preemption
    /// cost outweighs rebalance benefit.
    #[cfg_attr(feature = "serde", serde(alias = "Protected"))]
    Protected,
}

impl Preemptibility {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Preemptible => "preemptible",
            Self::Protected => "protected",
        }
    }
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::Preemptible => "accepts preemption per priority rules (default)",
            Self::Protected => "non-preemptible by ordinary scheduling; operator-declared",
        }
    }
    pub fn allows_preemption(self) -> bool {
        matches!(self, Self::Preemptible)
    }
}

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

/// Phase 218.2 — Lease-scope marker explaining WHY a specific lease
/// is non-preemptible right now, distinct from the workload-scope
/// `Preemptibility::Protected` declaration.
///
/// A workload that is overall `Preemptibility::Preemptible` may have
/// a transient lease that carries a `NonPreemptibleReason` — e.g. a
/// lease that's currently flushing a checkpoint. Once the reason
/// clears (checkpoint complete), the lease becomes preemptible again
/// per the workload's standing policy.
///
/// The typed reason set is closed and stable. Adding a variant is
/// wire-compatibility-grade — SIEM rules and the audit chain group
/// on these strings.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum NonPreemptibleReason {
    /// Lease is mid-checkpoint flush. Preempting now would lose the
    /// checkpoint. Cleared when the checkpoint reports complete.
    #[cfg_attr(feature = "serde", serde(alias = "CheckpointInProgress"))]
    CheckpointInProgress,
    /// Lease has an active data-plane binding (RDMA QP, NVMe-oF
    /// connection) that cannot be torn down without coordination.
    /// Cleared when the data plane releases.
    #[cfg_attr(feature = "serde", serde(alias = "DataPlaneActive"))]
    DataPlaneActive,
    /// Operator manually pinned this lease as non-preemptible via the
    /// admin surface. Cleared by an explicit operator unpin.
    #[cfg_attr(feature = "serde", serde(alias = "OperatorPin"))]
    OperatorPin,
    /// Lease has an attestation contract (TEE binding, sealed key)
    /// that requires the specific holder. Preemption would invalidate
    /// the attestation chain. Cleared when the attestation is
    /// renewed against a different holder.
    #[cfg_attr(feature = "serde", serde(alias = "AttestationLocked"))]
    AttestationLocked,
}

impl NonPreemptibleReason {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::CheckpointInProgress => "checkpoint_in_progress",
            Self::DataPlaneActive => "data_plane_active",
            Self::OperatorPin => "operator_pin",
            Self::AttestationLocked => "attestation_locked",
        }
    }

    pub fn human_summary(self) -> &'static str {
        match self {
            Self::CheckpointInProgress => {
                "lease is mid-checkpoint; preempting would lose the checkpoint"
            }
            Self::DataPlaneActive => "data-plane binding active; teardown requires coordination",
            Self::OperatorPin => "operator manually pinned this lease as non-preemptible",
            Self::AttestationLocked => "attestation chain requires this specific lease holder",
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 218.5 — ResourceBundle (slice 106)
// ---------------------------------------------------------------------------

/// Phase 218.5 — Hardware-generation tag for typed resource requirements.
///
/// Heterogeneous workloads (e.g. A100+H100 distributed training, MI300
/// inference) often must pin a requirement to a specific generation
/// because driver / interconnect / numeric characteristics differ
/// materially. `ResourceRequirement::hardware_generation` carries this
/// constraint; `None` means "any generation satisfying the kind".
///
/// The variant set is closed and stable. Adding a generation is
/// wire-compatibility-grade: operators query `--generation` on the
/// CLI surface (deferred to a follow-up slice) and SIEM rules group
/// on the `as_str()` label. The slice-90 single-source-of-truth pin
/// catches any drift between `as_str()` and the serde wire shape.
///
/// `Other` is the explicit landing for non-NVIDIA / non-AMD / non-Intel
/// accelerators (or unknown generations) so the enum does not need a
/// free-form `String` escape hatch — fail-closed if the operator's
/// CLI string does not resolve to a known variant.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum HardwareGeneration {
    /// NVIDIA Ampere (A100, A30, A40).
    NvidiaAmpere,
    /// NVIDIA Hopper (H100, H200).
    NvidiaHopper,
    /// NVIDIA Blackwell (B200, GB200).
    NvidiaBlackwell,
    /// AMD CDNA3 (MI300, MI300X, MI300A).
    AmdMi300,
    /// AMD CDNA4 (MI325X+).
    AmdMi325,
    /// Intel Gaudi 2/3.
    IntelGaudi,
    /// Other / generic. Use when no specific generation is required
    /// or the accelerator family is not yet enumerated.
    Other,
}

impl HardwareGeneration {
    /// Stable wire / log identifier (snake_case). Wire-format-grade —
    /// SIEM rules and dashboard panel selectors alert off this exact
    /// string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::NvidiaAmpere => "nvidia_ampere",
            Self::NvidiaHopper => "nvidia_hopper",
            Self::NvidiaBlackwell => "nvidia_blackwell",
            Self::AmdMi300 => "amd_mi300",
            Self::AmdMi325 => "amd_mi325",
            Self::IntelGaudi => "intel_gaudi",
            Self::Other => "other",
        }
    }

    /// Operator-readable one-line summary. Distinct surface from
    /// `as_str()`: this is what a CLI status page or dashboard
    /// tooltip renders. Carries the load-bearing generation noun
    /// (Ampere / Hopper / Blackwell / MI300 / MI325 / Gaudi) so a
    /// reader can tell which accelerator family the variant names.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::NvidiaAmpere => "NVIDIA Ampere (A100, A30, A40)",
            Self::NvidiaHopper => "NVIDIA Hopper (H100, H200)",
            Self::NvidiaBlackwell => "NVIDIA Blackwell (B200, GB200)",
            Self::AmdMi300 => "AMD CDNA3 (MI300, MI300X, MI300A)",
            Self::AmdMi325 => "AMD CDNA4 (MI325X and newer)",
            Self::IntelGaudi => "Intel Gaudi 2 / Gaudi 3",
            Self::Other => "other / generic accelerator family",
        }
    }
}

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

/// Typed parse error for hardware-generation labels.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ParseHardwareGenerationError(pub String);

impl fmt::Display for ParseHardwareGenerationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid hardware generation {:?} — valid values: nvidia_ampere | nvidia_hopper | nvidia_blackwell | amd_mi300 | amd_mi325 | intel_gaudi | other",
            self.0
        )
    }
}

impl std::error::Error for ParseHardwareGenerationError {}

impl core::str::FromStr for HardwareGeneration {
    type Err = ParseHardwareGenerationError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "nvidia_ampere" => Ok(Self::NvidiaAmpere),
            "nvidia_hopper" => Ok(Self::NvidiaHopper),
            "nvidia_blackwell" => Ok(Self::NvidiaBlackwell),
            "amd_mi300" => Ok(Self::AmdMi300),
            "amd_mi325" => Ok(Self::AmdMi325),
            "intel_gaudi" => Ok(Self::IntelGaudi),
            "other" => Ok(Self::Other),
            _ => Err(ParseHardwareGenerationError(s.to_string())),
        }
    }
}

// ---------------------------------------------------------------------------
// Phase 218.1 — Tenant quota schema (slice 116)
// ---------------------------------------------------------------------------

/// Per-GPU-generation quota entry.
///
/// The scheduler consumes this as policy. `fabricbios-core` only reports
/// hardware facts; it does not evaluate tenant quotas.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct GpuGenerationQuota {
    /// Accelerator generation the count applies to.
    pub generation: HardwareGeneration,
    /// Maximum active GPU leases of this generation.
    pub count: u32,
}

/// Phase 218.1 — typed tenant quota schema.
///
/// This is the cross-crate shape used to describe a tenant's hard quota
/// envelope. `None` means "no hard quota for this dimension". Zero means
/// an explicit zero-capacity quota and must be enforced as such.
///
/// The type intentionally lives in `grafos-core`, not `fabricbios-core`:
/// quota is scheduler policy. fabricBIOS enforces the lease/capability
/// result; it does not decide a tenant's quota envelope.
#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct QuotaSchema {
    /// Maximum memory bytes.
    pub mem_bytes: Option<u64>,
    /// Maximum CPU cores.
    pub cpu_cores: Option<u64>,
    /// Maximum total GPU leases regardless of hardware generation.
    pub gpu_count: Option<u32>,
    /// Maximum accelerator-local memory bytes. User-facing surfaces may call
    /// this GPU VRAM. It maps to `ResourceKind::GpuMem`, not `Gpu`, because
    /// GPU execution leases and GPU memory leases are distinct capacity
    /// dimensions.
    pub gpu_vram_bytes: Option<u64>,
    /// Optional per-generation GPU counts. When present, these refine the
    /// total `gpu_count` envelope for generation-aware placement.
    pub gpu_count_by_generation: Vec<GpuGenerationQuota>,
    /// Maximum block-storage bytes.
    pub block_bytes: Option<u64>,
    /// Maximum network bandwidth in bits per second.
    pub net_bps: Option<u64>,
    /// Maximum concurrent tasklet leases.
    pub tasklet_concurrency: Option<u32>,
    /// Maximum lease-create operations per minute.
    pub lease_create_per_minute: Option<u32>,
    /// Optional burst-credit policy shared by quota dimensions that allow
    /// bounded temporary overage.
    pub burst_credits: Option<BurstCreditPolicy>,
    /// Optional fair-share window tied to this quota record.
    pub fair_share: Option<FairShareWindow>,
}

impl QuotaSchema {
    /// Returns true when every hard quota dimension is absent.
    pub fn is_unlimited(&self) -> bool {
        self.mem_bytes.is_none()
            && self.cpu_cores.is_none()
            && self.gpu_count.is_none()
            && self.gpu_vram_bytes.is_none()
            && self.gpu_count_by_generation.is_empty()
            && self.block_bytes.is_none()
            && self.net_bps.is_none()
            && self.tasklet_concurrency.is_none()
            && self.lease_create_per_minute.is_none()
    }

    /// Returns the hard quota limit for the scheduler's coarse resource
    /// kind, when that kind maps directly to the schema.
    pub fn limit_for_resource_kind(&self, kind: crate::ResourceKind) -> Option<u64> {
        match kind {
            crate::ResourceKind::Mem => self.mem_bytes,
            crate::ResourceKind::Cpu => self.cpu_cores,
            crate::ResourceKind::Gpu => self.total_gpu_count().map(u64::from),
            crate::ResourceKind::GpuMem => self.gpu_vram_bytes,
            crate::ResourceKind::Block => self.block_bytes,
            crate::ResourceKind::Net => self.net_bps,
            crate::ResourceKind::Tasklet => self.tasklet_concurrency.map(u64::from),
        }
    }

    /// Total GPU-count quota across all generations, if configured.
    pub fn total_gpu_count(&self) -> Option<u32> {
        self.gpu_count.or_else(|| {
            if self.gpu_count_by_generation.is_empty() {
                None
            } else {
                Some(
                    self.gpu_count_by_generation
                        .iter()
                        .fold(0u32, |acc, q| acc.saturating_add(q.count)),
                )
            }
        })
    }

    /// Per-generation GPU quota, when configured.
    pub fn gpu_limit_for_generation(&self, generation: HardwareGeneration) -> Option<u32> {
        self.gpu_count_by_generation
            .iter()
            .find(|q| q.generation == generation)
            .map(|q| q.count)
    }
}

/// Deterministic burst-credit policy for quota overage.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct BurstCreditPolicy {
    /// Maximum burst capacity above the steady quota.
    pub capacity: u64,
    /// Refill rate in capacity units per minute.
    pub refill_per_minute: u64,
    /// Accounting window in seconds.
    pub window_secs: u64,
}

impl BurstCreditPolicy {
    /// Returns true iff the policy can make progress and has a bounded
    /// accounting window.
    pub fn is_valid(&self) -> bool {
        self.capacity > 0 && self.refill_per_minute > 0 && self.window_secs > 0
    }
}

/// Snapshot of tenant usage in the same dimensions as [`QuotaSchema`].
#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct QuotaUsage {
    pub mem_bytes: u64,
    pub cpu_cores: u64,
    pub gpu_count: u32,
    pub gpu_vram_bytes: u64,
    pub gpu_count_by_generation: Vec<GpuGenerationQuota>,
    pub block_bytes: u64,
    pub net_bps: u64,
    pub tasklet_concurrency: u32,
    pub lease_creates_in_window: u32,
}

impl QuotaUsage {
    /// Returns usage for the scheduler's coarse resource kind.
    pub fn usage_for_resource_kind(&self, kind: crate::ResourceKind) -> u64 {
        match kind {
            crate::ResourceKind::Mem => self.mem_bytes,
            crate::ResourceKind::Cpu => self.cpu_cores,
            crate::ResourceKind::Gpu => u64::from(self.gpu_count),
            crate::ResourceKind::GpuMem => self.gpu_vram_bytes,
            crate::ResourceKind::Block => self.block_bytes,
            crate::ResourceKind::Net => self.net_bps,
            crate::ResourceKind::Tasklet => u64::from(self.tasklet_concurrency),
        }
    }

    /// Per-generation GPU usage, when tracked.
    pub fn gpu_usage_for_generation(&self, generation: HardwareGeneration) -> u32 {
        self.gpu_count_by_generation
            .iter()
            .find(|q| q.generation == generation)
            .map_or(0, |q| q.count)
    }
}

/// Typed quota violation vocabulary.
///
/// This maps quota decisions onto stable labels without using free-form
/// strings. Admission paths may still include human prose, but this enum is
/// the load-bearing operator/API surface.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum QuotaViolation {
    MemBytesExceeded {
        limit: u64,
        used: u64,
        requested: u64,
    },
    CpuCoresExceeded {
        limit: u64,
        used: u64,
        requested: u64,
    },
    GpuCountExceeded {
        generation: Option<HardwareGeneration>,
        limit: u32,
        used: u32,
        requested: u32,
    },
    GpuVramBytesExceeded {
        limit: u64,
        used: u64,
        requested: u64,
    },
    BlockBytesExceeded {
        limit: u64,
        used: u64,
        requested: u64,
    },
    NetBpsExceeded {
        limit: u64,
        used: u64,
        requested: u64,
    },
    TaskletConcurrencyExceeded {
        limit: u32,
        used: u32,
        requested: u32,
    },
    LeaseCreateRateExceeded {
        limit_per_minute: u32,
        used_in_window: u32,
        requested: u32,
    },
    ActiveLeaseCountExceeded {
        limit: u32,
        active: u32,
        requested: u32,
    },
    PerNodeCapacityExceeded {
        limit: u64,
        used: u64,
        requested: u64,
    },
    BurstCreditExhausted {
        capacity: u64,
        remaining: u64,
        requested: u64,
    },
    FairShareExceeded {
        window_secs: u64,
        max_share_secs: u64,
        used_share_secs: u64,
        requested_share_secs: u64,
    },
    TenantQuotaMissing,
}

impl QuotaViolation {
    /// Stable snake_case label for logs, dashboards, and API consumers.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::MemBytesExceeded { .. } => "mem_bytes_exceeded",
            Self::CpuCoresExceeded { .. } => "cpu_cores_exceeded",
            Self::GpuCountExceeded { .. } => "gpu_count_exceeded",
            Self::GpuVramBytesExceeded { .. } => "gpu_vram_bytes_exceeded",
            Self::BlockBytesExceeded { .. } => "block_bytes_exceeded",
            Self::NetBpsExceeded { .. } => "net_bps_exceeded",
            Self::TaskletConcurrencyExceeded { .. } => "tasklet_concurrency_exceeded",
            Self::LeaseCreateRateExceeded { .. } => "lease_create_rate_exceeded",
            Self::ActiveLeaseCountExceeded { .. } => "active_lease_count_exceeded",
            Self::PerNodeCapacityExceeded { .. } => "per_node_capacity_exceeded",
            Self::BurstCreditExhausted { .. } => "burst_credit_exhausted",
            Self::FairShareExceeded { .. } => "fair_share_exceeded",
            Self::TenantQuotaMissing => "tenant_quota_missing",
        }
    }

    /// Tooltip-grade operator-readable summary.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::MemBytesExceeded { .. } => "tenant memory quota exceeded",
            Self::CpuCoresExceeded { .. } => "tenant CPU quota exceeded",
            Self::GpuCountExceeded { .. } => "tenant GPU-count quota exceeded",
            Self::GpuVramBytesExceeded { .. } => "tenant GPU VRAM quota exceeded",
            Self::BlockBytesExceeded { .. } => "tenant block-storage quota exceeded",
            Self::NetBpsExceeded { .. } => "tenant network-bandwidth quota exceeded",
            Self::TaskletConcurrencyExceeded { .. } => "tenant tasklet-concurrency quota exceeded",
            Self::LeaseCreateRateExceeded { .. } => "tenant lease-create rate quota exceeded",
            Self::ActiveLeaseCountExceeded { .. } => "tenant active-lease count quota exceeded",
            Self::PerNodeCapacityExceeded { .. } => "tenant per-node capacity quota exceeded",
            Self::BurstCreditExhausted { .. } => "tenant burst-credit envelope exhausted",
            Self::FairShareExceeded { .. } => "tenant fair-share window exceeded",
            Self::TenantQuotaMissing => "tenant has no quota record",
        }
    }

    /// Existing admission rejection bucket used until the admission surface
    /// grows per-violation typed fields.
    pub fn rejection_reason(self) -> RejectionReason {
        match self {
            Self::BurstCreditExhausted { .. } => RejectionReason::QuotaBurstExceeded,
            Self::TenantQuotaMissing => RejectionReason::TenantNotFound,
            _ => RejectionReason::QuotaHardLimitExceeded,
        }
    }
}

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

/// Phase 218.5 — Atomicity policy for a `ResourceBundleSpec`.
///
/// Slice 106 lands the typed vocabulary; the AdmissionGate wiring
/// that actually enforces atomicity is deferred to a follow-up slice
/// (see TODO.md Phase 218.5 carry-overs).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum BundleAtomicity {
    /// All-or-nothing: either every requirement is granted, or NONE.
    /// Partial allocation is impossible. The default for slice 106 —
    /// most bundle workloads (mixed-GPU training, CPU+mem+GPU
    /// inference) are meaningless under a partial grant.
    AllOrNothing,
    /// Best-effort: grant as many requirements as fit; the workload
    /// is told which were granted. Rare — included so the
    /// vocabulary surface is closed, not open to interpretation.
    BestEffort,
}

impl BundleAtomicity {
    /// Stable wire / log identifier (snake_case).
    pub fn as_str(self) -> &'static str {
        match self {
            Self::AllOrNothing => "all_or_nothing",
            Self::BestEffort => "best_effort",
        }
    }

    /// Operator-readable one-line summary.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::AllOrNothing => "all-or-nothing: every requirement granted or none",
            Self::BestEffort => "best-effort: grant as many requirements as fit",
        }
    }
}

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

impl Default for BundleAtomicity {
    fn default() -> Self {
        Self::AllOrNothing
    }
}

/// Phase 218.5 — A single resource requirement within a bundle.
///
/// A heterogeneous workload declares a list of `ResourceRequirement`
/// items wrapped in `ResourceBundleSpec`; the scheduler's
/// atomic-admission path grants ALL of them or rejects with a typed
/// `BundleAdmissionFailure`. This struct is the requirement shape;
/// `ResourceBundleSpec` is the bundle (list + atomicity).
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ResourceRequirement {
    /// Resource type required (Mem / Cpu / Gpu / Block / Net / Tasklet).
    pub kind: crate::ResourceKind,
    /// Capacity required, in the kind's natural units: bytes for `Mem`
    /// and `Block`, cores for `Cpu`, VRAM-bytes for `Gpu`, bytes/sec
    /// for `Net`, slots for `Tasklet`.
    pub capacity: u64,
    /// Optional hardware-generation constraint. `None` = any generation
    /// satisfying the kind; `Some(g)` = require this exact generation.
    /// Mostly applies to `Gpu` — operators express "A100 OR H100" by
    /// constructing two `ResourceBundleSpec` candidates and choosing
    /// at admission time, not by widening this field.
    pub hardware_generation: Option<HardwareGeneration>,
}

/// Phase 218.5 — A bundle of resource requirements admitted atomically.
///
/// The scheduler's atomic-admission path (deferred to a follow-up
/// slice) walks `requirements` and either grants them all (writing
/// the leases) or rejects with a typed `BundleAdmissionFailure`. An
/// empty `requirements` list is a typed error
/// (`BundleAdmissionFailure::EmptyBundle`), not a no-op grant.
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ResourceBundleSpec {
    /// The requirements. Order is not significant — the scheduler MAY
    /// satisfy them in any order. An empty `Vec` is rejected at
    /// admission as `BundleAdmissionFailure::EmptyBundle`.
    pub requirements: Vec<ResourceRequirement>,
    /// Atomicity policy. Defaults to `AllOrNothing`.
    #[cfg_attr(feature = "serde", serde(default))]
    pub atomicity: BundleAtomicity,
}

impl Default for ResourceBundleSpec {
    fn default() -> Self {
        Self {
            requirements: Vec::new(),
            atomicity: BundleAtomicity::AllOrNothing,
        }
    }
}

/// Phase 218.5 — Typed admission-failure reasons specific to bundle
/// admission.
///
/// Slice 106 lands the vocabulary; the AdmissionGate wiring that
/// emits these reasons is deferred to a follow-up slice. Operators
/// querying `--reason` on the (forthcoming) `grafos admissions`
/// bundle filter see these labels — the cross-layer pin pattern
/// (slice 87 / slice 93) will catch drift once the CLI surface lands.
///
/// `BundleAdmissionFailure` is its own axis, orthogonal to the
/// per-resource `RejectionReason` vocabulary. A bundle admission can
/// fail at the bundle level (e.g. `EmptyBundle`) without any single
/// requirement carrying a per-resource rejection. Whether the two
/// vocabularies fold or stay separate is a follow-up slice decision.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum BundleAdmissionFailure {
    /// The bundle had zero requirements. Operators occasionally send
    /// this from misconfigured templates; surface it as a typed
    /// reason rather than a string default.
    EmptyBundle,
    /// At least one requirement could not be satisfied with the
    /// available capacity, and the bundle's atomicity is
    /// `AllOrNothing`. The scheduler did NOT grant any requirement.
    InsufficientBundleCapacity,
    /// At least one requirement violates a placement constraint and
    /// no viable per-candidate placement exists for it, AND the
    /// atomicity is `AllOrNothing`. Distinct from the per-resource
    /// `RejectionReason::PlacementPolicyExcluded` which fires per
    /// candidate.
    BundleConstraintViolation,
    /// A specific `HardwareGeneration` requirement could not be met
    /// (e.g. the workload asked for an A100+H100 bundle and the
    /// cluster has no H100 inventory).
    HardwareGenerationUnavailable,
    /// Reserved placeholder for future bundle-failure reasons. The
    /// typed-vocabulary discipline rejects free-form `reason: String`,
    /// so the closed set has an explicit catch-all rather than an
    /// open `String` escape. New variants land via
    /// wire-format-grade slices.
    OtherBundleFailure,
}

impl BundleAdmissionFailure {
    /// Stable wire / log identifier (snake_case). Wire-format-grade —
    /// SIEM rules group on this exact string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::EmptyBundle => "empty_bundle",
            Self::InsufficientBundleCapacity => "insufficient_bundle_capacity",
            Self::BundleConstraintViolation => "bundle_constraint_violation",
            Self::HardwareGenerationUnavailable => "hardware_generation_unavailable",
            Self::OtherBundleFailure => "other_bundle_failure",
        }
    }

    /// Operator-readable one-line summary. Distinct surface from
    /// `as_str()`. Carries load-bearing nouns so a reader can tell
    /// why a bundle admission failed at a glance.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::EmptyBundle => "bundle had zero requirements; nothing to admit",
            Self::InsufficientBundleCapacity => {
                "insufficient capacity for at least one requirement; all-or-nothing rejected"
            }
            Self::BundleConstraintViolation => {
                "placement constraint excludes every candidate for at least one requirement"
            }
            Self::HardwareGenerationUnavailable => {
                "requested hardware generation has no matching inventory in the cluster"
            }
            Self::OtherBundleFailure => "other bundle admission failure; reserved catch-all",
        }
    }

    /// Fold bundle admission failures onto the flat admissions
    /// `RejectionReason` vocabulary used by `/api/v1/admissions`,
    /// `grafos admissions --reason`, and dashboard aggregation.
    pub fn rejection_reason(self) -> RejectionReason {
        match self {
            Self::EmptyBundle => RejectionReason::EmptyBundle,
            Self::InsufficientBundleCapacity => RejectionReason::InsufficientBundleCapacity,
            Self::BundleConstraintViolation => RejectionReason::BundleConstraintViolation,
            Self::HardwareGenerationUnavailable => RejectionReason::HardwareGenerationUnavailable,
            Self::OtherBundleFailure => RejectionReason::OtherBundleFailure,
        }
    }
}

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

/// Phase 218.5 / slice 108 — bundle-level admission decision summary.
///
/// The slice-107 `check_bundle_admission` validates; slice-108
/// `reserve_bundle` validates AND reserves under a critical section.
/// Each `reserve_bundle` call emits one `BundleAdmissionDecided`
/// audit record (in addition to the per-requirement `AdmissionDecided`
/// emits the inner `check_admission` calls already fire). Operators
/// querying `--kind admission_decided` see this bundle-level summary
/// alongside the per-requirement detail.
///
/// The four variants are closed — adding a new outcome shape is
/// wire-format-grade and lands via a follow-up slice.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum BundleDecision {
    /// Bundle was fully approved (AllOrNothing: all requirements
    /// granted; BestEffort: every requirement granted). The
    /// reservation is held under a critical section pending the
    /// caller's `commit()` or `rollback()`.
    Approved,
    /// AllOrNothing bundle rejected because at least one requirement
    /// failed admission. No capacity was reserved (the slice 108
    /// reservation path holds the lock through validation AND
    /// reservation, so a partial-fail rolls back cleanly).
    DeniedAllOrNothing,
    /// Bundle had zero requirements. Operators occasionally send this
    /// from misconfigured templates; the typed decision surfaces it
    /// distinctly from a capacity-shaped denial.
    DeniedEmpty,
    /// BestEffort bundle approved with some requirements granted and
    /// others denied. The caller's `BundleReservation` token holds
    /// the granted subset; the per-requirement results expose which
    /// failed.
    PartialBestEffort,
}

impl BundleDecision {
    /// Stable wire / log identifier (snake_case). Wire-format-grade —
    /// SIEM rules group on this exact string.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Approved => "approved",
            Self::DeniedAllOrNothing => "denied_all_or_nothing",
            Self::DeniedEmpty => "denied_empty",
            Self::PartialBestEffort => "partial_best_effort",
        }
    }

    /// Operator-readable one-line summary. Distinct surface from
    /// `as_str()`.
    pub fn human_summary(self) -> &'static str {
        match self {
            Self::Approved => "bundle fully approved; reservation held pending commit",
            Self::DeniedAllOrNothing => {
                "bundle rejected; at least one requirement failed and atomicity is all-or-nothing"
            }
            Self::DeniedEmpty => "bundle rejected; zero requirements",
            Self::PartialBestEffort => {
                "best-effort bundle approved with mixed per-requirement results"
            }
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 219 — AuditEventKind
// ---------------------------------------------------------------------------

/// Typed kinds for events that compose the Phase 219 audit chain. The
/// set here is the slice-1 minimum; subsequent slices add variants
/// alongside the code paths that emit them.
///
/// Important: this enum names what the daemon / scheduler / runtime
/// EMITS. The chain assembly (prev_event_hash, current_event_hash,
/// signature) lives in `fabricbiosd` per the Phase 217 audit_anchor
/// pin and the cross-phase invariant ("core emits typed records when
/// state transitions, it does not own the chain"). The collector then
/// stores the chain entries.
///
/// New variants MUST be added here, not synthesized from string fields
/// at emit time. Free-form `reason: String` event kinds are rejected.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum AuditEventKind {
    /// Capability token issued. Includes the issuer (Phase 220 custody-
    /// matrix entry) and the WorkloadIdentity audience.
    #[cfg_attr(feature = "serde", serde(alias = "CapabilityIssued"))]
    CapabilityIssued,
    /// Capability token revoked.
    #[cfg_attr(feature = "serde", serde(alias = "CapabilityRevoked"))]
    CapabilityRevoked,
    /// Lease allocated.
    #[cfg_attr(feature = "serde", serde(alias = "LeaseAllocated"))]
    LeaseAllocated,
    /// Lease renewed.
    #[cfg_attr(feature = "serde", serde(alias = "LeaseRenewed"))]
    LeaseRenewed,
    /// Lease released cooperatively by the holder.
    #[cfg_attr(feature = "serde", serde(alias = "LeaseReleased"))]
    LeaseReleased,
    /// Lease expired (TTL). The teardown path is observed by
    /// `fabricbiosd`.
    #[cfg_attr(feature = "serde", serde(alias = "LeaseExpired"))]
    LeaseExpired,
    /// Lease torn down successfully (cooperative or revoke-driven).
    #[cfg_attr(feature = "serde", serde(alias = "LeaseTorndown"))]
    LeaseTorndown,
    /// Lease teardown failed; the resource is fenced.
    #[cfg_attr(feature = "serde", serde(alias = "LeaseFenced"))]
    LeaseFenced,
    /// Scheduler admission decision (accept or reject).
    #[cfg_attr(feature = "serde", serde(alias = "AdmissionDecided"))]
    AdmissionDecided,
    /// Workload preempted. Includes `PreemptionReason`.
    #[cfg_attr(feature = "serde", serde(alias = "Preempted"))]
    Preempted,
    /// Operator-driven node/cell drain initiated.
    #[cfg_attr(feature = "serde", serde(alias = "DrainInitiated"))]
    DrainInitiated,
    /// Daemon emitted its first audit event after `audit_anchor`
    /// was unanchored — the chain anchor marker. Phase 219 collectors
    /// use this to distinguish fresh-boot from missed-events.
    #[cfg_attr(feature = "serde", serde(alias = "ChainAnchored"))]
    ChainAnchored,
    /// Phase 220 / slice 13 — a soft / weaker-mode toggle was
    /// enabled at process startup. The discipline preamble says:
    /// "Bearer / soft-mode surfaces are typed config flags with
    /// audit, not env vars." Examples include the spec §8.5
    /// trusted-fabric exception profile, Phase 220's worker-broader-
    /// signing opt-in, Phase 222's TokenReview kubelet-metadata
    /// fallback. Each emit names the specific mode (via
    /// `WorkloadIdentity::instance_id`) so an upstream collector can
    /// alert on enables of any soft-mode toggle without parsing
    /// free-form text.
    #[cfg_attr(feature = "serde", serde(alias = "SoftModeEnabled"))]
    SoftModeEnabled,
    /// Phase 218–222 / slice 77 — tenant CRUD: a new tenant was
    /// registered with the scheduler. Stage 2a of the audit-surface
    /// migration: producers now dual-write this typed kind alongside
    /// the older enterprise_audit `kind=tenant, outcome="created"`
    /// row. Operators querying the unified `/api/v1/admin/audit`
    /// endpoint with `kind=tenant_created` see typed rows for every
    /// `POST /api/v1/tenants` admission.
    #[cfg_attr(feature = "serde", serde(alias = "TenantCreated"))]
    TenantCreated,
    /// Phase 218–222 / slice 77 — tenant CRUD: an existing tenant was
    /// removed from the scheduler. Stage 2a producer convergence
    /// emits this alongside the older enterprise_audit `kind=tenant,
    /// outcome="deleted"` / `outcome="deleted_force"` row. The typed
    /// record's `instance_id` carries the `tenant:deleted:<name>`
    /// marker so collectors can grep delete events without joining
    /// against the enterprise log.
    #[cfg_attr(feature = "serde", serde(alias = "TenantDeleted"))]
    TenantDeleted,
    /// Phase 218–222 / slice 77 — tenant CRUD: a tenant's quota was
    /// updated. Stage 2a producer convergence emits this alongside
    /// the older enterprise_audit `kind=tenant, outcome="quota_updated"`
    /// row. The typed record carries the NEW values (mem_bytes,
    /// cpu_cores) — an operator reading the chain sees the resulting
    /// quota state.
    #[cfg_attr(feature = "serde", serde(alias = "TenantQuotaUpdated"))]
    TenantQuotaUpdated,
    /// Phase 218–222 / slice 79 — provider conformance run recorded.
    /// Stage 2b of the audit-surface migration: producers now dual-
    /// write this typed kind alongside the older enterprise_audit
    /// `kind=admin, outcome="provider_conformance_recorded"` row.
    /// Fires on `POST /api/v1/providers/{provider}/conformance` after
    /// the durable cloud-state record has been persisted.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderConformanceRecorded"))]
    ProviderConformanceRecorded,
    /// Phase 218–222 / slice 79 — provider bootstrap token issued.
    /// Stage 2b producer convergence emits this alongside the older
    /// `kind=admin, outcome="provider_bootstrap_token_issued"` row.
    /// Fires on `POST /api/v1/cells/bootstrap/tokens` after the new
    /// `BootstrapTokenRecord` is durable. The typed marker carries
    /// the bootstrap_id; a SIEM rule alerting on long-lived bootstrap
    /// tokens can grep `provider:bootstrap_token_issued:*` without
    /// joining against the older enterprise_audit details.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderBootstrapTokenIssued"))]
    ProviderBootstrapTokenIssued,
    /// Phase 218–222 / slice 79 — provider bootstrap exchanged for
    /// cell identity. Stage 2b producer convergence emits this
    /// alongside the older `kind=admin,
    /// outcome="provider_bootstrap_exchanged"` row. Fires on
    /// `POST /api/v1/cells/bootstrap/exchange` after the durable
    /// consume of the bootstrap token has succeeded.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderBootstrapExchanged"))]
    ProviderBootstrapExchanged,
    /// Phase 218–222 / slice 79 — cell identity certificate issued.
    /// Stage 2b producer convergence emits this alongside the older
    /// `kind=admin, outcome="provider_cell_identity_issued"` row.
    /// Fires on the same handler as `ProviderBootstrapExchanged`
    /// (immediately after); the two emits are separate so a SIEM rule
    /// can alert specifically on cert issuance without parsing the
    /// bootstrap-exchange row.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderCellIdentityIssued"))]
    ProviderCellIdentityIssued,
    /// Phase 218–222 / slice 79 — cell identity rotated. Stage 2b
    /// producer convergence emits this alongside the older
    /// `kind=admin, outcome="provider_cell_identity_rotated"` row.
    /// Fires on `POST /api/v1/cells/identity/rotate` after the
    /// new cert has been issued and the durable record updated. The
    /// marker carries the new registration_generation so a chain
    /// reader sees rotation cadence at a glance.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderCellIdentityRotated"))]
    ProviderCellIdentityRotated,
    /// Phase 218–222 / slice 79 — cell identity revoked. Stage 2b
    /// producer convergence emits this alongside the older
    /// `kind=admin, outcome="provider_cell_identity_revoked"` row.
    /// Fires on `POST /api/v1/providers/{provider}/cells/{cell_id}/revoke`
    /// after the durable cloud-state record marks the cell revoked.
    #[cfg_attr(feature = "serde", serde(alias = "ProviderCellIdentityRevoked"))]
    ProviderCellIdentityRevoked,
    /// Phase 218–222 / slice 80 — admin/auth bearer token issued.
    /// Stage 2c of the audit-surface migration: producers now dual-
    /// write this typed kind alongside the older
    /// `enterprise_audit::AuditKind::Token + outcome="created"` row.
    /// Fires on `POST /api/v1/admin/tokens` (cell-side and orchestrator
    /// surfaces). Distinct from `CapabilityIssued` — bearer tokens
    /// are HTTP Authorization-shaped admin/tenant API keys for
    /// authenticating control-plane requests, NOT lease-bound
    /// capability tokens (which are spec § 4 with audience binding
    /// and resource scope). The `bearer_token_*` snake_case prefix
    /// grep-disambiguates the two vocabularies so SIEM rules don't
    /// conflate them.
    #[cfg_attr(feature = "serde", serde(alias = "BearerTokenIssued"))]
    BearerTokenIssued,
    /// Phase 218–222 / slice 80 — admin/auth bearer token revoked.
    /// Stage 2c producer convergence emits this alongside the older
    /// `enterprise_audit::AuditKind::Token + outcome="revoked"` row.
    /// Fires on `DELETE /api/v1/admin/tokens/<id>` (cell-side and
    /// orchestrator surfaces). See `BearerTokenIssued` for the
    /// vocabulary distinction from `CapabilityRevoked`.
    #[cfg_attr(feature = "serde", serde(alias = "BearerTokenRevoked"))]
    BearerTokenRevoked,
    /// Phase 218–222 / slice 81 — cell-side scheduler active/standby
    /// promotion succeeded. Stage 2 mop-up of the audit-surface
    /// migration: this slice closes the cell-side admin emit slice 79
    /// missed (slice 79 covered orchestrator-side admin only).
    /// Producers now dual-write this typed kind alongside the older
    /// `enterprise_audit::AuditKind::Admin + outcome="promoted"` row
    /// emitted by `emit_admin_promote_succeeded`. Fires on a
    /// successful `POST /api/v1/admin/promote` after
    /// `promote_inner` returns `PromoteOutcome::Ok`. The marker
    /// embeds the new epoch (`scheduler:promoted:epoch=<n>`) so SIEM
    /// rules grouping by epoch transition find the row directly
    /// without joining against the enterprise row's details JSON.
    #[cfg_attr(feature = "serde", serde(alias = "SchedulerPromoted"))]
    SchedulerPromoted,
    /// Phase 218–222 / slice 81 — billing rate-card installation.
    /// Stage 2 mop-up: the only Billing-category producer
    /// (`enterprise_audit::AuditKind::Billing`). Lifecycle-axis,
    /// low-volume — clean dual-write. Producers emit this alongside
    /// the older `enterprise_audit::AuditKind::Billing +
    /// outcome="installed"` row produced by
    /// `emit_billing_rate_card_installed`. Fires on a successful
    /// `POST /api/v1/billing/rate-card` after the new card has been
    /// persisted. The marker carries the operator-supplied card
    /// name (`billing:rate_card_installed:<card_name>`) so a SIEM
    /// rule alerting on rate-card swaps can grep the typed marker
    /// space directly.
    #[cfg_attr(feature = "serde", serde(alias = "BillingRateCardInstalled"))]
    BillingRateCardInstalled,
    /// Slice 261 (EdgeRecord audit-chain integration arc, opened by
    /// slice 259's design doc). A rewrite has applied an edge mutation.
    /// The accompanying `AuditEventData::EdgeRewritten` payload (slice
    /// 260) carries the slice 226 canonical EdgeRecord encoding so
    /// audit readers can decode the typed graph-object schema for any
    /// edge that's been touched. Fired by the rewrite engine in slice
    /// 262 (producer wiring) for each affected edge on a committed
    /// rewrite; rollback / precondition-failed paths deliberately
    /// don't emit — `EdgeRewritten` implies durable edge state. SIEM
    /// rules can filter `--kind edge_rewritten` for the
    /// per-rewrite-edge ledger.
    #[cfg_attr(feature = "serde", serde(alias = "EdgeRewritten"))]
    EdgeRewritten,
}

impl AuditEventKind {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::CapabilityIssued => "capability_issued",
            Self::CapabilityRevoked => "capability_revoked",
            Self::LeaseAllocated => "lease_allocated",
            Self::LeaseRenewed => "lease_renewed",
            Self::LeaseReleased => "lease_released",
            Self::LeaseExpired => "lease_expired",
            Self::LeaseTorndown => "lease_torndown",
            Self::LeaseFenced => "lease_fenced",
            Self::AdmissionDecided => "admission_decided",
            Self::Preempted => "preempted",
            Self::DrainInitiated => "drain_initiated",
            Self::ChainAnchored => "chain_anchored",
            Self::SoftModeEnabled => "soft_mode_enabled",
            Self::TenantCreated => "tenant_created",
            Self::TenantDeleted => "tenant_deleted",
            Self::TenantQuotaUpdated => "tenant_quota_updated",
            Self::ProviderConformanceRecorded => "provider_conformance_recorded",
            Self::ProviderBootstrapTokenIssued => "provider_bootstrap_token_issued",
            Self::ProviderBootstrapExchanged => "provider_bootstrap_exchanged",
            Self::ProviderCellIdentityIssued => "provider_cell_identity_issued",
            Self::ProviderCellIdentityRotated => "provider_cell_identity_rotated",
            Self::ProviderCellIdentityRevoked => "provider_cell_identity_revoked",
            Self::BearerTokenIssued => "bearer_token_issued",
            Self::BearerTokenRevoked => "bearer_token_revoked",
            Self::SchedulerPromoted => "scheduler_promoted",
            Self::BillingRateCardInstalled => "billing_rate_card_installed",
            Self::EdgeRewritten => "edge_rewritten",
        }
    }
}

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

// ---------------------------------------------------------------------------
// Phase 220 — WorkloadIdentity
// ---------------------------------------------------------------------------

/// Phase 220 canonical workload identity. The shared shape used by
/// scheduler admission/audit, attestation, and Kubernetes/DRA
/// integration. No phase invents a parallel identity record.
///
/// Field semantics per `docs/design/217-222-cross-phase-invariants.md`
/// "Workload Identity Mapping":
///
/// | Canonical field | scheduler/grafOS         | Kubernetes DRA           |
/// | --------------- | ------------------------ | ------------------------ |
/// | tenant          | tenant id / org id       | namespace or namespace→tenant map |
/// | namespace_scope | project / service / run scope | Kubernetes namespace |
/// | service         | grafOS service / program identity | ServiceAccount name+UID |
/// | instance_id     | run id / tasklet id / lease holder | Pod UID + claim name |
/// | attestation     | TEE/runtime attestation record | optional pod attestation |
/// | policy_gen      | scheduler policy generation | DeviceClass/namespace gen |
///
/// The struct fields use `Option<String>` for the slots that don't
/// always apply (attestation, namespace_scope), so a caller emitting
/// an audit event for a non-tenant operation (e.g. operator drain)
/// can build the record cleanly. `tenant` is the only required field;
/// if there is no tenant context, use a sentinel like `"_system"`.
///
/// This type is deliberately simple — no signing, no validation. It
/// is the shape; correctness of any specific instance is the caller's
/// responsibility (and is asserted by the layers that compose it,
/// e.g. the DRA driver's TokenReview path validates the namespace and
/// service before constructing a `WorkloadIdentity`).
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct WorkloadIdentity {
    /// Tenant / org identifier. Required.
    pub tenant: String,
    /// Workload namespace, project, or run scope. Optional for
    /// operations that have no scope (e.g. operator-driven drain).
    pub namespace_scope: Option<String>,
    /// Service identity — grafOS program identity or Kubernetes
    /// ServiceAccount.
    pub service: Option<String>,
    /// Workload instance — run id, tasklet id, lease holder, or Pod UID.
    pub instance_id: Option<String>,
    /// Attestation evidence record when present (TEE quote, vTPM, etc.).
    /// Opaque to this type; consumers parse per their attestation root.
    pub attestation: Option<Vec<u8>>,
    /// Policy generation that admitted / authorized this identity.
    /// `None` means "no policy gen recorded"; concrete callers should
    /// fill this in for any decision worth auditing.
    pub policy_gen: Option<u64>,
}

impl WorkloadIdentity {
    /// System identity used for emits with no tenant context (e.g.
    /// daemon-restart `chain_anchored` events). Distinct from any
    /// real tenant by the `_system` prefix.
    pub fn system() -> Self {
        Self {
            tenant: "_system".to_string(),
            namespace_scope: None,
            service: None,
            instance_id: None,
            attestation: None,
            policy_gen: None,
        }
    }

    /// Minimal tenant-scoped identity. Convenience for tests; real
    /// emit paths should populate the optional fields.
    pub fn tenant_only(tenant: impl Into<String>) -> Self {
        Self {
            tenant: tenant.into(),
            namespace_scope: None,
            service: None,
            instance_id: None,
            attestation: None,
            policy_gen: None,
        }
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    #[test]
    fn preemption_reason_strings_are_stable() {
        // External collectors group on these strings — changing one
        // is a vocabulary breaking change. The expected values here
        // match docs/design/218-tenant-policy-and-lifecycle.md.
        assert_eq!(
            PreemptionReason::PriorityPreemption.as_str(),
            "priority_preemption"
        );
        assert_eq!(PreemptionReason::QuotaRebalance.as_str(), "quota_rebalance");
        assert_eq!(
            PreemptionReason::BurstCreditExhausted.as_str(),
            "burst_credit_exhausted"
        );
        assert_eq!(
            PreemptionReason::BudgetExhausted.as_str(),
            "budget_exhausted"
        );
        assert_eq!(
            PreemptionReason::CostCapEviction.as_str(),
            "cost_cap_eviction"
        );
        assert_eq!(PreemptionReason::OperatorDrain.as_str(), "operator_drain");
        assert_eq!(
            PreemptionReason::OperatorMigProfileChange.as_str(),
            "operator_mig_profile_change"
        );
        assert_eq!(
            PreemptionReason::MaintenanceWindow.as_str(),
            "maintenance_window"
        );
        assert_eq!(
            PreemptionReason::PolicyViolationRecovery.as_str(),
            "policy_violation_recovery"
        );
    }

    /// Phases 218-222 slice 73 — `PreemptionReason::human_summary()`
    /// returns a stable operator-readable string per variant.
    /// Pinning each by value means a future CLI / dashboard
    /// surface can rely on the prose without re-deriving it; it
    /// also catches an accidental rename that would shift what
    /// operators see.
    #[test]
    fn preemption_reason_human_summary_is_stable() {
        assert_eq!(
            PreemptionReason::PriorityPreemption.human_summary(),
            "reclaimed for higher-priority work that outranked it"
        );
        assert_eq!(
            PreemptionReason::QuotaRebalance.human_summary(),
            "reclaimed because tenant fair-share moved a different tenant in"
        );
        assert_eq!(
            PreemptionReason::BurstCreditExhausted.human_summary(),
            "reclaimed because the tenant's burst-bucket envelope was exceeded"
        );
        assert_eq!(
            PreemptionReason::BudgetExhausted.human_summary(),
            "reclaimed because the tenant's spend budget was exhausted"
        );
        assert_eq!(
            PreemptionReason::CostCapEviction.human_summary(),
            "reclaimed because the global cost cap could no longer be satisfied"
        );
        assert_eq!(
            PreemptionReason::OperatorDrain.human_summary(),
            "reclaimed because an operator drained the host node"
        );
        assert_eq!(
            PreemptionReason::OperatorMigProfileChange.human_summary(),
            "reclaimed because an operator recomposed the GPU MIG profile"
        );
        assert_eq!(
            PreemptionReason::MaintenanceWindow.human_summary(),
            "reclaimed by a scheduled maintenance window"
        );
        assert_eq!(
            PreemptionReason::PolicyViolationRecovery.human_summary(),
            "reclaimed because the workload no longer satisfied a mandatory policy"
        );
    }

    /// Every variant returns a non-empty summary. A blank
    /// summary would render as a hole in tooltip UI without
    /// surfacing the missing prose anywhere structured.
    #[test]
    fn preemption_reason_human_summary_is_non_empty() {
        for reason in [
            PreemptionReason::PriorityPreemption,
            PreemptionReason::QuotaRebalance,
            PreemptionReason::BurstCreditExhausted,
            PreemptionReason::BudgetExhausted,
            PreemptionReason::CostCapEviction,
            PreemptionReason::OperatorDrain,
            PreemptionReason::OperatorMigProfileChange,
            PreemptionReason::MaintenanceWindow,
            PreemptionReason::PolicyViolationRecovery,
        ] {
            assert!(
                !reason.human_summary().is_empty(),
                "{reason:?}: human_summary must be non-empty"
            );
        }
    }

    /// Load-bearing phrase pins. The summary text isn't fully
    /// stable in wording (we may tighten the prose), but the
    /// noun naming the cause is what makes the tooltip useful —
    /// "operator" for drain, "burst" for burst-credit, "policy"
    /// for policy-violation, etc. A future copy-edit that drops
    /// the load-bearing noun changes the meaning, not just the
    /// phrasing, and should fail the test.
    #[test]
    fn preemption_reason_human_summary_load_bearing_phrases() {
        assert!(
            PreemptionReason::OperatorDrain
                .human_summary()
                .contains("operator"),
            "OperatorDrain.human_summary must mention \"operator\""
        );
        assert!(
            PreemptionReason::OperatorMigProfileChange
                .human_summary()
                .contains("operator"),
            "OperatorMigProfileChange.human_summary must mention \"operator\""
        );
        assert!(
            PreemptionReason::OperatorMigProfileChange
                .human_summary()
                .contains("MIG"),
            "OperatorMigProfileChange.human_summary must mention \"MIG\""
        );
        assert!(
            PreemptionReason::BurstCreditExhausted
                .human_summary()
                .contains("burst"),
            "BurstCreditExhausted.human_summary must mention \"burst\""
        );
        assert!(
            PreemptionReason::BudgetExhausted
                .human_summary()
                .contains("budget"),
            "BudgetExhausted.human_summary must mention \"budget\""
        );
        assert!(
            PreemptionReason::CostCapEviction
                .human_summary()
                .contains("cost cap"),
            "CostCapEviction.human_summary must mention \"cost cap\""
        );
        assert!(
            PreemptionReason::MaintenanceWindow
                .human_summary()
                .contains("maintenance"),
            "MaintenanceWindow.human_summary must mention \"maintenance\""
        );
        assert!(
            PreemptionReason::PolicyViolationRecovery
                .human_summary()
                .contains("policy"),
            "PolicyViolationRecovery.human_summary must mention \"policy\""
        );
        assert!(
            PreemptionReason::PriorityPreemption
                .human_summary()
                .contains("higher-priority"),
            "PriorityPreemption.human_summary must mention \"higher-priority\""
        );
        assert!(
            PreemptionReason::QuotaRebalance
                .human_summary()
                .contains("fair-share"),
            "QuotaRebalance.human_summary must mention \"fair-share\""
        );
    }

    /// The 9-variant closed set must yield 9 distinct summaries.
    /// Two variants sharing one summary would lose meaning at
    /// the tooltip boundary; the audit chain still distinguishes
    /// them via `as_str()`, but operator-facing surfaces would
    /// not. This pins the closed set and the distinctness.
    #[test]
    fn preemption_reason_human_summary_count_and_distinct() {
        let summaries = [
            PreemptionReason::PriorityPreemption.human_summary(),
            PreemptionReason::QuotaRebalance.human_summary(),
            PreemptionReason::BurstCreditExhausted.human_summary(),
            PreemptionReason::BudgetExhausted.human_summary(),
            PreemptionReason::CostCapEviction.human_summary(),
            PreemptionReason::OperatorDrain.human_summary(),
            PreemptionReason::OperatorMigProfileChange.human_summary(),
            PreemptionReason::MaintenanceWindow.human_summary(),
            PreemptionReason::PolicyViolationRecovery.human_summary(),
        ];
        assert_eq!(summaries.len(), 9, "closed-set size pinned at 9 variants");
        for (i, a) in summaries.iter().enumerate() {
            for (j, b) in summaries.iter().enumerate() {
                if i != j {
                    assert_ne!(
                        a, b,
                        "human_summary collision between variant {i} and {j}: {a:?}"
                    );
                }
            }
        }
    }

    /// `as_str()` and `human_summary()` are intentionally
    /// distinct surfaces. `as_str()` is the wire-format-grade
    /// snake_case label SIEM rules alert off; `human_summary()`
    /// is the operator-facing rendering helper. A consumer that
    /// confuses the two would surface snake_case in tooltips or
    /// wire prose into a SIEM rule. Pin the distinction so a
    /// future refactor doesn't unify them.
    #[test]
    fn preemption_reason_human_summary_differs_from_as_str() {
        for reason in [
            PreemptionReason::PriorityPreemption,
            PreemptionReason::QuotaRebalance,
            PreemptionReason::BurstCreditExhausted,
            PreemptionReason::BudgetExhausted,
            PreemptionReason::CostCapEviction,
            PreemptionReason::OperatorDrain,
            PreemptionReason::OperatorMigProfileChange,
            PreemptionReason::MaintenanceWindow,
            PreemptionReason::PolicyViolationRecovery,
        ] {
            assert_ne!(
                reason.as_str(),
                reason.human_summary(),
                "{reason:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    #[test]
    fn evidence_label_ordering_matches_strength() {
        // The Ord derivation reflects evidence strength: stronger
        // labels compare greater. This is the order callers should
        // use when checking "is this label at least as strong as X."
        assert!(EvidenceLabel::DesignTarget < EvidenceLabel::LabEvidence);
        assert!(EvidenceLabel::LabEvidence < EvidenceLabel::StagedProviderEvidence);
        assert!(EvidenceLabel::StagedProviderEvidence < EvidenceLabel::DesignPartnerEvidence);
        assert!(EvidenceLabel::DesignPartnerEvidence < EvidenceLabel::ProductionEvidence);
    }

    #[test]
    fn evidence_label_requires_artifact_for_anything_above_design_target() {
        assert!(!EvidenceLabel::DesignTarget.requires_artifact());
        assert!(EvidenceLabel::UnitIntegrationEvidence.requires_artifact());
        assert!(EvidenceLabel::LabEvidence.requires_artifact());
        assert!(EvidenceLabel::StagedProviderEvidence.requires_artifact());
        assert!(EvidenceLabel::DesignPartnerEvidence.requires_artifact());
        assert!(EvidenceLabel::ProductionEvidence.requires_artifact());
    }

    #[test]
    fn audit_event_kind_strings_are_stable() {
        assert_eq!(
            AuditEventKind::CapabilityIssued.as_str(),
            "capability_issued"
        );
        assert_eq!(AuditEventKind::LeaseAllocated.as_str(), "lease_allocated");
        assert_eq!(AuditEventKind::LeaseFenced.as_str(), "lease_fenced");
        assert_eq!(AuditEventKind::Preempted.as_str(), "preempted");
        assert_eq!(AuditEventKind::ChainAnchored.as_str(), "chain_anchored");
        assert_eq!(
            AuditEventKind::SoftModeEnabled.as_str(),
            "soft_mode_enabled"
        );
        // Phase 218–222 / slice 77 — tenant CRUD typed kinds.
        // External SIEM rules / dashboard panels alert off these
        // exact strings; renaming a variant here is a wire-format
        // breaking change.
        assert_eq!(AuditEventKind::TenantCreated.as_str(), "tenant_created");
        assert_eq!(AuditEventKind::TenantDeleted.as_str(), "tenant_deleted");
        assert_eq!(
            AuditEventKind::TenantQuotaUpdated.as_str(),
            "tenant_quota_updated"
        );
        // Phase 218–222 / slice 79 — admin (provider/cell-identity)
        // typed kinds. Same external-API discipline as the slice-77
        // tenant kinds: dashboards and SIEM rules alert off these
        // exact strings.
        assert_eq!(
            AuditEventKind::ProviderConformanceRecorded.as_str(),
            "provider_conformance_recorded"
        );
        assert_eq!(
            AuditEventKind::ProviderBootstrapTokenIssued.as_str(),
            "provider_bootstrap_token_issued"
        );
        assert_eq!(
            AuditEventKind::ProviderBootstrapExchanged.as_str(),
            "provider_bootstrap_exchanged"
        );
        assert_eq!(
            AuditEventKind::ProviderCellIdentityIssued.as_str(),
            "provider_cell_identity_issued"
        );
        assert_eq!(
            AuditEventKind::ProviderCellIdentityRotated.as_str(),
            "provider_cell_identity_rotated"
        );
        assert_eq!(
            AuditEventKind::ProviderCellIdentityRevoked.as_str(),
            "provider_cell_identity_revoked"
        );
        // Phase 218–222 / slice 80 — admin/auth bearer-token typed
        // kinds. The "bearer_token_*" prefix is grep-disambiguated
        // from "capability_*" (lease-bound capability tokens, spec
        // § 4) so SIEM rules don't conflate the two vocabularies.
        // External wire-format-grade — rename = breaking.
        assert_eq!(
            AuditEventKind::BearerTokenIssued.as_str(),
            "bearer_token_issued"
        );
        assert_eq!(
            AuditEventKind::BearerTokenRevoked.as_str(),
            "bearer_token_revoked"
        );
        // Phase 218–222 / slice 81 — Stage 2 mop-up convergence
        // typed kinds (cell-side scheduler promote + billing rate-
        // card installation). Same external-API discipline: SIEM
        // rules / dashboard panels alert off these exact strings.
        assert_eq!(
            AuditEventKind::SchedulerPromoted.as_str(),
            "scheduler_promoted"
        );
        assert_eq!(
            AuditEventKind::BillingRateCardInstalled.as_str(),
            "billing_rate_card_installed"
        );
        // Slice 261 (EdgeRecord audit-chain integration arc) — kind
        // marker for committed rewrite-engine edge mutations. The
        // accompanying slice 260 `AuditEventData::EdgeRewritten`
        // payload carries the slice 226 canonical EdgeRecord
        // encoding.
        assert_eq!(AuditEventKind::EdgeRewritten.as_str(), "edge_rewritten");
    }

    /// Phase 218–222 / slice 80 — pin that bearer-token kinds and
    /// capability kinds remain distinct strings. They name
    /// different vocabularies (HTTP Authorization bearer tokens vs
    /// lease-bound capability tokens, spec § 4); a future merge of
    /// the two would silently fold SIEM-grouping rules together
    /// and is a wire-format-grade regression.
    #[test]
    fn bearer_token_kinds_distinct_from_capability_kinds() {
        assert_ne!(
            AuditEventKind::BearerTokenIssued.as_str(),
            AuditEventKind::CapabilityIssued.as_str()
        );
        assert_ne!(
            AuditEventKind::BearerTokenRevoked.as_str(),
            AuditEventKind::CapabilityRevoked.as_str()
        );
    }

    #[test]
    fn workload_identity_system_uses_underscore_prefix() {
        // The `_system` prefix is the convention for distinguishing
        // operator/system identities from real tenant identifiers.
        // Any future tenant-name validation MUST reject identifiers
        // starting with `_` so this prefix stays unambiguous.
        let id = WorkloadIdentity::system();
        assert!(id.tenant.starts_with('_'));
        assert_eq!(id.tenant, "_system");
        assert!(id.namespace_scope.is_none());
        assert!(id.service.is_none());
        assert!(id.instance_id.is_none());
        assert!(id.attestation.is_none());
        assert!(id.policy_gen.is_none());
    }

    #[test]
    fn workload_identity_tenant_only_carries_tenant() {
        let id = WorkloadIdentity::tenant_only("acme");
        assert_eq!(id.tenant, "acme");
        assert!(id.namespace_scope.is_none());
    }

    /// Phase 219.2 slice 33 — RejectionReason labels are wire-
    /// format-grade. SIEM rules and dashboard panels alert off
    /// these exact strings; pin every variant by value so a
    /// future variant rename can't silently shift the wire
    /// format.
    #[test]
    fn rejection_reason_labels_are_stable() {
        assert_eq!(
            RejectionReason::InsufficientCapacity.as_str(),
            "insufficient_capacity"
        );
        assert_eq!(
            RejectionReason::NoEligibleNodes.as_str(),
            "no_eligible_nodes"
        );
        assert_eq!(
            RejectionReason::QuotaHardLimitExceeded.as_str(),
            "quota_hard_limit_exceeded"
        );
        assert_eq!(
            RejectionReason::QuotaBurstExceeded.as_str(),
            "quota_burst_exceeded"
        );
        assert_eq!(
            RejectionReason::QuotaLeaseCountExceeded.as_str(),
            "quota_lease_count_exceeded"
        );
        assert_eq!(
            RejectionReason::QuotaPerNodeLimitExceeded.as_str(),
            "quota_per_node_limit_exceeded"
        );
        assert_eq!(RejectionReason::TenantNotFound.as_str(), "tenant_not_found");
        assert_eq!(RejectionReason::NodeFenced.as_str(), "node_fenced");
        assert_eq!(
            RejectionReason::BudgetExhausted.as_str(),
            "budget_exhausted"
        );
        assert_eq!(
            RejectionReason::ReservationExhausted.as_str(),
            "reservation_exhausted"
        );
        // Phase 219.2 slice 36 additions.
        assert_eq!(
            RejectionReason::PlacementPolicyExcluded.as_str(),
            "placement_policy_excluded"
        );
        assert_eq!(
            RejectionReason::NodeAddressUnknown.as_str(),
            "node_address_unknown"
        );
        // Phase 218 slice 68 addition.
        assert_eq!(RejectionReason::NodeDrained.as_str(), "node_drained");
        // Phase 218.5 slice 118 bundle-admission fold additions.
        assert_eq!(RejectionReason::EmptyBundle.as_str(), "empty_bundle");
        assert_eq!(
            RejectionReason::InsufficientBundleCapacity.as_str(),
            "insufficient_bundle_capacity"
        );
        assert_eq!(
            RejectionReason::BundleConstraintViolation.as_str(),
            "bundle_constraint_violation"
        );
        assert_eq!(
            RejectionReason::HardwareGenerationUnavailable.as_str(),
            "hardware_generation_unavailable"
        );
        assert_eq!(
            RejectionReason::OtherBundleFailure.as_str(),
            "other_bundle_failure"
        );
    }

    /// Phase 220.2 slice 46 — EgressEnforcement labels are
    /// wire-format-grade. Pin every variant by value.
    #[test]
    fn egress_enforcement_labels_are_stable() {
        assert_eq!(
            EgressEnforcement::FabricEnforced.as_str(),
            "fabric_enforced"
        );
        assert_eq!(
            EgressEnforcement::HostRuntimeIntegration.as_str(),
            "host_runtime_integration"
        );
        assert_eq!(
            EgressEnforcement::OperatorControlled.as_str(),
            "operator_controlled"
        );
        assert_eq!(EgressEnforcement::Unsupported.as_str(), "unsupported");
    }

    /// EgressTarget labels are stable.
    #[test]
    fn egress_target_labels_are_stable() {
        assert_eq!(EgressTarget::WasmTasklet.as_str(), "wasm_tasklet");
        assert_eq!(EgressTarget::NativeProgram.as_str(), "native_program");
        assert_eq!(
            EgressTarget::ContainerAdjacent.as_str(),
            "container_adjacent"
        );
        assert_eq!(EgressTarget::KubernetesDra.as_str(), "kubernetes_dra");
        assert_eq!(EgressTarget::BareMetal.as_str(), "bare_metal");
    }

    /// The target → enforcement mapping is the canonical
    /// matrix the scheduler consults. Pinning every entry by
    /// value means a future change to the matrix fails this
    /// test until the docs and any consumers are updated in
    /// the same change.
    #[test]
    fn egress_target_to_enforcement_matrix() {
        assert_eq!(
            EgressTarget::WasmTasklet.enforcement(),
            EgressEnforcement::FabricEnforced,
            "wasm tasklet must be fabric-enforced (deny-all under wasmi)"
        );
        assert_eq!(
            EgressTarget::NativeProgram.enforcement(),
            EgressEnforcement::OperatorControlled,
            "native program egress is operator-controlled (kernel owns NIC)"
        );
        assert_eq!(
            EgressTarget::ContainerAdjacent.enforcement(),
            EgressEnforcement::OperatorControlled,
            "container-adjacent egress is operator-controlled (container runtime)"
        );
        assert_eq!(
            EgressTarget::KubernetesDra.enforcement(),
            EgressEnforcement::OperatorControlled,
            "Kubernetes DRA egress is operator-controlled (NetworkPolicy / CNI)"
        );
        assert_eq!(
            EgressTarget::BareMetal.enforcement(),
            EgressEnforcement::HostRuntimeIntegration,
            "bare-metal default is host-runtime-integration; HCL may override"
        );
    }

    /// Display impl matches as_str on both enums.
    #[test]
    fn egress_display_matches_as_str() {
        assert_eq!(
            format!("{}", EgressEnforcement::FabricEnforced),
            "fabric_enforced"
        );
        assert_eq!(format!("{}", EgressTarget::WasmTasklet), "wasm_tasklet");
    }

    /// Phase 216 slice 53 — EconomicsSource labels are
    /// wire-format-grade. Pin every variant by value.
    #[test]
    fn economics_source_labels_are_stable() {
        assert_eq!(
            EconomicsSource::OperatorStaticConfig.as_str(),
            "operator_static_config"
        );
        assert_eq!(
            EconomicsSource::ProviderPriceSheet.as_str(),
            "provider_price_sheet"
        );
        assert_eq!(
            EconomicsSource::ProviderUsageExport.as_str(),
            "provider_usage_export"
        );
        assert_eq!(
            EconomicsSource::MeasuredPowerTelemetry.as_str(),
            "measured_power_telemetry"
        );
        assert_eq!(
            EconomicsSource::ThirdPartyCarbonFeed.as_str(),
            "third_party_carbon_feed"
        );
        assert_eq!(
            EconomicsSource::DerivedEstimate.as_str(),
            "derived_estimate"
        );
    }

    /// ObservationConfidence labels are stable.
    #[test]
    fn observation_confidence_labels_are_stable() {
        assert_eq!(ObservationConfidence::Low.as_str(), "low");
        assert_eq!(ObservationConfidence::Medium.as_str(), "medium");
        assert_eq!(ObservationConfidence::High.as_str(), "high");
    }

    /// ObservationConfidence is ordinal — Low < Medium <
    /// High. Filter queries `obs.confidence >= floor` rely
    /// on this; pin the contract.
    #[test]
    fn observation_confidence_is_ordinal() {
        assert!(ObservationConfidence::Low < ObservationConfidence::Medium);
        assert!(ObservationConfidence::Medium < ObservationConfidence::High);
        assert!(ObservationConfidence::Low < ObservationConfidence::High);
        // Filter idiom.
        let floor = ObservationConfidence::Medium;
        let high = ObservationConfidence::High;
        let low = ObservationConfidence::Low;
        assert!(high >= floor);
        assert!(!(low >= floor));
    }

    /// EconomicsGeneration is monotonic; UNANCHORED is the
    /// starting sentinel; next() advances by one and saturates.
    #[test]
    fn economics_generation_is_monotonic() {
        assert_eq!(EconomicsGeneration::UNANCHORED.0, 0);
        let g1 = EconomicsGeneration::UNANCHORED.next();
        assert_eq!(g1.0, 1);
        let g2 = g1.next();
        assert_eq!(g2.0, 2);
        assert!(g2 > g1);
        assert!(g1 > EconomicsGeneration::UNANCHORED);
        // Saturates at u64::MAX.
        let max = EconomicsGeneration(u64::MAX);
        assert_eq!(max.next().0, u64::MAX);
    }

    /// Display impls round-trip through as_str() for the
    /// enums; EconomicsGeneration uses the gen=N format.
    #[test]
    fn economics_display_matches_as_str() {
        assert_eq!(
            format!("{}", EconomicsSource::OperatorStaticConfig),
            "operator_static_config"
        );
        assert_eq!(format!("{}", ObservationConfidence::High), "high");
        assert_eq!(format!("{}", EconomicsGeneration(42)), "gen=42");
    }

    /// Phase 216 slice 59 — EconomicsObservation freshness
    /// window: `observed_at <= now < valid_until`.
    /// Boundary check: `now == observed_at` is fresh,
    /// `now == valid_until` is stale.
    #[test]
    fn economics_observation_freshness_boundaries() {
        let obs = EconomicsObservation {
            value: 42u32,
            source: EconomicsSource::OperatorStaticConfig,
            confidence: ObservationConfidence::Medium,
            observed_at: 100,
            valid_until: 200,
            generation: EconomicsGeneration(1),
        };
        // Below window: stale.
        assert!(!obs.is_fresh(99));
        // Lower edge inclusive: fresh.
        assert!(obs.is_fresh(100));
        // Mid window: fresh.
        assert!(obs.is_fresh(150));
        // Upper edge exclusive: stale.
        assert!(!obs.is_fresh(200));
        // Above window: stale.
        assert!(!obs.is_fresh(201));
    }

    /// Confidence floor uses the slice-53 ordinal contract.
    /// A High observation meets a Medium floor; a Low does
    /// not.
    #[test]
    fn economics_observation_confidence_floor() {
        let high = EconomicsObservation {
            value: 1u32,
            source: EconomicsSource::MeasuredPowerTelemetry,
            confidence: ObservationConfidence::High,
            observed_at: 0,
            valid_until: u64::MAX,
            generation: EconomicsGeneration(1),
        };
        let low = EconomicsObservation {
            confidence: ObservationConfidence::Low,
            ..high.clone()
        };
        let medium = EconomicsObservation {
            confidence: ObservationConfidence::Medium,
            ..high.clone()
        };

        assert!(high.meets_floor(ObservationConfidence::Low));
        assert!(high.meets_floor(ObservationConfidence::Medium));
        assert!(high.meets_floor(ObservationConfidence::High));

        assert!(medium.meets_floor(ObservationConfidence::Low));
        assert!(medium.meets_floor(ObservationConfidence::Medium));
        assert!(!medium.meets_floor(ObservationConfidence::High));

        assert!(low.meets_floor(ObservationConfidence::Low));
        assert!(!low.meets_floor(ObservationConfidence::Medium));
        assert!(!low.meets_floor(ObservationConfidence::High));
    }

    /// `admissible` combines freshness AND confidence floor.
    /// A scheduler doing a required-decision admission can
    /// rely on this single call rather than reimplementing
    /// the rule in every consumer.
    #[test]
    fn economics_observation_admissible_combines_freshness_and_confidence() {
        let obs = EconomicsObservation {
            value: 1u32,
            source: EconomicsSource::ProviderUsageExport,
            confidence: ObservationConfidence::Medium,
            observed_at: 100,
            valid_until: 200,
            generation: EconomicsGeneration(7),
        };
        // Fresh + meets floor → admissible.
        assert!(obs.admissible(150, ObservationConfidence::Medium));
        assert!(obs.admissible(150, ObservationConfidence::Low));
        // Fresh but below floor → NOT admissible.
        assert!(!obs.admissible(150, ObservationConfidence::High));
        // Stale (now >= valid_until) but meets floor → NOT admissible.
        assert!(!obs.admissible(200, ObservationConfidence::Medium));
        assert!(!obs.admissible(201, ObservationConfidence::Medium));
        // Stale AND below floor → NOT admissible.
        assert!(!obs.admissible(200, ObservationConfidence::High));
    }

    /// EconomicsObservation is generic over its value type.
    /// Pin that contract by constructing one over a struct
    /// type — a future cost-model integration can wrap any
    /// typed payload without new envelope code.
    #[test]
    fn economics_observation_is_generic_over_value_type() {
        #[derive(Clone, Debug, PartialEq, Eq)]
        struct CarbonGrams {
            grams_co2e_per_kwh: u64,
        }
        let obs = EconomicsObservation {
            value: CarbonGrams {
                grams_co2e_per_kwh: 250,
            },
            source: EconomicsSource::ThirdPartyCarbonFeed,
            confidence: ObservationConfidence::Medium,
            observed_at: 1_700_000_000,
            valid_until: 1_700_003_600,
            generation: EconomicsGeneration(1),
        };
        assert_eq!(obs.value.grams_co2e_per_kwh, 250);
        assert!(obs.admissible(1_700_001_000, ObservationConfidence::Medium));
    }

    /// Display impl is the same as `as_str()`.
    #[test]
    fn rejection_reason_display_matches_as_str() {
        assert_eq!(
            format!("{}", RejectionReason::InsufficientCapacity),
            "insufficient_capacity"
        );
        // Phase 218 slice 68 — Display pin for the new variant.
        assert_eq!(format!("{}", RejectionReason::NodeDrained), "node_drained");
    }

    /// Phase 219.2 slice 37 — `human_summary()` returns a
    /// stable operator-readable string per variant. Pinning
    /// each by value means a CLI / dashboard rendering test
    /// can rely on the prose without re-deriving it; it also
    /// catches an accidental rename that would shift what
    /// operators see.
    #[test]
    fn rejection_reason_human_summary_is_stable() {
        assert_eq!(
            RejectionReason::InsufficientCapacity.human_summary(),
            "insufficient free capacity across all eligible nodes"
        );
        assert_eq!(
            RejectionReason::NoEligibleNodes.human_summary(),
            "no nodes match the placement constraint"
        );
        assert_eq!(
            RejectionReason::QuotaHardLimitExceeded.human_summary(),
            "tenant quota hard limit reached"
        );
        assert_eq!(
            RejectionReason::QuotaBurstExceeded.human_summary(),
            "tenant burst quota cap reached"
        );
        assert_eq!(
            RejectionReason::QuotaLeaseCountExceeded.human_summary(),
            "tenant lease count limit reached"
        );
        assert_eq!(
            RejectionReason::QuotaPerNodeLimitExceeded.human_summary(),
            "tenant per-node capacity limit reached"
        );
        assert_eq!(
            RejectionReason::TenantNotFound.human_summary(),
            "tenant id not registered with the scheduler"
        );
        assert_eq!(
            RejectionReason::NodeFenced.human_summary(),
            "selected node is fenced for the requested resource type"
        );
        assert_eq!(
            RejectionReason::BudgetExhausted.human_summary(),
            "power or cost budget cap reached"
        );
        assert_eq!(
            RejectionReason::ReservationExhausted.human_summary(),
            "reservation has insufficient remaining capacity"
        );
        assert_eq!(
            RejectionReason::PlacementPolicyExcluded.human_summary(),
            "placement policy excluded this candidate"
        );
        assert_eq!(
            RejectionReason::NodeAddressUnknown.human_summary(),
            "scheduler does not have a control-plane address for this node"
        );
        assert_eq!(
            RejectionReason::NodeDrained.human_summary(),
            "target node is drained for maintenance; admission resumes after the node returns to accepting mode"
        );
        assert_eq!(
            RejectionReason::EmptyBundle.human_summary(),
            "bundle had zero requirements; nothing to admit"
        );
        assert_eq!(
            RejectionReason::InsufficientBundleCapacity.human_summary(),
            "insufficient capacity for at least one bundle requirement"
        );
        assert_eq!(
            RejectionReason::BundleConstraintViolation.human_summary(),
            "bundle placement constraint excludes every viable candidate plan"
        );
        assert_eq!(
            RejectionReason::HardwareGenerationUnavailable.human_summary(),
            "requested bundle hardware generation has no matching inventory"
        );
        assert_eq!(
            RejectionReason::OtherBundleFailure.human_summary(),
            "other bundle admission failure"
        );
    }

    /// Phase 218 slice 62 — `FairShareWindow` accepts a
    /// well-formed descriptor: min<=max, weight>0, window>0.
    #[test]
    fn fair_share_window_valid_accepts_well_formed() {
        let w = FairShareWindow {
            tenant_id: 0x0000_0000_0000_0000_0000_0000_0000_00ac,
            priority_class_weight: 100,
            window_secs: 600,
            min_share_secs: 60,
            max_share_secs: 300,
            generation: EconomicsGeneration::UNANCHORED.next(),
        };
        assert!(w.is_valid());
    }

    /// `min_share_secs > max_share_secs` is rejected. The
    /// scheduler treats a typed reject as fail-closed; the
    /// validator never panics.
    #[test]
    fn fair_share_window_invalid_rejects_min_above_max() {
        let w = FairShareWindow {
            tenant_id: 1,
            priority_class_weight: 50,
            window_secs: 600,
            min_share_secs: 400,
            max_share_secs: 300,
            generation: EconomicsGeneration::UNANCHORED,
        };
        assert!(!w.is_valid());
    }

    /// `priority_class_weight == 0` is rejected. A zero
    /// weight has no meaningful share-fraction conversion.
    #[test]
    fn fair_share_window_invalid_rejects_zero_weight() {
        let w = FairShareWindow {
            tenant_id: 1,
            priority_class_weight: 0,
            window_secs: 600,
            min_share_secs: 60,
            max_share_secs: 300,
            generation: EconomicsGeneration::UNANCHORED,
        };
        assert!(!w.is_valid());
    }

    /// `window_secs == 0` is rejected. A zero-length window
    /// has no rolling-window semantics.
    #[test]
    fn fair_share_window_invalid_rejects_zero_window() {
        let w = FairShareWindow {
            tenant_id: 1,
            priority_class_weight: 100,
            window_secs: 0,
            min_share_secs: 0,
            max_share_secs: 0,
            generation: EconomicsGeneration::UNANCHORED,
        };
        assert!(!w.is_valid());
    }

    /// Serde round-trip — the typed envelope must serialize
    /// and deserialize losslessly so a committed fair-share
    /// table on disk reads back identically.
    #[cfg(feature = "serde")]
    #[test]
    fn fair_share_window_serde_round_trip() {
        let w = FairShareWindow {
            tenant_id: 0xdead_beef_cafe_f00d_1234_5678_9abc_def0,
            priority_class_weight: 250,
            window_secs: 3600,
            min_share_secs: 120,
            max_share_secs: 1800,
            generation: EconomicsGeneration(7),
        };
        let json = serde_json::to_string(&w).expect("serialize");
        let back: FairShareWindow = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(w, back);
    }

    /// Phase 218.1 slice 145 — fair-share scopes distinguish tenant,
    /// project, and priority-class policy without inventing three
    /// unrelated table shapes.
    #[test]
    fn fair_share_scope_kind_labels_are_stable() {
        assert_eq!(FairShareScope::Tenant { tenant_id: 7 }.kind(), "tenant");
        assert_eq!(FairShareScope::Project { project_id: 11 }.kind(), "project");
        assert_eq!(
            FairShareScope::PriorityClass {
                priority: Priority::Guaranteed
            }
            .kind(),
            "priority_class"
        );
    }

    /// A weighted fair-share table accepts positive weights, a nonzero
    /// rolling window, and one entry per scope.
    #[test]
    fn weighted_fair_share_policy_accepts_tenant_project_and_priority_scopes() {
        let policy = WeightedFairSharePolicy {
            window_secs: 3600,
            generation: EconomicsGeneration(9),
            entries: vec![
                FairShareWeight {
                    scope: FairShareScope::Tenant { tenant_id: 1 },
                    weight: 100,
                    min_share_secs: 60,
                    max_share_secs: 1800,
                },
                FairShareWeight {
                    scope: FairShareScope::Project { project_id: 22 },
                    weight: 50,
                    min_share_secs: 0,
                    max_share_secs: 900,
                },
                FairShareWeight {
                    scope: FairShareScope::PriorityClass {
                        priority: Priority::Scavenger,
                    },
                    weight: 10,
                    min_share_secs: 0,
                    max_share_secs: 300,
                },
            ],
        };

        assert!(policy.is_valid());
        assert_eq!(policy.total_weight(), 160);
    }

    /// Duplicate scopes are rejected instead of using last-writer-wins.
    /// Fair-share policy must be reproducible from the committed table.
    #[test]
    fn weighted_fair_share_policy_rejects_duplicate_scope() {
        let scope = FairShareScope::Tenant { tenant_id: 1 };
        let policy = WeightedFairSharePolicy {
            window_secs: 3600,
            generation: EconomicsGeneration(9),
            entries: vec![
                FairShareWeight {
                    scope,
                    weight: 100,
                    min_share_secs: 0,
                    max_share_secs: 100,
                },
                FairShareWeight {
                    scope,
                    weight: 200,
                    min_share_secs: 0,
                    max_share_secs: 200,
                },
            ],
        };

        assert!(!policy.is_valid());
    }

    /// Invalid weights and windows fail closed through validation
    /// rather than silently creating a zero-share entry.
    #[test]
    fn weighted_fair_share_policy_rejects_zero_window_zero_weight_and_bad_bounds() {
        let zero_window = WeightedFairSharePolicy {
            window_secs: 0,
            generation: EconomicsGeneration(1),
            entries: vec![FairShareWeight {
                scope: FairShareScope::Tenant { tenant_id: 1 },
                weight: 100,
                min_share_secs: 0,
                max_share_secs: 100,
            }],
        };
        assert!(!zero_window.is_valid());

        let zero_weight = WeightedFairSharePolicy {
            window_secs: 60,
            generation: EconomicsGeneration(1),
            entries: vec![FairShareWeight {
                scope: FairShareScope::Tenant { tenant_id: 1 },
                weight: 0,
                min_share_secs: 0,
                max_share_secs: 100,
            }],
        };
        assert!(!zero_weight.is_valid());

        let bad_bounds = WeightedFairSharePolicy {
            window_secs: 60,
            generation: EconomicsGeneration(1),
            entries: vec![FairShareWeight {
                scope: FairShareScope::Tenant { tenant_id: 1 },
                weight: 100,
                min_share_secs: 101,
                max_share_secs: 100,
            }],
        };
        assert!(!bad_bounds.is_valid());
    }

    /// Serde round-trip pins the committed table shape before the
    /// scheduler starts persisting it.
    #[cfg(feature = "serde")]
    #[test]
    fn weighted_fair_share_policy_serde_round_trip() {
        let policy = WeightedFairSharePolicy {
            window_secs: 300,
            generation: EconomicsGeneration(12),
            entries: vec![
                FairShareWeight {
                    scope: FairShareScope::Tenant { tenant_id: 99 },
                    weight: 100,
                    min_share_secs: 10,
                    max_share_secs: 200,
                },
                FairShareWeight {
                    scope: FairShareScope::PriorityClass {
                        priority: Priority::Guaranteed,
                    },
                    weight: 300,
                    min_share_secs: 100,
                    max_share_secs: 300,
                },
            ],
        };

        let json = serde_json::to_string(&policy).expect("serialize");
        let back: WeightedFairSharePolicy =
            serde_json::from_str(&json).expect("deserialize fair-share policy");
        assert_eq!(policy, back);
    }

    /// Phase 218.2 slice 85 — `Priority::as_str()` snake_case
    /// labels are wire-format-grade. SIEM rules and dashboard
    /// panels (and the audit-chain priority markers) alert off
    /// these exact strings. Pin every variant by value.
    #[test]
    fn priority_as_str_is_stable() {
        assert_eq!(Priority::Scavenger.as_str(), "scavenger");
        assert_eq!(Priority::Standard.as_str(), "standard");
        assert_eq!(Priority::Guaranteed.as_str(), "guaranteed");
    }

    /// `human_summary()` is the CLI / dashboard rendering
    /// surface. Pinning each by value means a renderer can
    /// rely on the prose without re-deriving it; it also
    /// catches an accidental rename that would shift what
    /// operators see.
    #[test]
    fn priority_human_summary_is_stable() {
        assert_eq!(
            Priority::Scavenger.human_summary(),
            "uses leftover capacity; preempted first when contention rises"
        );
        assert_eq!(
            Priority::Standard.human_summary(),
            "uses unreserved capacity; preemptible by guaranteed work"
        );
        assert_eq!(
            Priority::Guaranteed.human_summary(),
            "reserved capacity; never preempted by ordinary scheduling"
        );
    }

    /// `human_summary()` carries load-bearing nouns — the
    /// reader should be able to tell "what does this priority
    /// class mean for preemption" from a glance. Pin the
    /// content phrases so a future rewrite that lost the
    /// preemption story would fail this lint.
    #[test]
    fn priority_human_summary_load_bearing_phrases() {
        assert!(
            Priority::Scavenger.human_summary().contains("preempt"),
            "Scavenger summary should mention preemption"
        );
        assert!(
            Priority::Standard.human_summary().contains("preempt"),
            "Standard summary should mention preemption"
        );
        assert!(
            Priority::Guaranteed.human_summary().contains("never"),
            "Guaranteed summary should mention 'never' (no preemption)"
        );
    }

    /// Three variants, three labels, three summaries — all
    /// distinct. A regression where two variants collapsed to
    /// the same string would silently merge dashboard rows or
    /// SIEM filters; pin the count + distinctness invariant.
    #[test]
    fn priority_count_and_distinct() {
        let all = [
            Priority::Scavenger,
            Priority::Standard,
            Priority::Guaranteed,
        ];
        assert_eq!(all.len(), 3, "Priority must have exactly 3 variants");

        // as_str() values are pairwise distinct.
        let labels: Vec<&str> = all.iter().map(|p| p.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        // human_summary() values are pairwise distinct.
        let summaries: Vec<&str> = all.iter().map(|p| p.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );
    }

    /// Ordering invariant — `Guaranteed > Standard > Scavenger`.
    /// Slice 85 relocated the enum from grafos-scheduler/tenant.rs;
    /// this pin asserts the move preserved the Ord behavior the
    /// scheduler depends on (preemption.rs, victim selection,
    /// admission ordering).
    #[test]
    fn priority_ordering_is_stable() {
        assert!(Priority::Guaranteed > Priority::Standard);
        assert!(Priority::Standard > Priority::Scavenger);
        assert!(Priority::Guaranteed > Priority::Scavenger);

        let mut prios = [
            Priority::Standard,
            Priority::Guaranteed,
            Priority::Scavenger,
        ];
        prios.sort();
        assert_eq!(
            prios,
            [
                Priority::Scavenger,
                Priority::Standard,
                Priority::Guaranteed
            ]
        );
    }

    /// `as_str()` and `human_summary()` are intentionally
    /// distinct surfaces. SIEM rules alert off `as_str()`;
    /// `human_summary()` renders to operators. A consumer that
    /// confuses them would surface snake_case to operators or
    /// wire prose into a SIEM rule.
    #[test]
    fn priority_human_summary_differs_from_as_str() {
        for p in [
            Priority::Scavenger,
            Priority::Standard,
            Priority::Guaranteed,
        ] {
            assert_ne!(
                p.as_str(),
                p.human_summary(),
                "{p:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    /// Display impl matches as_str (matches the convention used
    /// by the rest of the typed-vocab enums).
    #[test]
    fn priority_display_matches_as_str() {
        assert_eq!(format!("{}", Priority::Scavenger), "scavenger");
        assert_eq!(format!("{}", Priority::Standard), "standard");
        assert_eq!(format!("{}", Priority::Guaranteed), "guaranteed");
    }

    /// Phase 218.2 slice 87 — `Priority::from_str` accepts every
    /// canonical snake_case label and round-trips through
    /// `as_str()`. The CLI/dashboard migration depends on this:
    /// operators type the label, the CLI parses to `Priority`,
    /// then re-emits via `as_str()` on the wire. A regression
    /// where a label parsed to the wrong variant would shift
    /// admission/preemption policy invisibly.
    #[test]
    fn priority_from_str_canonical_labels() {
        use core::str::FromStr;
        for (label, expected) in [
            ("scavenger", Priority::Scavenger),
            ("standard", Priority::Standard),
            ("guaranteed", Priority::Guaranteed),
        ] {
            let got = Priority::from_str(label)
                .unwrap_or_else(|e| panic!("from_str({label}) failed for canonical label: {e}"));
            assert_eq!(got, expected, "label {label} mapped to wrong variant");
            assert_eq!(
                got.as_str(),
                label,
                "round-trip from {label} must yield {label}"
            );
        }
    }

    /// Phase 218.2 slice 87 — `best_effort` is the documented
    /// deprecation alias. The Phase 48.5 hygiene rename moved
    /// the variant to `Standard`; the CLI/dashboard surfaces
    /// kept emitting `best_effort` until slice 87. The alias
    /// stays accepted so existing operator scripts and dashboard
    /// cookies don't fail closed during the migration window.
    /// Pin the alias mapping so a refactor that drops the alias
    /// must do so deliberately (and the carry-over in
    /// TODO.md Phase 218.2 stays the gate for that change).
    #[test]
    fn priority_from_str_accepts_best_effort_deprecation_alias() {
        use core::str::FromStr;
        assert_eq!(
            Priority::from_str("best_effort").expect("alias must parse"),
            Priority::Standard,
            "best_effort is the deprecation alias for Standard"
        );
    }

    /// Phase 218.2 slice 87 — unknown labels return a typed
    /// `ParsePriorityError` carrying the offending input. The
    /// error message names the canonical set so a clap
    /// value_parser surface or a dashboard validator can echo
    /// the operator's typo back with guidance. Fail-closed at
    /// parse time prevents a free-form `priority` string from
    /// reaching the wire — SIEM rules alert off the typed
    /// `as_str()` values, and a `--priority bogus` invocation
    /// that quietly fell through would shift those rules.
    #[test]
    fn priority_from_str_unknown_label_fails_closed() {
        use core::str::FromStr;
        let err = Priority::from_str("bogus").expect_err("unknown label must fail");
        assert_eq!(err.0, "bogus", "error must carry the offending input");
        let msg = format!("{err}");
        assert!(
            msg.contains("bogus"),
            "error message must echo the offending input: {msg}"
        );
        assert!(
            msg.contains("scavenger") && msg.contains("standard") && msg.contains("guaranteed"),
            "error message must list the canonical set: {msg}"
        );
    }

    /// Phase 218.2 slice 87 — only the one named historical
    /// spelling (`best_effort`) is accepted. Variants like
    /// `besteffort`, `Best Effort`, `BEST_EFFORT`, or empty
    /// string fail closed — the alias is not a free-form
    /// loose-match shim, just back-compat for one specific
    /// legacy literal.
    #[test]
    fn priority_from_str_does_not_loose_match_alias_variants() {
        use core::str::FromStr;
        for bad in [
            "besteffort",
            "Best Effort",
            "BEST_EFFORT",
            "",
            "Standard",
            "STANDARD",
        ] {
            assert!(
                Priority::from_str(bad).is_err(),
                "from_str must reject loose-match {bad:?}"
            );
        }
    }

    /// `human_summary()` and `as_str()` are intentionally
    /// distinct surfaces. `as_str()` is the wire-format-grade
    /// label SIEM rules alert off; `human_summary()` is the
    /// CLI / dashboard rendering helper. A consumer that
    /// confuses the two would surface snake_case to operators
    /// or wire `human_summary()` text into a SIEM rule. Pin
    /// the distinction so a future refactor doesn't unify
    /// them.
    #[test]
    fn rejection_reason_human_summary_differs_from_as_str() {
        for reason in [
            RejectionReason::InsufficientCapacity,
            RejectionReason::NoEligibleNodes,
            RejectionReason::QuotaHardLimitExceeded,
            RejectionReason::QuotaBurstExceeded,
            RejectionReason::QuotaLeaseCountExceeded,
            RejectionReason::QuotaPerNodeLimitExceeded,
            RejectionReason::TenantNotFound,
            RejectionReason::NodeFenced,
            RejectionReason::BudgetExhausted,
            RejectionReason::ReservationExhausted,
            RejectionReason::PlacementPolicyExcluded,
            RejectionReason::NodeAddressUnknown,
            RejectionReason::NodeDrained,
            RejectionReason::EmptyBundle,
            RejectionReason::InsufficientBundleCapacity,
            RejectionReason::BundleConstraintViolation,
            RejectionReason::HardwareGenerationUnavailable,
            RejectionReason::OtherBundleFailure,
        ] {
            assert_ne!(
                reason.as_str(),
                reason.human_summary(),
                "{reason:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    // -----------------------------------------------------------------------
    // Phase 218.3 slice 86 — RevokeState pin tests
    // -----------------------------------------------------------------------

    /// Phase 218.3 slice 86 — `RevokeState::as_str()` snake_case
    /// labels are wire-format-grade. SIEM rules, dashboard panel
    /// selectors, and audit-chain markers alert off these exact
    /// strings. Pin every variant by value so a future variant
    /// rename can't silently shift the wire format.
    #[test]
    fn revoke_state_as_str_is_stable() {
        assert_eq!(RevokeState::Active.as_str(), "active");
        assert_eq!(RevokeState::RevokeWarning.as_str(), "revoke_warning");
        assert_eq!(RevokeState::GraceRunning.as_str(), "grace_running");
        assert_eq!(
            RevokeState::CheckpointReported.as_str(),
            "checkpoint_reported"
        );
        assert_eq!(RevokeState::ForcedTeardown.as_str(), "forced_teardown");
        assert_eq!(RevokeState::Torndown.as_str(), "torndown");
        assert_eq!(RevokeState::Expired.as_str(), "expired");
        assert_eq!(RevokeState::Fenced.as_str(), "fenced");
        assert_eq!(RevokeState::FailedClosed.as_str(), "failed_closed");
    }

    /// `human_summary()` is the CLI / dashboard rendering surface.
    /// Pinning each by value means a renderer can rely on the prose
    /// without re-deriving it; it also catches an accidental rename
    /// that would shift what operators see.
    #[test]
    fn revoke_state_human_summary_is_stable() {
        assert_eq!(
            RevokeState::Active.human_summary(),
            "lease is active; no revoke pending"
        );
        assert_eq!(
            RevokeState::RevokeWarning.human_summary(),
            "revoke initiated; workload has been notified"
        );
        assert_eq!(
            RevokeState::GraceRunning.human_summary(),
            "grace period running; workload may checkpoint"
        );
        assert_eq!(
            RevokeState::CheckpointReported.human_summary(),
            "workload reported checkpoint; cooperative teardown"
        );
        assert_eq!(
            RevokeState::ForcedTeardown.human_summary(),
            "forced teardown in progress; no grace or grace exceeded"
        );
        assert_eq!(
            RevokeState::Torndown.human_summary(),
            "teardown complete; lease released"
        );
        assert_eq!(
            RevokeState::Expired.human_summary(),
            "lease TTL aged out without revoke"
        );
        assert_eq!(
            RevokeState::Fenced.human_summary(),
            "teardown failed; resource fenced for forensic clearing"
        );
        assert_eq!(
            RevokeState::FailedClosed.human_summary(),
            "fail-closed terminal; lease invariant violated"
        );
    }

    /// `human_summary()` carries load-bearing nouns — the reader
    /// should be able to tell what the lifecycle position means
    /// from a glance. Pin the content phrases so a future rewrite
    /// that lost the lifecycle story would fail this lint.
    #[test]
    fn revoke_state_human_summary_load_bearing_phrases() {
        assert!(
            RevokeState::Active.human_summary().contains("active"),
            "Active summary should mention 'active'"
        );
        assert!(
            RevokeState::RevokeWarning
                .human_summary()
                .contains("revoke"),
            "RevokeWarning summary should mention 'revoke'"
        );
        assert!(
            RevokeState::GraceRunning.human_summary().contains("grace"),
            "GraceRunning summary should mention 'grace'"
        );
        assert!(
            RevokeState::CheckpointReported
                .human_summary()
                .contains("checkpoint"),
            "CheckpointReported summary should mention 'checkpoint'"
        );
        assert!(
            RevokeState::ForcedTeardown
                .human_summary()
                .contains("forced"),
            "ForcedTeardown summary should mention 'forced'"
        );
        assert!(
            RevokeState::Torndown.human_summary().contains("teardown"),
            "Torndown summary should mention 'teardown'"
        );
        assert!(
            RevokeState::Expired.human_summary().contains("TTL"),
            "Expired summary should mention 'TTL'"
        );
        assert!(
            RevokeState::Fenced.human_summary().contains("fenced"),
            "Fenced summary should mention 'fenced'"
        );
        assert!(
            RevokeState::FailedClosed
                .human_summary()
                .contains("invariant"),
            "FailedClosed summary should mention 'invariant'"
        );
    }

    /// Nine variants, nine labels, nine summaries — all distinct.
    /// A regression where two variants collapsed to the same string
    /// would silently merge dashboard rows or SIEM filters; pin the
    /// count + distinctness invariant. Also asserts that `as_str()`
    /// values are pairwise disjoint from `human_summary()` values
    /// across all variants — a single combined label set must have
    /// no collisions, so a confusion between the two surfaces would
    /// be caught at build time rather than alert-time.
    #[test]
    fn revoke_state_count_and_distinct() {
        let all = [
            RevokeState::Active,
            RevokeState::RevokeWarning,
            RevokeState::GraceRunning,
            RevokeState::CheckpointReported,
            RevokeState::ForcedTeardown,
            RevokeState::Torndown,
            RevokeState::Expired,
            RevokeState::Fenced,
            RevokeState::FailedClosed,
        ];
        assert_eq!(all.len(), 9, "RevokeState must have exactly 9 variants");

        // as_str() values are pairwise distinct.
        let labels: Vec<&str> = all.iter().map(|s| s.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        // human_summary() values are pairwise distinct.
        let summaries: Vec<&str> = all.iter().map(|s| s.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );

        // Combined: no as_str() value collides with any
        // human_summary() value. Catches a copy-paste regression
        // where one surface accidentally aliased the other.
        let mut combined: Vec<&str> = labels
            .iter()
            .copied()
            .chain(summaries.iter().copied())
            .collect();
        combined.sort_unstable();
        let before = combined.len();
        combined.dedup();
        assert_eq!(
            combined.len(),
            before,
            "as_str and human_summary surfaces must not share any string"
        );
    }

    /// Terminal-state set: Torndown / Fenced / FailedClosed /
    /// Expired report `is_terminal() == true`; the other five
    /// report `false`. Pinning the set means a downstream observer
    /// gating on terminal status (drop the lease handle, finalize
    /// audit emit, settle billing) stays correct under variant
    /// renames.
    #[test]
    fn revoke_state_terminal_set() {
        // Terminals.
        assert!(RevokeState::Torndown.is_terminal());
        assert!(RevokeState::Fenced.is_terminal());
        assert!(RevokeState::FailedClosed.is_terminal());
        assert!(RevokeState::Expired.is_terminal());

        // Non-terminals.
        assert!(!RevokeState::Active.is_terminal());
        assert!(!RevokeState::RevokeWarning.is_terminal());
        assert!(!RevokeState::GraceRunning.is_terminal());
        assert!(!RevokeState::CheckpointReported.is_terminal());
        assert!(!RevokeState::ForcedTeardown.is_terminal());
    }

    /// Legal-transition set: pin every spec arrow plus the two
    /// teardown-failure arrows and the FailedClosed
    /// invariant-violation sink. Asserting illegal transitions are
    /// rejected catches a regression that would silently widen the
    /// state machine.
    #[test]
    fn revoke_state_legal_transitions() {
        use RevokeState::*;

        // Spec arrows from `active`.
        assert!(Active.legal_transition_to(RevokeWarning));
        assert!(Active.legal_transition_to(ForcedTeardown));
        assert!(Active.legal_transition_to(Expired));
        assert!(Active.legal_transition_to(Fenced));

        // Spec interior arrows.
        assert!(RevokeWarning.legal_transition_to(GraceRunning));
        assert!(GraceRunning.legal_transition_to(CheckpointReported));
        assert!(CheckpointReported.legal_transition_to(Torndown));
        assert!(ForcedTeardown.legal_transition_to(Torndown));
        assert!(Expired.legal_transition_to(FailedClosed));

        // Teardown-failure arrows (matches LeaseFenced audit-kind).
        assert!(CheckpointReported.legal_transition_to(Fenced));
        assert!(ForcedTeardown.legal_transition_to(Fenced));

        // FailedClosed sink — reachable from any non-terminal.
        assert!(Active.legal_transition_to(FailedClosed));
        assert!(RevokeWarning.legal_transition_to(FailedClosed));
        assert!(GraceRunning.legal_transition_to(FailedClosed));
        assert!(CheckpointReported.legal_transition_to(FailedClosed));
        assert!(ForcedTeardown.legal_transition_to(FailedClosed));

        // Illegal transitions — terminals don't transition out.
        assert!(!Torndown.legal_transition_to(Active));
        assert!(!Torndown.legal_transition_to(RevokeWarning));
        assert!(!Fenced.legal_transition_to(Active));
        assert!(!FailedClosed.legal_transition_to(Active));

        // Illegal — backward / sideways transitions in the
        // forward path.
        assert!(!RevokeWarning.legal_transition_to(Active));
        assert!(!GraceRunning.legal_transition_to(Active));
        assert!(!GraceRunning.legal_transition_to(RevokeWarning));
        assert!(!CheckpointReported.legal_transition_to(GraceRunning));
        assert!(!CheckpointReported.legal_transition_to(ForcedTeardown));

        // Illegal — `Active` cannot directly reach interior
        // grace / checkpoint / torndown states (must pass through
        // RevokeWarning -> GraceRunning, or ForcedTeardown).
        assert!(!Active.legal_transition_to(GraceRunning));
        assert!(!Active.legal_transition_to(CheckpointReported));
        assert!(!Active.legal_transition_to(Torndown));

        // Illegal — Expired routes only to FailedClosed per spec,
        // not Torndown or Fenced.
        assert!(!Expired.legal_transition_to(Torndown));
        assert!(!Expired.legal_transition_to(Fenced));
        assert!(!Expired.legal_transition_to(Active));
    }

    /// `as_str()` and `human_summary()` are intentionally distinct
    /// surfaces. SIEM rules alert off `as_str()`; `human_summary()`
    /// renders to operators. A consumer that confuses them would
    /// surface snake_case to operators or wire prose into a SIEM
    /// rule.
    #[test]
    fn revoke_state_human_summary_differs_from_as_str() {
        for state in [
            RevokeState::Active,
            RevokeState::RevokeWarning,
            RevokeState::GraceRunning,
            RevokeState::CheckpointReported,
            RevokeState::ForcedTeardown,
            RevokeState::Torndown,
            RevokeState::Expired,
            RevokeState::Fenced,
            RevokeState::FailedClosed,
        ] {
            assert_ne!(
                state.as_str(),
                state.human_summary(),
                "{state:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    /// Display impl matches as_str (matches the convention used by
    /// the rest of the typed-vocab enums).
    #[test]
    fn revoke_state_display_matches_as_str() {
        assert_eq!(format!("{}", RevokeState::Active), "active");
        assert_eq!(format!("{}", RevokeState::RevokeWarning), "revoke_warning");
        assert_eq!(format!("{}", RevokeState::GraceRunning), "grace_running");
        assert_eq!(
            format!("{}", RevokeState::CheckpointReported),
            "checkpoint_reported"
        );
        assert_eq!(
            format!("{}", RevokeState::ForcedTeardown),
            "forced_teardown"
        );
        assert_eq!(format!("{}", RevokeState::Torndown), "torndown");
        assert_eq!(format!("{}", RevokeState::Expired), "expired");
        assert_eq!(format!("{}", RevokeState::Fenced), "fenced");
        assert_eq!(format!("{}", RevokeState::FailedClosed), "failed_closed");
    }

    // -----------------------------------------------------------------------
    // Phase 218.3 slice 122 — RevokeGracePolicy pin tests
    // -----------------------------------------------------------------------

    #[test]
    fn slice_122_hard_revoke_policy_is_default_and_has_no_deadline() {
        let policy = RevokeGracePolicy::default();
        assert_eq!(policy, RevokeGracePolicy::hard_revoke());
        assert!(policy.is_hard_revoke());
        assert!(!policy.checkpoint_hooks_allowed());
        assert_eq!(policy.grace_deadline_unix_secs(1_700_000_000), Ok(None));
    }

    #[test]
    fn slice_122_bounded_grace_policy_accepts_checkpoint_hooks_with_deadline() {
        let policy = RevokeGracePolicy::bounded(30, 120, true).unwrap();
        assert!(!policy.is_hard_revoke());
        assert!(policy.checkpoint_hooks_allowed());
        assert_eq!(
            policy.grace_deadline_unix_secs(1_700_000_000),
            Ok(Some(1_700_000_030))
        );
    }

    #[test]
    fn slice_122_grace_policy_rejects_grace_above_maximum() {
        assert_eq!(
            RevokeGracePolicy::bounded(121, 120, false),
            Err(RevokeGracePolicyError::GraceExceedsMaximum)
        );
    }

    #[test]
    fn slice_122_grace_policy_rejects_checkpoint_hooks_without_grace() {
        assert_eq!(
            RevokeGracePolicy::bounded(0, 0, true),
            Err(RevokeGracePolicyError::CheckpointHooksRequireGrace)
        );
    }

    #[test]
    fn slice_122_grace_deadline_overflow_fails_closed() {
        let policy = RevokeGracePolicy::bounded(30, 30, false).unwrap();
        assert_eq!(
            policy.grace_deadline_unix_secs(u64::MAX - 10),
            Err(RevokeGracePolicyError::DeadlineOverflow)
        );
    }

    #[test]
    fn slice_122_grace_policy_error_labels_are_stable() {
        assert_eq!(
            RevokeGracePolicyError::GraceExceedsMaximum.as_str(),
            "grace_exceeds_maximum"
        );
        assert_eq!(
            RevokeGracePolicyError::CheckpointHooksRequireGrace.as_str(),
            "checkpoint_hooks_require_grace"
        );
        assert_eq!(
            RevokeGracePolicyError::DeadlineOverflow.as_str(),
            "deadline_overflow"
        );

        for err in [
            RevokeGracePolicyError::GraceExceedsMaximum,
            RevokeGracePolicyError::CheckpointHooksRequireGrace,
            RevokeGracePolicyError::DeadlineOverflow,
        ] {
            assert_eq!(format!("{err}"), err.as_str());
            assert_ne!(err.as_str(), err.human_summary());
        }
    }

    // -----------------------------------------------------------------------
    // Phase 218.2 slice 88 — Preemptibility pin tests
    // -----------------------------------------------------------------------

    /// Phase 218.2 slice 88 — `Preemptibility::as_str()` snake_case
    /// labels are wire-format-grade. SIEM rules and dashboard panels
    /// alert off these exact strings. Pin every variant by value.
    #[test]
    fn preemptibility_as_str_is_stable() {
        assert_eq!(Preemptibility::Preemptible.as_str(), "preemptible");
        assert_eq!(Preemptibility::Protected.as_str(), "protected");
    }

    /// `human_summary()` is the CLI / dashboard rendering surface.
    /// Pin each by value so a renderer can rely on the prose without
    /// re-deriving it.
    #[test]
    fn preemptibility_human_summary_is_stable() {
        assert_eq!(
            Preemptibility::Preemptible.human_summary(),
            "accepts preemption per priority rules (default)"
        );
        assert_eq!(
            Preemptibility::Protected.human_summary(),
            "non-preemptible by ordinary scheduling; operator-declared"
        );
    }

    /// Two variants, two labels, two summaries — all distinct.
    #[test]
    fn preemptibility_count_and_distinct() {
        let all = [Preemptibility::Preemptible, Preemptibility::Protected];
        assert_eq!(all.len(), 2, "Preemptibility must have exactly 2 variants");

        let labels: Vec<&str> = all.iter().map(|p| p.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        let summaries: Vec<&str> = all.iter().map(|p| p.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );
    }

    /// `allows_preemption()` is the load-bearing predicate the
    /// preemption manager will consult in the integration slice. Pin
    /// the per-variant truth value so a future variant rename can't
    /// silently flip the policy.
    #[test]
    fn preemptibility_allows_preemption() {
        assert!(Preemptibility::Preemptible.allows_preemption());
        assert!(!Preemptibility::Protected.allows_preemption());
    }

    /// Display impl matches as_str (matches the convention used by
    /// the rest of the typed-vocab enums).
    #[test]
    fn preemptibility_display_matches_as_str() {
        assert_eq!(format!("{}", Preemptibility::Preemptible), "preemptible");
        assert_eq!(format!("{}", Preemptibility::Protected), "protected");
    }

    /// `as_str()` and `human_summary()` are intentionally distinct
    /// surfaces. SIEM rules alert off `as_str()`; `human_summary()`
    /// renders to operators.
    #[test]
    fn preemptibility_human_summary_differs_from_as_str() {
        for p in [Preemptibility::Preemptible, Preemptibility::Protected] {
            assert_ne!(
                p.as_str(),
                p.human_summary(),
                "{p:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    // -----------------------------------------------------------------------
    // Phase 218.2 slice 88 — NonPreemptibleReason pin tests
    // -----------------------------------------------------------------------

    /// Phase 218.2 slice 88 — `NonPreemptibleReason::as_str()`
    /// snake_case labels are wire-format-grade. SIEM rules and the
    /// audit chain group on these exact strings. Pin every variant
    /// by value so a future variant rename can't silently shift the
    /// wire format.
    #[test]
    fn non_preemptible_reason_as_str_is_stable() {
        assert_eq!(
            NonPreemptibleReason::CheckpointInProgress.as_str(),
            "checkpoint_in_progress"
        );
        assert_eq!(
            NonPreemptibleReason::DataPlaneActive.as_str(),
            "data_plane_active"
        );
        assert_eq!(NonPreemptibleReason::OperatorPin.as_str(), "operator_pin");
        assert_eq!(
            NonPreemptibleReason::AttestationLocked.as_str(),
            "attestation_locked"
        );
    }

    /// `human_summary()` is the CLI / dashboard rendering surface.
    /// Pin each by value.
    #[test]
    fn non_preemptible_reason_human_summary_is_stable() {
        assert_eq!(
            NonPreemptibleReason::CheckpointInProgress.human_summary(),
            "lease is mid-checkpoint; preempting would lose the checkpoint"
        );
        assert_eq!(
            NonPreemptibleReason::DataPlaneActive.human_summary(),
            "data-plane binding active; teardown requires coordination"
        );
        assert_eq!(
            NonPreemptibleReason::OperatorPin.human_summary(),
            "operator manually pinned this lease as non-preemptible"
        );
        assert_eq!(
            NonPreemptibleReason::AttestationLocked.human_summary(),
            "attestation chain requires this specific lease holder"
        );
    }

    /// Four variants, four labels, four summaries — all distinct.
    #[test]
    fn non_preemptible_reason_count_and_distinct() {
        let all = [
            NonPreemptibleReason::CheckpointInProgress,
            NonPreemptibleReason::DataPlaneActive,
            NonPreemptibleReason::OperatorPin,
            NonPreemptibleReason::AttestationLocked,
        ];
        assert_eq!(
            all.len(),
            4,
            "NonPreemptibleReason must have exactly 4 variants"
        );

        let labels: Vec<&str> = all.iter().map(|r| r.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        let summaries: Vec<&str> = all.iter().map(|r| r.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );
    }

    /// `human_summary()` carries load-bearing nouns — the reader
    /// should be able to tell why a lease is non-preemptible from a
    /// glance. Pin the content phrases so a future rewrite that lost
    /// the reason would fail this lint.
    #[test]
    fn non_preemptible_reason_load_bearing_phrases() {
        assert!(
            NonPreemptibleReason::CheckpointInProgress
                .human_summary()
                .contains("checkpoint"),
            "CheckpointInProgress summary should mention 'checkpoint'"
        );
        assert!(
            NonPreemptibleReason::DataPlaneActive
                .human_summary()
                .contains("data-plane"),
            "DataPlaneActive summary should mention 'data-plane'"
        );
        assert!(
            NonPreemptibleReason::OperatorPin
                .human_summary()
                .contains("operator"),
            "OperatorPin summary should mention 'operator'"
        );
        assert!(
            NonPreemptibleReason::AttestationLocked
                .human_summary()
                .contains("attestation"),
            "AttestationLocked summary should mention 'attestation'"
        );
    }

    /// Display impl matches as_str (matches the convention used by
    /// the rest of the typed-vocab enums).
    #[test]
    fn non_preemptible_reason_display_matches_as_str() {
        assert_eq!(
            format!("{}", NonPreemptibleReason::CheckpointInProgress),
            "checkpoint_in_progress"
        );
        assert_eq!(
            format!("{}", NonPreemptibleReason::DataPlaneActive),
            "data_plane_active"
        );
        assert_eq!(
            format!("{}", NonPreemptibleReason::OperatorPin),
            "operator_pin"
        );
        assert_eq!(
            format!("{}", NonPreemptibleReason::AttestationLocked),
            "attestation_locked"
        );
    }

    /// `as_str()` and `human_summary()` are intentionally distinct
    /// surfaces. SIEM rules alert off `as_str()`; `human_summary()`
    /// renders to operators.
    #[test]
    fn non_preemptible_reason_human_summary_differs_from_as_str() {
        for r in [
            NonPreemptibleReason::CheckpointInProgress,
            NonPreemptibleReason::DataPlaneActive,
            NonPreemptibleReason::OperatorPin,
            NonPreemptibleReason::AttestationLocked,
        ] {
            assert_ne!(
                r.as_str(),
                r.human_summary(),
                "{r:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    // -----------------------------------------------------------------------
    // Phase 218.5 slice 106 — ResourceBundleSpec primitive pin tests
    // -----------------------------------------------------------------------

    /// Slice 106 — `HardwareGeneration::as_str()` snake_case labels are
    /// wire-format-grade. SIEM rules and dashboard panel selectors
    /// alert off these exact strings. Pin every variant by value.
    #[test]
    fn hardware_generation_as_str_is_stable() {
        assert_eq!(HardwareGeneration::NvidiaAmpere.as_str(), "nvidia_ampere");
        assert_eq!(HardwareGeneration::NvidiaHopper.as_str(), "nvidia_hopper");
        assert_eq!(
            HardwareGeneration::NvidiaBlackwell.as_str(),
            "nvidia_blackwell"
        );
        assert_eq!(HardwareGeneration::AmdMi300.as_str(), "amd_mi300");
        assert_eq!(HardwareGeneration::AmdMi325.as_str(), "amd_mi325");
        assert_eq!(HardwareGeneration::IntelGaudi.as_str(), "intel_gaudi");
        assert_eq!(HardwareGeneration::Other.as_str(), "other");
    }

    /// `human_summary()` is the CLI / dashboard rendering surface.
    /// Pin each by value so a renderer can rely on the prose without
    /// re-deriving it.
    #[test]
    fn hardware_generation_human_summary_is_stable() {
        assert_eq!(
            HardwareGeneration::NvidiaAmpere.human_summary(),
            "NVIDIA Ampere (A100, A30, A40)"
        );
        assert_eq!(
            HardwareGeneration::NvidiaHopper.human_summary(),
            "NVIDIA Hopper (H100, H200)"
        );
        assert_eq!(
            HardwareGeneration::NvidiaBlackwell.human_summary(),
            "NVIDIA Blackwell (B200, GB200)"
        );
        assert_eq!(
            HardwareGeneration::AmdMi300.human_summary(),
            "AMD CDNA3 (MI300, MI300X, MI300A)"
        );
        assert_eq!(
            HardwareGeneration::AmdMi325.human_summary(),
            "AMD CDNA4 (MI325X and newer)"
        );
        assert_eq!(
            HardwareGeneration::IntelGaudi.human_summary(),
            "Intel Gaudi 2 / Gaudi 3"
        );
        assert_eq!(
            HardwareGeneration::Other.human_summary(),
            "other / generic accelerator family"
        );
    }

    /// Seven variants, seven labels, seven summaries — all distinct.
    #[test]
    fn hardware_generation_count_and_distinct() {
        let all = [
            HardwareGeneration::NvidiaAmpere,
            HardwareGeneration::NvidiaHopper,
            HardwareGeneration::NvidiaBlackwell,
            HardwareGeneration::AmdMi300,
            HardwareGeneration::AmdMi325,
            HardwareGeneration::IntelGaudi,
            HardwareGeneration::Other,
        ];
        assert_eq!(
            all.len(),
            7,
            "HardwareGeneration must have exactly 7 variants"
        );

        let labels: Vec<&str> = all.iter().map(|g| g.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        let summaries: Vec<&str> = all.iter().map(|g| g.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );
    }

    /// Each generation's summary carries the load-bearing accelerator
    /// noun (Ampere / Hopper / Blackwell / MI300 / MI325 / Gaudi).
    /// A future rewrite that lost the noun would fail this lint.
    #[test]
    fn hardware_generation_load_bearing_phrases() {
        assert!(
            HardwareGeneration::NvidiaAmpere
                .human_summary()
                .contains("Ampere"),
            "NvidiaAmpere summary should mention 'Ampere'"
        );
        assert!(
            HardwareGeneration::NvidiaHopper
                .human_summary()
                .contains("Hopper"),
            "NvidiaHopper summary should mention 'Hopper'"
        );
        assert!(
            HardwareGeneration::NvidiaBlackwell
                .human_summary()
                .contains("Blackwell"),
            "NvidiaBlackwell summary should mention 'Blackwell'"
        );
        assert!(
            HardwareGeneration::AmdMi300
                .human_summary()
                .contains("MI300"),
            "AmdMi300 summary should mention 'MI300'"
        );
        assert!(
            HardwareGeneration::AmdMi325
                .human_summary()
                .contains("MI325"),
            "AmdMi325 summary should mention 'MI325'"
        );
        assert!(
            HardwareGeneration::IntelGaudi
                .human_summary()
                .contains("Gaudi"),
            "IntelGaudi summary should mention 'Gaudi'"
        );
    }

    /// Display impl matches as_str (matches the convention used by
    /// the rest of the typed-vocab enums).
    #[test]
    fn hardware_generation_display_matches_as_str() {
        for g in [
            HardwareGeneration::NvidiaAmpere,
            HardwareGeneration::NvidiaHopper,
            HardwareGeneration::NvidiaBlackwell,
            HardwareGeneration::AmdMi300,
            HardwareGeneration::AmdMi325,
            HardwareGeneration::IntelGaudi,
            HardwareGeneration::Other,
        ] {
            assert_eq!(format!("{}", g), g.as_str());
        }
    }

    #[test]
    fn hardware_generation_from_str_accepts_canonical_labels() {
        use core::str::FromStr;

        for generation in [
            HardwareGeneration::NvidiaAmpere,
            HardwareGeneration::NvidiaHopper,
            HardwareGeneration::NvidiaBlackwell,
            HardwareGeneration::AmdMi300,
            HardwareGeneration::AmdMi325,
            HardwareGeneration::IntelGaudi,
            HardwareGeneration::Other,
        ] {
            assert_eq!(
                HardwareGeneration::from_str(generation.as_str()),
                Ok(generation)
            );
        }
    }

    #[test]
    fn hardware_generation_from_str_unknown_label_fails_closed() {
        use core::str::FromStr;

        let err = HardwareGeneration::from_str("nvidia-hopper").expect_err("loose label must fail");
        assert_eq!(err, ParseHardwareGenerationError("nvidia-hopper".into()));
    }

    // -----------------------------------------------------------------------
    // Phase 218.1 slice 116 — QuotaSchema primitive pin tests
    // -----------------------------------------------------------------------

    #[test]
    fn quota_schema_default_is_unlimited() {
        let schema = QuotaSchema::default();
        assert!(schema.is_unlimited());
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Mem),
            None
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Gpu),
            None
        );
    }

    #[test]
    fn quota_schema_maps_resource_kind_limits() {
        let schema = QuotaSchema {
            mem_bytes: Some(1024),
            cpu_cores: Some(8),
            gpu_count: Some(2),
            gpu_vram_bytes: Some(80 * 1024 * 1024 * 1024),
            gpu_count_by_generation: Vec::new(),
            block_bytes: Some(4096),
            net_bps: Some(10_000_000_000),
            tasklet_concurrency: Some(64),
            lease_create_per_minute: Some(120),
            burst_credits: None,
            fair_share: None,
        };

        assert!(!schema.is_unlimited());
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Mem),
            Some(1024)
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Cpu),
            Some(8)
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Gpu),
            Some(2)
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::GpuMem),
            Some(80 * 1024 * 1024 * 1024)
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Block),
            Some(4096)
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Net),
            Some(10_000_000_000)
        );
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Tasklet),
            Some(64)
        );
    }

    #[test]
    fn quota_schema_gpu_generation_limits_are_typed() {
        let schema = QuotaSchema {
            gpu_count: None,
            gpu_count_by_generation: vec![
                GpuGenerationQuota {
                    generation: HardwareGeneration::NvidiaAmpere,
                    count: 2,
                },
                GpuGenerationQuota {
                    generation: HardwareGeneration::NvidiaHopper,
                    count: 4,
                },
            ],
            ..QuotaSchema::default()
        };

        assert_eq!(schema.total_gpu_count(), Some(6));
        assert_eq!(
            schema.limit_for_resource_kind(crate::ResourceKind::Gpu),
            Some(6)
        );
        assert_eq!(
            schema.gpu_limit_for_generation(HardwareGeneration::NvidiaAmpere),
            Some(2)
        );
        assert_eq!(
            schema.gpu_limit_for_generation(HardwareGeneration::NvidiaBlackwell),
            None
        );
    }

    #[test]
    fn quota_schema_total_gpu_count_prefers_explicit_total() {
        let schema = QuotaSchema {
            gpu_count: Some(10),
            gpu_count_by_generation: vec![GpuGenerationQuota {
                generation: HardwareGeneration::NvidiaHopper,
                count: 4,
            }],
            ..QuotaSchema::default()
        };

        assert_eq!(schema.total_gpu_count(), Some(10));
    }

    #[test]
    fn quota_usage_maps_resource_kind_usage() {
        let usage = QuotaUsage {
            mem_bytes: 1024,
            cpu_cores: 8,
            gpu_count: 2,
            gpu_vram_bytes: 80,
            gpu_count_by_generation: vec![GpuGenerationQuota {
                generation: HardwareGeneration::NvidiaHopper,
                count: 2,
            }],
            block_bytes: 4096,
            net_bps: 10_000,
            tasklet_concurrency: 64,
            lease_creates_in_window: 12,
        };

        assert_eq!(
            usage.usage_for_resource_kind(crate::ResourceKind::Mem),
            1024
        );
        assert_eq!(usage.usage_for_resource_kind(crate::ResourceKind::Gpu), 2);
        assert_eq!(
            usage.usage_for_resource_kind(crate::ResourceKind::GpuMem),
            80
        );
        assert_eq!(
            usage.gpu_usage_for_generation(HardwareGeneration::NvidiaHopper),
            2
        );
        assert_eq!(
            usage.gpu_usage_for_generation(HardwareGeneration::NvidiaAmpere),
            0
        );
    }

    #[test]
    fn burst_credit_policy_validates_progress_and_window() {
        assert!(BurstCreditPolicy {
            capacity: 100,
            refill_per_minute: 10,
            window_secs: 60,
        }
        .is_valid());

        assert!(!BurstCreditPolicy {
            capacity: 0,
            refill_per_minute: 10,
            window_secs: 60,
        }
        .is_valid());
        assert!(!BurstCreditPolicy {
            capacity: 100,
            refill_per_minute: 0,
            window_secs: 60,
        }
        .is_valid());
        assert!(!BurstCreditPolicy {
            capacity: 100,
            refill_per_minute: 10,
            window_secs: 0,
        }
        .is_valid());
    }

    #[test]
    fn quota_violation_as_str_is_stable() {
        assert_eq!(
            QuotaViolation::MemBytesExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "mem_bytes_exceeded"
        );
        assert_eq!(
            QuotaViolation::CpuCoresExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "cpu_cores_exceeded"
        );
        assert_eq!(
            QuotaViolation::GpuCountExceeded {
                generation: Some(HardwareGeneration::NvidiaHopper),
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "gpu_count_exceeded"
        );
        assert_eq!(
            QuotaViolation::GpuVramBytesExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "gpu_vram_bytes_exceeded"
        );
        assert_eq!(
            QuotaViolation::BlockBytesExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "block_bytes_exceeded"
        );
        assert_eq!(
            QuotaViolation::NetBpsExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "net_bps_exceeded"
        );
        assert_eq!(
            QuotaViolation::TaskletConcurrencyExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "tasklet_concurrency_exceeded"
        );
        assert_eq!(
            QuotaViolation::LeaseCreateRateExceeded {
                limit_per_minute: 1,
                used_in_window: 2,
                requested: 3,
            }
            .as_str(),
            "lease_create_rate_exceeded"
        );
        assert_eq!(
            QuotaViolation::ActiveLeaseCountExceeded {
                limit: 1,
                active: 2,
                requested: 1,
            }
            .as_str(),
            "active_lease_count_exceeded"
        );
        assert_eq!(
            QuotaViolation::PerNodeCapacityExceeded {
                limit: 1,
                used: 2,
                requested: 3,
            }
            .as_str(),
            "per_node_capacity_exceeded"
        );
        assert_eq!(
            QuotaViolation::BurstCreditExhausted {
                capacity: 1,
                remaining: 0,
                requested: 3,
            }
            .as_str(),
            "burst_credit_exhausted"
        );
        assert_eq!(
            QuotaViolation::FairShareExceeded {
                window_secs: 60,
                max_share_secs: 10,
                used_share_secs: 10,
                requested_share_secs: 1,
            }
            .as_str(),
            "fair_share_exceeded"
        );
        assert_eq!(
            QuotaViolation::TenantQuotaMissing.as_str(),
            "tenant_quota_missing"
        );
    }

    #[test]
    fn quota_violation_display_matches_as_str() {
        let violation = QuotaViolation::MemBytesExceeded {
            limit: 1,
            used: 2,
            requested: 3,
        };
        assert_eq!(format!("{violation}"), violation.as_str());
    }

    #[test]
    fn quota_violation_rejection_reason_mapping_is_stable() {
        assert_eq!(
            QuotaViolation::TenantQuotaMissing.rejection_reason(),
            RejectionReason::TenantNotFound
        );
        assert_eq!(
            QuotaViolation::BurstCreditExhausted {
                capacity: 10,
                remaining: 0,
                requested: 1,
            }
            .rejection_reason(),
            RejectionReason::QuotaBurstExceeded
        );
        assert_eq!(
            QuotaViolation::CpuCoresExceeded {
                limit: 1,
                used: 1,
                requested: 1,
            }
            .rejection_reason(),
            RejectionReason::QuotaHardLimitExceeded
        );
    }

    #[cfg(feature = "serde")]
    #[test]
    fn quota_schema_serde_round_trip_uses_snake_case_fields() {
        let schema = QuotaSchema {
            mem_bytes: Some(1024),
            gpu_count_by_generation: vec![GpuGenerationQuota {
                generation: HardwareGeneration::NvidiaHopper,
                count: 2,
            }],
            burst_credits: Some(BurstCreditPolicy {
                capacity: 100,
                refill_per_minute: 10,
                window_secs: 60,
            }),
            ..QuotaSchema::default()
        };

        let json = serde_json::to_string(&schema).expect("serialize quota schema");
        assert!(json.contains("\"mem_bytes\":1024"));
        assert!(json.contains("\"generation\":\"nvidia_hopper\""));
        assert!(json.contains("\"gpu_count_by_generation\""));

        let back: QuotaSchema = serde_json::from_str(&json).expect("deserialize quota schema");
        assert_eq!(back, schema);
    }

    /// Slice 106 — `BundleAtomicity::as_str()` snake_case labels are
    /// wire-format-grade. Pin every variant.
    #[test]
    fn bundle_atomicity_as_str_is_stable() {
        assert_eq!(BundleAtomicity::AllOrNothing.as_str(), "all_or_nothing");
        assert_eq!(BundleAtomicity::BestEffort.as_str(), "best_effort");
    }

    /// `human_summary()` is the CLI / dashboard rendering surface.
    #[test]
    fn bundle_atomicity_human_summary_is_stable() {
        assert_eq!(
            BundleAtomicity::AllOrNothing.human_summary(),
            "all-or-nothing: every requirement granted or none"
        );
        assert_eq!(
            BundleAtomicity::BestEffort.human_summary(),
            "best-effort: grant as many requirements as fit"
        );
    }

    /// Two variants, two labels — all distinct.
    #[test]
    fn bundle_atomicity_count_and_distinct() {
        let all = [BundleAtomicity::AllOrNothing, BundleAtomicity::BestEffort];
        assert_eq!(all.len(), 2, "BundleAtomicity must have exactly 2 variants");

        let labels: Vec<&str> = all.iter().map(|b| b.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        let summaries: Vec<&str> = all.iter().map(|b| b.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );
    }

    /// The default atomicity is `AllOrNothing` — most bundle workloads
    /// are meaningless under a partial grant.
    #[test]
    fn bundle_atomicity_default_is_all_or_nothing() {
        assert_eq!(BundleAtomicity::default(), BundleAtomicity::AllOrNothing);
    }

    /// Display impl matches as_str.
    #[test]
    fn bundle_atomicity_display_matches_as_str() {
        assert_eq!(
            format!("{}", BundleAtomicity::AllOrNothing),
            "all_or_nothing"
        );
        assert_eq!(format!("{}", BundleAtomicity::BestEffort), "best_effort");
    }

    /// Slice 106 — `BundleAdmissionFailure::as_str()` snake_case labels
    /// are wire-format-grade. SIEM rules and the audit chain group on
    /// these exact strings. Pin every variant by value.
    #[test]
    fn bundle_admission_failure_as_str_is_stable() {
        assert_eq!(BundleAdmissionFailure::EmptyBundle.as_str(), "empty_bundle");
        assert_eq!(
            BundleAdmissionFailure::InsufficientBundleCapacity.as_str(),
            "insufficient_bundle_capacity"
        );
        assert_eq!(
            BundleAdmissionFailure::BundleConstraintViolation.as_str(),
            "bundle_constraint_violation"
        );
        assert_eq!(
            BundleAdmissionFailure::HardwareGenerationUnavailable.as_str(),
            "hardware_generation_unavailable"
        );
        assert_eq!(
            BundleAdmissionFailure::OtherBundleFailure.as_str(),
            "other_bundle_failure"
        );
    }

    /// `human_summary()` is the CLI / dashboard rendering surface.
    #[test]
    fn bundle_admission_failure_human_summary_is_stable() {
        assert_eq!(
            BundleAdmissionFailure::EmptyBundle.human_summary(),
            "bundle had zero requirements; nothing to admit"
        );
        assert_eq!(
            BundleAdmissionFailure::InsufficientBundleCapacity.human_summary(),
            "insufficient capacity for at least one requirement; all-or-nothing rejected"
        );
        assert_eq!(
            BundleAdmissionFailure::BundleConstraintViolation.human_summary(),
            "placement constraint excludes every candidate for at least one requirement"
        );
        assert_eq!(
            BundleAdmissionFailure::HardwareGenerationUnavailable.human_summary(),
            "requested hardware generation has no matching inventory in the cluster"
        );
        assert_eq!(
            BundleAdmissionFailure::OtherBundleFailure.human_summary(),
            "other bundle admission failure; reserved catch-all"
        );
    }

    /// Five variants, five labels, five summaries — all distinct.
    #[test]
    fn bundle_admission_failure_count_and_distinct() {
        let all = [
            BundleAdmissionFailure::EmptyBundle,
            BundleAdmissionFailure::InsufficientBundleCapacity,
            BundleAdmissionFailure::BundleConstraintViolation,
            BundleAdmissionFailure::HardwareGenerationUnavailable,
            BundleAdmissionFailure::OtherBundleFailure,
        ];
        assert_eq!(
            all.len(),
            5,
            "BundleAdmissionFailure must have exactly 5 variants"
        );

        let labels: Vec<&str> = all.iter().map(|r| r.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");

        let summaries: Vec<&str> = all.iter().map(|r| r.human_summary()).collect();
        let mut sorted_s = summaries.clone();
        sorted_s.sort_unstable();
        sorted_s.dedup();
        assert_eq!(
            sorted_s.len(),
            summaries.len(),
            "human_summary strings must be distinct"
        );
    }

    /// `human_summary()` carries load-bearing nouns so an operator
    /// can tell why a bundle admission failed at a glance.
    #[test]
    fn bundle_admission_failure_load_bearing_phrases() {
        assert!(
            BundleAdmissionFailure::EmptyBundle
                .human_summary()
                .contains("empty")
                || BundleAdmissionFailure::EmptyBundle
                    .human_summary()
                    .contains("zero"),
            "EmptyBundle summary should mention 'empty' or 'zero'"
        );
        assert!(
            BundleAdmissionFailure::InsufficientBundleCapacity
                .human_summary()
                .contains("capacity"),
            "InsufficientBundleCapacity summary should mention 'capacity'"
        );
        assert!(
            BundleAdmissionFailure::BundleConstraintViolation
                .human_summary()
                .contains("placement")
                || BundleAdmissionFailure::BundleConstraintViolation
                    .human_summary()
                    .contains("constraint"),
            "BundleConstraintViolation summary should mention 'placement' or 'constraint'"
        );
        assert!(
            BundleAdmissionFailure::HardwareGenerationUnavailable
                .human_summary()
                .contains("hardware generation")
                || BundleAdmissionFailure::HardwareGenerationUnavailable
                    .human_summary()
                    .contains("inventory"),
            "HardwareGenerationUnavailable summary should mention 'hardware generation' or 'inventory'"
        );
        assert!(
            BundleAdmissionFailure::OtherBundleFailure
                .human_summary()
                .contains("catch-all")
                || BundleAdmissionFailure::OtherBundleFailure
                    .human_summary()
                    .contains("other"),
            "OtherBundleFailure summary should mention 'catch-all' or 'other'"
        );
    }

    /// Display impl matches as_str.
    #[test]
    fn bundle_admission_failure_display_matches_as_str() {
        for r in [
            BundleAdmissionFailure::EmptyBundle,
            BundleAdmissionFailure::InsufficientBundleCapacity,
            BundleAdmissionFailure::BundleConstraintViolation,
            BundleAdmissionFailure::HardwareGenerationUnavailable,
            BundleAdmissionFailure::OtherBundleFailure,
        ] {
            assert_eq!(format!("{}", r), r.as_str());
        }
    }

    #[test]
    fn bundle_admission_failure_rejection_reason_fold_is_stable() {
        let cases = [
            (
                BundleAdmissionFailure::EmptyBundle,
                RejectionReason::EmptyBundle,
            ),
            (
                BundleAdmissionFailure::InsufficientBundleCapacity,
                RejectionReason::InsufficientBundleCapacity,
            ),
            (
                BundleAdmissionFailure::BundleConstraintViolation,
                RejectionReason::BundleConstraintViolation,
            ),
            (
                BundleAdmissionFailure::HardwareGenerationUnavailable,
                RejectionReason::HardwareGenerationUnavailable,
            ),
            (
                BundleAdmissionFailure::OtherBundleFailure,
                RejectionReason::OtherBundleFailure,
            ),
        ];

        for (bundle_failure, rejection_reason) in cases {
            assert_eq!(bundle_failure.rejection_reason(), rejection_reason);
            assert_eq!(
                bundle_failure.as_str(),
                rejection_reason.as_str(),
                "bundle fold must preserve the stable admissions label"
            );
        }
    }

    // -----------------------------------------------------------------------
    // Phase 218.5 slice 108 — BundleDecision pin tests
    // -----------------------------------------------------------------------

    /// Slice 108 — `BundleDecision::as_str()` snake_case labels are
    /// wire-format-grade. SIEM rules and the audit chain group on
    /// these exact strings. Pin every variant by value.
    #[test]
    fn bundle_decision_as_str_is_stable() {
        assert_eq!(BundleDecision::Approved.as_str(), "approved");
        assert_eq!(
            BundleDecision::DeniedAllOrNothing.as_str(),
            "denied_all_or_nothing"
        );
        assert_eq!(BundleDecision::DeniedEmpty.as_str(), "denied_empty");
        assert_eq!(
            BundleDecision::PartialBestEffort.as_str(),
            "partial_best_effort"
        );
    }

    /// Slice 108 — four variants. Adding a new outcome shape is
    /// wire-format-grade.
    #[test]
    fn bundle_decision_has_exactly_four_variants() {
        let all = [
            BundleDecision::Approved,
            BundleDecision::DeniedAllOrNothing,
            BundleDecision::DeniedEmpty,
            BundleDecision::PartialBestEffort,
        ];
        assert_eq!(all.len(), 4, "BundleDecision must have exactly 4 variants");
        let labels: Vec<&str> = all.iter().map(|d| d.as_str()).collect();
        let mut sorted = labels.clone();
        sorted.sort_unstable();
        sorted.dedup();
        assert_eq!(sorted.len(), labels.len(), "as_str labels must be distinct");
    }

    /// Slice 108 — `Display` impl matches `as_str()`.
    #[test]
    fn bundle_decision_display_matches_as_str() {
        for d in [
            BundleDecision::Approved,
            BundleDecision::DeniedAllOrNothing,
            BundleDecision::DeniedEmpty,
            BundleDecision::PartialBestEffort,
        ] {
            assert_eq!(format!("{}", d), d.as_str());
        }
    }

    /// Slice 108 — `human_summary()` is a distinct surface from
    /// `as_str()`.
    #[test]
    fn bundle_decision_human_summary_differs_from_as_str() {
        for d in [
            BundleDecision::Approved,
            BundleDecision::DeniedAllOrNothing,
            BundleDecision::DeniedEmpty,
            BundleDecision::PartialBestEffort,
        ] {
            assert_ne!(
                d.as_str(),
                d.human_summary(),
                "{d:?}: as_str and human_summary must differ"
            );
        }
    }

    /// `as_str()` and `human_summary()` are intentionally distinct
    /// surfaces.
    #[test]
    fn bundle_admission_failure_human_summary_differs_from_as_str() {
        for r in [
            BundleAdmissionFailure::EmptyBundle,
            BundleAdmissionFailure::InsufficientBundleCapacity,
            BundleAdmissionFailure::BundleConstraintViolation,
            BundleAdmissionFailure::HardwareGenerationUnavailable,
            BundleAdmissionFailure::OtherBundleFailure,
        ] {
            assert_ne!(
                r.as_str(),
                r.human_summary(),
                "{r:?}: as_str and human_summary must be different surfaces"
            );
        }
    }

    /// `ResourceBundleSpec::default()` is an empty `AllOrNothing`
    /// bundle. Pin so a future Default impl change can't shift the
    /// scheduler's interpretation of "default bundle".
    #[test]
    fn resource_bundle_spec_default_is_empty_all_or_nothing() {
        let spec = ResourceBundleSpec::default();
        assert!(
            spec.requirements.is_empty(),
            "Default ResourceBundleSpec must have no requirements"
        );
        assert_eq!(
            spec.atomicity,
            BundleAtomicity::AllOrNothing,
            "Default ResourceBundleSpec atomicity must be AllOrNothing"
        );
    }

    /// A `ResourceRequirement` can declare an optional hardware
    /// generation. Pin so the field stays `Option<HardwareGeneration>`
    /// (a future widening to a free-form String would fail this build).
    #[test]
    fn resource_requirement_can_have_optional_hardware_generation() {
        // No generation constraint.
        let any = ResourceRequirement {
            kind: crate::ResourceKind::Gpu,
            capacity: 80 * 1024 * 1024 * 1024,
            hardware_generation: None,
        };
        assert!(any.hardware_generation.is_none());

        // Pinned to a specific generation.
        let h100 = ResourceRequirement {
            kind: crate::ResourceKind::Gpu,
            capacity: 80 * 1024 * 1024 * 1024,
            hardware_generation: Some(HardwareGeneration::NvidiaHopper),
        };
        assert_eq!(
            h100.hardware_generation,
            Some(HardwareGeneration::NvidiaHopper)
        );
    }

    /// Slice 106 — pin the canonical JSON wire shape of a
    /// `ResourceBundleSpec` round-trip. Field names are snake_case
    /// (struct fields are already snake_case in Rust); enum variants
    /// inside the spec serialize as snake_case thanks to the
    /// slice-90 `rename_all` discipline.
    #[cfg(feature = "serde")]
    #[test]
    fn resource_bundle_spec_round_trips_through_serde() {
        let spec = ResourceBundleSpec {
            requirements: vec![
                ResourceRequirement {
                    kind: crate::ResourceKind::Cpu,
                    capacity: 8,
                    hardware_generation: None,
                },
                ResourceRequirement {
                    kind: crate::ResourceKind::Gpu,
                    capacity: 80 * 1024 * 1024 * 1024,
                    hardware_generation: Some(HardwareGeneration::NvidiaHopper),
                },
            ],
            atomicity: BundleAtomicity::AllOrNothing,
        };
        let json = serde_json::to_string(&spec).expect("serialize");
        // Pin load-bearing wire substrings (snake_case discipline).
        assert!(json.contains("\"atomicity\":\"all_or_nothing\""), "{json}");
        assert!(
            json.contains("\"hardware_generation\":\"nvidia_hopper\""),
            "{json}"
        );
        assert!(json.contains("\"hardware_generation\":null"), "{json}");
        let back: ResourceBundleSpec = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(back, spec);
    }

    // -----------------------------------------------------------------------
    // Phase 218-222 slice 90 — wire-format-drift closure
    //
    // Every typed enum in this module now carries
    // `#[serde(rename_all = "snake_case")]` plus per-variant
    // `#[serde(alias = "PascalCase")]` for back-compat with pre-slice-90
    // records on disk. The tests below pin both directions of the migration
    // window so a future refactor cannot:
    //   - silently drop the `rename_all` (would re-introduce PascalCase
    //     drift), or
    //   - drop the per-variant alias attributes (would break legacy chain
    //     parsing during the migration window).
    // The migration window's exit criterion is tracked as a sub-bullet
    // under TODO.md Phase 218.2 — alias removal is a separate slice.
    // -----------------------------------------------------------------------

    /// Slice 90 — every variant of every typed enum that has a
    /// snake_case `as_str()` serializes through serde to the SAME
    /// snake_case string. The `as_str()` and serde paths are now
    /// the single source of truth on the JSON wire.
    ///
    /// `EvidenceLabel` is excluded from this single-source pin because
    /// its `as_str()` returns operator-prose with spaces (intentional
    /// for the docs-lint surface) — its serde shape is canonical
    /// snake_case but it does not match `as_str()` byte-for-byte. A
    /// dedicated `evidence_label_serde_round_trip` test below pins
    /// the EvidenceLabel wire shape independently.
    #[cfg(feature = "serde")]
    #[test]
    fn snake_case_serde_matches_as_str_round_trip() {
        macro_rules! pin {
            ($($value:expr),* $(,)?) => {{
                $({
                    let v = $value;
                    let json = serde_json::to_string(&v).expect("serialize");
                    let expected = format!("\"{}\"", v.as_str());
                    assert_eq!(
                        json, expected,
                        "{:?}: serde wire shape must match as_str() (slice 90 \
                         single-source-of-truth)",
                        v
                    );
                })*
            }};
        }

        pin!(
            // PreemptionReason
            PreemptionReason::PriorityPreemption,
            PreemptionReason::QuotaRebalance,
            PreemptionReason::BurstCreditExhausted,
            PreemptionReason::BudgetExhausted,
            PreemptionReason::CostCapEviction,
            PreemptionReason::OperatorDrain,
            PreemptionReason::OperatorMigProfileChange,
            PreemptionReason::MaintenanceWindow,
            PreemptionReason::PolicyViolationRecovery,
            // Priority
            Priority::Scavenger,
            Priority::Standard,
            Priority::Guaranteed,
            // RejectionReason
            RejectionReason::InsufficientCapacity,
            RejectionReason::NoEligibleNodes,
            RejectionReason::QuotaHardLimitExceeded,
            RejectionReason::QuotaBurstExceeded,
            RejectionReason::QuotaLeaseCountExceeded,
            RejectionReason::QuotaPerNodeLimitExceeded,
            RejectionReason::TenantNotFound,
            RejectionReason::NodeFenced,
            RejectionReason::BudgetExhausted,
            RejectionReason::ReservationExhausted,
            RejectionReason::PlacementPolicyExcluded,
            RejectionReason::NodeAddressUnknown,
            RejectionReason::NodeDrained,
            RejectionReason::EmptyBundle,
            RejectionReason::InsufficientBundleCapacity,
            RejectionReason::BundleConstraintViolation,
            RejectionReason::HardwareGenerationUnavailable,
            RejectionReason::OtherBundleFailure,
            // EgressEnforcement
            EgressEnforcement::FabricEnforced,
            EgressEnforcement::HostRuntimeIntegration,
            EgressEnforcement::OperatorControlled,
            EgressEnforcement::Unsupported,
            // EgressTarget
            EgressTarget::WasmTasklet,
            EgressTarget::NativeProgram,
            EgressTarget::ContainerAdjacent,
            EgressTarget::KubernetesDra,
            EgressTarget::BareMetal,
            // EconomicsSource
            EconomicsSource::OperatorStaticConfig,
            EconomicsSource::ProviderPriceSheet,
            EconomicsSource::ProviderUsageExport,
            EconomicsSource::MeasuredPowerTelemetry,
            EconomicsSource::ThirdPartyCarbonFeed,
            EconomicsSource::DerivedEstimate,
            // ObservationConfidence
            ObservationConfidence::Low,
            ObservationConfidence::Medium,
            ObservationConfidence::High,
            // RevokeState
            RevokeState::Active,
            RevokeState::RevokeWarning,
            RevokeState::GraceRunning,
            RevokeState::CheckpointReported,
            RevokeState::ForcedTeardown,
            RevokeState::Torndown,
            RevokeState::Expired,
            RevokeState::Fenced,
            RevokeState::FailedClosed,
            // Preemptibility
            Preemptibility::Preemptible,
            Preemptibility::Protected,
            // NonPreemptibleReason
            NonPreemptibleReason::CheckpointInProgress,
            NonPreemptibleReason::DataPlaneActive,
            NonPreemptibleReason::OperatorPin,
            NonPreemptibleReason::AttestationLocked,
            // Phase 218.5 slice 106 — bundle vocabulary
            HardwareGeneration::NvidiaAmpere,
            HardwareGeneration::NvidiaHopper,
            HardwareGeneration::NvidiaBlackwell,
            HardwareGeneration::AmdMi300,
            HardwareGeneration::AmdMi325,
            HardwareGeneration::IntelGaudi,
            HardwareGeneration::Other,
            BundleAtomicity::AllOrNothing,
            BundleAtomicity::BestEffort,
            BundleAdmissionFailure::EmptyBundle,
            BundleAdmissionFailure::InsufficientBundleCapacity,
            BundleAdmissionFailure::BundleConstraintViolation,
            BundleAdmissionFailure::HardwareGenerationUnavailable,
            BundleAdmissionFailure::OtherBundleFailure,
            // Phase 218.5 slice 108 — BundleDecision summary
            BundleDecision::Approved,
            BundleDecision::DeniedAllOrNothing,
            BundleDecision::DeniedEmpty,
            BundleDecision::PartialBestEffort,
            // AuditEventKind
            AuditEventKind::CapabilityIssued,
            AuditEventKind::CapabilityRevoked,
            AuditEventKind::LeaseAllocated,
            AuditEventKind::LeaseRenewed,
            AuditEventKind::LeaseReleased,
            AuditEventKind::LeaseExpired,
            AuditEventKind::LeaseTorndown,
            AuditEventKind::LeaseFenced,
            AuditEventKind::AdmissionDecided,
            AuditEventKind::Preempted,
            AuditEventKind::DrainInitiated,
            AuditEventKind::ChainAnchored,
            AuditEventKind::SoftModeEnabled,
            AuditEventKind::TenantCreated,
            AuditEventKind::TenantDeleted,
            AuditEventKind::TenantQuotaUpdated,
            AuditEventKind::ProviderConformanceRecorded,
            AuditEventKind::ProviderBootstrapTokenIssued,
            AuditEventKind::ProviderBootstrapExchanged,
            AuditEventKind::ProviderCellIdentityIssued,
            AuditEventKind::ProviderCellIdentityRotated,
            AuditEventKind::ProviderCellIdentityRevoked,
            AuditEventKind::BearerTokenIssued,
            AuditEventKind::BearerTokenRevoked,
            AuditEventKind::SchedulerPromoted,
            AuditEventKind::BillingRateCardInstalled,
        );
    }

    /// Slice 90 — every variant of every typed enum also DESERIALIZES
    /// from its `as_str()` value (the canonical snake_case wire shape).
    /// Together with `snake_case_serde_matches_as_str_round_trip`, this
    /// is the symmetric round-trip pin for every variant.
    #[cfg(feature = "serde")]
    #[test]
    fn snake_case_serde_deserialize_round_trip() {
        macro_rules! pin {
            ($ty:ty: $($value:expr),* $(,)?) => {{
                $({
                    let v = $value;
                    let s = format!("\"{}\"", v.as_str());
                    let back: $ty = serde_json::from_str(&s)
                        .expect(&format!("must deserialize from snake_case for {:?}", v));
                    assert_eq!(back, v, "round-trip mismatch for {:?}", v);
                })*
            }};
        }

        pin!(PreemptionReason:
            PreemptionReason::PriorityPreemption,
            PreemptionReason::QuotaRebalance,
            PreemptionReason::BurstCreditExhausted,
            PreemptionReason::BudgetExhausted,
            PreemptionReason::CostCapEviction,
            PreemptionReason::OperatorDrain,
            PreemptionReason::OperatorMigProfileChange,
            PreemptionReason::MaintenanceWindow,
            PreemptionReason::PolicyViolationRecovery,
        );
        pin!(Priority:
            Priority::Scavenger,
            Priority::Standard,
            Priority::Guaranteed,
        );
        pin!(RejectionReason:
            RejectionReason::InsufficientCapacity,
            RejectionReason::NoEligibleNodes,
            RejectionReason::QuotaHardLimitExceeded,
            RejectionReason::QuotaBurstExceeded,
            RejectionReason::QuotaLeaseCountExceeded,
            RejectionReason::QuotaPerNodeLimitExceeded,
            RejectionReason::TenantNotFound,
            RejectionReason::NodeFenced,
            RejectionReason::BudgetExhausted,
            RejectionReason::ReservationExhausted,
            RejectionReason::PlacementPolicyExcluded,
            RejectionReason::NodeAddressUnknown,
            RejectionReason::NodeDrained,
            RejectionReason::EmptyBundle,
            RejectionReason::InsufficientBundleCapacity,
            RejectionReason::BundleConstraintViolation,
            RejectionReason::HardwareGenerationUnavailable,
            RejectionReason::OtherBundleFailure,
        );
        pin!(EgressEnforcement:
            EgressEnforcement::FabricEnforced,
            EgressEnforcement::HostRuntimeIntegration,
            EgressEnforcement::OperatorControlled,
            EgressEnforcement::Unsupported,
        );
        pin!(EgressTarget:
            EgressTarget::WasmTasklet,
            EgressTarget::NativeProgram,
            EgressTarget::ContainerAdjacent,
            EgressTarget::KubernetesDra,
            EgressTarget::BareMetal,
        );
        pin!(EconomicsSource:
            EconomicsSource::OperatorStaticConfig,
            EconomicsSource::ProviderPriceSheet,
            EconomicsSource::ProviderUsageExport,
            EconomicsSource::MeasuredPowerTelemetry,
            EconomicsSource::ThirdPartyCarbonFeed,
            EconomicsSource::DerivedEstimate,
        );
        pin!(ObservationConfidence:
            ObservationConfidence::Low,
            ObservationConfidence::Medium,
            ObservationConfidence::High,
        );
        pin!(RevokeState:
            RevokeState::Active,
            RevokeState::RevokeWarning,
            RevokeState::GraceRunning,
            RevokeState::CheckpointReported,
            RevokeState::ForcedTeardown,
            RevokeState::Torndown,
            RevokeState::Expired,
            RevokeState::Fenced,
            RevokeState::FailedClosed,
        );
        pin!(Preemptibility:
            Preemptibility::Preemptible,
            Preemptibility::Protected,
        );
        pin!(NonPreemptibleReason:
            NonPreemptibleReason::CheckpointInProgress,
            NonPreemptibleReason::DataPlaneActive,
            NonPreemptibleReason::OperatorPin,
            NonPreemptibleReason::AttestationLocked,
        );
        // Phase 218.5 slice 106 — bundle vocabulary deserialize coverage.
        // No PascalCase alias attributes (no legacy wire data for the new
        // primitive — they have never been on disk), so this round-trip
        // pin is one-direction snake_case only.
        pin!(HardwareGeneration:
            HardwareGeneration::NvidiaAmpere,
            HardwareGeneration::NvidiaHopper,
            HardwareGeneration::NvidiaBlackwell,
            HardwareGeneration::AmdMi300,
            HardwareGeneration::AmdMi325,
            HardwareGeneration::IntelGaudi,
            HardwareGeneration::Other,
        );
        pin!(BundleAtomicity:
            BundleAtomicity::AllOrNothing,
            BundleAtomicity::BestEffort,
        );
        pin!(BundleAdmissionFailure:
            BundleAdmissionFailure::EmptyBundle,
            BundleAdmissionFailure::InsufficientBundleCapacity,
            BundleAdmissionFailure::BundleConstraintViolation,
            BundleAdmissionFailure::HardwareGenerationUnavailable,
            BundleAdmissionFailure::OtherBundleFailure,
        );
        // Phase 218.5 slice 108 — BundleDecision deserialize coverage.
        // No PascalCase alias attributes (new primitive, never on disk),
        // so snake_case only.
        pin!(BundleDecision:
            BundleDecision::Approved,
            BundleDecision::DeniedAllOrNothing,
            BundleDecision::DeniedEmpty,
            BundleDecision::PartialBestEffort,
        );
        pin!(AuditEventKind:
            AuditEventKind::CapabilityIssued,
            AuditEventKind::CapabilityRevoked,
            AuditEventKind::LeaseAllocated,
            AuditEventKind::LeaseRenewed,
            AuditEventKind::LeaseReleased,
            AuditEventKind::LeaseExpired,
            AuditEventKind::LeaseTorndown,
            AuditEventKind::LeaseFenced,
            AuditEventKind::AdmissionDecided,
            AuditEventKind::Preempted,
            AuditEventKind::DrainInitiated,
            AuditEventKind::ChainAnchored,
            AuditEventKind::SoftModeEnabled,
            AuditEventKind::TenantCreated,
            AuditEventKind::TenantDeleted,
            AuditEventKind::TenantQuotaUpdated,
            AuditEventKind::ProviderConformanceRecorded,
            AuditEventKind::ProviderBootstrapTokenIssued,
            AuditEventKind::ProviderBootstrapExchanged,
            AuditEventKind::ProviderCellIdentityIssued,
            AuditEventKind::ProviderCellIdentityRotated,
            AuditEventKind::ProviderCellIdentityRevoked,
            AuditEventKind::BearerTokenIssued,
            AuditEventKind::BearerTokenRevoked,
            AuditEventKind::SchedulerPromoted,
            AuditEventKind::BillingRateCardInstalled,
        );
    }

    /// Slice 90 — pre-slice-90 records on disk carry the
    /// PascalCase variant form (`"AdmissionDecided"`, `"Standard"`,
    /// etc.). The migration window guarantees those records still
    /// parse: every variant is reachable from BOTH the canonical
    /// snake_case label AND the legacy PascalCase form. This pin
    /// proves the back-compat alias attributes are wired on every
    /// variant of every typed enum — without it, dropping an alias
    /// silently breaks legacy chain parsing.
    ///
    /// Helper macro pattern: the PascalCase form is the variant's
    /// Debug name (which is what `{:?}` emits for a unit variant).
    /// We synthesize the JSON literal from `format!("{:?}", v)`.
    #[cfg(feature = "serde")]
    #[test]
    fn pascal_case_legacy_alias_round_trip() {
        macro_rules! pin {
            ($ty:ty: $($value:expr),* $(,)?) => {{
                $({
                    let v = $value;
                    let pascal = format!("{:?}", v);
                    let json = format!("\"{}\"", pascal);
                    let back: $ty = serde_json::from_str(&json).unwrap_or_else(|e| {
                        panic!("legacy PascalCase {} must parse for {:?}: {}", json, v, e)
                    });
                    assert_eq!(back, v, "alias mismatch for legacy {} -> {:?}", json, v);
                })*
            }};
        }

        pin!(PreemptionReason:
            PreemptionReason::PriorityPreemption,
            PreemptionReason::QuotaRebalance,
            PreemptionReason::BurstCreditExhausted,
            PreemptionReason::BudgetExhausted,
            PreemptionReason::CostCapEviction,
            PreemptionReason::OperatorDrain,
            PreemptionReason::OperatorMigProfileChange,
            PreemptionReason::MaintenanceWindow,
            PreemptionReason::PolicyViolationRecovery,
        );
        pin!(Priority:
            Priority::Scavenger,
            Priority::Standard,
            Priority::Guaranteed,
        );
        pin!(EvidenceLabel:
            EvidenceLabel::DesignTarget,
            EvidenceLabel::UnitIntegrationEvidence,
            EvidenceLabel::LabEvidence,
            EvidenceLabel::StagedProviderEvidence,
            EvidenceLabel::DesignPartnerEvidence,
            EvidenceLabel::ProductionEvidence,
        );
        pin!(RejectionReason:
            RejectionReason::InsufficientCapacity,
            RejectionReason::NoEligibleNodes,
            RejectionReason::QuotaHardLimitExceeded,
            RejectionReason::QuotaBurstExceeded,
            RejectionReason::QuotaLeaseCountExceeded,
            RejectionReason::QuotaPerNodeLimitExceeded,
            RejectionReason::TenantNotFound,
            RejectionReason::NodeFenced,
            RejectionReason::BudgetExhausted,
            RejectionReason::ReservationExhausted,
            RejectionReason::PlacementPolicyExcluded,
            RejectionReason::NodeAddressUnknown,
            RejectionReason::NodeDrained,
            RejectionReason::EmptyBundle,
            RejectionReason::InsufficientBundleCapacity,
            RejectionReason::BundleConstraintViolation,
            RejectionReason::HardwareGenerationUnavailable,
            RejectionReason::OtherBundleFailure,
        );
        pin!(EgressEnforcement:
            EgressEnforcement::FabricEnforced,
            EgressEnforcement::HostRuntimeIntegration,
            EgressEnforcement::OperatorControlled,
            EgressEnforcement::Unsupported,
        );
        pin!(EgressTarget:
            EgressTarget::WasmTasklet,
            EgressTarget::NativeProgram,
            EgressTarget::ContainerAdjacent,
            EgressTarget::KubernetesDra,
            EgressTarget::BareMetal,
        );
        pin!(EconomicsSource:
            EconomicsSource::OperatorStaticConfig,
            EconomicsSource::ProviderPriceSheet,
            EconomicsSource::ProviderUsageExport,
            EconomicsSource::MeasuredPowerTelemetry,
            EconomicsSource::ThirdPartyCarbonFeed,
            EconomicsSource::DerivedEstimate,
        );
        pin!(ObservationConfidence:
            ObservationConfidence::Low,
            ObservationConfidence::Medium,
            ObservationConfidence::High,
        );
        pin!(RevokeState:
            RevokeState::Active,
            RevokeState::RevokeWarning,
            RevokeState::GraceRunning,
            RevokeState::CheckpointReported,
            RevokeState::ForcedTeardown,
            RevokeState::Torndown,
            RevokeState::Expired,
            RevokeState::Fenced,
            RevokeState::FailedClosed,
        );
        pin!(Preemptibility:
            Preemptibility::Preemptible,
            Preemptibility::Protected,
        );
        pin!(NonPreemptibleReason:
            NonPreemptibleReason::CheckpointInProgress,
            NonPreemptibleReason::DataPlaneActive,
            NonPreemptibleReason::OperatorPin,
            NonPreemptibleReason::AttestationLocked,
        );
        pin!(AuditEventKind:
            AuditEventKind::CapabilityIssued,
            AuditEventKind::CapabilityRevoked,
            AuditEventKind::LeaseAllocated,
            AuditEventKind::LeaseRenewed,
            AuditEventKind::LeaseReleased,
            AuditEventKind::LeaseExpired,
            AuditEventKind::LeaseTorndown,
            AuditEventKind::LeaseFenced,
            AuditEventKind::AdmissionDecided,
            AuditEventKind::Preempted,
            AuditEventKind::DrainInitiated,
            AuditEventKind::ChainAnchored,
            AuditEventKind::SoftModeEnabled,
            AuditEventKind::TenantCreated,
            AuditEventKind::TenantDeleted,
            AuditEventKind::TenantQuotaUpdated,
            AuditEventKind::ProviderConformanceRecorded,
            AuditEventKind::ProviderBootstrapTokenIssued,
            AuditEventKind::ProviderBootstrapExchanged,
            AuditEventKind::ProviderCellIdentityIssued,
            AuditEventKind::ProviderCellIdentityRotated,
            AuditEventKind::ProviderCellIdentityRevoked,
            AuditEventKind::BearerTokenIssued,
            AuditEventKind::BearerTokenRevoked,
            AuditEventKind::SchedulerPromoted,
            AuditEventKind::BillingRateCardInstalled,
        );
    }

    /// Slice 90 — `EvidenceLabel` is excluded from the
    /// `as_str()` single-source-of-truth pin because its
    /// `as_str()` returns operator-prose with spaces and slashes
    /// (`"design target"`, `"unit/integration evidence"`) for the
    /// docs-lint surface. Pin its serde wire shape independently:
    /// canonical snake_case from `rename_all`, alias to legacy
    /// PascalCase. The serde JSON wire is distinct from the
    /// docs-lint string surface — both are valid by design.
    #[cfg(feature = "serde")]
    #[test]
    fn evidence_label_serde_wire_shape() {
        // Canonical snake_case wire shape.
        for (variant, expected) in [
            (EvidenceLabel::DesignTarget, "design_target"),
            (
                EvidenceLabel::UnitIntegrationEvidence,
                "unit_integration_evidence",
            ),
            (EvidenceLabel::LabEvidence, "lab_evidence"),
            (
                EvidenceLabel::StagedProviderEvidence,
                "staged_provider_evidence",
            ),
            (
                EvidenceLabel::DesignPartnerEvidence,
                "design_partner_evidence",
            ),
            (EvidenceLabel::ProductionEvidence, "production_evidence"),
        ] {
            let json = serde_json::to_string(&variant).expect("serialize");
            assert_eq!(
                json,
                format!("\"{}\"", expected),
                "{:?} wire shape mismatch",
                variant
            );
            let back: EvidenceLabel = serde_json::from_str(&json).expect("deserialize canonical");
            assert_eq!(back, variant);
        }
    }

    /// Slice 90 — typo protection: an unknown JSON string for any
    /// typed enum fails closed at deserialize time. Without this
    /// pin a future refactor that relaxed serde to accept arbitrary
    /// strings would silently propagate typos through the wire.
    #[cfg(feature = "serde")]
    #[test]
    fn snake_case_serde_rejects_unknown_strings() {
        assert!(serde_json::from_str::<Priority>("\"bogus\"").is_err());
        assert!(serde_json::from_str::<AuditEventKind>("\"not_a_kind\"").is_err());
        assert!(serde_json::from_str::<RevokeState>("\"in_between\"").is_err());
        assert!(serde_json::from_str::<RejectionReason>("\"placeholder\"").is_err());
        assert!(serde_json::from_str::<Preemptibility>("\"\"").is_err());
        assert!(serde_json::from_str::<NonPreemptibleReason>("\"unknown\"").is_err());
        // Phase 218.5 slice 106 — bundle vocabulary fails closed on
        // unknown strings (no String escape hatch).
        assert!(serde_json::from_str::<HardwareGeneration>("\"unknown_gpu\"").is_err());
        assert!(serde_json::from_str::<BundleAtomicity>("\"maybe\"").is_err());
        assert!(serde_json::from_str::<BundleAdmissionFailure>("\"no_reason\"").is_err());
    }
}