sonagram 0.1.0__tar.gz

sonagram-0.1.0/KGLite/Cargo.toml

@@ -0,0 +1,37 @@
+[workspace]
+members = [
+    "crates/kglite",
+    "crates/kglite-py",
+    "crates/kglite-mcp-server",
+    "crates/kglite-bolt-server",
+    "crates/kglite-c",
+    "crates/kglite-cli",
+]
+resolver = "2"
+
+# Single source of truth for the crate version. Every member crate sets
+# `version.workspace = true`, so a release bumps this one line instead of
+# six. All published crates ship in lockstep at the same version.
+[workspace.package]
+version = "0.14.0"
+
+# Phase G.4 — workspace root is now virtual (no `[package]`).
+# Polars-style layout: each crate has its own home under
+# `crates/`. The `kglite` Python wheel is built by maturin from
+# `crates/kglite-py/` (see `pyproject.toml`'s `[tool.maturin]
+# manifest-path`).
+
+[profile.release]
+lto = "thin"
+codegen-units = 1
+strip = "symbols"
+
+# Same codegen as release but keeps line tables + symbols so samply
+# / `cargo flamegraph` / Instruments can attribute hot frames. Use
+# with `maturin develop --profile profiling` for Python-driven
+# profiling, or `cargo build --profile profiling --bin bz2_bench`
+# for native binaries.
+[profile.profiling]
+inherits = "release"
+debug = "line-tables-only"
+strip = "none"

sonagram-0.1.0/KGLite/crates/kglite/Cargo.toml

@@ -0,0 +1,144 @@
+[package]
+# Pure-Rust core, polars-style. The Python wheel is built by
+# maturin from `crates/kglite-py/` (which depends on this crate).
+# Rust embedders depend on this crate directly:
+#   kglite = { path = "..." }  # pre-publish
+#   kglite = "0.10"            # post-crates.io-publish
+name = "kglite"
+version.workspace = true
+edition = "2021"
+authors = ["Kristian dF Kollsgård <kkollsg@gmail.com>"]
+license = "MIT"
+description = "Pure-Rust embedded Cypher knowledge graph engine with in-memory, mmap, and disk storage, and agent-facing schema introspection"
+readme = "README.md"
+repository = "https://github.com/kkollsga/kglite"
+homepage = "https://github.com/kkollsga/kglite"
+documentation = "https://docs.rs/kglite"
+keywords = ["cypher", "knowledge-graph", "graph-database", "embedded-database", "rust"]
+categories = ["database", "data-structures"]
+
+[lib]
+# `[lib] name = "kglite"` matches the `[package] name` so
+# dependent crates do the natural `use kglite::api::*`. The
+# kglite-py wrapper uses `[lib] name = "kglite_py"` to avoid
+# producing the same rlib filename as this crate (they're different
+# artifact types — rlib here, cdylib over there — but cargo still
+# requires distinct filenames).
+name = "kglite"
+doctest = false
+
+# Standalone perf microbench for the bz2 decoder. Requires the
+# `parallel-bz2` feature because it calls the optional decoder directly. Run
+# with `cargo run -p kglite --bin bz2_bench --release --features
+# parallel-bz2 -- <path>`.
+[[bin]]
+name = "bz2_bench"
+path = "src/bin/bz2_bench.rs"
+required-features = ["parallel-bz2"]
+
+[features]
+default = []
+# Rust-native embedder backend behind the `fastembed` Cargo feature.
+# Downloads ONNX model weights on first use (cached at
+# `~/.cache/fastembed/`). Off by default — the Python wheel relies
+# on user-provided Python embedder classes via `PyEmbedderAdapter`,
+# and we don't want to pull a 100-200 MB ONNX runtime into every
+# wheel build. The `kglite-mcp-server` binary enables this feature
+# so the Rust-only deployment path supports `text_score()` semantic
+# search without a Python embedder.
+fastembed = ["dep:fastembed"]
+# Block-level parallel decoder for single-stream `.bz2` files (the
+# Wikidata `latest-truthy.nt.bz2` shape). With this feature off the loader
+# still parallelises multi-stream pbzip2-produced files; only the
+# single-stream block-level path falls back to sequential
+# `bzip2::read::MultiBzDecoder`. Wikidata-scale ingest is the only
+# workload that actually benefits — opt in if you're decompressing
+# > 50 GB single-stream files. The `bz2_bench` binary requires this
+# feature.
+parallel-bz2 = ["dep:parallel-bz2-redux"]
+
+# OKF (Open Knowledge Format) bundle loader — parses a directory of
+# markdown files with YAML frontmatter, cross-linked by markdown links,
+# into a knowledge graph (read-only ingestion, like `code_tree` but for
+# OKF / memory / skills / Obsidian bundles). Off by default so the bare
+# crate pulls no YAML parser; the Python wheel enables it. `regex` (link
+# extraction) and `walkdir` (tree walk) are already non-optional deps.
+okf = ["dep:yaml-rust2"]
+# General-purpose RDF loader (Turtle / N-Triples / N-Quads / TriG via
+# the oxttl parser family). Off by default so the bare crate pulls no
+# RDF parser; `oxttl` + `oxrdf` are only in the dep tree when `rdf` is
+# enabled. Phase 1 covers the in-memory (Default) backend only.
+rdf = ["dep:oxttl", "dep:oxrdf"]
+
+# `--cfg loom` is set manually when running the loom interleaving model
+# (tests/loom_session.rs); register it so normal builds don't warn (and
+# `make lint`'s `-D warnings` doesn't fail) on the `#[cfg(loom)]` gate.
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(loom)'] }
+
+[dependencies]
+petgraph = { version = "0.8.3", features = ["serde-1"] }
+fastembed = { version = "5", optional = true, default-features = false, features = ["ort-download-binaries-native-tls", "hf-hub-native-tls"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.149"
+bincode = "1.3"
+postcard = { version = "1.1.3", default-features = false, features = ["use-std"] }
+chrono = { version = "0.4.43", features = ["serde"] }
+geo = "0.33"
+rstar = "0.12"
+wkt = "0.14"
+regex = "1"
+rayon = "1.10"
+flate2 = "1"
+zstd = "0.13"
+memmap2 = "0.9"
+libc = "0.2"
+bzip2 = "0.6"
+# Published, bounded-memory block-parallel decoder for both ordinary
+# single-stream and concatenated `.bz2` data. Optional so graph-only users do
+# not pull its scanner/pipeline dependencies.
+parallel-bz2-redux = { version = "1.1.1", optional = true }
+walkdir = "2.5.0"
+tempfile = "3"
+fs2 = "0.4"
+sha2 = "0.10"
+memchr = "2"
+rustc-hash = "2"
+csv = "1.3"
+geojson = "0.24"
+indexmap = { version = "2", features = ["serde"] }
+
+# OKF loader YAML frontmatter parser — gated behind the `okf` feature.
+# `yaml-rust2` is a pure-Rust, actively-maintained YAML 1.2 parser (no
+# `unsafe`/libyaml, no unmaintained advisory); only pulled when `okf` is
+# enabled (the wheel enables it; bare builds don't).
+yaml-rust2 = { version = "0.10", optional = true }
+
+# RDF loader deps — gated behind the `rdf` feature. `oxttl` is the
+# Oxigraph family's standalone Turtle/N-Triples/N-Quads/TriG parser;
+# it re-exports `oxrdf` term types (Triple / Quad / Term / Literal).
+# oxttl 0.2.3 resolves oxrdf 0.3.x — pin oxrdf to the version oxttl
+# pulls so they agree on the term types.
+oxttl = { version = "0.2", optional = true }
+oxrdf = { version = "0.3", optional = true }
+
+[target.'cfg(windows)'.dependencies]
+same-file = "1"
+
+[dev-dependencies]
+tempfile = "3"
+
+# loom — exhaustive interleaving model-checker for the Session commit/snapshot
+# lock pattern. Only pulled in under `--cfg loom` (the loom test is
+# `#![cfg(loom)]`), so normal `cargo test` / `cargo build` never compile it.
+# Run: RUSTFLAGS="--cfg loom" cargo test -p kglite --test loom_session
+[target.'cfg(loom)'.dev-dependencies]
+loom = "0.7"
+
+# docs.rs builds with these features so the published API page covers
+# the optional loaders + fastembed adapter, which would otherwise be
+# missing (defaults are intentionally empty). `rustdoc-args` enables doc-cfg
+# annotations so feature-gated APIs are visually marked on the page.
+[package.metadata.docs.rs]
+features = ["fastembed", "okf", "rdf", "parallel-bz2"]
+rustdoc-args = ["--cfg", "docsrs"]

sonagram-0.1.0/KGLite/crates/kglite/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kristian de Figueiredo Kollsgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sonagram-0.1.0/KGLite/crates/kglite/README.md

@@ -0,0 +1,179 @@
+# kglite
+
+[![crates.io](https://img.shields.io/crates/v/kglite)](https://crates.io/crates/kglite)
+[![docs.rs](https://img.shields.io/docsrs/kglite)](https://docs.rs/kglite)
+[![License: MIT](https://img.shields.io/crates/l/kglite)](https://github.com/kkollsga/kglite/blob/main/LICENSE)
+
+**Pure-Rust knowledge graph engine** — Cypher pipeline,
+snapshot/working CoW transactions, columnar / mmap / disk storage
+backends, optional RDF / OKF format loaders. Pre-packaged domain
+dataset loaders (SEC EDGAR, Sodir, Wikidata) live in the separate
+kglite-datasets project. Zero PyO3 in the dependency tree; embed
+directly from any Rust binary.
+
+> Looking for the Python wheel? `pip install kglite` — the wheel
+> is a separate PyO3 wrapper (`kglite-py`) built on top of this
+> crate. See the [workspace README] for the Python story; this
+> page is the crates.io-side documentation.
+
+[workspace README]: https://github.com/kkollsga/kglite#kglite--knowledge-graph-for-python-built-for-llm-agents
+
+## Quick start
+
+```toml
+[dependencies]
+kglite = "0.10"
+```
+
+```rust
+use kglite::api::{load_file, session, Value};
+use std::collections::HashMap;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Load any .kgl file — same format the Python wheel writes.
+    let graph = load_file("graph.kgl")?;
+
+    let params = HashMap::new();
+    let opts = session::ExecuteOptions {
+        params: &params,
+        deadline: None,
+        max_rows: None,
+        lazy_eligible: false,
+        disabled_passes: None,
+        embedder: None,
+    };
+    let outcome = session::execute_read(
+        &graph,
+        "MATCH (n:Person) RETURN n.name LIMIT 10",
+        &opts,
+    )?;
+
+    for row in &outcome.result.rows {
+        if let Some(Value::String(name)) = row.first() {
+            println!("{}", name);
+        }
+    }
+    Ok(())
+}
+```
+
+Verify no Python dep leaked in:
+
+```bash
+cargo tree -p your-crate | grep pyo3   # → (empty)
+```
+
+## What's in it
+
+| Surface | Purpose |
+|---|---|
+| `kglite::api::DirGraph` | The in-memory graph. Owned by your binding's graph handle. |
+| `kglite::api::Value` | The Cypher value type — scalars, `List`, `Map`, `Node`, `Relationship`, `Path`. |
+| `kglite::api::KgError`, `KgErrorCode` | Typed error enum (16 variants) for binding-friendly error mapping. |
+| `kglite::api::session::Session` / `Transaction` | Snapshot/working CoW transaction model with optimistic concurrency control. |
+| `kglite::api::session::execute_read` / `execute_mut` | The canonical Cypher pipeline — parse, validate, optimise, execute. |
+| `kglite::api::cypher::*` | Lower-level pipeline primitives for building custom orchestrations. |
+| `kglite::api::load_file` / `save_graph` | `.kgl` portable graph snapshots — copy, share, reload across bindings. |
+| `kglite::api::compute_description` / `compute_schema` | Schema introspection: XML for LLM system prompts, structured types for programmatic use. |
+
+## Transactions
+
+The `Session` / `Transaction` types wrap the snapshot/working CoW
++ optimistic concurrency control. Pattern: begin, mutate, commit.
+On a concurrent-writer conflict, the second commit returns
+`CommitOutcome::ConflictDetected` and the binding surfaces it to
+its caller as a retryable error.
+
+```rust
+use kglite::api::session::{CommitOutcome, ExecuteOptions, Session};
+use kglite::api::DirGraph;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+let session = Arc::new(Session::new(DirGraph::new()));
+let params: HashMap<String, kglite::api::Value> = HashMap::new();
+let opts = ExecuteOptions {
+    params: &params, deadline: None, max_rows: None,
+    lazy_eligible: false, disabled_passes: None, embedder: None,
+};
+
+let mut tx = session.begin();
+kglite::api::session::execute_mut(
+    tx.working_mut()?,
+    "CREATE (:Person {id: 1, name: 'Alice'})",
+    &opts,
+)?;
+
+match session.commit(tx, /* check_occ = */ true) {
+    CommitOutcome::Committed { new_version } => {
+        println!("committed at version {}", new_version);
+    }
+    CommitOutcome::ConflictDetected { current_version, base_version } => {
+        eprintln!("conflict: base={} current={}", base_version, current_version);
+    }
+    CommitOutcome::NoWritesNoOp => {}
+}
+```
+
+## Examples
+
+Three runnable examples ship with the crate:
+
+```bash
+cargo run --example embedded_basic -- graph.kgl
+cargo run --example embedded_session
+cargo run --example embedded_blueprint
+```
+
+- `embedded_basic` — load + query. Smallest embedder.
+- `embedded_session` — two concurrent transactions; OCC catches
+  the conflict.
+- `embedded_blueprint` — parse the kglite source tree itself,
+  query the resulting graph.
+
+## Feature flags
+
+Polars-io style: opt in only to what you use.
+
+| Feature | What it pulls in |
+|---|---|
+| `default` | The engine. No optional loaders. (Domain dataset loaders live in the kglite-datasets project; code-graph building in the codingest crate.) |
+| `rdf` | RDF loader (Turtle / N-Triples / N-Quads / TriG via oxttl). |
+| `okf` | Open Knowledge Format bundle loader (markdown + YAML frontmatter). |
+| `fastembed` | Rust-native ONNX embedder for `text_score()` semantic search. |
+
+```toml
+[dependencies]
+kglite = { version = "0.13", features = ["rdf", "okf"] }
+```
+
+## Documentation
+
+- **[Rust quickstart](https://kglite.readthedocs.io/en/latest/rust/index.html)**
+  — load + query + transaction examples.
+- **[Embedding guide](https://kglite.readthedocs.io/en/latest/rust/embedding.html)**
+  — workspace layout, the `kglite::api::*` surface tour, sketches
+  for cgo / napi / JNI wrappers if you're building a binding in
+  another language.
+- **[Session abstraction](https://kglite.readthedocs.io/en/latest/rust/session.html)**
+  — binding-implementer reference for the canonical Cypher pipeline
+  + CoW transaction model.
+- **[API manifest](https://kglite.readthedocs.io/en/latest/rust/api-reference.html)**
+  — curated inventory of `kglite::api::*` items + semver rules.
+- **Per-symbol docs at [docs.rs/kglite](https://docs.rs/kglite).**
+
+The full kglite docs site at
+[kglite.readthedocs.io](https://kglite.readthedocs.io) has more
+on the Cypher subset, design rationale, and the protocol-server
+binaries that ship alongside this crate.
+
+## Semver
+
+`kglite::api::*` items get semver guarantees within a minor
+release. Anything outside that surface — `kglite::graph::*`,
+`kglite::datatypes::*`, raw module paths — is internal and may
+move freely between minor releases.
+
+## License
+
+MIT — see [LICENSE](https://github.com/kkollsga/kglite/blob/main/LICENSE).

sonagram-0.1.0/KGLite/crates/kglite/examples/embedded_basic.rs

@@ -0,0 +1,65 @@
+//! Smallest possible kglite embedder: load a `.kgl` file from disk
+//! and run a Cypher query against it. Zero PyO3 in the dep tree.
+//!
+//! Run with:
+//!
+//! ```bash
+//! # From the workspace root, against any kgl in your environment:
+//! cargo run -p kglite --example embedded_basic -- path/to/graph.kgl
+//!
+//! # Verify the dep tree is pyo3-free:
+//! cargo tree -p kglite --example embedded_basic | grep pyo3
+//! # → (empty)
+//! ```
+//!
+//! The single .kgl file produced by Python (`kg.save("graph.kgl")`)
+//! is the same file this Rust binary reads. The on-disk format is
+//! the engine's portable contract; it travels across any kglite
+//! binding.
+
+use kglite::api::io::load_file;
+use kglite::api::{session, Value};
+use std::collections::HashMap;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let path = std::env::args()
+        .nth(1)
+        .ok_or("Usage: embedded_basic <path/to/graph.kgl>")?;
+
+    // ── 1. Load the graph from disk ───────────────────────────────
+    //
+    // `load_file` returns an `Arc<DirGraph>` — the engine type. No
+    // pyo3 wrapping (`KnowledgeGraph` is a pyo3 concern; it lives
+    // in the kglite-py wrapper crate, not here).
+    let graph = load_file(&path)?;
+    println!(
+        "Loaded {}: {} bytes resident",
+        path,
+        std::mem::size_of_val(&*graph)
+    );
+
+    // ── 2. Count nodes via Cypher ─────────────────────────────────
+    //
+    // The session module is the canonical query pipeline — same
+    // path Python, Bolt, and MCP all flow through (Phase E).
+    let params = HashMap::new();
+    let opts = session::ExecuteOptions::eager(&params);
+    let outcome = session::execute_read(&graph, "MATCH (n) RETURN count(n) AS total", &opts)?;
+    for row in &outcome.result.rows {
+        if let Some(Value::Int64(n)) = row.first() {
+            println!("Total nodes: {}", n);
+        }
+    }
+
+    // ── 3. Sample a few node titles ───────────────────────────────
+    let outcome =
+        session::execute_read(&graph, "MATCH (n) RETURN n.title AS title LIMIT 5", &opts)?;
+    println!("\nSample nodes:");
+    for row in &outcome.result.rows {
+        if let Some(Value::String(s)) = row.first() {
+            println!("  - {}", s);
+        }
+    }
+
+    Ok(())
+}

sonagram-0.1.0/KGLite/crates/kglite/examples/embedded_session.rs

@@ -0,0 +1,88 @@
+//! Demonstrates the snapshot/working CoW transaction model from
+//! `kglite::api::session` — including OCC conflict handling.
+//!
+//! Two transactions race to mutate the same graph: A wins, B's
+//! commit detects the conflict and is rejected. This is the
+//! pattern bindings (Bolt server, etc.) use to surface
+//! "Transaction conflict — retry the transaction" errors.
+//!
+//! Run with:
+//!
+//! ```bash
+//! cargo run -p kglite --example embedded_session
+//! ```
+
+use kglite::api::session::{CommitOutcome, ExecuteOptions, Session};
+use kglite::api::DirGraph;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+fn opts<'a>(params: &'a HashMap<String, kglite::api::Value>) -> ExecuteOptions<'a> {
+    ExecuteOptions::eager(params)
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let session = Arc::new(Session::new(DirGraph::new()));
+    let params: HashMap<String, kglite::api::Value> = HashMap::new();
+
+    // ── Tx A: begin, create a node ────────────────────────────────
+    let mut tx_a = session.begin();
+    let working_a = tx_a.working_mut()?;
+    kglite::api::session::execute_mut(
+        working_a,
+        "CREATE (:Person {id: 1, name: 'Alice'})",
+        &opts(&params),
+    )?;
+    println!("Tx A: created Person(id=1, name='Alice') in working copy");
+
+    // ── Tx B: begin (sees pre-A snapshot), create a different node ─
+    let mut tx_b = session.begin();
+    let working_b = tx_b.working_mut()?;
+    kglite::api::session::execute_mut(
+        working_b,
+        "CREATE (:Person {id: 2, name: 'Bob'})",
+        &opts(&params),
+    )?;
+    println!("Tx B: created Person(id=2, name='Bob') in working copy");
+
+    // ── Commit A: succeeds, graph version bumps to 1 ──────────────
+    let outcome_a = session.commit(tx_a, /* check_occ = */ true);
+    match outcome_a {
+        CommitOutcome::Committed { new_version } => {
+            println!("\n✓ Tx A committed → version {}", new_version);
+        }
+        other => panic!("expected Committed, got {:?}", other),
+    }
+
+    // ── Commit B: OCC detects stale snapshot (base 0, current 1) ──
+    let outcome_b = session.commit(tx_b, /* check_occ = */ true);
+    match outcome_b {
+        CommitOutcome::ConflictDetected {
+            current_version,
+            base_version,
+        } => {
+            println!(
+                "✗ Tx B rejected (OCC): base_version={} but current_version={}",
+                base_version, current_version
+            );
+            println!("  Client retry pattern: re-run the transaction against a fresh snapshot.");
+        }
+        other => panic!("expected ConflictDetected, got {:?}", other),
+    }
+
+    // ── Verify final state: only Alice landed ─────────────────────
+    let snap = session.snapshot();
+    let outcome = kglite::api::session::execute_read(
+        &snap,
+        "MATCH (p:Person) RETURN p.name AS name ORDER BY p.id",
+        &opts(&params),
+    )?;
+    println!("\nFinal graph:");
+    for row in &outcome.result.rows {
+        if let Some(kglite::api::Value::String(s)) = row.first() {
+            println!("  - {}", s);
+        }
+    }
+
+    Ok(())
+}

sonagram-0.1.0/KGLite/crates/kglite/src/bin/bz2_bench.rs

@@ -0,0 +1,99 @@
+//! Parallel bzip2 throughput microbench. Decompresses `<path>` to a
+//! `/dev/null` sink with **zero parsing or scanning overhead** — tells
+//! us the raw ceiling we're up against vs. the loader's observed rate.
+//!
+//! Usage:
+//!     cargo run --bin bz2_bench --release -- <path-to-bz2> [decompressed-cap-mb]
+//!
+//!     decompressed-cap-mb — stop after this many MB of decompressed output
+//!                          (default: read the whole file)
+//!
+//! We call `parallel_bz2_redux::ParBz2Decoder` directly instead of going
+//! through `parallel_bz2::open` so we sidestep the stream-boundary
+//! pre-scan — that's a separate concern, and we want the steady-state
+//! number, not startup time.
+use std::io::{self, Read, Write};
+use std::path::Path;
+use std::time::Instant;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 2 {
+        eprintln!("usage: bz2_bench <path-to-bz2> [decompressed-cap-mb=full]");
+        std::process::exit(2);
+    }
+    let path = Path::new(&args[1]);
+
+    let cap_bytes: Option<u64> = args
+        .get(2)
+        .and_then(|s| s.parse::<u64>().ok())
+        .map(|mb| mb * 1024 * 1024);
+
+    let file_size = std::fs::metadata(path).map(|m| m.len()).unwrap_or(0);
+
+    eprintln!(
+        "bz2_bench: {} ({:.2} GB compressed)",
+        path.display(),
+        file_size as f64 / 1e9,
+    );
+    if let Some(c) = cap_bytes {
+        eprintln!("  cap:      {:.2} GB decompressed", c as f64 / 1e9);
+    }
+
+    let mut decoder = parallel_bz2_redux::ParBz2Decoder::open(path).expect("open decoder");
+
+    let start = Instant::now();
+    let mut buf = vec![0u8; 8 * 1024 * 1024];
+    let mut total: u64 = 0;
+    let mut last_log = start;
+
+    loop {
+        let n = match decoder.read(&mut buf) {
+            Ok(0) => break,
+            Ok(n) => n,
+            Err(e) => {
+                eprintln!("read error after {} bytes: {}", total, e);
+                std::process::exit(1);
+            }
+        };
+        total += n as u64;
+        if let Some(cap) = cap_bytes {
+            if total >= cap {
+                break;
+            }
+        }
+        if last_log.elapsed().as_secs_f64() >= 2.0 {
+            let elapsed = start.elapsed().as_secs_f64();
+            let mb_s = (total as f64 / 1e6) / elapsed;
+            eprintln!(
+                "  {:.2} GB decompressed in {:.1}s = {:.1} MB/s",
+                total as f64 / 1e9,
+                elapsed,
+                mb_s,
+            );
+            let _ = io::stderr().flush();
+            last_log = Instant::now();
+        }
+    }
+
+    let elapsed = start.elapsed().as_secs_f64();
+    let mb_decompressed_per_sec = (total as f64 / 1e6) / elapsed;
+    let triples_per_sec = mb_decompressed_per_sec / 80.0; // ~80 bytes/triple
+
+    println!();
+    println!("=== BZ2 BENCHMARK ===");
+    println!(
+        "  decompressed:    {:.2} GB ({:.0} bytes)",
+        total as f64 / 1e9,
+        total as f64
+    );
+    println!("  wall time:       {:.2} s", elapsed);
+    println!(
+        "  decompress rate: {:.1} MB/s decompressed",
+        mb_decompressed_per_sec
+    );
+    println!(
+        "  triple-rate eq:  {:.2} M tri/s (assuming ~80 bytes/triple)",
+        triples_per_sec
+    );
+}