tickvault 0.1.1

Full-depth crypto order book recorder and archive that publishes its own gap statistics
Documentation
# Querying and replaying the archive

```
tickvault query  --archive ./archive --venue kraken --symbol BTC-USD --bar-secs 10
tickvault replay --archive ./archive --venue kraken --symbol BTC-USD --speed 5
```

## Everything streams

A range query opens one file and holds one Parquet batch at a time. Asking
about a day costs the same resident memory as asking about a second, and a
consumer never has to decide how much of the archive fits in RAM. Measured on a
63-file archive: a query over the whole thing opened all 63 files, one narrowed
to the last eighth opened 9.

The starting book comes from [reconstruction](reconstruction.md), so a query
over the last hour of a day costs the last hour rather than the day. The two
share one implementation of applying archived rows to a book; they differ in
which rows they feed it, which is where the bugs have actually been.

The cursor is deliberately **not** an `Iterator`. Yielding the book would copy
it once per message, and a day of a busy venue is millions of messages.
Borrowing it is what a lending iterator would do and Rust has no such trait, so
the cursor advances and the caller reads the book in place.

## Aggregations come from the book

```
 bar start (s)         open         high          low        close     msgs  spread bp       volume
1787626110.000     80768.15     80784.25     80768.15     80775.95      652       0.10      unknown
1787626120.000     80775.95     80775.95     80751.05     80751.05      408       0.07      unknown

final book: mid 80723.05 spread 0.1 imbalance -0.8375 over 5 levels
```

Open, high, low and close are the **mid price**, sampled from the book after
every message. Not from bars: a bar built from a bar has already lost the thing
a microstructure question is about.

Also available, all from the book that was actually there: spread (absolute and
in basis points), order book imbalance over the top N levels, and the quantity
resting within a price offset of the mid, which is the question "how much can I
trade before moving the price by X".

### Volume says `unknown`, and that is the point

An OHLCV bar normally carries traded volume, and this is a *book* archive. An
aggregated feed shows a level shrinking and never says whether it traded or was
cancelled, so the volume of a Kraken or Coinbase bar is not something the data
contains. It is reported as `unknown` rather than zero, because **zero would
claim nothing traded.**

An order-by-order feed does report executions, so a Bitstamp L3 bar carries a
real traded quantity. Same column, honest in both cases, with the difference
visible rather than averaged away.

### Empty intervals are absent, not flat

An interval with no messages does not produce a bar. A bar that was never
observed is not the same as a flat one, and filling it in would hide exactly the
outages this archive exists to publish.

Two more things that are `None` rather than a plausible number: the mid of a
one-sided book, and the imbalance of an empty one. Both are undefined, and
neither is zero.

## Replay

```
$ tickvault replay --archive ./archive --venue kraken --symbol BTC-USD --every 250
 1787626116056015084      80775.9 / 80776        spread 0.1
 1787626120695287167      80759.1 / 80762.9      spread 3.8
 1787626128889858875      80752.7 / 80752.8      spread 0.1

2828 messages (0 suspect) covering 58.105s in 0.017s, 3508.0x real time
```

`--speed 0` runs as fast as the archive reads, which is what a backtest wants.
Any other value preserves the recorded gaps, scaled: `--speed 1` is real time,
`--speed 5` is five times faster. Measured: 4.848s of archive replayed in 1.221s
at a 5x request.

Pacing is against the recorded receipt gaps, so a replay reproduces the feed's
own rhythm rather than a smoothed version of it. That is the difference between
testing whether a strategy *works* and testing whether it can *keep up*: a burst
that arrived in one millisecond is delivered as one millisecond of work.

A consumer that takes longer than a gap simply proceeds. Sleeping the full gap
anyway would make every later message later still, and the replay would drift
further behind the whole way through.

## Suspect data travels with the query

A cursor reports what it could not vouch for: the seed's doubts plus anything
the range itself carried, as suspect rows and their span. Suspect messages are
still delivered, and each `Tick` says whether it was one. The caller decides
what to do; the query's job is to make sure it cannot be used without knowing.