grafos_observe/

metrics.rs

//! Core metrics types for fabric observability.
//!
//! All types use atomics and work in `no_std` environments. The
//! [`FabricMetrics`] singleton collects system-wide counters and gauges.

use core::sync::atomic::{AtomicI64, AtomicU64, Ordering};

/// Monotonically increasing counter (atomic u64).
///
/// Counters only go up — use them for totals like "operations completed"
/// or "bytes transferred". Thread-safe via relaxed atomic operations.
///
/// # Examples
///
/// ```
/// use grafos_observe::MetricCounter;
///
/// let c = MetricCounter::new();
/// c.inc();
/// c.add(10);
/// assert_eq!(c.get(), 11);
///
/// let prev = c.reset();
/// assert_eq!(prev, 11);
/// assert_eq!(c.get(), 0);
/// ```
pub struct MetricCounter {
    value: AtomicU64,
}

impl Default for MetricCounter {
    fn default() -> Self {
        Self::new()
    }
}

impl MetricCounter {
    /// Create a new counter starting at zero.
    pub const fn new() -> Self {
        Self {
            value: AtomicU64::new(0),
        }
    }

    /// Increment the counter by one.
    pub fn inc(&self) {
        self.value.fetch_add(1, Ordering::Relaxed);
    }

    /// Increment the counter by `n`.
    pub fn add(&self, n: u64) {
        self.value.fetch_add(n, Ordering::Relaxed);
    }

    /// Read the current counter value.
    pub fn get(&self) -> u64 {
        self.value.load(Ordering::Relaxed)
    }

    /// Reset the counter to zero. Returns the previous value.
    pub fn reset(&self) -> u64 {
        self.value.swap(0, Ordering::Relaxed)
    }
}

/// Current-value gauge (atomic i64).
///
/// Gauges go up and down — use them for values like "active leases"
/// or "connections open".
///
/// # Examples
///
/// ```
/// use grafos_observe::MetricGauge;
///
/// let g = MetricGauge::new();
/// g.inc();
/// g.inc();
/// g.dec();
/// assert_eq!(g.get(), 1);
///
/// g.set(-5);
/// assert_eq!(g.get(), -5);
/// ```
pub struct MetricGauge {
    value: AtomicI64,
}

impl Default for MetricGauge {
    fn default() -> Self {
        Self::new()
    }
}

impl MetricGauge {
    /// Create a new gauge starting at zero.
    pub const fn new() -> Self {
        Self {
            value: AtomicI64::new(0),
        }
    }

    /// Increment the gauge by one.
    pub fn inc(&self) {
        self.value.fetch_add(1, Ordering::Relaxed);
    }

    /// Decrement the gauge by one.
    pub fn dec(&self) {
        self.value.fetch_sub(1, Ordering::Relaxed);
    }

    /// Set the gauge to an absolute value.
    pub fn set(&self, val: i64) {
        self.value.store(val, Ordering::Relaxed);
    }

    /// Read the current gauge value.
    pub fn get(&self) -> i64 {
        self.value.load(Ordering::Relaxed)
    }
}

/// Fixed-bucket latency histogram.
///
/// Tracks the distribution of values (typically durations in microseconds)
/// across predefined buckets. No allocator needed — the bucket array is
/// inline. Uses 10 buckets: 100us, 500us, 1ms, 5ms, 10ms, 50ms, 100ms,
/// 500ms, 1s, +Inf.
///
/// Buckets are cumulative: each bucket count includes all observations that
/// also fall into lower buckets. This matches the Prometheus histogram
/// convention.
///
/// # Examples
///
/// ```
/// use grafos_observe::MetricHistogram;
///
/// let h = MetricHistogram::new();
/// h.observe(50);     // 50us — lands in the <=100us bucket
/// h.observe(2_000);  // 2ms  — lands in the <=5ms bucket
///
/// assert_eq!(h.count(), 2);
/// assert_eq!(h.sum(), 2050);
/// assert_eq!(h.bucket_count(0), 1); // <=100us: only the 50us observation
/// assert_eq!(h.bucket_count(3), 2); // <=5ms: both observations
/// ```
pub struct MetricHistogram {
    /// Bucket upper bounds in microseconds. The last bucket is +Inf (u64::MAX).
    bounds: [u64; Self::NUM_BUCKETS],
    /// Counts per bucket (cumulative — each bucket includes all lower buckets).
    counts: [AtomicU64; Self::NUM_BUCKETS],
    /// Sum of all observed values.
    sum: AtomicU64,
    /// Total number of observations.
    total: AtomicU64,
}

impl Default for MetricHistogram {
    fn default() -> Self {
        Self::new()
    }
}

impl MetricHistogram {
    /// Number of histogram buckets.
    pub const NUM_BUCKETS: usize = 10;

    /// Bucket boundaries in microseconds.
    pub const BUCKET_BOUNDS: [u64; Self::NUM_BUCKETS] = [
        100,       // 100us
        500,       // 500us
        1_000,     // 1ms
        5_000,     // 5ms
        10_000,    // 10ms
        50_000,    // 50ms
        100_000,   // 100ms
        500_000,   // 500ms
        1_000_000, // 1s
        u64::MAX,  // +Inf
    ];

    /// Create a new histogram with the default bucket boundaries.
    #[allow(clippy::declare_interior_mutable_const)]
    pub const fn new() -> Self {
        Self {
            bounds: Self::BUCKET_BOUNDS,
            counts: [
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
                AtomicU64::new(0),
            ],
            sum: AtomicU64::new(0),
            total: AtomicU64::new(0),
        }
    }

    /// Record an observation (value in microseconds).
    ///
    /// Increments the count for every bucket whose bound is >= the value
    /// (cumulative histogram, matching Prometheus convention).
    pub fn observe(&self, value_us: u64) {
        self.sum.fetch_add(value_us, Ordering::Relaxed);
        self.total.fetch_add(1, Ordering::Relaxed);
        for (i, &bound) in self.bounds.iter().enumerate() {
            if value_us <= bound {
                self.counts[i].fetch_add(1, Ordering::Relaxed);
            }
        }
    }

    /// Read the cumulative count for a specific bucket index.
    pub fn bucket_count(&self, index: usize) -> u64 {
        if index < Self::NUM_BUCKETS {
            self.counts[index].load(Ordering::Relaxed)
        } else {
            0
        }
    }

    /// Read the bucket upper bound for a specific bucket index (in microseconds).
    pub fn bucket_bound(&self, index: usize) -> u64 {
        if index < Self::NUM_BUCKETS {
            self.bounds[index]
        } else {
            u64::MAX
        }
    }

    /// Total number of observations.
    pub fn count(&self) -> u64 {
        self.total.load(Ordering::Relaxed)
    }

    /// Sum of all observed values (in microseconds).
    pub fn sum(&self) -> u64 {
        self.sum.load(Ordering::Relaxed)
    }
}

/// Global fabric metrics registry.
///
/// Tracks system-wide counters and gauges for lease lifecycles,
/// data-plane operations, and graph rewrites. Access the process-wide
/// singleton via [`FabricMetrics::global()`].
///
/// # Examples
///
/// ```
/// use grafos_observe::FabricMetrics;
///
/// let m = FabricMetrics::global();
/// m.leases_total.inc();
/// m.leases_active.inc();
/// m.ops_total.add(5);
/// m.bytes_read.add(1024);
/// m.op_latency.observe(300);
/// ```
pub struct FabricMetrics {
    /// Currently active leases (gauge — goes up on acquire, down on drop/expire).
    pub leases_active: MetricGauge,
    /// Total leases ever created (counter).
    pub leases_total: MetricCounter,
    /// Total leases that expired (counter).
    pub leases_expired: MetricCounter,
    /// Total leases that entered fenced state (counter).
    pub leases_fenced: MetricCounter,
    /// Total data-plane operations completed (counter).
    pub ops_total: MetricCounter,
    /// Total data-plane operations that failed (counter).
    pub ops_errors: MetricCounter,
    /// Total bytes read across all data-plane operations (counter).
    pub bytes_read: MetricCounter,
    /// Total bytes written across all data-plane operations (counter).
    pub bytes_written: MetricCounter,
    /// Total graph rewrites initiated (counter).
    pub rewrites_total: MetricCounter,
    /// Histogram of operation latencies in microseconds.
    pub op_latency: MetricHistogram,
    /// Total leases explicitly revoked (counter) — distinct from expired.
    pub leases_revoked: MetricCounter,
    /// Histogram of lease bind latency in microseconds.
    pub bind_latency: MetricHistogram,
    /// Histogram of lease renewal latency in microseconds.
    pub renew_latency: MetricHistogram,
    /// Histogram of lease revocation latency in microseconds.
    pub revoke_latency: MetricHistogram,
    /// Histogram of teardown execution latency in microseconds.
    pub teardown_latency: MetricHistogram,
    /// Total authentication failures (counter).
    pub auth_failures: MetricCounter,
    /// Total anti-replay cache rejections (counter).
    pub replay_rejections: MetricCounter,
    /// Total capability token validations (counter).
    pub token_validations: MetricCounter,
    /// Total capability token validation failures (counter).
    pub token_failures: MetricCounter,
    /// Total stale access attempts after revoke/expiry (counter).
    pub stale_access_rejections: MetricCounter,
    /// Histogram of control-plane operation latencies in microseconds.
    pub control_latency: MetricHistogram,
    /// Histogram of dataplane operation latencies in microseconds.
    pub dataplane_latency: MetricHistogram,
    /// Histogram of tasklet submit (full dispatch) latencies in microseconds.
    pub tasklet_submit_latency: MetricHistogram,
    /// Histogram of tasklet execution-only latencies in microseconds.
    pub tasklet_exec_latency: MetricHistogram,
    /// Total tasklet submissions received (counter).
    pub tasklet_submits: MetricCounter,
    /// Total tasklet executions that completed successfully (counter).
    pub tasklet_completions: MetricCounter,
    /// Total tasklet executions that failed (counter).
    pub tasklet_failures: MetricCounter,
    /// Histogram of tasklet wall-clock duration in microseconds.
    pub tasklet_duration: MetricHistogram,
    /// Total module cache hits (counter).
    pub module_cache_hits: MetricCounter,
    /// Total module cache misses (counter).
    pub module_cache_misses: MetricCounter,
    /// Total module cache stores (counter).
    pub module_cache_stores: MetricCounter,
    /// Total module cache hash mismatches (counter).
    pub module_cache_hash_mismatches: MetricCounter,
    // ── Phase 219 / slice 20 — audit-chain emit counters ──
    //
    // Per-AuditEventKind counters that bump every time a daemon /
    // scheduler emits an audit record. SREs scrape these via
    // Prometheus to see lifecycle event RATES (emits/sec) without
    // tailing the chain itself. The breakdown by kind lets a
    // dashboard distinguish "lease churn" (lots of allocated +
    // released) from "instability" (lots of fenced + expired).
    /// Total `CapabilityIssued` audit records emitted (counter).
    pub audit_capability_issued: MetricCounter,
    /// Total `CapabilityRevoked` audit records emitted (counter).
    pub audit_capability_revoked: MetricCounter,
    /// Total `LeaseAllocated` audit records emitted (counter).
    pub audit_lease_allocated: MetricCounter,
    /// Total `LeaseRenewed` audit records emitted (counter).
    pub audit_lease_renewed: MetricCounter,
    /// Total `LeaseReleased` audit records emitted (counter).
    pub audit_lease_released: MetricCounter,
    /// Total `LeaseExpired` audit records emitted (counter).
    pub audit_lease_expired: MetricCounter,
    /// Total `LeaseFenced` audit records emitted (counter).
    pub audit_lease_fenced: MetricCounter,
    /// Total `LeaseTorndown` audit records emitted (counter).
    pub audit_lease_torndown: MetricCounter,
    /// Total `AdmissionDecided` audit records emitted (counter).
    pub audit_admission_decided: MetricCounter,
    /// Total `Preempted` audit records emitted (counter).
    pub audit_preempted: MetricCounter,
    /// Total `DrainInitiated` audit records emitted (counter).
    pub audit_drain_initiated: MetricCounter,
    /// Total `ChainAnchored` audit records emitted (counter). A
    /// non-zero value indicates the chain has been anchored at
    /// least once — operators monitor this for key-rotation
    /// boundaries.
    pub audit_chain_anchored: MetricCounter,
    /// Total `SoftModeEnabled` audit records emitted (counter).
    /// **Should normally be ZERO in production**. Any non-zero
    /// value means a weaker-mode toggle was enabled and warrants
    /// operator attention.
    pub audit_soft_mode_enabled: MetricCounter,
    /// Phase 218–222 / slice 77 — total `TenantCreated` audit
    /// records emitted (counter). Tenant-CRUD typed kinds were
    /// added in Stage 2a of the audit-surface migration; producers
    /// dual-write to both this typed counter and the older
    /// enterprise_audit log during Stage 2.
    pub audit_tenant_created: MetricCounter,
    /// Phase 218–222 / slice 77 — total `TenantDeleted` audit
    /// records emitted (counter).
    pub audit_tenant_deleted: MetricCounter,
    /// Phase 218–222 / slice 77 — total `TenantQuotaUpdated` audit
    /// records emitted (counter).
    pub audit_tenant_quota_updated: MetricCounter,
    /// Phase 218–222 / slice 79 — total `ProviderConformanceRecorded`
    /// audit records emitted (counter). Stage 2b of the audit-surface
    /// migration: the orchestrator dual-writes this typed counter
    /// alongside the older enterprise_audit `kind=admin,
    /// outcome="provider_conformance_recorded"` row.
    pub audit_provider_conformance_recorded: MetricCounter,
    /// Phase 218–222 / slice 79 — total
    /// `ProviderBootstrapTokenIssued` audit records emitted.
    pub audit_provider_bootstrap_token_issued: MetricCounter,
    /// Phase 218–222 / slice 79 — total `ProviderBootstrapExchanged`
    /// audit records emitted.
    pub audit_provider_bootstrap_exchanged: MetricCounter,
    /// Phase 218–222 / slice 79 — total `ProviderCellIdentityIssued`
    /// audit records emitted.
    pub audit_provider_cell_identity_issued: MetricCounter,
    /// Phase 218–222 / slice 79 — total `ProviderCellIdentityRotated`
    /// audit records emitted.
    pub audit_provider_cell_identity_rotated: MetricCounter,
    /// Phase 218–222 / slice 79 — total `ProviderCellIdentityRevoked`
    /// audit records emitted.
    pub audit_provider_cell_identity_revoked: MetricCounter,
    /// Phase 218–222 / slice 80 — total `BearerTokenIssued` audit
    /// records emitted (counter). Stage 2c of the audit-surface
    /// migration: cell-side and orchestrator-side mint paths dual-
    /// write this typed counter alongside the older enterprise_audit
    /// `kind=token, outcome="created"` row. Distinct from
    /// `audit_capability_issued`: bearer tokens are HTTP
    /// Authorization-shaped admin/tenant API keys (not lease-bound
    /// capability tokens). Operators monitoring token churn or
    /// alerting on suspicious mint cadence read this counter.
    pub audit_bearer_token_issued: MetricCounter,
    /// Phase 218–222 / slice 80 — total `BearerTokenRevoked` audit
    /// records emitted (counter). Distinct from
    /// `audit_capability_revoked` (lease-bound capability revoke).
    /// Operators monitoring token revocation rate or alerting on
    /// mass-revoke incidents read this counter.
    pub audit_bearer_token_revoked: MetricCounter,
    /// Phase 218–222 / slice 81 — total `SchedulerPromoted` audit
    /// records emitted (counter). Stage 2 mop-up of the audit-surface
    /// migration: the cell-side `handle_promote` dual-writes this
    /// typed counter alongside the older enterprise_audit
    /// `kind=admin, outcome="promoted"` row. A non-zero value (and
    /// especially a sustained rate) is operator-relevant: each emit
    /// represents a leadership transition.
    pub audit_scheduler_promoted: MetricCounter,
    /// Phase 218–222 / slice 81 — total `BillingRateCardInstalled`
    /// audit records emitted (counter). Stage 2 mop-up: the only
    /// Billing-category producer. Lifecycle-axis, low-volume.
    /// Operators alerting on rate-card swaps (a billing-impacting
    /// admin action) read this counter.
    pub audit_billing_rate_card_installed: MetricCounter,
    /// Slice 261 (EdgeRecord audit-chain integration arc) — total
    /// `EdgeRewritten` audit records emitted (counter). One emit per
    /// affected edge per committed rewrite (producer wiring in slice
    /// 262). High-volume relative to other audit kinds because a
    /// rewrite typically touches multiple edges; operators reading
    /// this counter expect throughput proportional to graph mutation
    /// rate.
    pub audit_edge_rewritten: MetricCounter,
    /// Total audit records emitted across all kinds (counter).
    /// Equal to the sum of the per-kind counters; exposed
    /// separately for cheap "total emit rate" dashboards.
    pub audit_records_emitted: MetricCounter,

    /// Phase 219 slice 23 — total audit records persisted to the
    /// JSONL sink (counter). Bumps once per successful
    /// `grafos_audit::write_record` call. Difference from
    /// `audit_records_emitted` indicates JSONL lag or the daemon
    /// running without `--audit-jsonl-path`.
    pub audit_jsonl_writes: MetricCounter,
    /// Phase 219 slice 23 — total audit JSONL writes that failed
    /// (counter). Bumps once per `write_record` Err. Operator
    /// attention warranted; chain integrity is preserved but the
    /// downstream collector is missing records.
    pub audit_jsonl_write_failed: MetricCounter,
}

impl Default for FabricMetrics {
    fn default() -> Self {
        Self::new()
    }
}

impl FabricMetrics {
    /// Create a new metrics instance with all values at zero.
    pub const fn new() -> Self {
        Self {
            leases_active: MetricGauge::new(),
            leases_total: MetricCounter::new(),
            leases_expired: MetricCounter::new(),
            leases_fenced: MetricCounter::new(),
            ops_total: MetricCounter::new(),
            ops_errors: MetricCounter::new(),
            bytes_read: MetricCounter::new(),
            bytes_written: MetricCounter::new(),
            rewrites_total: MetricCounter::new(),
            op_latency: MetricHistogram::new(),
            leases_revoked: MetricCounter::new(),
            bind_latency: MetricHistogram::new(),
            renew_latency: MetricHistogram::new(),
            revoke_latency: MetricHistogram::new(),
            teardown_latency: MetricHistogram::new(),
            auth_failures: MetricCounter::new(),
            replay_rejections: MetricCounter::new(),
            token_validations: MetricCounter::new(),
            token_failures: MetricCounter::new(),
            stale_access_rejections: MetricCounter::new(),
            control_latency: MetricHistogram::new(),
            dataplane_latency: MetricHistogram::new(),
            tasklet_submit_latency: MetricHistogram::new(),
            tasklet_exec_latency: MetricHistogram::new(),
            tasklet_submits: MetricCounter::new(),
            tasklet_completions: MetricCounter::new(),
            tasklet_failures: MetricCounter::new(),
            tasklet_duration: MetricHistogram::new(),
            module_cache_hits: MetricCounter::new(),
            module_cache_misses: MetricCounter::new(),
            module_cache_stores: MetricCounter::new(),
            module_cache_hash_mismatches: MetricCounter::new(),
            audit_capability_issued: MetricCounter::new(),
            audit_capability_revoked: MetricCounter::new(),
            audit_lease_allocated: MetricCounter::new(),
            audit_lease_renewed: MetricCounter::new(),
            audit_lease_released: MetricCounter::new(),
            audit_lease_expired: MetricCounter::new(),
            audit_lease_fenced: MetricCounter::new(),
            audit_lease_torndown: MetricCounter::new(),
            audit_admission_decided: MetricCounter::new(),
            audit_preempted: MetricCounter::new(),
            audit_drain_initiated: MetricCounter::new(),
            audit_chain_anchored: MetricCounter::new(),
            audit_soft_mode_enabled: MetricCounter::new(),
            audit_tenant_created: MetricCounter::new(),
            audit_tenant_deleted: MetricCounter::new(),
            audit_tenant_quota_updated: MetricCounter::new(),
            audit_provider_conformance_recorded: MetricCounter::new(),
            audit_provider_bootstrap_token_issued: MetricCounter::new(),
            audit_provider_bootstrap_exchanged: MetricCounter::new(),
            audit_provider_cell_identity_issued: MetricCounter::new(),
            audit_provider_cell_identity_rotated: MetricCounter::new(),
            audit_provider_cell_identity_revoked: MetricCounter::new(),
            audit_bearer_token_issued: MetricCounter::new(),
            audit_bearer_token_revoked: MetricCounter::new(),
            audit_scheduler_promoted: MetricCounter::new(),
            audit_billing_rate_card_installed: MetricCounter::new(),
            audit_edge_rewritten: MetricCounter::new(),
            audit_records_emitted: MetricCounter::new(),
            audit_jsonl_writes: MetricCounter::new(),
            audit_jsonl_write_failed: MetricCounter::new(),
        }
    }

    /// Phase 219 slice 20 — bump the per-kind audit-emit counter
    /// for `kind`, plus the overall `audit_records_emitted` counter.
    /// Callers (typically `fabricbiosd`'s emit_*_audit helpers and
    /// the tick thread's inline emit) call this on every successful
    /// `assemble_record` so the Prometheus dashboard sees the rate.
    /// The match arms cover every `AuditEventKind` variant — adding
    /// a new variant in `grafos-core::policy_vocab` MUST also add
    /// the corresponding counter and an arm here, otherwise the
    /// new kind's emit rate is invisible.
    pub fn count_audit_emit(&self, kind: grafos_core::AuditEventKind) {
        use grafos_core::AuditEventKind as K;
        let counter = match kind {
            K::CapabilityIssued => &self.audit_capability_issued,
            K::CapabilityRevoked => &self.audit_capability_revoked,
            K::LeaseAllocated => &self.audit_lease_allocated,
            K::LeaseRenewed => &self.audit_lease_renewed,
            K::LeaseReleased => &self.audit_lease_released,
            K::LeaseExpired => &self.audit_lease_expired,
            K::LeaseFenced => &self.audit_lease_fenced,
            K::LeaseTorndown => &self.audit_lease_torndown,
            K::AdmissionDecided => &self.audit_admission_decided,
            K::Preempted => &self.audit_preempted,
            K::DrainInitiated => &self.audit_drain_initiated,
            K::ChainAnchored => &self.audit_chain_anchored,
            K::SoftModeEnabled => &self.audit_soft_mode_enabled,
            K::TenantCreated => &self.audit_tenant_created,
            K::TenantDeleted => &self.audit_tenant_deleted,
            K::TenantQuotaUpdated => &self.audit_tenant_quota_updated,
            K::ProviderConformanceRecorded => &self.audit_provider_conformance_recorded,
            K::ProviderBootstrapTokenIssued => &self.audit_provider_bootstrap_token_issued,
            K::ProviderBootstrapExchanged => &self.audit_provider_bootstrap_exchanged,
            K::ProviderCellIdentityIssued => &self.audit_provider_cell_identity_issued,
            K::ProviderCellIdentityRotated => &self.audit_provider_cell_identity_rotated,
            K::ProviderCellIdentityRevoked => &self.audit_provider_cell_identity_revoked,
            K::BearerTokenIssued => &self.audit_bearer_token_issued,
            K::BearerTokenRevoked => &self.audit_bearer_token_revoked,
            K::SchedulerPromoted => &self.audit_scheduler_promoted,
            K::BillingRateCardInstalled => &self.audit_billing_rate_card_installed,
            K::EdgeRewritten => &self.audit_edge_rewritten,
        };
        counter.inc();
        self.audit_records_emitted.inc();
    }

    /// Access the global metrics instance.
    pub fn global() -> &'static FabricMetrics {
        static INSTANCE: FabricMetrics = FabricMetrics::new();
        &INSTANCE
    }
}

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

    #[test]
    fn counter_inc_and_add() {
        let c = MetricCounter::new();
        assert_eq!(c.get(), 0);
        c.inc();
        assert_eq!(c.get(), 1);
        c.add(10);
        assert_eq!(c.get(), 11);
    }

    #[test]
    fn counter_reset() {
        let c = MetricCounter::new();
        c.add(42);
        let prev = c.reset();
        assert_eq!(prev, 42);
        assert_eq!(c.get(), 0);
    }

    #[test]
    fn gauge_inc_dec_set() {
        let g = MetricGauge::new();
        assert_eq!(g.get(), 0);
        g.inc();
        g.inc();
        assert_eq!(g.get(), 2);
        g.dec();
        assert_eq!(g.get(), 1);
        g.set(100);
        assert_eq!(g.get(), 100);
        g.set(-5);
        assert_eq!(g.get(), -5);
    }

    #[test]
    fn histogram_observe() {
        let h = MetricHistogram::new();
        // Observation of 50us should land in the 100us bucket (index 0) and all above.
        h.observe(50);
        assert_eq!(h.count(), 1);
        assert_eq!(h.sum(), 50);
        // Bucket 0 (<=100us) should have 1 count.
        assert_eq!(h.bucket_count(0), 1);
        // Bucket 9 (+Inf) should also have 1 count.
        assert_eq!(h.bucket_count(9), 1);
    }

    #[test]
    fn histogram_multiple_observations() {
        let h = MetricHistogram::new();
        h.observe(50); // <=100us bucket
        h.observe(200); // <=500us bucket
        h.observe(2_000); // <=5ms bucket
        h.observe(999_999); // <=1s bucket

        assert_eq!(h.count(), 4);
        assert_eq!(h.sum(), 50 + 200 + 2_000 + 999_999);

        // Bucket 0 (<=100us): only the 50us observation.
        assert_eq!(h.bucket_count(0), 1);
        // Bucket 1 (<=500us): 50 + 200.
        assert_eq!(h.bucket_count(1), 2);
        // Bucket 3 (<=5ms): 50 + 200 + 2000.
        assert_eq!(h.bucket_count(3), 3);
        // Bucket 8 (<=1s): all four.
        assert_eq!(h.bucket_count(8), 4);
        // +Inf: all four.
        assert_eq!(h.bucket_count(9), 4);
    }

    #[test]
    fn histogram_out_of_bounds_index() {
        let h = MetricHistogram::new();
        assert_eq!(h.bucket_count(99), 0);
        assert_eq!(h.bucket_bound(99), u64::MAX);
    }

    #[test]
    fn fabric_metrics_global_is_singleton() {
        let m1 = FabricMetrics::global();
        let m2 = FabricMetrics::global();
        // Same address.
        assert!(core::ptr::eq(m1, m2));
    }

    #[test]
    fn fabric_metrics_fields() {
        let m = FabricMetrics::new();
        m.leases_active.inc();
        m.leases_total.inc();
        m.ops_total.add(5);
        m.bytes_read.add(1024);
        m.bytes_written.add(512);
        m.rewrites_total.inc();
        m.leases_expired.inc();
        m.leases_fenced.inc();
        m.ops_errors.inc();

        assert_eq!(m.leases_active.get(), 1);
        assert_eq!(m.leases_total.get(), 1);
        assert_eq!(m.ops_total.get(), 5);
        assert_eq!(m.bytes_read.get(), 1024);
        assert_eq!(m.bytes_written.get(), 512);
        assert_eq!(m.rewrites_total.get(), 1);
        assert_eq!(m.leases_expired.get(), 1);
        assert_eq!(m.leases_fenced.get(), 1);
        assert_eq!(m.ops_errors.get(), 1);

        m.leases_revoked.inc();
        m.auth_failures.inc();
        m.replay_rejections.inc();
        m.token_validations.add(10);
        m.token_failures.inc();
        m.stale_access_rejections.inc();
        m.bind_latency.observe(100);
        m.renew_latency.observe(200);
        m.revoke_latency.observe(300);
        m.teardown_latency.observe(400);

        assert_eq!(m.leases_revoked.get(), 1);
        assert_eq!(m.auth_failures.get(), 1);
        assert_eq!(m.replay_rejections.get(), 1);
        assert_eq!(m.token_validations.get(), 10);
        assert_eq!(m.token_failures.get(), 1);
        assert_eq!(m.stale_access_rejections.get(), 1);
        assert_eq!(m.bind_latency.count(), 1);
        assert_eq!(m.renew_latency.count(), 1);
        assert_eq!(m.revoke_latency.count(), 1);
        assert_eq!(m.teardown_latency.count(), 1);
    }

    /// Phase 219 slice 20 — count_audit_emit routes each
    /// AuditEventKind to the correct per-kind counter AND bumps
    /// the overall `audit_records_emitted`. A regression in the
    /// match arms (e.g., a future variant added without an arm)
    /// would silently miss-route emits — this test pins each
    /// variant's counter mapping.
    #[test]
    fn count_audit_emit_routes_each_kind_to_correct_counter() {
        use grafos_core::AuditEventKind as K;
        let m = FabricMetrics::new();

        // Each kind bumps its specific counter and the overall total.
        // Walk every variant; if a future variant lands without a
        // match arm in count_audit_emit, this loop would not
        // exercise it — the compile-time exhaustiveness check on
        // the match itself is the regression guard, but this test
        // verifies the runtime mapping for every existing variant.
        let kinds_and_getters: &[(K, fn(&FabricMetrics) -> u64)] = &[
            (K::CapabilityIssued, |m| m.audit_capability_issued.get()),
            (K::CapabilityRevoked, |m| m.audit_capability_revoked.get()),
            (K::LeaseAllocated, |m| m.audit_lease_allocated.get()),
            (K::LeaseRenewed, |m| m.audit_lease_renewed.get()),
            (K::LeaseReleased, |m| m.audit_lease_released.get()),
            (K::LeaseExpired, |m| m.audit_lease_expired.get()),
            (K::LeaseFenced, |m| m.audit_lease_fenced.get()),
            (K::LeaseTorndown, |m| m.audit_lease_torndown.get()),
            (K::AdmissionDecided, |m| m.audit_admission_decided.get()),
            (K::Preempted, |m| m.audit_preempted.get()),
            (K::DrainInitiated, |m| m.audit_drain_initiated.get()),
            (K::ChainAnchored, |m| m.audit_chain_anchored.get()),
            (K::SoftModeEnabled, |m| m.audit_soft_mode_enabled.get()),
            (K::TenantCreated, |m| m.audit_tenant_created.get()),
            (K::TenantDeleted, |m| m.audit_tenant_deleted.get()),
            (K::TenantQuotaUpdated, |m| {
                m.audit_tenant_quota_updated.get()
            }),
            (K::ProviderConformanceRecorded, |m| {
                m.audit_provider_conformance_recorded.get()
            }),
            (K::ProviderBootstrapTokenIssued, |m| {
                m.audit_provider_bootstrap_token_issued.get()
            }),
            (K::ProviderBootstrapExchanged, |m| {
                m.audit_provider_bootstrap_exchanged.get()
            }),
            (K::ProviderCellIdentityIssued, |m| {
                m.audit_provider_cell_identity_issued.get()
            }),
            (K::ProviderCellIdentityRotated, |m| {
                m.audit_provider_cell_identity_rotated.get()
            }),
            (K::ProviderCellIdentityRevoked, |m| {
                m.audit_provider_cell_identity_revoked.get()
            }),
            (K::BearerTokenIssued, |m| m.audit_bearer_token_issued.get()),
            (K::BearerTokenRevoked, |m| {
                m.audit_bearer_token_revoked.get()
            }),
            (K::SchedulerPromoted, |m| m.audit_scheduler_promoted.get()),
            (K::BillingRateCardInstalled, |m| {
                m.audit_billing_rate_card_installed.get()
            }),
            (K::EdgeRewritten, |m| m.audit_edge_rewritten.get()),
        ];
        for (kind, getter) in kinds_and_getters.iter() {
            let before = getter(&m);
            m.count_audit_emit(*kind);
            let after = getter(&m);
            assert_eq!(
                after,
                before + 1,
                "kind {:?} did not bump its counter",
                kind
            );
        }
        // Overall counter equals the number of emits we made.
        assert_eq!(
            m.audit_records_emitted.get(),
            kinds_and_getters.len() as u64
        );
    }
}