clock-lib 1.0.0

# v1.0.0 — Stable API

`clock-lib` reaches 1.0. The public surface, the performance, the documentation, and the supply-chain story are all settled. From this release forward, every change against this major version is non-breaking.

## What `clock-lib` Is

A thin, well-inlined layer over `std::time` that gives you the two kinds of time every program needs — **monotonic** for measuring elapsed time, **wall-clock** for timestamps — as distinct types the compiler refuses to mix. A `Clock` trait makes time-driven code testable without `thread::sleep`. Zero runtime dependencies, no `unsafe`, `no_std`-compatible.

```rust
use clock_lib as clock;

// Measure how long something takes (never goes backwards).
let start = clock::now();
// ... do work ...
let took = clock::elapsed(start);

// Stamp an event (calendar time).
let secs = clock::unix();
```

```toml
[dependencies]
clock-lib = "1.0"
```

## The Stable Surface

Everything below is committed for the 1.x line and will not change without a major version bump.

### Tier-1 free functions

`now`, `elapsed`, `wall`, `unix`, `unix_ms`, `unix_ns` — one-line entry points for the common case.

### Types

- [`Monotonic`](../API.md#monotonic) — `now`, `elapsed`, `duration_since`, `checked_duration_since`, `saturating_duration_since`.
- [`Wall`](../API.md#wall-1) — `now`, `unix_seconds`, `unix_millis`, `unix_nanos`. Pre-epoch system clocks saturate to `0`; no panics, no silent wrapping.

### Trait + implementations

- [`Clock`](../API.md#clock) &mdash; `Send + Sync` trait with `now` and `wall` methods. Blanket impls for `Arc<C>` and `&C`.
- [`SystemClock`](../API.md#systemclock) &mdash; zero-sized, `Copy`, `const`-constructible production clock.
- [`ManualClock`](../API.md#manualclock) &mdash; lock-free, atomic-offset test clock. `new`, `advance`, `offset`.

### Constants

- [`VERSION`](../API.md#version) &mdash; the only item exposed without the `std` feature.

## Performance, Verified

The [performance document](../PERFORMANCE.md) records the recorded median for every public reading alongside the raw `std::time` call it forwards to. The wrappers sit on top of the bare std functions inside criterion's noise band on Windows 11 / Rust 1.85.

| Wrapper | Δ vs raw `std::time` |
| --- | --- |
| `clock_lib::now` | &minus;0.2% |
| `Monotonic::now` | &minus;0.7% |
| `SystemClock::now` | &minus;0.9% |
| `clock_lib::wall` | &minus;0.7% |
| `Wall::now` | &minus;0.6% |
| `clock_lib::elapsed` | &minus;0.2% |

`ManualClock::now` runs in **752 ps**; `ManualClock::advance(1ns)` in **3.75 ns**. A test that calls advance + now a million times spends about 4 ms on the clock.

## Engineering Posture

- **`#![forbid(unsafe_code)]`** at the crate root.
- **REPS-complete lint stack** &mdash; `#![deny(warnings)]`, `clippy::unwrap_used`, `expect_used`, `todo`, `unimplemented`, `dbg_macro`, `print_*`, `unreachable`, plus `#![warn(clippy::pedantic)]`.
- **Reproducible builds** &mdash; `rust-toolchain.toml` pins 1.85.0; `Cargo.lock` is committed.
- **Supply chain** &mdash; `cargo audit` (RustSec) and `cargo deny` (license + yanked + wildcard policy) run on every push.
- **Cross-platform CI** &mdash; Linux, macOS, and Windows on stable and MSRV; bare-metal `no_std` build on `thumbv7em-none-eabihf`.

## Compatibility

- **MSRV:** Rust 1.85
- **Edition:** 2024
- **Platforms:** Linux, macOS, Windows; `no_std` targets via `default-features = false`.
- **Public API:** unchanged from 0.5.0. Code written against any 0.x version since 0.3 compiles unchanged against 1.0.

## Upgrading From 0.x

Bump the version. There is no code migration.

```toml
[dependencies]
clock-lib = "1.0"
```

## Out of Scope

`clock-lib` is deliberately small. It does **not** handle:

- Calendar math, date formatting, or timezones &mdash; use [`chrono`](https://crates.io/crates/chrono) or [`time`](https://crates.io/crates/time).
- Timers, sleeping, or scheduling &mdash; that's a separate concern that should depend on `clock-lib`, not be part of it.
- Async &mdash; the readings are synchronous; async code calls them like any other function.

## Stability Promise

Anything documented in [docs/API.md](../API.md) is part of the 1.x contract. Behavioral changes that would break correct downstream code will only ship with a major version bump. The crate is feature-complete for its scope; future work is bug fixes, performance refinement, and platform support, not new APIs.