tickvault-ob 0.1.0__tar.gz

tickvault_ob-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: ci
+
+on: [push, pull_request]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  # Formatting, lints and the whole suite. Clippy is -D warnings because a
+  # warning nobody fails on is a warning nobody reads.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup component add rustfmt clippy
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo test --release
+
+  # The phase 3 acceptance gate, and the reason the archive can claim anything
+  # about crashes: SIGKILL the writer at randomised offsets during sustained
+  # write, restart, and assert every file reads back and the truncation point is
+  # recorded. It spawns and kills real processes, so it lives behind --ignored
+  # and runs here rather than on every developer's `cargo test`.
+  crash-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - run: cargo test --release --test gate_crash_recovery -- --ignored --nocapture
+
+  # Two claims. The read half of the crate compiles without the capture half,
+  # which is what makes the viewer possible; and the viewer rebuilds the same
+  # book the library does, which is what makes the viewer honest.
+  wasm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup target add wasm32-unknown-unknown
+      # The feature split: no tokio, no TLS stack, no C compression codec.
+      - run: cargo check --lib --no-default-features --target wasm32-unknown-unknown
+      - name: viewer compiles to wasm
+        working-directory: viewer
+        run: cargo build --release --target wasm32-unknown-unknown
+      - name: viewer agrees with the library
+        working-directory: viewer
+        run: cargo test --release
+
+  # The bindings, against a wheel rather than a source tree, so the tests
+  # exercise what someone actually installs.
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # The Python tests replay committed tapes through this binary to build a
+      # fixture archive, so they need it built but never need a live venue.
+      - run: cargo build --release --bin tickvault
+      - run: pip install maturin pytest pyarrow polars pandas matplotlib
+      - name: build and install the wheel
+        working-directory: bindings
+        run: |
+          maturin build --release --out dist
+          pip install --no-index --find-links dist tickvault-ob
+      - working-directory: bindings
+        run: pytest tests -q

tickvault_ob-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: release
+
+# Tag driven. `git tag v0.1.0 && git push --tags` builds wheels for every
+# platform and publishes them, so the README's `pip install tickvault` stops
+# being a claim about something that does not exist.
+on:
+  push:
+    tags: ['v*']
+  # Buildable on demand too, so the wheels can be checked without claiming a
+  # version on PyPI.
+  workflow_dispatch:
+
+jobs:
+  wheels:
+    name: wheel (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          # macos-latest runners are Apple silicon, so an Intel Mac would
+          # otherwise fall back to the sdist and compile Rust at install time.
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # One wheel per platform covers every Python from 3.9 up, because the
+      # extension is built against the stable ABI. Without that it would be a
+      # wheel per platform per interpreter version.
+      - name: build
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          target: ${{ matrix.target }}
+          args: --release --out dist --manifest-path bindings/Cargo.toml
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist --manifest-path bindings/Cargo.toml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  # Checks the wheel actually installs and works before anything is published.
+  # A release that ships a broken wheel is worse than no release.
+  verify:
+    needs: [wheels]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels-x86_64-unknown-linux-gnu
+          path: dist
+      # The Python tests replay committed tapes through this binary, so they
+      # need it built and never need a live venue.
+      - run: cargo build --release --bin tickvault
+      - run: pip install pytest pyarrow polars pandas matplotlib
+      - run: pip install --no-index --find-links dist tickvault-ob
+      - working-directory: bindings
+        run: pytest tests -q
+
+  publish:
+    needs: [wheels, sdist, verify]
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: pypi
+    # Trusted publishing: PyPI verifies this workflow rather than a long-lived
+    # token living in the repo's secrets.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

tickvault_ob-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/target
+
+# Python build artefacts from the bindings.
+__pycache__/
+*.so
+.pytest_cache/
+
+# wasm build output
+viewer/pkg/
+viewer/target/

tickvault_ob-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to tickvault
+
+Thanks for looking. tickvault records order books, and its whole claim is that
+the resulting dataset is honest about its own holes. So the bar for anything
+touching what the archive says about itself is deliberately high, and the bar
+for everything else is normal.
+
+## The contract you must not break
+
+**Nothing may claim to be clean unless it was checked.** That is the sentence
+the repo exists to defend, and most of the review of a change goes into whether
+it quietly weakens one of these:
+
+- **A detected gap stops the book.** Never stitch deltas across a hole. A
+  stitched book looks continuous and is wrong, which is the exact failure that
+  makes free order book data untrustworthy.
+- **Unverifiable is not clean.** A message that could not be checked is counted
+  apart from one that was checked and passed. Bitstamp's aggregated feed reports
+  0% verified, and it is never rounded up to look like the others.
+- **Null is not zero.** Where the data cannot answer, it returns nothing. A
+  one-sided book has no mid. An aggregated feed does not know what traded.
+  Writing a zero there is a claim, and a false one.
+- **Our faults are labelled as ours.** Rows lost because the writer fell behind
+  are counted separately from messages the venue never sent. Same for retention:
+  data we chose to stop keeping is a different manifest entry from data we lost.
+- **Never blame the venue for our own defect.** If our decimal rendering lost
+  digits, or the book was shallower than the checksum covers, that message is
+  unverifiable, not a gap.
+
+If a change of yours makes a gate fail, the change is wrong, not the gate. Three
+of the gates were written after a passing test turned out to be passing for the
+wrong reason, which is why they assert properties rather than outputs.
+
+## Getting oriented
+
+| Path | What lives there |
+|---|---|
+| `src/venue/` | The `Venue` trait, six implementations, and the capability matrix that keeps the ingest loop free of special cases. |
+| `src/session.rs` | The ingest loop. Exactly two branches on venue capabilities; everything else is data. |
+| `src/gap.rs` | Suspect windows and the report they feed. The product. |
+| `src/store/` | Parquet schema, writer, manifest, recovery, retention. |
+| `src/reconstruct/`, `src/query/` | Rebuilding a book at an instant, and reading the archive. |
+| `src/supervise.rs`, `src/status.rs` | Running as a service, and answering for it. |
+| `docs/venues.md` | Per-venue findings, measured rather than read off a doc page. |
+| `docs/schema.md` | Every column, and what null means in it. |
+| `tests/gate_*.rs` | The gates. Each states a property. |
+| `viewer/` | The reconstruction engine compiled to wasm, behind the demo page. |
+| `bindings/` | The Python package. |
+
+## Building and testing
+
+```bash
+cargo test                     # the suite
+cargo test -- --ignored        # real SIGKILLs, plus one live venue reconciliation
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+```
+
+CI runs all of that except the live reconciliation, which measures Bitstamp's two
+feeds against each other and would make the build depend on a venue's afternoon.
+
+The Python and wasm halves have their own commands:
+
+```bash
+cd bindings && maturin develop --release && pytest tests
+scripts/build-viewer.sh && cd viewer && cargo test
+```
+
+## Adding a venue
+
+This is meant to be mechanical rather than archaeological, and the conformance
+suite in `tests/conformance.rs` is what makes it so. Implement `Venue`, declare
+its capabilities honestly, add a captured fixture, and the suite will tell you
+what is inconsistent.
+
+Two things worth knowing before you start:
+
+- **Measure the feed, do not read the docs.** Nearly every interesting line in
+  `docs/venues.md` contradicts what the venue's documentation implies. Capture a
+  tape with `tickvault record --out tape.jsonl` and look at it.
+- **Declare what the venue cannot prove.** A venue with no sequencing gets a
+  `MonotonicTimestamp` scheme and a blind spot entry, not a hopeful guess. The
+  capability matrix is what keeps the honesty rules enforceable in one place.
+
+## Style
+
+Commits are one logical change each, buildable on their own, with a subject in
+the imperative and a body explaining why rather than what. Several of the
+existing messages record a measurement that overturned an assumption; that is
+the useful kind.
+
+No em dashes anywhere, in code, comments, docs or commit messages.
+
+Comments explain why, not what. If a comment restates the line below it, delete
+one of them.
+
+## Publishing a number
+
+Any figure in the README has to be reproducible by a command in the README.
+`tickvault bench` backs the throughput claim, `tests/gate_*.rs` back the
+correctness ones, and `docs/venues.md` says which machine and which capture each
+measurement came from. A number without a way to check it does not belong here.