# tsoracle-core

Sync algorithm core for the [tsoracle](https://github.com/prisma-risk/tsoracle) timestamp oracle.

No I/O, no async, no tokio. Runtime-neutral, property-testable in microseconds. Anything you need to reason about tsoracle's timestamp generation lives here — the higher layers (`tsoracle-server`, `tsoracle-client`, the consensus drivers) are wiring around this core.

## What's in the box

- `Allocator` — the window allocator. Hands out 46/18-bit-packed `Timestamp`s within a granted window, tracks the leader's epoch, and exposes the `WindowGrant` lifecycle used by the server's leader-watch + fence pipeline.
- `Timestamp` — the 64-bit packed representation. `PHYSICAL_MS_MAX` and `LOGICAL_MAX` document the bit budget; `TimestampError` covers the narrow space of invalid encodings.
- `Epoch` — the leader-watermark identifier the failover fence checks. Persisted alongside the high water by every `ConsensusDriver` impl.
- `Clock` + `SystemClock` — the trait for "what time is it" abstraction. `clock::testing` exposes deterministic fakes for property tests.
- `Bt` — backtrace-on-error helper. ZST and no-op unless the `bt` feature is on; with it on, capture is still gated by `RUST_BACKTRACE` / `RUST_LIB_BACKTRACE`.
- `CoreError` — the algorithm-level error type. Server, client, and driver crates wrap it in their own variants.

## Feature flags

- `std` (default) — enables `std`-dependent surface (most of it). Disabling gives a `no_std` core; the public surface shrinks but the allocator + timestamp math still work.
- `serde` — derives `Serialize` / `Deserialize` on the public types so they cross wire and storage boundaries cleanly.
- `test-clock` — exposes the `clock::testing` module to downstream test code without needing `cfg(test)` machinery.
- `bt` — captures `std::backtrace::Backtrace` in instrumented error variants. Off by default to keep cold paths free.

## Documentation

- [`docs/architecture-deep-dive.md`](https://github.com/prisma-risk/tsoracle/blob/main/docs/architecture-deep-dive.md) — the algorithm and bit-packing contract this crate implements.
- [`docs/consensus-integration.md`](https://github.com/prisma-risk/tsoracle/blob/main/docs/consensus-integration.md) — how the `Allocator` interacts with a `ConsensusDriver` impl.
