//! os_observatory: universal observability primitives for operating systems
//!
//! This crate provides a zero-dependency, `no_std`-first toolkit that helps OS authors
//! instrument their kernels with structured logging, low-overhead tracing, and panic reporting.
//! It is designed to compile on bare metal, with optional `std` support for host-side testing.
//!
//! Design goals:
//! - Independence: no external crate dependencies, only `core` and optionally `alloc/std`.
//! - Determinism: constant-time operations in interrupt contexts, lock-free paths.
//! - Portability: abstract I/O sinks so you can plug in UART, memory, semihosting, etc.
//! - Documentation: extensively commented APIs to render well on docs.rs.
//! - Testability: host-side tests under `std`; kernel-side tests via stub sinks.
//!
//! Modules:
//! - `sink`: trait and implementations for safe output targets
//! - `logging`: macros and logger with compile-time levels
//! - `tracer`: fixed-capacity event tracing buffers with timestamps
//! - `build`: compile-time build information (name, version, etc.)
//! - `mem`: small memory utilities useful in kernels
//! - `panic`: helpers to report panics through your chosen sink
//!
//! Licensing:
//! - MIT License.
//! - Authored by an AI Assistant (GPT-5-medium), originating from an idea by alisio85.
//! - See LICENSE-MIT for details.
//!
//! Usage quickstart (no_std):
//! - Implement `sink::Sink` for your hardware writer
//! - Initialize a `logging::Logger` with your sink
//! - Use `os_log!`, `os_warn!`, `os_error!`, `os_trace!` macros
//! - Configure `tracer::EventTracer` for performance-critical instrumentation
//! - Wire `panic::report_panic` inside your panic handler to emit diagnostics
//!
//! Safety notes:
//! - All APIs aim to be `no_std` and interrupt-safe; avoid heap unless opting into `alloc`.
//! - Logging uses bounded buffers and does not allocate.
//! - Tracing uses lock-free atomics and fixed-size records.
//! - Panics are reported in a minimalistic, reentrant-aware fashion.

#![cfg_attr(not(feature = "std"), no_std)]
#![deny(warnings)]
#![forbid(unsafe_op_in_unsafe_fn)]
#![cfg_attr(docsrs, feature(doc_cfg))]

/// Output abstraction and in-crate sinks.
pub mod sink;
/// Structured logging and user-facing macros.
pub mod logging;
/// Low-overhead event tracing.
pub mod tracer;
/// Build metadata helpers.
pub mod build;
/// Memory utilities for OS code.
pub mod mem;
/// Panic reporting utilities for integration into `#[panic_handler]`.
pub mod panic;

/// Re-export commonly used items for convenience.
pub mod prelude {
    //! Convenient re-exports for typical usage patterns.
    pub use crate::build::BuildStamp;
    pub use crate::{os_error, os_log, os_trace, os_warn};
    pub use crate::logging::{Level, Logger};
    pub use crate::sink::{RingBufferSink, Sink};
    pub use crate::tracer::{EventId, EventRecord, EventTracer};
}
