PriceLevel

A price level implementation for limit order books in Rust. A [PriceLevel] owns every order resting at one price: it matches an incoming taker against that queue in strict price-time order, tracks visible / hidden quantity counters, records execution statistics, and round-trips through checksum-protected snapshots. It is the building block an order book composes across prices, not a full order book.

The crate is synchronous and built from lock-free components (a crossbeam-skiplist ordered index and atomic counters) plus a small number of documented locks. The complete public methods are not lock-free: see Concurrency Model for which method takes which lock.

• Strict price-time (FIFO) matching at a single price, with deterministic trade emission
• Support for diverse order types including standard limit orders, iceberg orders, post-only, fill-or-kill, and more
• Thread-safe concurrent admissions, updates (cancel / resize) and reads alongside one logical matcher per level (see Concurrency Model)
• Lock-free ordered index (crossbeam-skiplist) and atomic quantity / statistics counters; order storage is a sharded DashMap
• Checked arithmetic on the quantity / value accessors (total_quantity, executed_quantity, executed_value) with typed errors, and a fallible snapshot() whose aggregates always agree with its own orders; removing the remaining production panic paths is tracked in #161
• Checksum-protected (SHA-256) snapshots for persistence and recovery
• Designed with domain-driven principles for financial markets
• Comprehensive test suite, including concurrent usage scenarios
• Optimized statistics tracking for each price level

Intended as a building block for matching engines, market data systems, algorithmic trading platforms, and financial exchanges.

The library provides comprehensive support for various order types used in modern trading systems:

• Standard Limit Order: Basic price-quantity orders with specified execution price
• Iceberg Order: Orders with visible and hidden quantities that replenish automatically
• Post-Only Order: Orders that will not execute immediately against existing orders
• Trailing Stop Order: Orders that adjust based on market price movements
• Pegged Order: Orders that adjust their price based on a reference price
• Market-to-Limit Order: Orders that convert to limit orders after initial execution
• Reserve Order: Orders with custom replenishment logic for visible quantities

The library supports the following time-in-force policies:

• Good Till Canceled (GTC): Order remains active until explicitly canceled
• Immediate Or Cancel (IOC): Order must be filled immediately (partially or completely) or canceled
• Fill Or Kill (FOK): Order must be filled completely immediately or canceled entirely
• Good Till Date (GTD): Order remains active until a specified date/time (Unix milliseconds)
• Day Order: Order valid only for the current trading day

• Thread Safety: Lock-free ordered index and atomic counters, a sharded DashMap for order storage (per-shard locks), and a per-level reader-writer guard used to make fill-or-kill all-or-nothing. See Concurrency Model
• Order Queue Management: Specialized order queue keeping strict price-time priority via a lock-free crossbeam-skiplist ordered index keyed by insertion sequence
• Statistics Tracking: Each price level tracks execution statistics in real-time
• Snapshot Capabilities: Create point-in-time snapshots of price levels for market data distribution
• Efficient Matching: Matching walks the ordered index from the front in price-time order
• Support for Special Order Types: Custom handling for iceberg orders, reserve orders, and other special types

• Atomic Counters: Uses atomic types for thread-safe quantity tracking
• Efficient Order Storage: Optimized data structures for order storage and retrieval
• Visibility Controls: Separate tracking of visible and hidden quantities
• Performance Monitoring: Built-in statistics for monitoring execution performance
• Order Matching Logic: Sophisticated algorithms for matching orders at each price level

"Lock-free" describes components, not complete public methods.

What each public method acquires:

The supported execution model:

• One logical matcher per level. Two concurrent [PriceLevel::match_order] calls on the same level are not made safe by the crate; the caller must serialize them (an order book typically matches a level from one thread).
• Concurrent mutators are supported. [PriceLevel::add_order] and [PriceLevel::update_order] may run from any number of threads, concurrently with the matcher and with each other.
• The maker entry is the serialization point. The matcher applies each fill while holding that maker's DashMap shard write lock, the same lock a cancel or resize of that order takes, so a cancel racing the fill either fully wins or fully loses; it is never lost. Admissions, cancels and resizes of other orders that hash to the same shard also wait on that lock.
• Fill-or-kill excludes every mutator on the level. A Fok match holds the level guard exclusively for its whole dry-run and sweep, so admissions, updates and snapshots on that level block for a section proportional to the makers the fill visits while they fit the dry run's lazy budget (max(8, depth / 64) makers), and O(depth log depth) past it, when the dry run collects and sorts the remaining makers (issue #143). The other time-in-force paths skip that guard, but skipping it is not the absence of locking: they still take the per-maker shard lock.
• Readers are always allowed. Counter reads never block. A [PriceLevel::snapshot] waits only behind an in-flight fill-or-kill or a held shard lock; it walks the shards without a transaction over the whole level, so under concurrent same-side resizes it is not a linearizable point-in-time view. It is coherent: its aggregates always equal the checked sums over its own collected orders. A walk whose orders mix sides or whose sums overflow u64 is recollected at most 8 times in total, after which the call returns a typed [PriceLevelError::InvalidOperation] rather than looping or substituting a live counter (#162).
• Statistics have a single writer. [PriceLevelStatistics] supports exactly one concurrent writer of its execution aggregates: [PriceLevelStatistics::record_execution] is driven by the one logical matcher, and [PriceLevelStatistics::reset] / [PriceLevelStatistics::reset_at] require quiescence (no match or recording in flight). Under that contract the multi-field reads (Clone, which backs [PriceLevel::snapshot], serde and Display) may run from any number of threads and always return a complete execution state, never a partial or later rolled-back one. The sequence guard behind those reads protects readers only; it is not a writer lock, so overlapping record_execution calls (or a reset during one) are unsupported and a reader can then capture a partial execution (issue #153). Order admission and removal counters are plain atomic increments and may be bumped from any thread.

Some operations run code the crate does not own: trait impls on a generic [OrderType<T>] payload, the [OrderType::map_extra_fields] closure, a caller's formatter destination, serializer or deserializer, the body of an [PriceLevel::iter_orders] loop, and the process-installed tracing subscriber. Trait bounds cannot express "does not panic", so that is a caller obligation: supplied code must not panic and must not re-enter the level that is calling it, except where documented.

• Generic payloads are pure. OrderType<T> utilities hold no lock and mutate no library state. The engine stores only OrderType<()>, so no payload code runs under its locks.
• No caller code under a shard write lock. Formatting and serializing a level or queue materialize first and hold no lock, and no tracing event is emitted under a DashMap shard write lock or between a match step's queue commit and its counter bookkeeping.
• Remaining boundaries. iter_orders holds a shard read lock while the loop body runs. A subscriber panic during a sweep loses the MatchResult for trades already committed, and during a Fok sweep it poisons the level.
• No recovery promise. The library does not catch caller panics, installs no panic hook and never aborts deliberately. An allocator OOM abort is not a typed error.

The per-call inventory (guard held, partial mutation, unwind effect) is in doc/panic-boundaries.md.

This crate currently publishes no throughput or latency figures. The Criterion benchmarks under benches/ (make bench) are the supported way to measure the build you run, on your hardware and toolchain.

Releases up to 0.9.x printed a "High-Frequency Trading Simulation" table and a contention table produced by the hft_simulation and contention_test examples. Those numbers are withdrawn and excluded from any current performance conclusion:

• They have no provenance: no commit, compiler version, build profile, or workload manifest was recorded.
• They were internally inconsistent: the table reported 237,347.51 total operations per second, while the analysis below it claimed more than 264,000.
• The simulation ran ten taker threads calling match_order on one shared level, outside the single-matcher contract above.
• The example's periodic counter flush over-counted matches and cancellations whenever a thread's success count sat on a flush boundary, and the contention tables counted rejected and missing-order calls as operations.
• Aggregate throughput is not an operation latency, so the figures never supported the "microsecond-level" or production-suitability claims made alongside them.

No replacement run is published in their place.

Any number published for this crate must state which of these distinct metrics it measures, together with the commit, toolchain, build profile, hardware and workload (thread roles, id ranges, order mix, run length):

• Attempted calls: every call to a public method, whatever its outcome.
• Successful admissions / cancels / updates: calls that changed the level, reported separately from calls that were rejected (for example a duplicate id) or that targeted a missing order.
• Successful takers: match_order calls that executed a non-zero quantity.
• Emitted fills: the number of [Trade] values produced; one taker may emit many.
• Whole-lifecycle throughput: complete order lifecycles (admit, then fill or cancel) per second.

Throughput of any kind is not an operation-latency percentile; a latency claim needs per-operation timing and a reported distribution (for example p50 / p99 / p99.9 / max).

• Price-time priority across partial fills (issue #39). A partial fill previously re-queued the resting maker's residual at the back of its price level, so the next aggressor at that price matched a later arrival instead of the older, partially-filled maker (a wrong maker_order_id in the trade stream). The order queue now keeps strict price-time priority: the residual stays at the front. Iceberg / reserve replenishment keeps its existing semantics (a refreshed tranche still loses time priority).

• Internal queue moved to a lock-free crossbeam-skiplist ordered index. The method surface of [OrderQueue] is unchanged, but because the new index relies on interior mutability, [OrderQueue] and [PriceLevel] no longer implement [std::panic::UnwindSafe] / [std::panic::RefUnwindSafe] (they remain Send + Sync). This is the only breaking change and is why this release is 0.8.0 rather than a patch. Callers that wrapped these types in [std::panic::catch_unwind] are affected; nothing else is.

• Matching concurrency contract. [PriceLevel::match_order] assumes a single logical matcher per level at a time. Concurrent add_order / update_order (including a cancel of the resting order the matcher is currently consuming) from other threads are safe and linearizable — the match and the cancel serialize on the maker's per-entry lock (issue #81), and a fill-or-kill match additionally takes a level-exclusive guard so it stays all-or-nothing against those mutators (issue #112). Only two concurrent match_order calls on the same level remain the caller's responsibility to serialize.

• Reserve replenish amounts are now NonZeroU64 (issue #70). A replenish amount of 0 is structurally invalid: it would draw an empty visible tranche from the hidden quantity, silently leaving nothing visible. The reserve replenish surface therefore moved from Quantity (which permits 0) and raw u64 to [std::num::NonZeroU64]:

  v0.8 (before)	v0.8 (now)
  ReserveOrder.replenish_amount: Option<Quantity>	Option<NonZeroU64>
  DEFAULT_RESERVE_REPLENISH_AMOUNT: u64	NonZeroU64 (value 80)
  OrderType::refresh_iceberg(&self, u64)	refresh_iceberg(&self, NonZeroU64)

  Constructing a reserve order with a zero replenish is now impossible at the type level. Build the amount with [std::num::NonZeroU64::new], which returns an Option. For a known-good literal, a compile-time constant is simplest. For a runtime value n, match on NonZeroU64::new(n) and treat None as an invalid amount to reject — do not blindly .unwrap() it (that panics on 0), and do not pass NonZeroU64::new(n) straight into the Option field (that silently maps 0 to None, which falls back to the default replenish instead of flagging the bad input). On the text / JSON deserialization path a replenish_amount of 0 is rejected with a typed [PriceLevelError::InvalidFieldValue] (text) or a deserialization error (JSON) rather than silently accepted — never a panic. Reading the default as a raw integer now requires DEFAULT_RESERVE_REPLENISH_AMOUNT.get().

Version 0.7.0 introduces several intentional breaking changes to improve type safety, correctness, and API ergonomics. This section provides a complete mapping from the old API surface to the new one.

The execution domain was renamed from Transaction to Trade to align with standard financial terminology.

Raw Uuid identifiers were replaced with the [Id] enum, which supports UUID, ULID, and sequential (u64) formats. Trade IDs are generated via [UuidGenerator].

Raw numeric primitives used in the public API were replaced with validated domain newtypes. Each provides new(), try_new(), Display, FromStr, and serde support.

use pricelevel::{Price, Quantity, TimestampMs};

let price = Price::new(10_000);
let qty   = Quantity::new(100);
let ts    = TimestampMs::new(1_716_000_000_000);

// Convert back to primitives
assert_eq!(price.as_u128(), 10_000);
assert_eq!(qty.as_u64(), 100);
assert_eq!(ts.as_u64(), 1_716_000_000_000);

All arithmetic in financial-critical paths now uses checked operations and returns Result<T, PriceLevelError> instead of raw values. No silent saturation or wrapping is performed.

use pricelevel::{PriceLevel, PriceLevelError};

let level = PriceLevel::new(10_000);
// total_quantity() now returns Result
let total: Result<u64, PriceLevelError> = level.total_quantity();
assert_eq!(total.unwrap(), 0);

All struct fields in the execution and snapshot modules are now private. Use the provided accessor methods instead of direct field access.

Trade:

MatchResult:

TradeList:

The iter_orders() method now returns an iterator instead of a Vec, reducing allocations on the hot path. Use snapshot_orders() when a materialized Vec is needed.

Snapshots are now protected with SHA-256 checksums via [PriceLevelSnapshotPackage]. The full persistence/recovery flow is:

use pricelevel::PriceLevel;

let level = PriceLevel::new(10_000);

// Serialize to JSON (includes checksum)
let json = level.snapshot_to_json().unwrap();

// Restore from JSON (validates checksum)
let restored = PriceLevel::from_snapshot_json(&json).unwrap();

• #[must_use] is now applied to all pure/computed methods (price(), quantity(), trade_id(), order_count(), visible_quantity(), is_complete(), etc.). Ignoring a return value from these methods will produce a compiler warning.
• #[repr(u8)] is applied to small enums exposed in the public API ([Side], [TimeInForce]).

[PriceLevelError] gained new variants for the expanded error surface:

1. Replace Transaction / TransactionList with [Trade] / [TradeList].
2. Replace raw Uuid with [Id]; use [UuidGenerator] for trade IDs.
3. Wrap raw price/quantity/timestamp literals with Price::new(), Quantity::new(), TimestampMs::new().
4. Replace direct field access on Trade, MatchResult, TradeList with accessors.
5. Handle Result returns from total_quantity(), executed_quantity(), executed_value(), average_price(), and add_trade().
6. Replace iter_orders() collecting into Vec with snapshot_orders() if needed.
7. Update snapshot code to use [PriceLevelSnapshotPackage] for checksum validation.
8. Address new #[must_use] warnings on query methods.

[PriceLevel::match_order] now takes an explicit timestamp: TimestampMs argument, inserted between taker_order_id and the trade-id generator:

Why. The match path previously read the wall clock once per emitted [Trade] (SystemTime::now()) and once per fill inside the statistics update. That made the trade stream non-deterministic (each replay produced different Trade::timestamp values) and put two syscalls per fill on the hot path. The caller now threads a single taker timestamp in; it is stamped onto every [Trade] and used as the execution time for statistics. No clock is read on the match path, so matching the same input twice with the same timestamp yields a byte-identical trade stream — a prerequisite for snapshot/replay equivalence.

Pass the taker's arrival timestamp (or any deterministic value for tests/replay), e.g. [TimestampMs::new].

[PriceLevel::match_order] now honors the taker's [TimeInForce] and a new TakerKind. Two parameters are inserted between taker_order_id and timestamp:

To preserve the previous "fill what you can, report the remainder" behavior, pass [TimeInForce::Gtc] and [TakerKind::Standard].

New single-level semantics. Let available be the quantity this level can actually fill for the taker, capped at the incoming quantity:

• [TakerKind::PostOnly]: rejected if available > 0 (would take liquidity) — zero trades, full remainder, queue untouched.
• [TimeInForce::Fok]: killed if available < incoming — zero trades, full remainder, queue untouched; otherwise filled completely.
• [TimeInForce::Ioc]: fills available, discards the remainder (the taker is never rested by this layer).
• [TimeInForce::Gtc] / [TimeInForce::Gtd] / [TimeInForce::Day] and [TakerKind::MarketToLimit]: fill available, report the remainder in MatchResult::remaining_quantity for the order book to rest / convert.

New MatchResult signal. A fill-or-kill kill and a post-only rejection both leave zero trades and the full remainder — indistinguishable through the old fields from "the level had no liquidity". [MatchResult] gains an additive MatchOutcome (Filled / PartiallyFilled / NotFilled / Killed / Rejected), read via MatchResult::outcome, MatchResult::was_killed, and MatchResult::was_rejected. All existing fields and accessors are unchanged. The field is #[serde(default)] so older JSON deserializes (as NotFilled); the text Display / FromStr format is unchanged and re-derives the benign outcome on parse (a Killed / Rejected signal is not carried by the text format).

Resting-maker time-in-force expiry is still not enforced by the match path — only the taker's intent is honored here. Skipping / evicting expired makers remains the order book's responsibility.

The checksum-protected snapshot format now persists per-level statistics (issue #63). [PriceLevelSnapshot] carries the eight PriceLevelStatistics counters — orders added / removed / executed, quantity and value executed, last-execution and first-arrival timestamps, and the waiting-time sum — and [PriceLevel::from_snapshot_json] / [PriceLevel::from_snapshot] restore them instead of resetting to a fresh, zeroed set. The new field is covered by the package SHA-256 checksum automatically.

The snapshot format version (SNAPSHOT_FORMAT_VERSION) is bumped from 1 to 2. Snapshot packages written by an earlier release carry version: 1 and no statistics; they are no longer accepted — [PriceLevelSnapshotPackage::validate] rejects them up-front with a [PriceLevelError::InvalidOperation] version mismatch (not a confusing checksum error). Re-take any persisted snapshots with this release. No code changes are required at the call sites: snapshot_to_json() / from_snapshot_json() keep the same signatures.

SNAPSHOT_FORMAT_VERSION is bumped from 2 to 3 (issue #129). Version 3 owns the optional 9th statistics field, stats_degraded (issue #117): a degraded level — one where an execution's statistics contribution was dropped all-or-nothing — serializes that field, and such a payload is now a v3 package rather than a v2 package mislabelled with an extra field an old 8-field-only reader would reject.

Restore is backward compatible: [PriceLevelSnapshotPackage::validate] accepts both v2 (legacy, 8-field statistics, stats_degraded defaults false) and v3, so snapshots written by the previous release keep restoring unchanged; only v1 is still rejected. Checksum recomputation is version-agnostic — a non-degraded level serializes the same 8 fields under either version, so a legacy v2 package's SHA-256 still matches. New snapshots are written at v3. No code changes are required at the call sites.

PriceLevelStatistics::value_executed() (reached through [PriceLevel::stats]) now returns u128 instead of u64 (issue #140). It accumulates quantity * price, the same product that MatchResult::executed_value and Trade::total_value already return as u128. With a u64 accumulator, a caller scaling both price and quantity to fixed point (e.g. 1e8 each) exhausted it under ordinary volume (after 1845 executions of 1.0 @ 1.0), after which every execution's statistics were dropped and the level was permanently marked degraded. The trade stream was never affected. Callers that bind the result to a u64 must widen it (or convert with u64::try_from).

The accumulator is a lock-free AtomicU128 from the portable-atomic crate (a new dependency) on targets with a native 128-bit CAS (aarch64, and x86_64 with cmpxchg16b); elsewhere portable-atomic falls back to a lock for this one counter. A u128 overflow is still rejected all-or-nothing and marks the statistics degraded.

SNAPSHOT_FORMAT_VERSION is bumped from 3 to 4. A v4 payload may carry a value_executed above u64::MAX, which a v3 reader cannot represent, so new packages are labelled v4. A pre-0.10 reader rejects every v4 package, but it deserializes the whole package before checking the version: a v4 package whose value fits in u64 fails with a version mismatch ([PriceLevelError::InvalidOperation]), while one whose value exceeds u64::MAX fails earlier with a [PriceLevelError::DeserializationError]. Either way the old reader errors and never restores wrong statistics. Restore is backward compatible: [PriceLevelSnapshotPackage::validate] accepts v2, v3 and v4, and the JSON of a legacy u64 value is unchanged, so snapshots written by earlier releases keep restoring with their original SHA-256 checksum. The Display / FromStr text form likewise parses both widths.

Trade::total_value now returns Result<u128, PriceLevelError> instead of u128. It computes price * quantity with checked_mul and returns [PriceLevelError::InvalidOperation] on overflow, matching the checked arithmetic of MatchResult::executed_value, which previously used an unchecked * that could panic in debug or wrap in release. Callers must handle the Result (e.g. trade.total_value()?).

Accessors that previously returned raw integers for a domain concept now return the crate newtype, so raw u64 / u128 no longer leak across module boundaries (OrderType::price / id / side already returned newtypes — this completes the quantity / timestamp surface). Call .as_u64() / .as_u128() to recover the primitive, or keep working in the newtype.

[MatchResult::executed_value] / Trade::total_value still return u128 — there is no monetary newtype. [PriceLevel::match_order] keeps its incoming_quantity: u64 input (it is converted to [Quantity] at the [MatchResult] boundary internally); its 124 call sites are unchanged.

Snapshot wire format is unchanged. [Price] and [Quantity] are #[serde(transparent)], so a snapshot serializes the same JSON numbers as before; the snapshot format version is not bumped and the SHA-256 checksum over an unchanged payload still validates. Existing snapshot JSON restores without migration.

[PriceLevel::add_order] now returns Result<Arc<OrderType<()>>, PriceLevelError> instead of Arc<OrderType<()>>. It reserves the order's visible / hidden quantity and its count slot on the level's atomic counters (with checked fetch_update) before publishing the order to the queue, and returns [PriceLevelError::InvalidOperation] if any counter would overflow u64 — leaving the level completely unchanged rather than wrapping a counter while the queue already holds the admitted order. Callers must handle the Result — propagate with level.add_order(order)? (test fixtures and binaries may prefer .expect(...)); the returned Arc is unchanged on success. Admissions that stay within u64 (all normal use) behave exactly as before.

add_order also now rejects a duplicate id: publishing is an insert-if-absent, so reusing the id of an order already resting at the level returns the new [PriceLevelError::DuplicateOrderId] variant (again leaving the level unchanged) instead of overwriting the live order and leaving the id-keyed map and the ordered index disagreeing. Snapshot restore ([PriceLevel::from_snapshot] and the JSON / package forms) likewise rejects an orders vector that repeats an id rather than silently overwriting. Submitting genuinely distinct ids (all normal use) is unaffected.

Three intentional breaking changes remove infallible / overwriting paths that could desync a level's counters from its queue:

• impl From<&PriceLevelSnapshot> for PriceLevel is removed; use [TryFrom]. The old From swallowed aggregate-overflow errors and built the queue keep-first, so a snapshot repeating an id restored counters computed over every copy while the queue kept one. Replace PriceLevel::from(&snapshot) / let lvl: PriceLevel = (&snapshot).into(); with PriceLevel::try_from(&snapshot)? (or .expect(...) in tests). It delegates to [PriceLevel::from_snapshot], returning [PriceLevelError::DuplicateOrderId] on a repeated id and the per-order / level aggregate-overflow errors instead of hiding them.
• OrderQueue::push is now pub(crate). Unconditional overwriting publication is never safe for an external caller (reusing a live id would silently replace the resting order and strand its old index entry). Admission goes through add_order (or, at the queue layer, the insert-if-absent try_push); there is no public overwriting insert.
• OrderQueue::from_vec is now pub(crate). It is a keep-first constructor that drops duplicates silently; the public restore path is [PriceLevel::from_snapshot], which rejects them.

A [PriceLevel] now enforces that every resting order sits at the level's price and shares a single side (the first admitted maker pins the side; a fully drained level accepts either side again). [PriceLevel::add_order] returns [PriceLevelError::InvalidOperation] for an order whose price does not match the level, or whose side is incompatible with the resting side, and [PriceLevel::from_snapshot] rejects a snapshot that violates either (previously such orders were admitted, trading at the level price rather than their own and producing contradictory taker sides in one [MatchResult]). Callers that composed a level from mixed-price or mixed-side orders must route each order to the correct level.

Single-side coherence is a correctness invariant, not an eventually-consistent one like the advisory counters: it holds only when a given level's admissions arrive from a single logical writer (the composing order book routes each price to one admission path). The side is derived from the live queue, so under genuinely concurrent multi-writer admission a narrow race — an opposite side slipping into a momentarily empty level — can still admit a mixed side; see the note on the [PriceLevel] type.

[PriceLevel::matchable_quantity] gains a taker_id parameter: matchable_quantity(incoming_quantity) becomes matchable_quantity(incoming_quantity, taker_id). A resting maker sharing the taker id is skipped (self-trade prevention), matching the sweep, so a fill-or-kill dry run and the real sweep agree. match_order applies the same self-trade skip deterministically in every build profile (it used to be a debug-only assertion): a resting maker whose id equals the taker's is skipped — no self-trade is emitted and the other makers still match.

This self-trade guard is order-id identity — an order can never match itself. It is NOT account/owner-level self-trade prevention: two distinct order ids owned by the same user_id will still trade. Account-level STP is the responsibility of the order book composing these levels, which owns the account relationships a single price level does not.

A quantity increase via [PriceLevel::update_order] still demotes the maker to the back of the queue (fresh tail sequence, original timestamp), but it now does so in place — the order id never leaves the internal map. This closes the concurrency window the previous remove + re-insert opened (issue #119): a concurrent cancel can no longer be lost or resurrect the order, a concurrent same-id admission can no longer slip into the gap (add_order for a live id is always rejected), and the match sweep can no longer act on a stale front position. The public behaviour of update_order is unchanged; only its concurrency safety improves.

The internal OrderQueue::push — a blind, overwrite-on-collision insert with no remaining production caller — is removed from the public API (it is now test-only). Admission uses try_push (insert-if-absent) and the quantity-increase demotion uses the internal atomic re-sequence, so push was a footgun with no safe use; construct queues through [PriceLevel]'s public surface instead.

The random [Id] constructors could panic inside uuid / ulid / rand when the operating system failed to provide entropy (or an RNG failed to seed or reseed), and Default hid that behind an infallible trait. They are replaced by fallible constructors that draw bytes from a caller-supplied [EntropySource] and, for ULIDs, take their timestamp from a caller-supplied [UnixClock] or an explicit [TimestampMs]. The crate owns no randomness source and no clock reader, and adds no dependency.

All return Result<Id, PriceLevelError>:

• an entropy failure is returned unchanged from the source (conventionally the new [PriceLevelError::EntropyUnavailable] variant);
• a clock failure is returned unchanged from the caller's [UnixClock];
• a timestamp above [Id::ULID_MAX_TIMESTAMP_MS] (the 48-bit ULID time field) is rejected with [PriceLevelError::InvalidFieldValue] instead of being silently masked, and before any entropy is drawn.

No nil, repeated or predictable fallback identifier is ever substituted. Successful ids keep their wire formats: UUIDs are RFC 4122 / 9562 version 4 (version and variant bits set exactly as Uuid::new_v4 does), ULIDs carry the 48-bit timestamp and 80 random bits.

Implement [EntropySource] over the randomness facility your application already uses (an OS call such as getrandom, or a CSPRNG) and map its failure into a [PriceLevelError]. Implementations must not panic and must never report success without writing fresh unpredictable bytes into the whole buffer; return Err instead. A caller-supplied [UnixClock] carries the same no-panic obligation. Note that std::time::SystemTime::now panics inside std if the platform clock call fails, so a strictly panic-free clock needs a fallible time source; [TimestampMs::try_from_system_time] converts an already-read SystemTime with checked arithmetic (pre-epoch and u64 overflow are typed errors).

The adapter below delegates to a fill function the application owns and maps its error. Until a real source is wired in, the example's stand-in fails, and the constructors surface that failure instead of producing an id:

use pricelevel::{EntropySource, Id, PriceLevelError, TimestampMs};

/// Adapts an application-owned fallible fill function, for example
/// `FillEntropy(getrandom::fill)` with `getrandom` as your own dependency.
struct FillEntropy<F>(F);

impl<F, E> EntropySource for FillEntropy<F>
where
    F: FnMut(&mut [u8]) -> Result<(), E>,
    E: std::fmt::Display,
{
    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), PriceLevelError> {
        (self.0)(dest).map_err(|error| PriceLevelError::EntropyUnavailable {
            message: error.to_string(),
        })
    }
}

// Stand-in for an entropy source that is not configured (or has failed).
let mut entropy = FillEntropy(|_dest: &mut [u8]| Err("entropy source not configured"));

let uuid = Id::try_new_uuid(&mut entropy);
assert!(matches!(uuid, Err(PriceLevelError::EntropyUnavailable { .. })));

let ulid = Id::try_new_ulid_at(TimestampMs::new(1_716_000_000_000), &mut entropy);
assert!(matches!(ulid, Err(PriceLevelError::EntropyUnavailable { .. })));

Deterministic ids that need no entropy are unchanged: [Id::sequential], [Id::from_u64], [Id::from_uuid], [Id::from_ulid], [Id::nil] and [UuidGenerator].

Id::from_str (and Id's serde Deserialize, which parses the same text) now tries a 26-character ULID first, then any UUID text form, and only then a decimal u64. Previously u64 came first, so an all-digit ULID such as the nil ULID 00000000000000000000000000 came back as [Id::Sequential]. Now id.to_string().parse::<Id>() == Ok(id) holds for every [Id], and canonical sequential text (at most 20 digits) is unaffected.

Only non-canonical sequential spellings change meaning (the nil ULID text is the canonical ULID spelling; what changes is that it no longer reads as a zero-padded sequential id):

If you store sequential ids zero-padded to 26 or 32 characters, strip the padding (or build them with [Id::sequential]) before parsing.

use pricelevel::Id;

let nil_ulid: Id = "00000000000000000000000000".parse().unwrap();
assert!(nil_ulid.is_ulid());
assert_eq!("18446744073709551615".parse::<Id>().unwrap(), Id::sequential(u64::MAX));

Trade::new and the statistics helpers read the wall clock, narrowed Duration::as_millis() from u128 to u64 with as, and substituted 0 for a pre-epoch clock. The crate now reads no clock at all: time is either supplied by the caller as a [TimestampMs] or read once from a caller-supplied [UnixClock] whose failure is returned unchanged.

Semantics:

• reset(&clock) reads the clock before mutating anything; on failure every counter, timestamp and the degraded flag is left unchanged.
• time_since_last_execution* returns Ok(None) only when no execution was recorded (the clock is not read then); a clock failure is Err, and a now earlier than the last execution is [PriceLevelError::InvalidOperation] (it used to be None).
• Behavior change, no signature change: [PriceLevelStatistics::new], its [Default], [PriceLevel::new], [PriceLevelSnapshot::new], [PriceLevelSnapshot::with_orders], PriceLevelSnapshot::from_str and a snapshot payload that omits statistics no longer stamp the wall clock: first_arrival_time() starts at 0, meaning unstamped. They are now deterministic (identical input gives byte-identical, identically checksummed snapshots), and no clock failure can hide behind them. Use new_at / try_new, or reset_at / reset on a still-quiescent level, to record a start time.
• A serialized statistics object that omits first_arrival_time now decodes it as 0 (unstamped) instead of the restore instant, which was never the original start time. Every package this crate writes carries the field, so v2, v3 and v4 packages and their checksums are unaffected.
• [PriceLevel::match_order] was already clock-free; trade fields, explicit timestamps and matching determinism are unchanged.
• [PriceLevelStatistics] is now re-exported at the crate root so the new constructors are nameable (it was previously reachable only through [PriceLevel::stats] and [PriceLevelSnapshot::statistics]).

A conforming [UnixClock] must not panic. std::time::SystemTime::now can panic inside std if the platform clock call fails, so an implementation built on it does not meet that contract. The simplest path needs no clock trait: read the time in your own code (with whatever failure policy your application accepts), convert it with the checked [TimestampMs::try_from_system_time] (pre-epoch and u64 overflow are typed errors), and pass the explicit timestamp to the _at APIs or [Trade::with_timestamp]. A clock you inject for tests or replay can be a fixed value:

use pricelevel::{PriceLevelError, PriceLevelStatistics, TimestampMs, UnixClock};
use std::time::{Duration, UNIX_EPOCH};

// Explicit-timestamp path: the application owns the clock read.
// (`UNIX_EPOCH + ...` stands in for a time your code already read.)
let read_by_caller = UNIX_EPOCH + Duration::from_millis(1_716_000_000_500);
let now = TimestampMs::try_from_system_time(read_by_caller)?;

let stats = PriceLevelStatistics::new_at(TimestampMs::new(1_716_000_000_000));
stats.record_execution(10, 100, 0, 1_716_000_000_000)?;
assert_eq!(stats.time_since_last_execution_at(now)?, Some(500));
stats.reset_at(now)?;

// Injected clock path: a fixed clock that cannot panic.
struct FixedClock(TimestampMs);

impl UnixClock for FixedClock {
    fn try_now_ms(&self) -> Result<TimestampMs, PriceLevelError> {
        Ok(self.0)
    }
}

stats.reset(&FixedClock(now))?;
assert_eq!(stats.first_arrival_time(), now.as_u64());
assert_eq!(stats.time_since_last_execution(&FixedClock(now))?, None);

The text (FromStr) parsers now use checked access and a bounded nesting counter. Text written by Display parses exactly as before, and so does almost every malformed input. Two contracts tightened:

Segmentation is unchanged, and an element that fails to parse is still reported before a bracket imbalance, so errors for other malformed input are the same. A parser that cannot grow its output vector reports [PriceLevelError::CapacityExceeded] instead of aborting (resource Text; an InvalidOperation before #164).

use pricelevel::{PriceLevelError, TradeList};
use std::str::FromStr;

let trade = "Trade:trade_id=1;taker_order_id=2;maker_order_id=3;price=4;quantity=5;taker_side=BUY;timestamp=6";
assert!(TradeList::from_str(&format!("Trades:[{trade};note=[ok]]")).is_ok());
assert!(matches!(
    TradeList::from_str(&format!("Trades:[{trade};note=]]")),
    Err(PriceLevelError::InvalidFormat)
));

[PriceLevel::snapshot] walks the order shards without a transaction over the whole level, so a same-side quantity transfer between two shards during the walk (one order resized down, another up) could capture a set of orders whose visible or hidden sum overflows u64, even though every committed level state fits. The old code hit a debug_assert! in debug builds and, in release builds, silently stored the live atomic counter as the aggregate, a value that disagreed with the snapshot's own orders. It now rejects that walk, recollects a bounded number of times (8 attempts), and returns a typed error if no attempt is coherent.

Semantics:

• Coherent, not linearizable. A returned snapshot's visible_quantity, hidden_quantity and order_count always equal the checked sums and the length of its own orders. The orders may still combine states observed at different instants under concurrent same-side mutation; only a fill-or-kill match is excluded as a whole.
• Bounded retries. A walk is recollected when it came back mixed-side across a side transition (previously an unbounded loop until flipping stopped) or its aggregates overflow u64. After 8 rejected attempts the call returns [PriceLevelError::InvalidOperation] and leaves the level unchanged; retry later or quiesce mutators first.
• [PriceLevelSnapshot::refresh_aggregates] is now transactional: on error no field changes (previously order_count was updated before a later overflow was detected).
• Snapshot format v4, the package checksum and restore order are unchanged for every snapshot that succeeds.

use pricelevel::{PriceLevel, PriceLevelError};

let level = PriceLevel::new(10_000);
// Before: let snapshot = level.snapshot();
let snapshot = level.snapshot()?;
assert_eq!(snapshot.order_count(), snapshot.orders().len());

Result allocation and growth no longer panic (#170), and [MatchResult] carries the failure that stopped a match early (#164 contract).

• Capacity failures (an unrepresentable size such as usize::MAX, or an allocator refusal) return [PriceLevelError::CapacityExceeded], whose payload is fixed-size so reporting it never allocates. n == 0 never allocates.
• [MatchResult::add_trade] validates and reserves before committing, so an Err leaves trades, filled ids, remaining quantity, completion and outcome unchanged.
• [PriceLevel::match_order] still returns [MatchResult]. When a step fails, the sweep stops and [MatchResult::error] is Some; the trades, filled ids and remaining quantity describe exactly what the level committed. The stop causes are: maker arithmetic (#169), the resting-order count (#163), result growth (#170), trade-id exhaustion (#168), FIFO sequence exhaustion (#165), a parked-sequence set that cannot grow (#164), and, after a committed step, a failed count release (#163) or a refused post-lock replenish counter transition (#128 fallback, #164). For every cause except the last two the level's counters agree with its queue; the last two poison the level (counters known to disagree): later mutators return InvalidOperation, matching is refused, and the caller must treat the level as failed and reconstruct it from a snapshot. See the match_order failure contract. A fill-or-kill taker checks or reserves everything before touching any maker: on failure it is [MatchOutcome::Killed] with the error set and the level unchanged. Callers that used to treat every result as a natural end must check result.error() before resting a remainder: a stopped sweep's remainder is not "no more liquidity", and resting it after a self-trade race can duplicate an id at the level.
• [PriceLevel::matchable_quantity] now replays the resting queue in insertion-sequence (sweep) order rather than (timestamp, sequence) order, the order match_order actually consumes it. This is a correctness fix that can change the returned total, and therefore a fill-or-kill verdict, when iceberg / reserve replenishment headroom depends on visit order: for example Standard(qty 1, ts 200), Iceberg(visible 0, hidden 1, ts 100), Standard(qty u64::MAX - 1, ts 300) inserted in that order with a taker requesting 2 returned 0 before (the old timestamp-order replay tried the iceberg at full visible capacity) and now returns 2, matching what the sweep executes.
• [PriceLevelError] now derives Clone, PartialEq, Eq, Serialize and Deserialize (it travels inside MatchResult). Exhaustive matches need an arm for CapacityExceeded; [CapacityResource] is #[non_exhaustive].
• Wire format: serde (JSON and bincode) emits an error field (null / None when the match ran to its end). JSON written before the field existed decodes as "no error". Positional encoders (bincode) must decode with the same crate version that encoded, as with any added field. The Display / FromStr text form does not carry the error slot (it decodes as "no error", like outcome).

Every quantity operation in the order-matching paths is checked (#169).

• The tuple contents are unchanged on success. Add ? (or match the Result); an Err is [PriceLevelError::InvalidOperation] and the input order is unchanged (both methods borrow self).
• A reserve order whose partial-fill replenishment new_visible + replenish_qty overflows u64 now returns InvalidOperation. Before, it returned the "no progress" tuple (0, Some(self.clone()), 0, incoming). Only an order whose own visible + hidden exceeds u64::MAX reaches this, and [PriceLevel::add_order] never admits one, so a level's matching is unchanged for every admitted order. Every subtraction is bounded by a preceding comparison or min, so its error branch is unreachable.
• [PriceLevel::match_order] handles an Err from match_against under the #164 contract: the sweep stops at that maker before mutating it and reports the committed prefix with [MatchResult::error] set; a fill-or-kill taker detects it in its dry run and is [MatchOutcome::Killed] with the error set and the level unchanged. [PriceLevel::matchable_quantity] returns the same prefix.
• [DEFAULT_RESERVE_REPLENISH_AMOUNT] keeps its type (NonZeroU64) and value (80); only its construction changed (no unreachable!).

[UuidGenerator] no longer wraps its sequence counter (#168). The old next() advanced it with an unchecked atomic fetch_add: that never panicked, but at u64::MAX it wrapped to 0 and re-issued the counter-zero id, a duplicate-id correctness defect reachable at once by deserializing a generator near the end of its range.

• Usable sequence values are 0 ..= u64::MAX - 1; u64::MAX is the exhaustion sentinel and is never issued. Every issued value produces the same UUID bytes as before (v5 over the same namespace and decimal name).
• Once exhausted, every request returns [PriceLevelError::CapacityExceeded] { resource: IdSequence, additional } forever; the counter never wraps, saturates or resets. The serde form is unchanged, and an exhausted generator serializes as "counter": 18446744073709551615 and restores exhausted.
• [PriceLevel::match_order] reserves each trade id before committing the maker mutation for that step. On exhaustion the sweep stops with [MatchResult::error] set and the committed prefix reported (the #164 contract); later calls against crossable depth with that generator return no trades and the error. A fill-or-kill taker reserves all of its ids up front: if the generator cannot supply them, it is [MatchOutcome::Killed] with the error set, the level is unchanged and no id is consumed.
• Trade ids are consumed only by steps that emit a trade. For a generator used sequentially by one level (no other caller drawing from it) and with no abandoned reservation, the trade-id stream for a fixed input is therefore gap-free and deterministic; a generator shared across levels or direct callers interleaves its values by scheduling and guarantees only uniqueness. A value reserved for a step that then aborts on a visible-counter overflow, or a fill-or-kill id left unused, is skipped and never re-issued.

use pricelevel::{CapacityResource, PriceLevelError, UuidGenerator};

let generator: UuidGenerator = serde_json::from_str(
    r#"{"namespace":"00000000-0000-0000-0000-000000000000","counter":18446744073709551614}"#,
)
.map_err(|e| PriceLevelError::DeserializationError { message: e.to_string() })?;
let _last = generator.try_next()?;
assert!(generator.is_exhausted());
assert!(matches!(
    generator.try_next(),
    Err(PriceLevelError::CapacityExceeded { resource: CapacityResource::IdSequence, .. })
));

Monotonic internal counters no longer wrap at their maximum (#165); each now has a typed, allocation-free outcome instead of a silent wrap to zero. The 64-bit counters (the FIFO sequence, the epochs and the statistics seqlock sequence) are out of reach at any practical operation rate. The usize statistics counters orders_added / orders_removed are not on 32-bit targets: they reach usize::MAX after about 4.29 billion events (roughly 12 hours at 100k events/s), after which the statistics are marked degraded while admissions and cancels continue.

• Statistics order-event counters keep usize::MAX, set the sticky stats_degraded flag and return CounterExhausted. The engine's admissions and removals still succeed (the queue mutation has committed; the counters are advisory).
• Statistics seqlock. A write section opens only while its sequence can also close without wrapping. A refused record_execution drops the execution all-or-nothing and marks the statistics degraded (the match is unaffected); a refused reset / reset_at changes nothing. A restored or cloned statistics object starts a fresh sequence.
• FIFO sequences are reserved before any commit. [PriceLevel::add_order] and a quantity-increasing [PriceLevel::update_order] return CounterExhausted with the level unchanged; [PriceLevel::match_order] stops at a replenishment that finds no sequence, reporting the committed prefix and the error in [MatchResult::error] (fill-or-kill is killed before any maker is touched).
• Stop-cause precedence in one sweep step. Before a step commits anything, the sweep checks, in this fixed order: the maker's match_against arithmetic (InvalidOperation, #169), for a full consume the resting-order count release (InvalidOperation, #163; see the next guide), the trade id (CapacityExceeded { resource: IdSequence }, #168), the FIFO sequence for a replenishment (CounterExhausted { counter: QueueSequence }), and the level's visible headroom. The first failure stops the sweep with the committed prefix. A fill-or-kill taker checks the same causes up front: epoch headroom, the dry run's stop error (arithmetic or count, whichever maker comes first), depth, sequence headroom, result storage, then the trade-id block.
• Epochs stop at u64::MAX, which readers treat as unknown; mutations and sweeps are refused before they start once an epoch is within 2^32 of it. A post-only taker that cannot linearize its depth scan is rejected with the error. Rebuild the level from a snapshot to reset the epochs and sequences.
• OrderQueue's From<Vec<_>> silently dropped orders it could not insert (a repeated id); TryFrom rejects instead.

Engine invariant checks that used to be debug-only assertions, or silent no-ops in release builds, are now typed, transactional failures (#163). No public signature changes; the observable behavior below is new.

• Resting-order count release. A cancel / price-moving update ([PriceLevel::update_order]) and every full consume in [PriceLevel::match_order] validate the level's resting-order count BEFORE the queue removal, inside the same per-entry critical section that performs the removal, so a concurrent admission or cancellation of the same id can never produce a spurious error: the removal either sees the order (with its count) or reports it absent (Ok(None) for update_order). A count that disagrees with the queue (zero while the order rests) now returns [PriceLevelError::InvalidOperation] with the queue, priority, counters and statistics untouched. Previously release builds removed the order and silently skipped the decrement.
  • A non-fill-or-kill sweep stops at that maker with the committed prefix and [MatchResult::error] set (the #164 contract).
  • A fill-or-kill taker is [MatchOutcome::Killed] with the error before its first mutation: its dry run (and [PriceLevel::matchable_quantity]) projects the same count.
  • If the release still fails after the removal committed (reachable only when the count already disagreed and a concurrent removal took the last count), the call returns the error and the level is poisoned: later mutators return InvalidOperation and matching is refused, as for a panicked guard holder. Reconstruct the level from a snapshot.
• Update decisions. A resize validates the decided order's id before any level-counter reservation, and the counter deltas are checked. A rejected update never leaves a partial reservation. If a rollback of a partial reservation cannot be applied, the level is poisoned instead of the counters drifting.
• Poison message. The poisoned-level error now reads "price level poisoned by a panicked operation or a broken internal invariant; reconstruct it from a snapshot". Match on the variant, not the text.
• Width policy. [PriceLevel::order_count] converts the stored u64 count with a checked conversion. Admission and snapshot restore cap the count at usize::MAX on targets narrower than 64 bits (in addition to the 62-bit count field), so the value is exact on every target. A restore whose order vector exceeds that cap returns InvalidOperation. The match pre-size hint uses a checked usize::try_from of the taker quantity: a quantity above usize::MAX sizes by the order count instead of truncating.

Every owned collection the engine and the snapshot / serialization paths grow is now reserved through try_reserve* before any state mutation (#164). A refused reservation is reported as the fixed-size [PriceLevelError::CapacityExceeded] (its [CapacityResource] tag is Copy, so reporting it never allocates) instead of aborting the process. CapacityResource gains OrderSnapshot, SweepScratch, RestoreScratch and SerializationBuffer (it is #[non_exhaustive]).

Behavior:

• Sorting. [OrderQueue::snapshot_vec] (and [PriceLevel::snapshot_orders]) sort in place with an unstable sort on the unique (timestamp, sequence) key: same order as before, no hidden stable-sort scratch buffer.
• Matching. The sweep's parked-sequence set holds its first live key inline (no allocation; the self-trade skip, the only park that fires today, has at most one live key, and the slot frees itself when that key goes stale through a cancel, readmission or demotion) and grows fallibly beyond it. A fill-or-kill dry run can predict a park (a maker sharing the taker id admitted between the self-match lookup and the exclusive guard). A park that cannot be recorded stops a non-fill-or-kill sweep with the committed prefix and [MatchResult::error] carrying the original SweepScratch error. A fill-or-kill taker reserves its dry-run working copy and its park set before the first mutation; a refusal kills it with the level untouched, the error set and an ERROR event. [PriceLevel::matchable_quantity] returns Err only when its working copy cannot be reserved (a silent 0 would under-report depth). Callers must check result.error() before resting a taker's remainder: a stopped sweep's remainder is not "no more liquidity", and resting it after a self-trade race can duplicate an id at the level.
• Snapshots. [PriceLevel::snapshot] returns the capacity error at once (no recollection). The checksum payload is streamed into SHA-256 (no payload buffer; checksums are byte-identical), the hex string and [PriceLevelSnapshotPackage::to_json] output grow fallibly, and decoded order vectors / checksum strings are reserved fallibly (a refusal while decoding surfaces as DeserializationError through serde). Legacy payloads decode unchanged.
• Formatting. Display / Debug for [PriceLevel] and [OrderQueue] never return fmt::Error on a refused materialization (that would make to_string panic): they write an orders=!<error> / <unavailable: ..> marker, which the FromStr parsers reject.
• Text parsers. A refused parser buffer is now CapacityExceeded (resource Text) instead of an InvalidOperation whose message was allocated after the failure.
• Poisoning. The defensive post-lock replenish counter branch (#128, unreachable today) no longer ignores a refused counter transition: it logs at ERROR, poisons the level and stops the sweep with InvalidOperation, like the #163 failed rollback. The result still reports the committed trades exactly, but the level's counters are known to disagree with its queue: treat the level as failed.
• Not covered. DashMap / SkipMap node insertion and Arc::new have no stable fallible API; an allocator failure there aborts the process (not a Rust panic). See doc/panic-boundaries.md.

1. Clone the repository:

git clone https://github.com/joaquinbejar/PriceLevel.git
cd PriceLevel

2. Build the project:

make build

3. Run tests:

make test

4. Format the code:

make fmt

5. Run linting:

make lint

6. Clean the project:

make clean

7. Run the project:

make run

8. Fix issues:

make fix

9. Run pre-push checks:

make pre-push

10. Generate documentation:

make doc

11. Publish the package:

make publish

12. Generate coverage report:

make coverage

To use the library in your project, add the following to your Cargo.toml:

[dependencies]
pricelevel = { git = "https://github.com/joaquinbejar/PriceLevel.git" }

Here are some examples of how to use the library:

To run unit tests:

make test

To run tests with coverage:

make coverage

We welcome contributions to this project! If you would like to contribute, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and ensure that the project still builds and all tests pass.
4. Commit your changes and push your branch to your forked repository.
5. Submit a pull request to the main repository.

If you have any questions, issues, or would like to provide feedback, please feel free to contact the project maintainer:

Joaquín Béjar García

• Email: jb@taunais.com
• Telegram: @joaquin_bejar
• GitHub: joaquinbejar

We appreciate your interest and look forward to your contributions!

License: MIT

Repositories by the same author that this project depends on, and repositories that depend on it.