bistun-core 2.0.3

The authoritative Linguistic DNA models and DTOs for the Bistun LMS. Provides a high-performance, immutable contract layer for BCP 47 locale resolution, typographic traits, and linguistic metadata.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

// Copyright (C) 2026 Francis Xavier Wazeter IV
// SPDX-License-Identifier: GPL-3.0-or-later
//
// This file is part of the Bistun Linguistic Metadata Service (LMS).
// See the LICENSE file in the workspace root for full license information.

#![cfg(feature = "ops")]

//! # Operational Models
//! **Crate**: `bistun-core`
//! **Ref**: `[007-LMS-OPS]`
//! **Domain**: `Operations`
//! **Location**: `crates/bistun-core/src/ops.rs`
//!
//! **Why**: This module centralizes the Service Level models required for `SDK` operational monitoring and telemetry.
//! **Impact**: Defines the standard states the system can exist in and the metrics reported to observability sinks, which guarantees the strict `Latency Budget (SLI)`.
//!
//! ### Architectural Topology
//! * **Tier**: `0`
//! * **Dependencies**: `serde`
//! * **Consumers**: Telemetry layers, Observability sinks, `Coordinator` orchestrators.
//! * **State Model**: `Stateless`
//! * **Design Patterns**: `Stub`
//!
//! ### Local Definitions
//! * **`SdkState`**: The operational health of the manager (`Bootstrapping`, `Ready`, `Degraded`).
//! * **Circuit Breaker**: A distributed systems safety pattern that transitions the service to a `DEGRADED` state during network failures, serving safe hardcoded defaults to prevent cascading application crashes.

use serde::{Deserialize, Serialize};

/// Represents the operational health and readiness of the `SDK`.
///
/// ### `OpenAPI` Schema
/// ```yaml
/// schema: SdkState
/// description: The operational health of the manager (`Bootstrapping`, `Ready`, `Degraded`).
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum SdkState {
    /// The manager is initializing and executing `Bootstrapping` processes to load configurations.
    Bootstrapping,
    /// The manager is fully hydrated and operating normally.
    Ready,
    /// The manager failed to hydrate and is running in `Circuit Breaker` mode.
    Degraded,
}

/// Tracks the operational health and synchronization history of the capability engine.
///
/// ### `OpenAPI` Schema
/// ```yaml
/// schema: SyncMetrics
/// description: Tracks the operational health and synchronization history of the capability engine.
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct SyncMetrics {
    /// Unix timestamp of the last time the worker attempted to fetch a snapshot.
    pub last_attempted_sync: u64,
    /// Unix timestamp of the last time the worker successfully hot-swapped a valid snapshot.
    pub last_successful_sync: u64,
    /// The cumulative number of failed hydration attempts since boot.
    pub sync_error_count: u64,
}

/// Tracks the runtime resolution telemetry for the Capability Engine.
///
/// ### `OpenAPI` Schema
/// ```yaml
/// schema: ResolutionMetrics
/// description: Tracks the runtime resolution telemetry for the Capability Engine.
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct ResolutionMetrics {
    /// Total number of manifests generated.
    pub total_manifests_resolved: u64,
    /// Total number of logical rules successfully translated via `Synthesis`.
    pub rule_synthesis_count: u64,
    /// Number of times the `Pessimistic Complexity Heuristic` algorithm successfully resolved a rule conflict.
    pub rule_conflict_resolved_total: u64,
    /// Number of times the `Asset URI Router` failed to map an `ID` to a `URI`.
    pub resource_resolution_failures: u64,
}