Tracebook 0.4.1: Externally Validated Rust Semantics

Tracebook 0.4.1: Externally Validated Rust Semantics

Version 0.4.1 is a focused validation patch. It does not expand Tracebook's
protocol or campaign surface. It incorporates the first independent maintainer
review of a native engine adapter and makes the resulting boundary executable.

Maintainer Review

The orderbook-rs maintainer reviewed Tracebook's adapter against the current
0.11.0 source in
orderbook-rs issue #203.
They confirmed that, for fifo-limit-v1:

1. a native quantity decrease keeps its existing FIFO insertion sequence;
2. replacement is cancel-and-add and always loses time priority;
3. maker and taker source IDs are translated faithfully; and
4. snapshot queue order agrees with matching order because admission timestamps
   are monotonic and the profile never increases quantity in place.

The adapter now pins orderbook-rs 0.11.0 and constructs each symbol with a
stable UUID-v5 trade-ID namespace. Equal native command streams therefore mint
equal native trade IDs. Protocol v1 still compares portable source-order fills,
not engine-private trade IDs, so this is a determinism improvement without a
wire-schema change.

Upstream Impact

The review established that Tracebook was consuming queue-priority behavior as
a public contract. Upstream responded by documenting that contract and adding
property-based decrease/increase priority tests in
orderbook-rs PR #204.

Review of that work also exposed a real discrepancy outside Tracebook's current
profile: an in-place quantity increase receives a fresh insertion sequence but
keeps its old timestamp, so a snapshot round-trip could restore the order at
its former queue position. The issue is tracked in
orderbook-rs #205,
and the lower-level snapshot repair landed in
PriceLevel PR #110.

This was surfaced by independent review of Tracebook's adapter boundary, not by
an automatic Tracebook campaign. fifo-limit-v1 and fifo-full-v1 remain
unaffected because they only decrease quantity in place, model replacement as
cancel-and-new, and never restore candidate snapshots.

Executable Boundary

The native adapter test suite now proves:

• decrease leaves two same-price makers in their original order;
• replacement moves the replaced maker behind its peer;
• equal symbol and command streams mint equal native trade IDs;
• different symbols receive distinct native trade-ID streams; and
• the intentionally faulty adapter still diverges at event 173 and reduces to
  the same five-event reproducer.

The correct 0.11.0 adapter retains the same public results: 13/13 on the fixed
trace, 7/8 on the standard suite with only pro-rata excluded, and 1000/1000
on the deterministic fifo-full-v1 campaign.

Compatibility

• Distribution: tracebook-sim==0.4.1
• Python: 3.10-3.13
• Conformance protocol: version 1, unchanged
• Artifact schemas: version 1, unchanged
• Campaign generator: version 2, unchanged
• Campaign hashes and the event-173 failure ID: unchanged

The next product milestone remains third-party adapter adoption. Additional
profiles and candidate benchmarking should follow feedback from an engine
author who did not help design the protocol.

Tracebook 0.4.0: From Semantic Diff To Failure Corpus

Tracebook 0.4.0: From Semantic Diff To Failure Corpus

Version 0.3.0 changed Tracebook from a Python order-book simulator into a
matching-engine correctness lab. Version 0.4.0 makes that category operational:
it can search for a lifecycle bug, preserve the first failure, reduce it, replay
it exactly, and turn it into a CI regression asset.

The release is built around one public proof, not a passing-event count.

The Proof

The repository ships two native Rust binaries over the pinned orderbook-rs
0.10.4 engine. One is correct. The other intentionally applies stale FIFO
priority after a reduce-and-replace sequence in the structured probe book.

With fifo-limit-v1, seed 42, and 200 events per trace, Tracebook:

1. generates the lifecycle workload independently of candidate behavior;
2. detects the first incorrect maker trade at original event 173;
3. classifies it as queue-priority drift;
4. reduces the 173-event prefix to five causal events;
5. proves the result is one-minimal within the reduction contract;
6. replays the same maker-ID mismatch deterministically; and
7. runs the five-event trace successfully against the correct Rust binary.

The campaign hash is
sha256:3630ea1789e27b6e416e1e241ca4ef8d5a28f0f2bf660fae3c0a1c8ff39ba7c6.
The failure ID is failure-bc8b19d3e0e3441a98db.

Public Surface

• tracebook-conformance campaign generates deterministic stateful workloads,
  stops at the first drift, and automatically minimizes it.
• tracebook-conformance minimize reduces an existing divergent trace.
• tracebook-conformance reproduce loads sibling corpus metadata and requires
  the exact saved failure class and structural divergence.
• --candidate-cmd accepts one shell-style candidate command while allowing
  Tracebook options to follow it. The legacy final-position --candidate form
  remains supported.
• --output-dir preserves the 0.4 development bundle layout;
  --corpus-dir adds deterministic failure directories with top-level
  original.jsonl, reduced.jsonl, and failure.json.
• run, suite, minimize, campaign, and reproduce emit canonical JSON
  and optional JUnit XML.
• Campaign JSON reports reference-observed semantic capability coverage for
  every declared capability in the selected profile.

Packaging

The tracebook-sim sdist includes the complete integrations/orderbook_rs
source tree, pinned Cargo manifest and lockfile, Rust toolchain declaration,
correct adapter, and intentionally faulty example. Compiled Rust artifacts are
not distributed. The wheel contains the Python runner and CLIs; users who want
the maintained Rust example obtain its source from the sdist or repository.

The copy-paste GitHub Actions workflow installs tracebook-sim==0.4.0 from
public PyPI, builds the candidate engine, runs fifo-limit-v1, and uploads the
JSON corpus plus JUnit report even when conformance fails.

Compatibility

• Distribution name: tracebook-sim
• Import namespace: tracebook
• Python: 3.10-3.13
• Conformance protocol: version 1
• JSON artifact schemas: version 1
• Campaign generator: version 2
• Built-in profiles: fifo-limit-v1, fifo-full-v1

Generator version 2 intentionally changes campaign and trace hashes from the
0.4.0 development snapshots by adding the structured FIFO probe. Profile names
stay stable because every campaign artifact records its generator version.

What Comes Next

The next milestone is external validation, not another feature expansion. The
highest-value outcomes are an adapter review from an engine maintainer, a
third-party engine adopting the campaign runner in CI, or a real semantic
discrepancy found outside the intentionally faulty example. Candidate
benchmarking and additional engines should follow evidence from those adapter
authors rather than assumptions made solely inside this repository.

Tracebook remains a reference oracle and reproducible failure workbench. It is
not a production exchange, exchange certification, or an HFT latency claim.

Tracebook 0.3.0: A Matching-Engine Correctness Lab

Tracebook 0.3.0: A Matching-Engine Correctness Lab

Version 0.3.0 changes the category of the project.

Earlier releases made Tracebook a trustworthy, installable Python order-book
simulator with deterministic replay, historical L3 normalization, lifecycle
semantics, profiling, and bounded benchmarks. That remains useful, but it does
not answer the sharpest question an engine author has:

Does my implementation produce the same trades and queue state, event by
event, and what is the smallest trace that proves it does not?

0.3.0 answers that question. Tracebook is now a conformance-testing and
reproducible failure-analysis toolkit with an inspectable reference engine.

Before And After

Before 0.3.0	In 0.3.0
Run workloads through a Python simulator	Run the same trace through Tracebook and any external engine
Inspect one engine's final state	Compare outcomes, trades, queue position, and complete state after every event
Reproduce a bug manually	Preserve and automatically minimize the failing trace
Treat examples as informal	Run a SHA-256-locked adversarial corpus locally and in CI
Describe portability	Prove it through a pinned integration with a second implementation

This is not an attempt to out-simulate agent-based research platforms or replace
a production exchange. It is a smaller and more testable role: the correctness
oracle, semantic diff, and regression corpus beside another matching engine.

What Ships

• A versioned, language-neutral NDJSON protocol for Rust, C++, Java, Python, or
  any process that can read stdin and write stdout.
• Per-event comparison of applied/rejected outcomes, stable rejection codes,
  ordered source-ID trades, resting-order counts, and canonical queue-state
  hashes.
• Full-state localization at the first divergence, including exact JSON paths
  for order fields and queue positions.
• Deterministic delta debugging that reports either a proven one-minimal trace
  or honest run-budget exhaustion.
• Eight hash-locked cases spanning FIFO, pro-rata, IOC/FOK/market orders, STP,
  replacement, reduction, tick policy, deep cancellation, and multiple symbols.
• tracebook-conformance run, suite, sample, and minimize commands,
  versioned JSON artifacts, public adapter APIs, package fixtures, and wheel
  smoke tests.
• A pinned PythonMatchingEngine integration and scheduled compatibility check.

Why The External Integration Matters

The PythonMatchingEngine adapter validates 13 native FIFO/LIMIT lifecycle events
with identical trades, queue priority, rejection behavior, and final state. Its
full-suite profile agrees on fifo-lifecycle and deep-cancellation, then
reports six expected differences where the engine's contract is narrower.

That result is more useful than a manufactured green badge. Tracebook identifies
where two contracts stop agreeing without declaring that every difference is a
bug. Engine authors decide which behavior is required; Tracebook makes that
decision executable and reviewable.

Compatibility

• The Python distribution remains tracebook-sim; imports remain tracebook.
• Existing matching, replay, corpus, benchmark, dashboard, and web commands are
  retained.
• Conformance protocol version 1 and artifact schema version 1 are the new
  interoperability contracts. Future incompatible changes require new versions.
• Adapters must reserve stdout for NDJSON protocol frames and send diagnostics
  to stderr.

Known Boundaries

• The reference semantics are explicit, not universal exchange law. A different
  venue contract can legitimately diverge.
• Adapter-process timing includes serialization, pipes, translation, and OS
  scheduling. Conformance reports are correctness artifacts, not latency
  benchmarks.
• The first maintained third-party integration is PythonMatchingEngine. More
  languages and engines are still needed to establish a broader ecosystem.
• Capability negotiation and suite filtering are not part of protocol v1;
  narrower engines should run a compatible suite and retain the standard suite
  as a separately interpreted profile.

Start Here

1. Run the real-engine demo.
2. Read the protocol and adapter contract.
3. Add the copy-paste CI workflow.
4. Preserve every confirmed mismatch as a minimized JSONL regression fixture.

Tracebook 0.2.0

Tracebook 0.2.0

A trust, installability, and real-data workflow release.

Highlights

• Published distribution name: tracebook-sim (Python imports remain tracebook).
• New normalized CSV/JSON/JSONL order-event replay API and tracebook-replay CLI.
• Hardened order ownership, validation, replacement, replay fidelity, callbacks, snapshots, simulation lifecycle, and profiling.
• PEP 561 typing metadata, packaged dashboard assets, Python 3.10-3.13 CI, a 75% coverage gate, installed-wheel smoke tests, and OIDC Trusted Publishing.
• Expanded API stability, event replay, performance, security, support, and release documentation.

Install

python -m pip install tracebook-sim==0.2.0

See the full changelog.

Tracebook remains alpha software and is not production trading infrastructure.

tracebook v0.1.1

Patch release from an adversarial QA pass — 8 confirmed bugs fixed, each with a regression test. Recommended upgrade from v0.1.0.

Fixes

Matching correctness

• Sub-tick incoming price could rest beside a matchable order and lock the book (match used the raw price while resting prices were snapped) — incoming prices are now snapped before validation/matching.
• A positive sub-half-tick price could snap to 0.0 and execute for free — such prices are now rejected.

Resource / lifecycle

• matching_engine.trades grew unbounded (memory leak) — now a capped deque; total_trades stays cumulative.
• MagicTraceSession.stop() wedged the session and left a zombie child when magic-trace self-exited — now guards poll(), always reaps, and unwedges in finally.

Concurrency

• replace_order and the performance-monitor alert path fired user callbacks while holding a lock (deadlock vector) — callbacks now fire lock-free; the replace rollback is guarded against a concurrent clear().

Determinism

• start_recording() on a non-empty book silently diverged on replay (or crashed on a later cancel) — it now requires an empty book.

Hardening

• The property-based invariant fuzz now samples off-grid prices, so the locked-book class of bug is guarded going forward.

131 tests, mypy src/tracebook clean, black / flake8 / bandit clean. See CHANGELOG.md.

Alpha software: APIs may still evolve before v1.

tracebook v0.1.0

First tagged alpha release of tracebook — a latency-focused order-book simulation and market-microstructure workbench built for inspectable behavior over inflated performance claims.

Highlights

Matching core

• FIFO and pro-rata matching with limit / market / IOC / FOK semantics
• Integer tick grid (exact price-level keying), single resting-price execution rule
• Atomic replace_order, bounded duplicate-id guard
• Self-trade prevention (CANCEL_RESTING / CANCEL_INCOMING)

Determinism & tooling

• Deterministic record/replay (EventLog → replay) reproducing identical trades and book state
• Reproducible benchmark runner with 8 scenarios (deep book, high-cancellation, pro-rata-with-events, multi-symbol)
• Honest, separated metrics (generation vs matching vs event latency); Dash dashboard demo

Performance

• Pure-Python order book, no JIT theater — hot paths are O(1)/flat where it counts (in-level cancel, FIFO matching), bisect-indexed price levels
• Per-order path ~4× faster than the pre-1.0 baseline

Quality

• 124 tests including property-based matching invariants and artifact JSON-schema tests
• Package-wide mypy (with check_untyped_defs) enforced in CI; black / flake8 / bandit clean

See CHANGELOG.md for the full history and docs/performance.md for local benchmark baselines.

Alpha software: APIs may still evolve before v1. Benchmark numbers are local artifacts, not portable claims.