crest-sc 0.3.0__tar.gz

crest_sc-0.3.0/.github/workflows/CI.yml

@@ -0,0 +1,218 @@
+# This file is autogenerated by maturin v1.12.4
+# To update, run
+#
+#    maturin generate-ci github
+#
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Rust unit tests
+        run: cargo test --release
+      - name: Build and install
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          pip install maturin
+          maturin develop --release --extras test
+      - name: Python tests (incl. scanpy parity)
+        run: |
+          . .venv/bin/activate
+          pytest -q
+
+  docs:
+    # same build as Read the Docs (.readthedocs.yaml): no Rust, native module mocked
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build the documentation (warnings are errors)
+        run: |
+          pip install -r docs/requirements.txt
+          sphinx-build -W --keep-going -b html docs docs/_build/html
+
+  linux:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: x86
+          - runner: ubuntu-22.04
+            target: aarch64
+          - runner: ubuntu-22.04
+            target: armv7
+          # s390x and ppc64le removed: psm crate assembly errors on these targets,
+          # and no single-cell analysis workloads run on mainframes
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: x86
+          - runner: ubuntu-22.04
+            target: aarch64
+          - runner: ubuntu-22.04
+            target: armv7
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: musllinux_1_2
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-musllinux-${{ matrix.platform.target }}
+          path: dist
+
+  windows:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: windows-latest
+            target: x64
+            python_arch: x64
+          - runner: windows-latest
+            target: x86
+            python_arch: x86
+          - runner: windows-11-arm
+            target: aarch64
+            python_arch: arm64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.13
+          architecture: ${{ matrix.platform.python_arch }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-windows-${{ matrix.platform.target }}
+          path: dist
+
+  macos:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: macos-15-intel
+            target: x86_64
+          - runner: macos-latest
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-macos-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v5
+        with:
+          name: wheels-sdist
+          path: dist
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    needs: [test, linux, musllinux, windows, macos, sdist]
+    permissions:
+      # Use to sign the release artifacts
+      id-token: write
+      # Used to upload release artifacts
+      contents: write
+      # Used to generate artifact attestation
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v6
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-path: 'wheels-*/*'
+      - name: Install uv
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        uses: astral-sh/setup-uv@v7
+      - name: Publish to PyPI
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        run: uv publish 'wheels-*/*'
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}

crest_sc-0.3.0/.gitignore

@@ -0,0 +1,117 @@
+/target
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+.pytest_cache/
+*.py[cod]
+
+# Compiled extensions
+*.so
+*.dylib
+
+# Distribution / packaging
+.Python
+.venv/
+env/
+bin/
+build/
+develop-eggs/
+dist/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+include/
+man/
+venv/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+pip-selfcheck.json
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Rope
+.ropeproject
+
+# Django stuff:
+*.log
+*.pot
+
+.DS_Store
+
+# Sphinx documentation
+docs/_build/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# Pyenv
+.python-version
+
+# ================================
+# BioPolars Project-Specific
+# ================================
+
+# Large datasets and data files
+data/
+!tests/data/
+*.h5
+*.mtx
+*.mtx.gz
+*.tsv
+*.tsv.gz
+*.parquet
+*.h5ad
+
+# Benchmark outputs
+bench/__pycache__/
+bench/*.png
+bench/*.svg
+bench/*.pdf
+
+# Debug and scratch files
+bench/debug_*.py
+
+# Docker build artifacts
+_docker_build/
+
+# Deprecated/removed directories
+bio-polars/
+polars_src/
+polars/
+rust_analysis/
+bench_results/
+research/
+
+# Misc
+.ruff_cache/
+.claude/
+
+# Local benchmark runs
+.venv-bench/
+bench_data/
+bench_results/

crest_sc-0.3.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs build configuration: https://docs.readthedocs.io/en/stable/config-file/v2.html
+#
+# The docs are built with Sphinx from docs/. The package is NOT installed: CREST's
+# compiled Rust extension would need a Rust build on Read the Docs. Instead docs/conf.py
+# puts the repository on sys.path and mocks the native module, so autodoc can read every
+# docstring from the pure-Python layer. See docs/readthedocs.md for the step-by-step setup.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - requirements: docs/requirements.txt

crest_sc-0.3.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+## Unreleased
+
+## 0.3.0 (2026-09-29)
+
+### Changed
+- The acronym now reads **Chunked** Rust Engine for Single-cell Transcriptomics (was
+  "Columnar"): the engine streams chunks of cells through fused Rust kernels; Polars is only
+  the table and Parquet layer. Package and import names are unchanged (`crest-sc`, `crest`).
+
+### New
+- **Pseudobulk DESeq2 in Rust.** `crest.tl.DESeq2` ports DESeq2 1.42 `DESeq()` +
+  `results()`: median-of-ratios size factors, Cox-Reid gene-wise dispersions,
+  parametric trend, MAP shrinkage, NB-GLM Wald tests, Cook's filtering and
+  outlier replacement, and independent filtering. It matches R to ~1e-9 on
+  simulated designs, is ~18× faster than R and ~28× faster than pydeseq2 on
+  Kang 2018 pseudobulk. See `docs/deseq2.md`.
+- `crest.tl.pseudobulk` (streamed raw-count sums per sample × group) and
+  `crest.tl.pseudobulk_de` (per-cell-type DESeq2 in one call).
+- `bench/deseq2/`: R comparison on simulated designs and on Kang et al. 2018.
+- **Harmony** batch integration in Rust (`crest.tl.harmony`), the harmony2 algorithm of
+  R harmony >= 1.2 / harmonypy 2.x; 3.5x faster than harmonypy at equal integration quality.
+- **Scrublet** doublet detection (`crest.pp.scrublet`), sparse and streamed; 12x faster
+  than `scanpy.pp.scrublet` with the same AUROC on demuxlet-labelled doublets.
+- `highly_variable_genes(flavor="seurat_v3" | "seurat_v3_paper", batch_key=...)`, with a
+  port of netlib loess (`crest._loess`); identical to scanpy.
+- `crest.tl.leiden_sweep`: many resolutions/seeds on one graph in parallel, with
+  ARI-based stability; `crest.tl.adjusted_rand_index`.
+- `crest.tl.ingest`: project a query onto a reference PCA, transfer labels and UMAP.
+  `uns['pca']['projection']` now stores what the projection needs.
+- DESeq2 likelihood-ratio test: `DESeq2(test="LRT", reduced="~ ...")`, matching R.
+- Native `knn_query` (reference -> query kNN, exact or IVF).
+- `scripts/crest_paper_bench.sh` + `bench/paper/`: one-command publication benchmark
+  (datasets, per-core CPU/clock/memory monitoring, statistics, figures).
+- `scripts/crest_git_housekeeping.sh`: repository housekeeping (dev branch, stale branches).
+- **Documentation site** (Sphinx + MyST, Read the Docs): installation, quickstart, concepts,
+  full API reference, benchmarks, developer guide; `.readthedocs.yaml`; CI `docs` job.
+- `work.md`: the development history; `CLAUDE.md` / `HANDOVER.md` rewritten for new sessions.
+
+### Removed
+- The `.bio` Polars expression namespace and its Rust plugin code (duplicated the
+  validated API, was not validated itself, and tied the wheel to Polars' plugin ABI).
+  The `polars`/`pyo3-polars` Rust dependencies go with it.
+- SLAF support (`BioFrame.from_slaf`, `crest/slaf_io.py`, the `slaf` extra).
+- Legacy scripts: `bench/*.py` from the biopolars era, `notebooks/`, the Docker setup,
+  `docs/dev/`, and `bench/whitepaper/`'s scripts (superseded by `bench/paper/`; its
+  0.2.0 results stay).
+
+### Fixed
+- `BioFrame.to_anndata()` / `from_anndata()` no longer need pyarrow.
+- `crest_paper_bench.sh` stops with a clear message when the work directory is not writable,
+  and records the work directory's device and filesystem.
+
+## 0.2.0
+
+A correctness and performance release. Every step of the standard scanpy
+workflow has been re-implemented and validated against scanpy.
+
+### Fixed (results from 0.1.0 should not be used)
+- **kNN / Leiden / UMAP**: the HNSW index shuffled points and its id map was
+  ignored, so neighbour indices pointed at random cells (recall@15 = 0.005).
+- **Leiden** was a single-level local-move heuristic (thousands of singleton
+  clusters) with a modularity gain off by a factor of 2; now Traag et al. 2019
+  Leiden (local moving, refinement, aggregation). Modularity equals or exceeds
+  `leidenalg`.
+- **normalize_cpm / qc / filter_cells / scale / score_genes** Polars plugins
+  were declared elementwise, so Polars computed per-cell sums on partial
+  batches; `normalize_cpm` ignored `target_sum`.
+- **rank_genes_groups** divided by non-zero counts instead of group sizes.
+- **Randomized PCA** lost trailing components (no re-orthonormalisation).
+- **HVG** "seurat" flavour was raw variance/mean (883/2000 overlap with scanpy).
+- **Wilcoxon** p-values underflowed to 0.
+
+### New
+- `crest.pp` / `crest.tl` scanpy-style API on `BioFrame`, with raw counts held
+  in compact CSR, a Polars triplet frame, or a Parquet dataset streamed from disk.
+  Filters and `normalize_total` / `log1p` / `scale` are applied lazily inside
+  fused native kernels: no normalised, scaled or dense copy is ever made.
+- Exact PCA from a streamed Gram matrix with `sc.pp.scale(max_value)` applied
+  implicitly (0.000 deg from scanpy's ARPACK result).
+- kNN: tiled GEMM brute force (small n) and IVF + NN-descent (large n).
+- UMAP: umap-learn semantics, parallelised by domain decomposition.
+- Sparse Wilcoxon ranking only non-zeros; all-groups Welch t-test.
+- `score_genes` reproducing scanpy's control-gene sampling.
+- Readers: `read_10x_h5` (optionally streamed to Parquet), `read_h5ad`,
+  `read_10x_mtx`; `write_parquet` / `read_parquet`; AnnData conversion.
+- `bench/whitepaper/` benchmark harness.
+
+### Changed
+- `bio.deseq2` renamed `bio.nb_glm` (it fits an NB GLM with given dispersions;
+  not the full DESeq2 procedure) and returns null when IRLS does not converge.
+- In `bio.leiden` / `bio.umap`, `n_neighbors` now counts the cell itself (scanpy convention).
+- `crest.tl.sparse_masked_pca` / `incremental_pca` removed (superseded by `crest.tl.pca`).
+- Distribution renamed `crest-sc` (the import name stays `crest`); Python >= 3.10.

crest_sc-0.3.0/CLAUDE.md

@@ -0,0 +1,182 @@
+# CREST: operating manual for Claude Code
+
+Read this file completely at the start of every session. Then read `HANDOVER.md` (current
+status, open work, decisions). If you wonder *why* something is the way it is, search
+`work.md`: it is the full history of the sessions that built the project, with every request
+and every reply. Use `grep -n "<keyword>" work.md` rather than reading it top to bottom. The
+"Context summary" sections are dense recaps. `scripts/export_chat.py` regenerates it from a
+Claude Code transcript (`~/.claude/projects/<project>/<session>.jsonl`); append new sessions
+rather than replacing the history.
+
+## 1. What this project is
+
+CREST is a Python package (`pip install crest-sc`, `import crest`) with a Rust core
+(PyO3 + maturin). It runs the scanpy single-cell RNA-seq workflow and gives **the same
+results as scanpy** (and as R DESeq2 / harmonypy for those modules), while being several
+times faster and using far less memory. The owner is a computational biologist who works
+mostly in R (Seurat); the goal is a publishable package with an arXiv/bioRxiv-grade
+performance paper.
+
+The steps covered:
+
+* **Workflow:** QC → filter → `normalize_total` → `log1p` → HVG → `scale` → PCA →
+  neighbours → Leiden → UMAP → marker genes (t-test / Wilcoxon) → `score_genes`.
+* **After clustering:** pseudobulk DESeq2 (Wald + LRT), Harmony, Scrublet, `seurat_v3`
+  HVGs, Leiden resolution sweep, ingest (label transfer).
+
+History in one paragraph: the project began (Feb 2026) as "biopolars", Polars expression
+plugins for single-cell data. That design was wrong (per-cell sums over partial batches,
+broken kNN id mapping, a fake Leiden). In Sept 2026 it was rebuilt around a `BioFrame` with
+lazy transforms and fused Rust kernels, validated step by step against scanpy, and released
+as 0.2.0. Downstream modules followed in 0.3.0. The Polars plugin layer was deleted; Polars
+remains only as the metadata / table / Parquet layer. Hence the acronym now reads **Chunked**
+Rust Engine for Single-cell Transcriptomics (it was "Columnar" until 0.3.0).
+
+## 2. The mental model (read before touching code)
+
+**Raw counts are stored once and never modified.** Everything else is recorded, and applied
+on the fly inside Rust kernels as the data is streamed chunk by chunk:
+
+```text
+BioFrame
+  store  : CSRStore (in-memory CSR) | FrameStore (Polars triplets) | ParquetStore (on disk, out-of-core)
+  obs    : polars.DataFrame, kept cells; obs["cell_id"] indexes the store
+  var    : polars.DataFrame, kept genes; var["gene_id"] indexes the store
+  ops    : [("normalize_total", 1e4), ("log1p",)]   <- recorded transforms
+  uns    : {"scale": {...}, "hvg": {...}, "pca": {...}, "neighbors": {...}, ...}
+  obsm / varm : embeddings (X_pca, X_umap, X_pca_harmony) / PCs
+
+for ctx in bf.iter_ctx():          # one raw chunk + cell_map/gene_map (-1 = filtered) + transform
+    _native.<kernel>(*ctx, outputs...)   # Rust: filter + normalise + log1p (+ scale) per cell, accumulate
+```
+
+The consequences are rules, not suggestions:
+
+* **Filters return a new BioFrame that shares the store:** `bf = crest.pp.filter_cells(bf, ...)`.
+  All other functions mutate `bf` in place and also return it.
+* **Nothing is ever cells × genes and dense.** Results are per-gene, per-cell, per-group, or
+  genes × genes (the PCA Gram matrix, with HVGs only; capped at 20k genes).
+* **PCA with `scale` is exact without densifying.** Zeros map to a per-gene constant
+  `b_j`, so `Z = 1·bᵀ + S` with `S` sparse. Centring removes `1·bᵀ`, so the Gram matrix
+  is accumulated from sparse rows (`docs/memory_model.md`).
+* **What each step reads:**
+  - raw counts: QC, filters, `seurat_v3`, Scrublet, pseudobulk / DESeq2;
+  - log-normalised values: `seurat` / `cell_ranger` HVG, DE, `score_genes`;
+  - scaled values: PCA;
+  - `obsm` embeddings: neighbours, Leiden, UMAP, Harmony, ingest.
+* `ParquetStore` = out-of-core: one Parquet part in RAM at a time, ~1 GB peak at any size,
+  ~2× slower.
+
+Full user-level explanation: `docs/concepts.md`. The chunk protocol tuple and the table of
+all native functions: `docs/development.md`.
+
+## 3. Build, test, docs
+
+```bash
+# one-time: Rust stable >= 1.80, Python >= 3.10; the owner uses uv
+uv venv .venv --python 3.11 && source .venv/bin/activate && uv pip install maturin
+maturin develop --release -E test      # rebuild after ANY change under src/ (always --release)
+cargo test --release                   # 26 Rust unit tests
+pytest -q                              # 27 Python tests: scanpy / R-DESeq2 / harmonypy / skmisc / skimage parity
+pip install -r docs/requirements.txt && sphinx-build -W -b html docs docs/_build/html   # docs
+```
+
+* A Python-only change needs no rebuild.
+* If `maturin` says "Both VIRTUAL_ENV and CONDA_PREFIX are set", run `conda deactivate`
+  (the owner's shell starts in conda `base`).
+* The R-DESeq2 reference outputs are stored in `tests/data/`, so the tests don't need R.
+  They are regenerated with `Rscript tests/data/make_lrt_fixtures.R` and the scripts in
+  `bench/deseq2/`.
+
+## 4. Where things are
+
+| need | file |
+|---|---|
+| BioFrame, stores, `iter_ctx`, AnnData / Parquet I/O | `crest/core.py` |
+| readers | `crest/io.py` |
+| QC, filters, lazy transforms, HVG (3 flavours), neighbours | `crest/pp.py` |
+| PCA, Leiden, `leiden_sweep`, UMAP, DE, `score_genes` | `crest/tl.py` |
+| pseudobulk + DESeq2 (formulas, Wald / LRT, results, independent filtering) | `crest/deseq2.py` + `src/deseq/` |
+| Harmony / Scrublet / ingest / loess | `crest/harmony.py` + `src/harmony.rs`, `crest/doublets.py`, `crest/ingest.py`, `crest/_loess.py` |
+| streaming kernels | `src/kernels.rs` (`ChunkView`) |
+| kNN (exact GEMM ≤ 20k cells; IVF + NN-descent above; `knn_query`) | `src/knn.rs` |
+| Leiden, UMAP | `src/leiden.rs`, `src/umap/` |
+| Python ↔ Rust bindings (validation, GIL release) | `src/py.rs` |
+| tests | `tests/test_crest.py`, `tests/data/` |
+| paper benchmark | `scripts/crest_paper_bench.sh` → `bench/paper/{datasets,run_one,run_all,monitor,accuracy,summarize}.py` |
+| module benchmarks | `bench/{deseq2,harmony,doublets,ingest}/` (results in `results/`) |
+| user docs (Read the Docs) | `docs/*.md`, `docs/conf.py`, `.readthedocs.yaml`, `docs/readthedocs.md` |
+| design / validation notes | `docs/concepts.md`, `docs/memory_model.md`, `docs/deseq2.md`, `docs/downstream.md`, `docs/benchmarks.md` |
+| history | `work.md`, `CHANGELOG.md` |
+
+## 5. Rules
+
+1. **Parity first.** Results must match the reference tool: scanpy 1.11 for the workflow,
+   R DESeq2 1.42 for `DESeq2`, harmonypy 2.x for Harmony, `skmisc` for loess and `skimage`
+   for `threshold_minimum`.
+   - A new method gets a parity test before it is optimised.
+   - If a change moves a parity test, find out why. **Never loosen a tolerance** to make
+     it pass.
+   - Where exact parity is impossible (random streams: Scrublet pairs, Harmony init), compare
+     outcomes statistically and document it.
+2. **Bounded memory.** Stream through `iter_ctx()`. Never build dense cells × genes, and never
+   call `to_scipy()` inside library code.
+3. **Speed lives in Rust.** Loops over non-zeros or cells go in `src/`. Release the GIL
+   (`py.allow_threads`), parallelise with rayon, and validate inputs in `py.rs` so errors
+   raise instead of panicking.
+4. **scanpy-compatible names and defaults.** Deviations are documented in the docstring and
+   in `docs/`.
+5. **Honest benchmarks.** These rules come from the owner:
+   - The headline comparison is the `core` pipeline; optional modules go in a separate table.
+   - Speed-ups are quoted at each tool's *best* thread count and at matched threads; the
+     conservative one is the headline.
+   - Report the steps where CREST is not faster, its thread-scaling limits, and every failed
+     run.
+   - No cherry-picking.
+6. **Docs move with code.**
+   - A new public function gets a docstring and an entry in `docs/api.md`.
+   - A behaviour change updates `docs/` and `CHANGELOG.md` (Unreleased).
+   - `sphinx-build -W` must stay clean (CI enforces it).
+
+## 6. Git and GitHub
+
+* Branches: `main` (releases only; **never push to it**), `dev` (integration; PRs land
+  here), and feature branches. A release merges `dev` → `main` and tags `vX.Y.Z`.
+* The version lives in `Cargo.toml`. `pyproject.toml` and `docs/conf.py` read it from there.
+  `crest/__init__.py` has a copy: bump both.
+* Commit prefixes: `feat:`, `fix:`, `bench:`, `docs:`, `chore:`. Before pushing, run
+  `cargo test --release && pytest -q`.
+* CI (`.github/workflows/CI.yml`) runs on PRs and pushes to main:
+  - the `test` job (cargo + pytest);
+  - the `docs` job (Sphinx, warnings are errors);
+  - wheel builds for all platforms, published to PyPI on a tag.
+* Deleting or tagging shared branches is done by the owner with
+  `scripts/crest_git_housekeeping.sh`; don't try to work around permission refusals.
+* Old branches are archived as tags `archive/feat-leiden-hnsw-faer` and
+  `archive/fix-production-readiness`.
+
+## 7. The owner's machine (where benchmarks run)
+
+* **Machine:** `rinamochana`, AMD Threadripper PRO 3975WX (32 cores / 64 threads),
+  128 GB DDR4-2667 ECC, Ubuntu 26.04.
+* **Disks:**
+  - `/home` is small (OS only): **never write data or caches there**;
+  - `/mnt/scratch` is a 1.8 TB NVMe (ext4, `/dev/nvme0n1`); run benchmarks here;
+  - `/storage` is a large ZFS pool on HDDs.
+* **Benchmark:**
+  - Run from `/mnt/scratch` with
+    `bash crest_paper_bench.sh --tier quick|standard|full`.
+  - Everything, including uv / cargo / numba caches, goes under `./crest-bench`.
+  - Results go to `crest-bench/results/<host>-<date>/`, and a `.tar.gz` is written to send
+    back.
+* The owner uses `uv` for Python environments.
+
+## 8. Working style the owner expects
+
+* **Think thoroughly and weigh trade-offs.** Quality comes first, and every claim should be
+  verified: run the code, rebuild, re-test.
+* Scripts they run locally must work from the current directory, log everything, and fail
+  early with a clear message.
+* When you finish a session that changed anything, update `HANDOVER.md` (Status and Next
+  steps), and add a `CHANGELOG.md` entry for user-visible changes.
+* Never put model identifiers in commits, code or docs.