release: v0.3.0-alpha.4

docs: update generated docs
global: fixes
2026-06-22 12:23:04 -07:00 · 2026-04-04 11:59:17 +02:00 · 2026-04-04 11:58:50 +02:00 · 2026-04-04 11:53:27 +02:00 · 2026-04-04 01:05:04 +02:00 · 2026-04-04 01:04:38 +02:00
1909 changed files with 817426 additions and 70817 deletions
@@ -0,0 +1,5 @@
+[build]
+rustflags = ["-C", "target-cpu=native"]
+
+[alias]
+dev = "run -p brk_cli --features brk_server/bindgen"
@@ -0,0 +1,3 @@
+.git
+target
+docker
@@ -0,0 +1,15 @@
+name: Check outdated dependencies
+
+on:
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+jobs:
+  outdated:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo install cargo-outdated
+      - run: cargo outdated --exit-code 1 --depth 1
@@ -64,7 +64,7 @@ jobs:
        # we specify bash to get pipefail; it guards against the `curl` command
        # failing. otherwise `sh` won't catch that `curl` returned non-0
        shell: bash
-        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.30.0/cargo-dist-installer.sh | sh"
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.30.2/cargo-dist-installer.sh | sh"
      - name: Cache dist
        uses: actions/upload-artifact@v4
        with:
@@ -217,8 +217,8 @@ jobs:
      - plan
      - build-local-artifacts
      - build-global-artifacts
-    # Only run if we're "publishing", and only if local and global didn't fail (skipped is fine)
-    if: ${{ always() && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }}
+    # Only run if we're "publishing", and only if plan, local and global didn't fail (skipped is fine)
+    if: ${{ always() && needs.plan.result == 'success' && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }}
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    runs-on: "ubuntu-22.04"
@@ -6,15 +6,28 @@ target
 websites/dist
 bridge/
 /ids.txt
+rust_out

 # Copies
 *\ copy*

 # Ignored
 _*
+!__*.py
+/*.md
+/*.py
+/*.json
+/*.html
+/research
+/filter_*
+/heatmaps*
+/oracle*
+/playground
+/*.txt
+/*.csv

 # Logs
-.log
+*.log*

 # Environment variables/configs
 .env
@@ -26,3 +39,13 @@ flamegraph.svg

 # AI
 .claude/settings*
+
+# Expand
+expand.rs
+
+# Benchmarks
+[0-9]/
+/benches
+
+# AI
+.claude
@@ -1,22 +0,0 @@
-{
-  "file_scan_exclusions": [
-    // default
-    "**/.git",
-    "**/.svn",
-    "**/.hg",
-    "**/.jj",
-    "**/CVS",
-    "**/.DS_Store",
-    "**/Thumbs.db",
-    "**/.classpath",
-    "**/.settings",
-    // custom
-    "**/lean-qr/*/index.mjs",
-    "**/modern-screenshot/*/index.mjs",
-    "**/solidjs-signals/*/dist/prod.js",
-    "uFuzzy.mjs",
-    "lightweight-charts.standalone.production.mjs"
-    // "scripts/packages",
-    // "dist"
-  ]
-}
@@ -4,11 +4,10 @@ members = ["crates/*"]
 package.description = "The Bitcoin Research Kit is a suite of tools designed to extract, compute and display data stored on a Bitcoin Core node"
 package.license = "MIT"
 package.edition = "2024"
-package.version = "0.0.110"
+package.version = "0.3.0-alpha.4"
 package.homepage = "https://bitcoinresearchkit.org"
 package.repository = "https://github.com/bitcoinresearchkit/brk"
 package.readme = "README.md"
-package.rust-version = "1.89"

 [profile.dev]
 lto = "thin"
@@ -23,71 +22,83 @@ panic = "abort"
 strip = true
 overflow-checks = false

-[profile.profiling]
-inherits = "release"
+[profile.bloaty]
 debug = true
+lto = false
+strip = false
+inherits = "release"

 [profile.dist]
 inherits = "release"

-[profile.clippy]
-inherits = "dev"
-lto = "off"
-codegen-units = 256
-opt-level = 0
-debug = false
-overflow-checks = false
-panic = "abort"
-debug-assertions = false
+[profile.profiling]
+inherits = "release"
+debug = true

 [workspace.dependencies]
-allocative = { version = "0.3.4", features = ["parking_lot"] }
-axum = "0.8.6"
-bitcoin = { version = "0.32.7", features = ["serde"] }
+aide = { version = "0.16.0-alpha.3", features = ["axum-json", "axum-query"] }
+axum = { version = "0.8.8", default-features = false, features = ["http1", "json", "query", "tokio", "tracing"] }
+bitcoin = { version = "0.32.8", features = ["serde"] }
 bitcoincore-rpc = "0.19.0"
-brk_binder = { version = "0.0.110", path = "crates/brk_binder" }
-brk_bundler = { version = "0.0.110", path = "crates/brk_bundler" }
-brk_cli = { version = "0.0.110", path = "crates/brk_cli" }
-brk_computer = { version = "0.0.110", path = "crates/brk_computer" }
-brk_error = { version = "0.0.110", path = "crates/brk_error" }
-brk_fetcher = { version = "0.0.110", path = "crates/brk_fetcher" }
-brk_indexer = { version = "0.0.110", path = "crates/brk_indexer" }
-brk_interface = { version = "0.0.110", path = "crates/brk_interface" }
-brk_logger = { version = "0.0.110", path = "crates/brk_logger" }
-brk_mcp = { version = "0.0.110", path = "crates/brk_mcp" }
-brk_parser = { version = "0.0.110", path = "crates/brk_parser" }
-brk_server = { version = "0.0.110", path = "crates/brk_server" }
-brk_store = { version = "0.0.110", path = "crates/brk_store" }
-brk_structs = { version = "0.0.110", path = "crates/brk_structs" }
-byteview = "=0.6.1"
-derive_deref = "1.1.1"
-fjall = "2.11.2"
-jiff = "0.2.15"
-log = "0.4.28"
-minreq = { version = "2.14.1", features = ["https", "serde_json"] }
-parking_lot = "0.12.4"
-quick_cache = "0.6.16"
+brk_alloc = { version = "0.3.0-alpha.4", path = "crates/brk_alloc" }
+brk_bencher = { version = "0.3.0-alpha.4", path = "crates/brk_bencher" }
+brk_bindgen = { version = "0.3.0-alpha.4", path = "crates/brk_bindgen" }
+brk_cli = { version = "0.3.0-alpha.4", path = "crates/brk_cli" }
+brk_client = { version = "0.3.0-alpha.4", path = "crates/brk_client" }
+brk_cohort = { version = "0.3.0-alpha.4", path = "crates/brk_cohort" }
+brk_computer = { version = "0.3.0-alpha.4", path = "crates/brk_computer" }
+brk_error = { version = "0.3.0-alpha.4", path = "crates/brk_error" }
+brk_fetcher = { version = "0.3.0-alpha.4", path = "crates/brk_fetcher" }
+brk_indexer = { version = "0.3.0-alpha.4", path = "crates/brk_indexer" }
+brk_iterator = { version = "0.3.0-alpha.4", path = "crates/brk_iterator" }
+brk_logger = { version = "0.3.0-alpha.4", path = "crates/brk_logger" }
+brk_mempool = { version = "0.3.0-alpha.4", path = "crates/brk_mempool" }
+brk_oracle = { version = "0.3.0-alpha.4", path = "crates/brk_oracle" }
+brk_query = { version = "0.3.0-alpha.4", path = "crates/brk_query", features = ["tokio"] }
+brk_reader = { version = "0.3.0-alpha.4", path = "crates/brk_reader" }
+brk_rpc = { version = "0.3.0-alpha.4", path = "crates/brk_rpc" }
+brk_server = { version = "0.3.0-alpha.4", path = "crates/brk_server" }
+brk_store = { version = "0.3.0-alpha.4", path = "crates/brk_store" }
+brk_traversable = { version = "0.3.0-alpha.4", path = "crates/brk_traversable", features = ["pco", "derive"] }
+brk_traversable_derive = { version = "0.3.0-alpha.4", path = "crates/brk_traversable_derive" }
+brk_types = { version = "0.3.0-alpha.4", path = "crates/brk_types" }
+brk_website = { version = "0.3.0-alpha.4", path = "crates/brk_website" }
+byteview = "0.10.1"
+color-eyre = "0.6.5"
+corepc-client = { package = "brk-corepc-client", version = "0.11.0", features = ["client-sync"] }
+corepc-jsonrpc = { package = "brk-corepc-jsonrpc", version = "0.19.0", features = ["simple_http"], default-features = false }
+derive_more = { version = "2.1.1", features = ["deref", "deref_mut"] }
+fjall = "=3.0.4"
+indexmap = { version = "2.13.0", features = ["serde"] }
+jiff = { version = "0.2.23", features = ["perf-inline", "tz-system"], default-features = false }
+owo-colors = "4.3.0"
+parking_lot = "0.12.5"
+pco = "1.0.1"
 rayon = "1.11.0"
-schemars = "1.0.4"
+rustc-hash = "2.1.2"
+schemars = { version = "1.2.1", features = ["indexmap2"] }
 serde = "1.0.228"
 serde_bytes = "0.11.19"
 serde_derive = "1.0.228"
-serde_json = { version = "1.0.145", features = ["float_roundtrip"] }
-sonic-rs = "0.5.5"
-tokio = { version = "1.47.1", features = ["rt-multi-thread"] }
-# vecdb = { path = "../seqdb/crates/vecdb", features = ["derive"]}
-vecdb = { version = "0.2.16", features = ["derive"]}
-zerocopy = "0.8.27"
-zerocopy-derive = "0.8.27"
+serde_json = { version = "1.0.149", features = ["float_roundtrip", "preserve_order"] }
+smallvec = "1.15.1"
+tokio = { version = "1.50.0", features = ["rt-multi-thread"] }
+tower-http = { version = "0.6.8", features = ["catch-panic", "compression-br", "compression-gzip", "compression-zstd", "cors", "normalize-path", "timeout", "trace"] }
+tower-layer = "0.3"
+tracing = { version = "0.1", default-features = false, features = ["std"] }
+ureq = { version = "3.3.0", features = ["json"] }
+vecdb = { version = "0.9.3", features = ["derive", "serde_json", "pco", "schemars"] }
+# vecdb = { path = "../anydb/crates/vecdb", features = ["derive", "serde_json", "pco", "schemars"] }

 [workspace.metadata.release]
 shared-version = true
 tag-name = "v{{version}}"
 pre-release-commit-message = "release: v{{version}}"
 tag-message = "release: v{{version}}"
+allow-branch = ["main", "next"]

 [workspace.metadata.dist]
-cargo-dist-version = "0.30.0"
+cargo-dist-version = "0.30.2"
 ci = "github"
 allow-dirty = ["ci"]
 installers = []
@@ -6,54 +6,69 @@ homepage.workspace = true
 repository.workspace = true
 edition.workspace = true
 version.workspace = true
-rust-version.workspace = true
-build = "build.rs"

 [features]
 full = [
-    "binder",
-    "bundler",
+    "bencher",
+    "bindgen",
+    "client",
    "computer",
    "error",
    "fetcher",
+    "cohort",
    "indexer",
-    "interface",
+    "iterator",
    "logger",
-    "mcp",
-    "parser",
+    "mempool",
+    "oracle",
+    "query",
+    "reader",
+    "rpc",
    "server",
    "store",
-    "structs",
+    "traversable",
+    "types",
 ]
-binder = ["brk_binder"]
-bundler = ["brk_bundler"]
+bencher = ["brk_bencher"]
+bindgen = ["brk_bindgen"]
+client = ["brk_client"]
 computer = ["brk_computer"]
 error = ["brk_error"]
 fetcher = ["brk_fetcher"]
+cohort = ["brk_cohort"]
 indexer = ["brk_indexer"]
-interface = ["brk_interface"]
+iterator = ["brk_iterator"]
 logger = ["brk_logger"]
-mcp = ["brk_mcp"]
-parser = ["brk_parser"]
+mempool = ["brk_mempool"]
+oracle = ["brk_oracle"]
+query = ["brk_query"]
+reader = ["brk_reader"]
+rpc = ["brk_rpc"]
 server = ["brk_server"]
 store = ["brk_store"]
-structs = ["brk_structs"]
+traversable = ["brk_traversable"]
+types = ["brk_types"]

 [dependencies]
-brk_binder = { workspace = true, optional = true }
-brk_bundler = { workspace = true, optional = true }
-brk_cli = { workspace = true }
+brk_bencher = { workspace = true, optional = true }
+brk_bindgen = { workspace = true, optional = true }
+brk_client = { workspace = true, optional = true }
 brk_computer = { workspace = true, optional = true }
 brk_error = { workspace = true, optional = true }
 brk_fetcher = { workspace = true, optional = true }
+brk_cohort = { workspace = true, optional = true }
 brk_indexer = { workspace = true, optional = true }
-brk_interface = { workspace = true, optional = true }
+brk_iterator = { workspace = true, optional = true }
 brk_logger = { workspace = true, optional = true }
-brk_mcp = { workspace = true, optional = true }
-brk_parser = { workspace = true, optional = true }
+brk_mempool = { workspace = true, optional = true }
+brk_oracle = { workspace = true, optional = true }
+brk_query = { workspace = true, optional = true }
+brk_reader = { workspace = true, optional = true }
+brk_rpc = { workspace = true, optional = true, features = ["corepc"] }
 brk_server = { workspace = true, optional = true }
 brk_store = { workspace = true, optional = true }
-brk_structs = { workspace = true, optional = true }
+brk_traversable = { workspace = true, optional = true }
+brk_types = { workspace = true, optional = true }

 [package.metadata.docs.rs]
 all-features = true
@@ -1,273 +1,68 @@
 # brk

-Unified Bitcoin Research Kit crate providing optional feature-gated access to all BRK components.
+Umbrella crate for the Bitcoin Research Kit.

-[![Crates.io](https://img.shields.io/crates/v/brk.svg)](https://crates.io/crates/brk)
-[![Documentation](https://docs.rs/brk/badge.svg)](https://docs.rs/brk)
+[crates.io](https://crates.io/crates/brk) | [docs.rs](https://docs.rs/brk)

-## Overview
+## Usage

-This crate serves as a unified entry point to the Bitcoin Research Kit ecosystem, providing feature-gated re-exports of all BRK components. It allows users to selectively include only the functionality they need while maintaining a single dependency declaration, with the `brk_cli` component always available for command-line interface access.
-
-**Key Features:**
-
- Feature-gated modular access to 12 specialized BRK components
- Single dependency entry point with selective compilation
- Always-available CLI component for command-line operations
- Comprehensive documentation aggregation with inline re-exports
- `full` feature for complete BRK functionality inclusion
- Optimized build configuration with docs.rs integration
-
-**Target Use Cases:**
-
- Applications requiring selective BRK functionality to minimize dependencies
- Library development where only specific Bitcoin analysis components are needed
- Prototyping and experimentation with different BRK component combinations
- Educational use cases demonstrating modular blockchain analytics architecture
-
-## Installation
+Single dependency to access any BRK component. Enable only what you need via feature flags.

 ```toml
 [dependencies]
-# Minimal installation with CLI only
-brk = "0.0.107"
-
-# Full functionality
-brk = { version = "0.0.107", features = ["full"] }
-
-# Selective features
-brk = { version = "0.0.107", features = ["indexer", "computer", "server"] }
+brk = { version = "0.1", features = ["query", "types"] }
 ```

-## Quick Start
-
-```rust
-// CLI is always available
-use brk::cli;
-
-// Feature-gated components
-#[cfg(feature = "indexer")]
-use brk::indexer::Indexer;
-
-#[cfg(feature = "computer")]
-use brk::computer::Computer;
-
-#[cfg(feature = "server")]
-use brk::server::Server;
-
-// Build complete pipeline with selected features
-#[cfg(all(feature = "indexer", feature = "computer", feature = "server"))]
-fn build_pipeline() -> Result<(), Box<dyn std::error::Error>> {
-    let indexer = Indexer::build("./data")?;
-    let computer = Computer::build("./analytics", &indexer)?;
-    let interface = brk::interface::Interface::build(&indexer, &computer);
-    let server = Server::new(interface, None);
-    Ok(())
-}
+```rust,ignore
+use brk::query::Query;
+use brk::types::Height;
 ```

-## API Overview
-
-### Feature Organization
-
-The crate provides feature-gated access to BRK components organized by functionality:
-
-**Core Data Processing:**
- `structs` - Bitcoin-aware data structures and type system
- `error` - Centralized error handling across components
- `store` - Transactional key-value storage wrapper
-
-**Blockchain Processing:**
- `parser` - Multi-threaded Bitcoin block parsing
- `indexer` - Blockchain data indexing with columnar storage
- `computer` - Analytics computation engine
-
-**Data Access:**
- `interface` - Unified query interface with fuzzy search
- `fetcher` - Multi-source price data aggregation
-
-**Service Layer:**
- `server` - HTTP API server with caching and compression
- `mcp` - Model Context Protocol bridge for LLM integration
- `logger` - Enhanced logging with colored output
-
-**Web Infrastructure:**
- `bundler` - Web asset bundling using Rolldown
-
-### Always Available
-
-**`cli`**: Command-line interface module (no feature gate required)
-Provides access to the complete BRK command-line interface for running full instances.
-
-## Examples
-
-### Minimal Bitcoin Parser
-
-```rust
-use brk::parser::Parser;
-
-fn parse_blocks() -> Result<(), Box<dyn std::error::Error>> {
-    #[cfg(feature = "parser")]
-    {
-        let parser = Parser::new("/path/to/blocks", None, rpc_client);
-        // Parse blockchain data
-        Ok(())
-    }
-    #[cfg(not(feature = "parser"))]
-    {
-        Err("Parser feature not enabled".into())
-    }
-}
-```
-
-### Analytics Pipeline
-
-```rust
-use brk::{indexer, computer, interface};
-
-#[cfg(all(feature = "indexer", feature = "computer", feature = "interface"))]
-fn analytics_pipeline() -> Result<(), Box<dyn std::error::Error>> {
-    // Initialize indexer
-    let indexer = indexer::Indexer::build("./blockchain_data")?;
-
-    // Compute analytics
-    let computer = computer::Computer::build("./analytics", &indexer)?;
-
-    // Create query interface
-    let interface = interface::Interface::build(&indexer, &computer);
-
-    // Query latest price
-    let params = interface::Params {
-        index: "date".to_string(),
-        ids: vec!["price-close".to_string()].into(),
-        from: Some(-1),
-        ..Default::default()
-    };
-
-    let result = interface.search_and_format(params)?;
-    println!("Latest Bitcoin price: {:?}", result);
-
-    Ok(())
-}
-```
-
-### Web Server Setup
-
-```rust
-use brk::{server, interface, indexer, computer};
-
-#[cfg(all(feature = "server", feature = "interface", feature = "indexer", feature = "computer"))]
-async fn web_server() -> Result<(), Box<dyn std::error::Error>> {
-    let indexer = indexer::Indexer::build("./data")?;
-    let computer = computer::Computer::build("./analytics", &indexer)?;
-    let interface = interface::Interface::build(&indexer, &computer);
-
-    let server = server::Server::new(interface, None);
-    server.serve(true).await?;
-
-    Ok(())
-}
-```
-
-### MCP Integration
-
-```rust
-use brk::{mcp, interface, indexer, computer};
-
-#[cfg(all(feature = "mcp", feature = "interface"))]
-fn mcp_server(interface: &'static interface::Interface) -> mcp::MCP {
-    mcp::MCP::new(interface)
-}
-```
-
-## Feature Combinations
-
-### Common Combinations
-
-**Data Processing**: `["structs", "parser", "indexer"]`
-Basic blockchain data processing and indexing.
-
-**Analytics**: `["indexer", "computer", "fetcher", "interface"]`
-Complete analytics pipeline with price data integration.
-
-**API Server**: `["interface", "server", "logger"]`
-HTTP API server with logging capabilities.
-
-**Full Stack**: `["full"]`
-All components for complete BRK functionality.
-
-### Dependency Optimization
-
-Feature selection allows for significant dependency reduction:
+Feature flags match crate names without the `brk_` prefix. Use `full` to enable all:

 ```toml
-# Minimal parser-only dependency
-brk = { version = "0.0.107", features = ["parser"] }
-
-# Analytics without web server
-brk = { version = "0.0.107", features = ["indexer", "computer", "interface"] }
-
-# Web server without parsing
-brk = { version = "0.0.107", features = ["interface", "server"] }
+[dependencies]
+brk = { version = "0.1", features = ["full"] }
 ```

-## Architecture
+## Crates

-### Re-export Pattern
+**Core Pipeline**

-The crate uses `#[doc(inline)]` re-exports to provide seamless access to component APIs:
+| Crate | Description |
+|-------|-------------|
+| [brk_reader](https://docs.rs/brk_reader) | Read blocks from `blk*.dat` with parallel parsing and XOR decoding |
+| [brk_indexer](https://docs.rs/brk_indexer) | Index transactions, addresses, and UTXOs |
+| [brk_computer](https://docs.rs/brk_computer) | Compute derived metrics (realized cap, MVRV, SOPR, cohorts, etc.) |
+| [brk_mempool](https://docs.rs/brk_mempool) | Monitor mempool, estimate fees, project upcoming blocks |
+| [brk_oracle](https://docs.rs/brk_oracle) | Pure on-chain BTC/USD price oracle |
+| [brk_query](https://docs.rs/brk_query) | Query interface for indexed and computed data |
+| [brk_server](https://docs.rs/brk_server) | REST API with OpenAPI docs |

-```rust
-#[cfg(feature = "component")]
-#[doc(inline)]
-pub use brk_component as component;
-```
+**Data & Storage**

-This pattern ensures:
- Feature-gated compilation for dependency optimization
- Inline documentation for unified API reference
- Namespace preservation for component-specific functionality
+| Crate | Description |
+|-------|-------------|
+| [brk_types](https://docs.rs/brk_types) | Domain types: `Height`, `Sats`, `Txid`, addresses, etc. |
+| [brk_store](https://docs.rs/brk_store) | Key-value storage (fjall wrapper) |
+| [brk_fetcher](https://docs.rs/brk_fetcher) | Fetch price data from exchanges |
+| [brk_rpc](https://docs.rs/brk_rpc) | Bitcoin Core RPC client |
+| [brk_iterator](https://docs.rs/brk_iterator) | Unified block iteration with automatic source selection |
+| [brk_cohort](https://docs.rs/brk_cohort) | UTXO and address cohort filtering |
+| [brk_traversable](https://docs.rs/brk_traversable) | Navigate hierarchical data structures |

-### Build Configuration
+**Clients & Integration**

- **Documentation**: `all-features = true` for complete docs.rs documentation
- **CLI Integration**: `brk_cli` always available without feature gates
- **Optional Dependencies**: All components except CLI are optional
+| Crate | Description |
+|-------|-------------|
+| [brk_client](https://docs.rs/brk_client) | Generated Rust API client |
+| [brk_bindgen](https://docs.rs/brk_bindgen) | Generate typed clients (Rust, JavaScript, Python) |

-## Configuration
+**Internal**

-### Feature Flags
-
-| Feature | Component | Description |
-|---------|-----------|-------------|
-| `bundler` | `brk_bundler` | Web asset bundling |
-| `computer` | `brk_computer` | Analytics computation |
-| `error` | `brk_error` | Error handling |
-| `fetcher` | `brk_fetcher` | Price data fetching |
-| `indexer` | `brk_indexer` | Blockchain indexing |
-| `interface` | `brk_interface` | Data query interface |
-| `logger` | `brk_logger` | Enhanced logging |
-| `mcp` | `brk_mcp` | Model Context Protocol |
-| `parser` | `brk_parser` | Block parsing |
-| `server` | `brk_server` | HTTP server |
-| `store` | `brk_store` | Key-value storage |
-| `structs` | `brk_structs` | Data structures |
-| `full` | All components | Complete functionality |
-
-### Documentation
-
-Documentation is aggregated from all components with `#![doc = include_str!("../README.md")]` ensuring comprehensive API reference across all features.
-
-## Code Analysis Summary
-
-**Main Structure**: Feature-gated re-export crate providing unified access to 12 BRK components \
-**Feature System**: Cargo features enabling selective compilation and dependency optimization \
-**CLI Integration**: Always-available `brk_cli` access without feature requirements \
-**Documentation**: Inline re-exports with comprehensive docs.rs integration \
-**Dependency Management**: Optional dependencies for all components except CLI \
-**Build Configuration**: Optimized compilation with all-features documentation \
-**Architecture**: Modular aggregation crate enabling flexible BRK ecosystem usage
-
---
-
-_This README was generated by Claude Code_
+| Crate | Description |
+|-------|-------------|
+| [brk_cli](https://docs.rs/brk_cli) | CLI binary (`cargo install --locked brk_cli`) |
+| [brk_error](https://docs.rs/brk_error) | Error types |
+| [brk_logger](https://docs.rs/brk_logger) | Logging infrastructure |
+| [brk_bencher](https://docs.rs/brk_bencher) | Benchmarking utilities |
@@ -1,8 +0,0 @@
-fn main() {
-    let profile = std::env::var("PROFILE").unwrap_or_default();
-
-    if profile == "release" {
-        println!("cargo:rustc-flag=-C");
-        println!("cargo:rustc-flag=target-cpu=native");
-    }
-}
@@ -1,19 +1,20 @@
 #![doc = include_str!("../README.md")]

-#[cfg(feature = "binder")]
+#[cfg(feature = "bencher")]
 #[doc(inline)]
-pub use brk_binder as binder;
+pub use brk_bencher as bencher;

-#[cfg(feature = "bundler")]
+#[cfg(feature = "bindgen")]
 #[doc(inline)]
-pub use brk_bundler as bundler;
+pub use brk_bindgen as bindgen;

+#[cfg(feature = "client")]
 #[doc(inline)]
-pub use brk_cli as cli;
+pub use brk_client as client;

-#[cfg(feature = "structs")]
+#[cfg(feature = "cohort")]
 #[doc(inline)]
-pub use brk_structs as structs;
+pub use brk_cohort as cohort;

 #[cfg(feature = "computer")]
 #[doc(inline)]
@@ -31,21 +32,33 @@ pub use brk_fetcher as fetcher;
 #[doc(inline)]
 pub use brk_indexer as indexer;

+#[cfg(feature = "iterator")]
+#[doc(inline)]
+pub use brk_iterator as iterator;
+
 #[cfg(feature = "logger")]
 #[doc(inline)]
 pub use brk_logger as logger;

-#[cfg(feature = "mcp")]
+#[cfg(feature = "mempool")]
 #[doc(inline)]
-pub use brk_mcp as mcp;
+pub use brk_mempool as mempool;

-#[cfg(feature = "parser")]
+#[cfg(feature = "oracle")]
 #[doc(inline)]
-pub use brk_parser as parser;
+pub use brk_oracle as oracle;

-#[cfg(feature = "interface")]
+#[cfg(feature = "query")]
 #[doc(inline)]
-pub use brk_interface as interface;
+pub use brk_query as query;
+
+#[cfg(feature = "reader")]
+#[doc(inline)]
+pub use brk_reader as reader;
+
+#[cfg(feature = "rpc")]
+#[doc(inline)]
+pub use brk_rpc as rpc;

 #[cfg(feature = "server")]
 #[doc(inline)]
@@ -54,3 +67,11 @@ pub use brk_server as server;
 #[cfg(feature = "store")]
 #[doc(inline)]
 pub use brk_store as store;
+
+#[cfg(feature = "traversable")]
+#[doc(inline)]
+pub use brk_traversable as traversable;
+
+#[cfg(feature = "types")]
+#[doc(inline)]
+pub use brk_types as types;
@@ -1 +0,0 @@
-use brk_cli::main;
@@ -0,0 +1,12 @@
+[package]
+name = "brk_alloc"
+description = "Global allocator and memory utilities for brk"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[dependencies]
+libmimalloc-sys = { version = "0.1.44", features = ["extended"] }
+mimalloc = { version = "0.1.48", features = ["v3"] }
@@ -0,0 +1,21 @@
+//! Global allocator and memory utilities for brk.
+//!
+//! This crate sets mimalloc as the global allocator and provides
+//! utilities for monitoring and managing memory.
+
+use mimalloc::MiMalloc as Allocator;
+
+#[global_allocator]
+static GLOBAL: Allocator = Allocator;
+
+/// Mimalloc allocator utilities
+pub struct Mimalloc;
+
+impl Mimalloc {
+    /// Eagerly free memory back to OS.
+    /// Only call at natural pause points.
+    #[inline]
+    pub fn collect() {
+        unsafe { libmimalloc_sys::mi_collect(true) }
+    }
+}
@@ -0,0 +1,16 @@
+[package]
+name = "brk_bencher"
+description = "A simple benchmarker for testing other crates."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[dependencies]
+brk_error = { workspace = true }
+brk_logger = { workspace = true }
+parking_lot = { workspace = true }
+
+[target.'cfg(target_os = "macos")'.dependencies]
+libproc = "0.14"
@@ -0,0 +1,43 @@
+# brk_bencher
+
+Resource monitoring for long-running Bitcoin indexing operations.
+
+## What It Enables
+
+Track disk usage, memory consumption (current + peak), and I/O throughput during indexing runs. Progress tracking hooks into brk_logger to record processing milestones automatically.
+
+## Key Features
+
+- **Multi-metric monitoring**: Disk, memory (RSS + peak), I/O read/write
+- **Progress tracking**: Integrates with logging to capture block heights as they're processed
+- **Run comparison**: Outputs timestamped CSVs for comparing multiple runs
+- **macOS optimized**: Uses libproc for accurate process metrics on macOS
+- **Non-blocking**: Monitors in background thread with 5-second sample interval
+
+## Core API
+
+```rust,ignore
+let mut bencher = Bencher::from_cargo_env("brk_indexer", &data_path)?;
+bencher.start()?;
+
+// ... run indexing ...
+
+bencher.stop()?;
+```
+
+## Output Structure
+
+```
+benches/
+└── brk_indexer/
+    └── 1703001234/
+        ├── disk.csv      # timestamp_ms, bytes
+        ├── memory.csv    # timestamp_ms, current, peak
+        ├── io.csv        # timestamp_ms, read, written
+        └── progress.csv  # timestamp_ms, height
+```
+
+## Built On
+
+- `brk_error` for error handling
+- `brk_logger` for progress hook integration
@@ -0,0 +1,66 @@
+use std::{
+    collections::HashMap,
+    fs::{self, File},
+    io::{self, Write},
+    os::unix::fs::MetadataExt,
+    path::{Path, PathBuf},
+    time::SystemTime,
+};
+
+pub struct DiskMonitor {
+    cache: HashMap<PathBuf, (u64, SystemTime)>, // path -> (bytes_used, mtime)
+    monitored_path: PathBuf,
+    writer: File,
+}
+
+impl DiskMonitor {
+    pub fn new(monitored_path: &Path, csv_path: &Path) -> io::Result<Self> {
+        let mut writer = File::create(csv_path)?;
+        writeln!(writer, "timestamp_ms,disk_usage")?;
+
+        Ok(Self {
+            cache: HashMap::new(),
+            monitored_path: monitored_path.to_path_buf(),
+            writer,
+        })
+    }
+
+    /// Record disk usage at the given timestamp
+    pub fn record(&mut self, elapsed_ms: u128) -> io::Result<()> {
+        if let Ok(bytes) = self.scan_recursive(&self.monitored_path.clone()) {
+            writeln!(self.writer, "{},{}", elapsed_ms, bytes)?;
+        }
+        Ok(())
+    }
+
+    fn scan_recursive(&mut self, path: &Path) -> io::Result<u64> {
+        let mut total = 0;
+
+        for entry in fs::read_dir(path)? {
+            let entry = entry?;
+            let path = entry.path();
+            let metadata = entry.metadata()?;
+
+            if metadata.is_file() {
+                let mtime = metadata.modified()?;
+
+                // Check cache: if mtime unchanged, use cached value
+                if let Some((cached_bytes, cached_mtime)) = self.cache.get(&path)
+                    && *cached_mtime == mtime
+                {
+                    total += cached_bytes;
+                    continue;
+                }
+
+                // File is new or modified - get actual disk usage
+                let bytes = metadata.blocks() * 512;
+                self.cache.insert(path, (bytes, mtime));
+                total += bytes;
+            } else if metadata.is_dir() {
+                total += self.scan_recursive(&path)?;
+            }
+        }
+
+        Ok(total)
+    }
+}
@@ -0,0 +1,83 @@
+use std::{
+    fs::File,
+    io::{self, Write},
+    path::Path,
+};
+
+#[cfg(target_os = "linux")]
+use std::fs;
+
+#[cfg(target_os = "macos")]
+use libproc::pid_rusage::{RUsageInfoV2, pidrusage};
+
+pub struct IoMonitor {
+    pid: u32,
+    writer: File,
+}
+
+impl IoMonitor {
+    pub fn new(pid: u32, csv_path: &Path) -> io::Result<Self> {
+        let mut writer = File::create(csv_path)?;
+        writeln!(writer, "timestamp_ms,bytes_read,bytes_written")?;
+
+        Ok(Self { pid, writer })
+    }
+
+    /// Record I/O usage at the given timestamp
+    pub fn record(&mut self, elapsed_ms: u128) -> io::Result<()> {
+        if let Ok((read, written)) = self.get_io_usage() {
+            writeln!(self.writer, "{},{},{}", elapsed_ms, read, written)?;
+        }
+        Ok(())
+    }
+
+    /// Get I/O usage in bytes
+    /// Returns (bytes_read, bytes_written)
+    fn get_io_usage(&self) -> io::Result<(u64, u64)> {
+        #[cfg(target_os = "linux")]
+        {
+            self.get_io_usage_linux()
+        }
+
+        #[cfg(target_os = "macos")]
+        {
+            self.get_io_usage_macos()
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    fn get_io_usage_linux(&self) -> io::Result<(u64, u64)> {
+        let io_content = fs::read_to_string(format!("/proc/{}/io", self.pid))?;
+
+        let mut read_bytes = None;
+        let mut write_bytes = None;
+
+        for line in io_content.lines() {
+            if line.starts_with("read_bytes:") {
+                if let Some(value_str) = line.split_whitespace().nth(1) {
+                    read_bytes = value_str.parse::<u64>().ok();
+                }
+            } else if line.starts_with("write_bytes:") {
+                if let Some(value_str) = line.split_whitespace().nth(1) {
+                    write_bytes = value_str.parse::<u64>().ok();
+                }
+            }
+        }
+
+        match (read_bytes, write_bytes) {
+            (Some(r), Some(w)) => Ok((r, w)),
+            _ => Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "Failed to parse I/O stats from /proc/[pid]/io",
+            )),
+        }
+    }
+
+    #[cfg(target_os = "macos")]
+    fn get_io_usage_macos(&self) -> io::Result<(u64, u64)> {
+        match pidrusage::<RUsageInfoV2>(self.pid as i32) {
+            Ok(info) => Ok((info.ri_diskio_bytesread, info.ri_diskio_byteswritten)),
+            Err(_) => Err(io::Error::other("Failed to get process I/O stats")),
+        }
+    }
+}
@@ -0,0 +1,162 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+    sync::{
+        Arc,
+        atomic::{AtomicBool, Ordering},
+    },
+    thread::{self, JoinHandle},
+    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
+};
+
+use brk_error::{Error, Result};
+
+mod disk;
+mod io;
+mod memory;
+mod progression;
+
+use disk::*;
+use io::*;
+use memory::*;
+use parking_lot::Mutex;
+use progression::*;
+
+#[derive(Clone)]
+pub struct Bencher(Arc<BencherInner>);
+
+struct BencherInner {
+    bench_dir: PathBuf,
+    monitored_path: PathBuf,
+    stop_flag: Arc<AtomicBool>,
+    monitor_thread: Mutex<Option<JoinHandle<Result<()>>>>,
+    progression: Arc<ProgressionMonitor>,
+}
+
+impl Bencher {
+    /// Create a new bencher for the given crate name
+    /// Creates directory structure: workspace_root/benches/{crate_name}/{timestamp}/
+    pub fn new(crate_name: &str, workspace_root: &Path, monitored_path: &Path) -> Result<Self> {
+        let timestamp = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs();
+
+        let bench_dir = workspace_root
+            .join("benches")
+            .join(crate_name)
+            .join(timestamp.to_string());
+
+        fs::create_dir_all(&bench_dir)?;
+
+        let progress_csv = bench_dir.join("progress.csv");
+        let progression = Arc::new(ProgressionMonitor::new(&progress_csv)?);
+        let progression_clone = progression.clone();
+
+        // Register hook with logger
+        brk_logger::register_hook(move |message| {
+            progression_clone.check_and_record(message);
+        })
+        .map_err(|e| std::io::Error::new(std::io::ErrorKind::AlreadyExists, e))?;
+
+        Ok(Self(Arc::new(BencherInner {
+            bench_dir,
+            monitored_path: monitored_path.to_path_buf(),
+            stop_flag: Arc::new(AtomicBool::new(false)),
+            progression,
+            monitor_thread: Mutex::new(None),
+        })))
+    }
+
+    /// Create a bencher using CARGO_MANIFEST_DIR to find workspace root
+    pub fn from_cargo_env(crate_name: &str, monitored_path: &Path) -> Result<Self> {
+        let mut current = std::env::current_dir()
+            .map_err(|e| format!("Failed to get current directory: {}", e))
+            .unwrap();
+
+        let workspace_root = loop {
+            let cargo_toml = current.join("Cargo.toml");
+            if cargo_toml.exists() {
+                let contents = std::fs::read_to_string(&cargo_toml)
+                    .map_err(|e| format!("Failed to read Cargo.toml: {}", e))
+                    .unwrap();
+                if contents.contains("[workspace]") {
+                    break current;
+                }
+            }
+
+            current = current
+                .parent()
+                .ok_or(Error::NotFound("Workspace root not found".into()))?
+                .to_path_buf();
+        };
+
+        Self::new(crate_name, &workspace_root, monitored_path)
+    }
+
+    /// Start monitoring disk usage and memory footprint
+    pub fn start(&mut self) -> Result<()> {
+        if self.0.monitor_thread.lock().is_some() {
+            return Err(Error::Internal("Bencher already started"));
+        }
+
+        let stop_flag = self.0.stop_flag.clone();
+        let bench_dir = self.0.bench_dir.clone();
+        let monitored_path = self.0.monitored_path.clone();
+
+        let handle =
+            thread::spawn(move || monitor_resources(&monitored_path, &bench_dir, stop_flag));
+
+        *self.0.monitor_thread.lock() = Some(handle);
+        Ok(())
+    }
+
+    /// Stop monitoring and wait for the thread to finish
+    pub fn stop(&self) -> Result<()> {
+        self.0.stop_flag.store(true, Ordering::Relaxed);
+
+        if let Some(handle) = self.0.monitor_thread.lock().take() {
+            handle
+                .join()
+                .map_err(|_| Error::Internal("Monitor thread panicked"))??;
+        }
+
+        self.0.progression.flush()?;
+
+        Ok(())
+    }
+}
+
+impl Drop for Bencher {
+    fn drop(&mut self) {
+        let _ = self.stop();
+    }
+}
+
+fn monitor_resources(
+    monitored_path: &Path,
+    bench_dir: &Path,
+    stop_flag: Arc<AtomicBool>,
+) -> Result<()> {
+    let pid = std::process::id();
+    let start = Instant::now();
+
+    let mut disk_monitor = DiskMonitor::new(monitored_path, &bench_dir.join("disk.csv"))?;
+    let mut memory_monitor = MemoryMonitor::new(pid, &bench_dir.join("memory.csv"))?;
+    let mut io_monitor = IoMonitor::new(pid, &bench_dir.join("io.csv"))?;
+
+    'l: loop {
+        let elapsed_ms = start.elapsed().as_millis();
+
+        disk_monitor.record(elapsed_ms)?;
+        memory_monitor.record(elapsed_ms)?;
+        io_monitor.record(elapsed_ms)?;
+
+        for _ in 0..50 {
+            // 50 * 100ms = 5 seconds
+            if stop_flag.load(Ordering::Relaxed) {
+                break 'l;
+            }
+            thread::sleep(Duration::from_millis(100));
+        }
+    }
+
+    Ok(())
+}
@@ -0,0 +1,143 @@
+use std::{
+    fs::File,
+    io::{self, Write},
+    path::Path,
+};
+
+#[cfg(target_os = "linux")]
+use std::fs;
+
+#[cfg(target_os = "macos")]
+use std::process::Command;
+
+pub struct MemoryMonitor {
+    pid: u32,
+    writer: File,
+}
+
+impl MemoryMonitor {
+    pub fn new(pid: u32, csv_path: &Path) -> io::Result<Self> {
+        let mut writer = File::create(csv_path)?;
+        writeln!(writer, "timestamp_ms,phys_footprint,phys_footprint_peak")?;
+
+        Ok(Self { pid, writer })
+    }
+
+    /// Record memory usage at the given timestamp
+    pub fn record(&mut self, elapsed_ms: u128) -> io::Result<()> {
+        if let Ok((footprint, peak)) = self.get_memory_usage() {
+            writeln!(self.writer, "{},{},{}", elapsed_ms, footprint, peak)?;
+        }
+        Ok(())
+    }
+
+    /// Get memory usage in bytes
+    /// Returns (current_bytes, peak_bytes)
+    fn get_memory_usage(&self) -> io::Result<(u64, u64)> {
+        #[cfg(target_os = "linux")]
+        {
+            self.get_memory_usage_linux()
+        }
+
+        #[cfg(target_os = "macos")]
+        {
+            self.get_memory_usage_macos()
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    fn get_memory_usage_linux(&self) -> io::Result<(u64, u64)> {
+        let status_content = fs::read_to_string(format!("/proc/{}/status", self.pid))?;
+
+        let mut vm_rss = None;
+        let mut vm_hwm = None;
+
+        for line in status_content.lines() {
+            if line.starts_with("VmRSS:") {
+                if let Some(value_str) = line.split_whitespace().nth(1) {
+                    if let Ok(kb) = value_str.parse::<u64>() {
+                        vm_rss = Some(kb * 1024); // KiB to bytes
+                    }
+                }
+            } else if line.starts_with("VmHWM:") {
+                if let Some(value_str) = line.split_whitespace().nth(1) {
+                    if let Ok(kb) = value_str.parse::<u64>() {
+                        vm_hwm = Some(kb * 1024); // KiB to bytes
+                    }
+                }
+            }
+        }
+
+        match (vm_rss, vm_hwm) {
+            (Some(rss), Some(hwm)) => Ok((rss, hwm)),
+            _ => Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "Failed to parse memory info from /proc/[pid]/status",
+            )),
+        }
+    }
+
+    #[cfg(target_os = "macos")]
+    fn get_memory_usage_macos(&self) -> io::Result<(u64, u64)> {
+        let output = Command::new("footprint")
+            .args(["-p", &self.pid.to_string()])
+            .output()?;
+
+        let stdout = String::from_utf8(output.stdout).map_err(|_| {
+            io::Error::new(io::ErrorKind::InvalidData, "Invalid UTF-8 from footprint")
+        })?;
+
+        parse_footprint_output(&stdout).ok_or_else(|| {
+            io::Error::new(
+                io::ErrorKind::InvalidData,
+                "Failed to parse footprint output",
+            )
+        })
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn parse_footprint_output(output: &str) -> Option<(u64, u64)> {
+    let mut phys_footprint = None;
+    let mut phys_footprint_peak = None;
+
+    for line in output.lines() {
+        let line = line.trim();
+
+        if line.starts_with("phys_footprint:") {
+            // Format: "phys_footprint: 7072 KB"
+            let parts: Vec<&str> = line.split_whitespace().collect();
+            if parts.len() >= 3 {
+                // parts[0] = "phys_footprint:"
+                // parts[1] = "7072"
+                // parts[2] = "KB"
+                phys_footprint = parse_size_to_bytes(parts[1], parts[2]);
+            }
+        } else if line.starts_with("phys_footprint_peak:") {
+            // Format: "phys_footprint_peak: 15 MB"
+            let parts: Vec<&str> = line.split_whitespace().collect();
+            if parts.len() >= 3 {
+                phys_footprint_peak = parse_size_to_bytes(parts[1], parts[2]);
+            }
+        }
+    }
+
+    match (phys_footprint, phys_footprint_peak) {
+        (Some(f), Some(p)) => Some((f, p)),
+        _ => None,
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn parse_size_to_bytes(value: &str, unit: &str) -> Option<u64> {
+    let value: f64 = value.parse().ok()?;
+
+    let multiplier = match unit.to_uppercase().as_str() {
+        "KB" => 1024.0,                   // KiB to bytes
+        "MB" => 1024.0 * 1024.0,          // MiB to bytes
+        "GB" => 1024.0 * 1024.0 * 1024.0, // GiB to bytes
+        _ => return None,
+    };
+
+    Some((value * multiplier) as u64)
+}
@@ -0,0 +1,74 @@
+use parking_lot::Mutex;
+use std::{
+    fs,
+    io::{self, BufWriter, Write},
+    path::Path,
+    time::Instant,
+};
+
+/// Patterns to match for progress tracking.
+const PROGRESS_PATTERNS: &[&str] = &[
+    "block ",    // "Indexing block 123..."
+    "chain at ", // "Processing chain at 456..."
+];
+
+pub struct ProgressionMonitor {
+    csv_file: Mutex<BufWriter<fs::File>>,
+    start_time: Instant,
+}
+
+impl ProgressionMonitor {
+    pub fn new(csv_path: &Path) -> io::Result<Self> {
+        let mut csv_file = BufWriter::new(fs::File::create(csv_path)?);
+        writeln!(csv_file, "timestamp_ms,value")?;
+
+        Ok(Self {
+            csv_file: Mutex::new(csv_file),
+            start_time: Instant::now(),
+        })
+    }
+
+    /// Check message for progress patterns and record if found
+    #[inline]
+    pub fn check_and_record(&self, message: &str) {
+        let Some(value) = parse_progress(message) else {
+            return;
+        };
+
+        if value % 10 != 0 {
+            return;
+        }
+
+        let elapsed_ms = self.start_time.elapsed().as_millis();
+        let _ = writeln!(self.csv_file.lock(), "{},{}", elapsed_ms, value);
+    }
+
+    pub fn flush(&self) -> io::Result<()> {
+        self.csv_file.lock().flush()
+    }
+}
+
+/// Parse progress value from message
+#[inline]
+fn parse_progress(message: &str) -> Option<u64> {
+    PROGRESS_PATTERNS
+        .iter()
+        .find_map(|pattern| parse_number_after(message, pattern))
+}
+
+/// Extract number immediately following the pattern
+#[inline]
+fn parse_number_after(message: &str, pattern: &str) -> Option<u64> {
+    let start = message.find(pattern)?;
+    let after = &message[start + pattern.len()..];
+
+    let end = after
+        .find(|c: char| !c.is_ascii_digit())
+        .unwrap_or(after.len());
+
+    if end == 0 {
+        return None;
+    }
+
+    after[..end].parse().ok()
+}
@@ -0,0 +1,12 @@
+[package]
+name = "brk_bencher_visualizer"
+description = "A generator of charts for brk_bencher"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+publish = false
+
+[dependencies]
+plotters = "0.3.7"
@@ -0,0 +1,34 @@
+# brk_bencher_visualizer
+
+SVG chart generation for benchmark visualization.
+
+## What It Enables
+
+Turn benchmark CSV data into publication-ready SVG charts showing disk usage, memory (current/peak), progress, and I/O over time. Compare multiple runs side-by-side with automatic color coding.
+
+## Key Features
+
+- **Multi-run comparison**: Overlay multiple benchmark runs with distinct colors
+- **Dual-axis charts**: Memory charts show both current and peak usage (solid vs dashed lines)
+- **Smart scaling**: Automatic unit conversion for bytes (KB/MB/GB) and time (seconds/minutes/hours)
+- **Per-run trimming**: Aligns data by progress cutoffs for fair comparison
+- **Dark theme**: Clean, readable charts with monospace fonts
+
+## Core API
+
+```rust,ignore
+let viz = Visualizer::from_cargo_env()?;
+viz.generate_all_charts()?;  // Process all crates in benches/
+```
+
+## Chart Types
+
+- `disk.svg` - Storage consumption over time
+- `memory.svg` - Current + peak memory usage
+- `progress.svg` - Processing progress (e.g., blocks indexed)
+- `io_read.svg` / `io_write.svg` - I/O throughput
+
+## Input Format
+
+Reads CSV files from `benches/<crate>/<run_id>/`:
+- `disk.csv`, `memory.csv`, `progress.csv`, `io.csv`
@@ -0,0 +1,285 @@
+use crate::data::{DataPoint, DualRun, Result, Run};
+use crate::format;
+use plotters::prelude::*;
+use std::path::Path;
+
+const FONT: &str = "monospace";
+const FONT_SIZE: i32 = 20;
+const FONT_SIZE_BIG: i32 = 30;
+const SIZE: (u32, u32) = (2000, 1000);
+const TIME_BUFFER_MS: u64 = 10_000;
+
+const BG_COLOR: RGBColor = RGBColor(18, 18, 24);
+const TEXT_COLOR: RGBColor = RGBColor(230, 230, 240);
+const COLORS: [RGBColor; 6] = [
+    RGBColor(255, 99, 132),  // Pink/Red
+    RGBColor(54, 162, 235),  // Blue
+    RGBColor(75, 192, 192),  // Teal
+    RGBColor(255, 206, 86),  // Yellow
+    RGBColor(153, 102, 255), // Purple
+    RGBColor(255, 159, 64),  // Orange
+];
+
+pub enum YAxisFormat {
+    Bytes,
+    Number,
+}
+
+pub struct ChartConfig<'a> {
+    pub output_path: &'a Path,
+    pub title: String,
+    pub y_label: String,
+    pub y_format: YAxisFormat,
+}
+
+/// Generate a simple line chart from runs
+pub fn generate(config: ChartConfig, runs: &[Run]) -> Result<()> {
+    if runs.is_empty() {
+        return Ok(());
+    }
+
+    let max_time_ms = runs.iter().map(|r| r.max_timestamp()).max().unwrap_or(1000) + TIME_BUFFER_MS;
+    let max_time_s = max_time_ms as f64 / 1000.0;
+    let max_value = runs.iter().map(|r| r.max_value()).fold(0.0, f64::max);
+
+    let (time_scaled, time_divisor, time_label) = format::time(max_time_s);
+    let (value_scaled, scale_factor, y_label) =
+        scale_y_axis(max_value, &config.y_label, &config.y_format);
+    let x_labels = label_count(time_scaled);
+
+    let root = SVGBackend::new(config.output_path, SIZE).into_drawing_area();
+    root.fill(&BG_COLOR)?;
+
+    let mut chart = ChartBuilder::on(&root)
+        .caption(
+            &config.title,
+            (FONT, FONT_SIZE_BIG).into_font().color(&TEXT_COLOR),
+        )
+        .margin(20)
+        .margin_right(40)
+        .x_label_area_size(50)
+        .margin_left(50)
+        .right_y_label_area_size(75)
+        .build_cartesian_2d(0.0..time_scaled * 1.025, 0.0..value_scaled * 1.1)?;
+
+    configure_mesh(&mut chart, time_label, &y_label, &config.y_format, x_labels)?;
+
+    for (idx, run) in runs.iter().enumerate() {
+        let color = COLORS[idx % COLORS.len()];
+        draw_series(
+            &mut chart,
+            &run.data,
+            &run.id,
+            color,
+            time_divisor,
+            scale_factor,
+        )?;
+    }
+
+    configure_legend(&mut chart)?;
+    root.present()?;
+    println!("Generated: {}", config.output_path.display());
+    Ok(())
+}
+
+/// Generate a chart with dual series per run (e.g., current + peak memory)
+pub fn generate_dual(
+    config: ChartConfig,
+    runs: &[DualRun],
+    primary_suffix: &str,
+    secondary_suffix: &str,
+) -> Result<()> {
+    if runs.is_empty() {
+        return Ok(());
+    }
+
+    let max_time_ms = runs
+        .iter()
+        .flat_map(|r| r.primary.iter().chain(r.secondary.iter()))
+        .map(|d| d.timestamp_ms)
+        .max()
+        .unwrap_or(1000)
+        + TIME_BUFFER_MS;
+    let max_time_s = max_time_ms as f64 / 1000.0;
+    let max_value = runs.iter().map(|r| r.max_value()).fold(0.0, f64::max);
+
+    let (time_scaled, time_divisor, time_label) = format::time(max_time_s);
+    let (value_scaled, scale_factor, y_label) =
+        scale_y_axis(max_value, &config.y_label, &config.y_format);
+    let x_labels = label_count(time_scaled);
+
+    let root = SVGBackend::new(config.output_path, SIZE).into_drawing_area();
+    root.fill(&BG_COLOR)?;
+
+    let mut chart = ChartBuilder::on(&root)
+        .caption(
+            &config.title,
+            (FONT, FONT_SIZE_BIG).into_font().color(&TEXT_COLOR),
+        )
+        .margin(20)
+        .margin_right(40)
+        .x_label_area_size(50)
+        .margin_left(50)
+        .right_y_label_area_size(75)
+        .build_cartesian_2d(0.0..time_scaled * 1.025, 0.0..value_scaled * 1.1)?;
+
+    configure_mesh(&mut chart, time_label, &y_label, &config.y_format, x_labels)?;
+
+    for (idx, run) in runs.iter().enumerate() {
+        let color = COLORS[idx % COLORS.len()];
+
+        // Primary series (solid)
+        draw_series(
+            &mut chart,
+            &run.primary,
+            &format!("{} {}", run.id, primary_suffix),
+            color,
+            time_divisor,
+            scale_factor,
+        )?;
+
+        // Secondary series (dashed)
+        draw_dashed_series(
+            &mut chart,
+            &run.secondary,
+            &format!("{} {}", run.id, secondary_suffix),
+            color.mix(0.5),
+            time_divisor,
+            scale_factor,
+        )?;
+    }
+
+    configure_legend(&mut chart)?;
+    root.present()?;
+    println!("Generated: {}", config.output_path.display());
+    Ok(())
+}
+
+fn scale_y_axis(max_value: f64, base_label: &str, y_format: &YAxisFormat) -> (f64, f64, String) {
+    match y_format {
+        YAxisFormat::Bytes => {
+            let (scaled, unit) = format::bytes(max_value);
+            let factor = max_value / scaled;
+            (scaled, factor, format!("{} ({})", base_label, unit))
+        }
+        YAxisFormat::Number => (max_value, 1.0, base_label.to_string()),
+    }
+}
+
+/// Calculate appropriate label count to avoid duplicates when rounding to integers
+fn label_count(max_value: f64) -> usize {
+    let max_int = max_value.ceil() as usize;
+    // Don't exceed the range, cap at 12 for readability
+    max_int.clamp(2, 12)
+}
+
+type Chart<'a, 'b> = ChartContext<
+    'a,
+    SVGBackend<'b>,
+    Cartesian2d<plotters::coord::types::RangedCoordf64, plotters::coord::types::RangedCoordf64>,
+>;
+
+fn configure_mesh(
+    chart: &mut Chart,
+    x_label: &str,
+    y_label: &str,
+    y_format: &YAxisFormat,
+    x_labels: usize,
+) -> Result<()> {
+    let y_formatter: Box<dyn Fn(&f64) -> String> = match y_format {
+        YAxisFormat::Bytes => Box::new(|y: &f64| {
+            if y.fract() == 0.0 {
+                format!("{:.0}", y)
+            } else {
+                format!("{:.1}", y)
+            }
+        }),
+        YAxisFormat::Number => Box::new(|y: &f64| format::axis_number(*y)),
+    };
+
+    chart
+        .configure_mesh()
+        .disable_mesh()
+        .x_desc(x_label)
+        .y_desc(y_label)
+        .x_label_formatter(&|x| format!("{:.0}", x))
+        .y_label_formatter(&y_formatter)
+        .x_labels(x_labels)
+        .y_labels(10)
+        .x_label_style((FONT, FONT_SIZE).into_font().color(&TEXT_COLOR.mix(0.7)))
+        .y_label_style((FONT, FONT_SIZE).into_font().color(&TEXT_COLOR.mix(0.7)))
+        .axis_style(TEXT_COLOR.mix(0.3))
+        .draw()?;
+    Ok(())
+}
+
+fn draw_series(
+    chart: &mut Chart,
+    data: &[DataPoint],
+    label: &str,
+    color: RGBColor,
+    time_divisor: f64,
+    scale_factor: f64,
+) -> Result<()> {
+    let points = data.iter().map(|d| {
+        (
+            d.timestamp_ms as f64 / 1000.0 / time_divisor,
+            d.value / scale_factor,
+        )
+    });
+
+    chart
+        .draw_series(LineSeries::new(points, color.stroke_width(1)))?
+        .label(label)
+        .legend(move |(x, y)| PathElement::new(vec![(x, y), (x + 20, y)], color.stroke_width(1)));
+    Ok(())
+}
+
+fn draw_dashed_series(
+    chart: &mut Chart,
+    data: &[DataPoint],
+    label: &str,
+    color: RGBAColor,
+    time_divisor: f64,
+    scale_factor: f64,
+) -> Result<()> {
+    let points: Vec<_> = data
+        .iter()
+        .map(|d| {
+            (
+                d.timestamp_ms as f64 / 1000.0 / time_divisor,
+                d.value / scale_factor,
+            )
+        })
+        .collect();
+
+    // Draw dashed line by skipping every other segment
+    chart
+        .draw_series(
+            points
+                .windows(2)
+                .enumerate()
+                .filter(|(i, _)| i % 2 == 0)
+                .map(|(_, w)| PathElement::new(vec![w[0], w[1]], color.stroke_width(2))),
+        )?
+        .label(label)
+        .legend(move |(x, y)| {
+            PathElement::new(
+                vec![(x, y), (x + 10, y), (x + 20, y)],
+                color.stroke_width(2),
+            )
+        });
+    Ok(())
+}
+
+fn configure_legend<'a>(chart: &mut Chart<'a, 'a>) -> Result<()> {
+    chart
+        .configure_series_labels()
+        .position(SeriesLabelPosition::UpperLeft)
+        .label_font((FONT, FONT_SIZE).into_font().color(&TEXT_COLOR.mix(0.9)))
+        .background_style(BG_COLOR.mix(0.98))
+        .border_style(BG_COLOR)
+        .margin(10)
+        .draw()?;
+    Ok(())
+}
@@ -0,0 +1,238 @@
+use std::{collections::HashMap, fs, path::Path};
+
+pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
+#[derive(Debug, Clone)]
+pub struct DataPoint {
+    pub timestamp_ms: u64,
+    pub value: f64,
+}
+
+/// Per-run cutoff timestamps for fair comparison
+pub struct Cutoffs {
+    by_id: HashMap<String, u64>,
+    default: u64,
+}
+
+impl Cutoffs {
+    /// Calculate cutoffs from progress runs.
+    /// Finds the common max progress, then returns when each run reached it.
+    pub fn from_progress(progress_runs: &[Run]) -> Self {
+        const TIME_BUFFER_MS: u64 = 10_000;
+
+        if progress_runs.is_empty() {
+            return Self {
+                by_id: HashMap::new(),
+                default: u64::MAX,
+            };
+        }
+
+        // Find the minimum of max progress values (the common point all runs reached)
+        let common_progress = progress_runs
+            .iter()
+            .map(|r| r.max_value())
+            .fold(f64::MAX, f64::min);
+
+        let by_id: HashMap<_, _> = progress_runs
+            .iter()
+            .map(|run| {
+                let cutoff = run
+                    .data
+                    .iter()
+                    .find(|d| d.value >= common_progress)
+                    .map(|d| d.timestamp_ms)
+                    .unwrap_or_else(|| run.max_timestamp())
+                    .saturating_add(TIME_BUFFER_MS);
+                (run.id.clone(), cutoff)
+            })
+            .collect();
+
+        let default = by_id.values().copied().max().unwrap_or(u64::MAX);
+
+        Self { by_id, default }
+    }
+
+    pub fn get(&self, id: &str) -> u64 {
+        self.by_id.get(id).copied().unwrap_or(self.default)
+    }
+
+    pub fn trim_runs(&self, runs: &[Run]) -> Vec<Run> {
+        runs.iter().map(|r| r.trimmed(self.get(&r.id))).collect()
+    }
+
+    pub fn trim_dual_runs(&self, runs: &[DualRun]) -> Vec<DualRun> {
+        runs.iter().map(|r| r.trimmed(self.get(&r.id))).collect()
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct Run {
+    pub id: String,
+    pub data: Vec<DataPoint>,
+}
+
+impl Run {
+    pub fn max_timestamp(&self) -> u64 {
+        self.data.iter().map(|d| d.timestamp_ms).max().unwrap_or(0)
+    }
+
+    pub fn max_value(&self) -> f64 {
+        self.data.iter().map(|d| d.value).fold(0.0, f64::max)
+    }
+
+    pub fn trimmed(&self, max_timestamp_ms: u64) -> Self {
+        Self {
+            id: self.id.clone(),
+            data: self
+                .data
+                .iter()
+                .filter(|d| d.timestamp_ms <= max_timestamp_ms)
+                .cloned()
+                .collect(),
+        }
+    }
+}
+
+/// Two data series from a single run (e.g., memory footprint + peak, or io read + write)
+#[derive(Debug, Clone)]
+pub struct DualRun {
+    pub id: String,
+    pub primary: Vec<DataPoint>,
+    pub secondary: Vec<DataPoint>,
+}
+
+impl DualRun {
+    pub fn trimmed(&self, max_timestamp_ms: u64) -> Self {
+        Self {
+            id: self.id.clone(),
+            primary: self
+                .primary
+                .iter()
+                .filter(|d| d.timestamp_ms <= max_timestamp_ms)
+                .cloned()
+                .collect(),
+            secondary: self
+                .secondary
+                .iter()
+                .filter(|d| d.timestamp_ms <= max_timestamp_ms)
+                .cloned()
+                .collect(),
+        }
+    }
+
+    pub fn max_value(&self) -> f64 {
+        self.primary
+            .iter()
+            .chain(self.secondary.iter())
+            .map(|d| d.value)
+            .fold(0.0, f64::max)
+    }
+}
+
+pub fn read_runs(crate_path: &Path, filename: &str) -> Result<Vec<Run>> {
+    let mut runs = Vec::new();
+
+    for entry in fs::read_dir(crate_path)? {
+        let run_path = entry?.path();
+        if !run_path.is_dir() {
+            continue;
+        }
+
+        let run_id = run_path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .ok_or("Invalid run ID")?
+            .to_string();
+
+        // Skip underscore-prefixed or numeric-only directories
+        if run_id.starts_with('_') || run_id.chars().all(|c| c.is_ascii_digit()) {
+            continue;
+        }
+
+        let csv_path = run_path.join(filename);
+        if csv_path.exists()
+            && let Ok(data) = read_csv(&csv_path)
+        {
+            runs.push(Run { id: run_id, data });
+        }
+    }
+
+    Ok(runs)
+}
+
+pub fn read_dual_runs(crate_path: &Path, filename: &str) -> Result<Vec<DualRun>> {
+    let mut runs = Vec::new();
+
+    for entry in fs::read_dir(crate_path)? {
+        let run_path = entry?.path();
+        if !run_path.is_dir() {
+            continue;
+        }
+
+        let run_id = run_path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .ok_or("Invalid run ID")?
+            .to_string();
+
+        if run_id.starts_with('_') || run_id.chars().all(|c| c.is_ascii_digit()) {
+            continue;
+        }
+
+        let csv_path = run_path.join(filename);
+        if csv_path.exists()
+            && let Ok((primary, secondary)) = read_dual_csv(&csv_path)
+        {
+            runs.push(DualRun {
+                id: run_id,
+                primary,
+                secondary,
+            });
+        }
+    }
+
+    Ok(runs)
+}
+
+fn read_csv(path: &Path) -> Result<Vec<DataPoint>> {
+    let content = fs::read_to_string(path)?;
+    let data = content
+        .lines()
+        .skip(1) // header
+        .filter_map(|line| {
+            let mut parts = line.split(',');
+            let timestamp_ms = parts.next()?.parse().ok()?;
+            let value = parts.next()?.parse().ok()?;
+            Some(DataPoint {
+                timestamp_ms,
+                value,
+            })
+        })
+        .collect();
+    Ok(data)
+}
+
+fn read_dual_csv(path: &Path) -> Result<(Vec<DataPoint>, Vec<DataPoint>)> {
+    let content = fs::read_to_string(path)?;
+    let mut primary = Vec::new();
+    let mut secondary = Vec::new();
+
+    for line in content.lines().skip(1) {
+        let mut parts = line.split(',');
+        if let (Some(ts), Some(v1), Some(v2)) = (parts.next(), parts.next(), parts.next())
+            && let (Ok(timestamp_ms), Ok(val1), Ok(val2)) =
+                (ts.parse(), v1.parse::<f64>(), v2.parse::<f64>())
+        {
+            primary.push(DataPoint {
+                timestamp_ms,
+                value: val1,
+            });
+            secondary.push(DataPoint {
+                timestamp_ms,
+                value: val2,
+            });
+        }
+    }
+
+    Ok((primary, secondary))
+}
@@ -0,0 +1,45 @@
+const KIB: f64 = 1024.0;
+const MIB: f64 = KIB * 1024.0;
+const GIB: f64 = MIB * 1024.0;
+
+const MINUTE: f64 = 60.0;
+const HOUR: f64 = 3600.0;
+
+/// Returns (scaled_value, unit_suffix)
+pub fn bytes(bytes: f64) -> (f64, &'static str) {
+    if bytes >= GIB {
+        (bytes / GIB, "GiB")
+    } else if bytes >= MIB {
+        (bytes / MIB, "MiB")
+    } else if bytes >= KIB {
+        (bytes / KIB, "KiB")
+    } else {
+        (bytes, "bytes")
+    }
+}
+
+/// Returns (scaled_value, divisor, axis_label)
+pub fn time(seconds: f64) -> (f64, f64, &'static str) {
+    if seconds >= HOUR * 2.0 {
+        (seconds / HOUR, HOUR, "Time (h)")
+    } else if seconds >= MINUTE * 2.0 {
+        (seconds / MINUTE, MINUTE, "Time (min)")
+    } else {
+        (seconds, 1.0, "Time (s)")
+    }
+}
+
+pub fn axis_number(value: f64) -> String {
+    if value >= 1000.0 {
+        let k = value / 1000.0;
+        if k.fract() == 0.0 || k >= 100.0 {
+            format!("{:.0}k", k)
+        } else if k >= 10.0 {
+            format!("{:.1}k", k)
+        } else {
+            format!("{:.2}k", k)
+        }
+    } else {
+        format!("{:.0}", value)
+    }
+}
@@ -0,0 +1,262 @@
+mod chart;
+mod data;
+mod format;
+
+use data::{Cutoffs, DualRun, Result, Run, read_dual_runs, read_runs};
+use std::{
+    fs,
+    path::{Path, PathBuf},
+};
+
+pub struct Visualizer {
+    workspace_root: PathBuf,
+}
+
+impl Visualizer {
+    pub fn new(workspace_root: impl AsRef<Path>) -> Self {
+        Self {
+            workspace_root: workspace_root.as_ref().to_path_buf(),
+        }
+    }
+
+    pub fn from_cargo_env() -> Result<Self> {
+        let workspace_root = Path::new(env!("CARGO_MANIFEST_DIR"))
+            .parent()
+            .and_then(|p| p.parent())
+            .ok_or("Failed to find workspace root")?
+            .to_path_buf();
+        Ok(Self { workspace_root })
+    }
+
+    pub fn generate_all_charts(&self) -> Result<()> {
+        let benches_dir = self.workspace_root.join("benches");
+        if !benches_dir.exists() {
+            return Err("Benches directory does not exist".into());
+        }
+
+        for entry in fs::read_dir(&benches_dir)? {
+            let path = entry?.path();
+            if path.is_dir() {
+                let crate_name = path
+                    .file_name()
+                    .and_then(|n| n.to_str())
+                    .ok_or("Invalid crate name")?;
+
+                println!("Generating charts for crate: {}", crate_name);
+                self.generate_crate_charts(&path, crate_name)?;
+            }
+        }
+
+        Ok(())
+    }
+
+    fn generate_crate_charts(&self, crate_path: &Path, crate_name: &str) -> Result<()> {
+        let disk_runs = read_runs(crate_path, "disk.csv")?;
+        let memory_runs = read_dual_runs(crate_path, "memory.csv")?;
+        let progress_runs = read_runs(crate_path, "progress.csv")?;
+        let io_runs = read_dual_runs(crate_path, "io.csv")?;
+
+        // Combined charts (all runs)
+        self.generate_combined_charts(
+            crate_path,
+            crate_name,
+            &disk_runs,
+            &memory_runs,
+            &progress_runs,
+            &io_runs,
+        )?;
+
+        // Individual charts (one per run)
+        self.generate_individual_charts(
+            crate_path,
+            crate_name,
+            &disk_runs,
+            &memory_runs,
+            &progress_runs,
+            &io_runs,
+        )?;
+
+        Ok(())
+    }
+
+    fn generate_combined_charts(
+        &self,
+        crate_path: &Path,
+        crate_name: &str,
+        disk_runs: &[Run],
+        memory_runs: &[DualRun],
+        progress_runs: &[Run],
+        io_runs: &[DualRun],
+    ) -> Result<()> {
+        let cutoffs = Cutoffs::from_progress(progress_runs);
+
+        // Trim data to per-run cutoffs for fair comparison
+        let disk_trimmed = cutoffs.trim_runs(disk_runs);
+        let memory_trimmed = cutoffs.trim_dual_runs(memory_runs);
+        let io_trimmed = cutoffs.trim_dual_runs(io_runs);
+
+        if !disk_trimmed.is_empty() {
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &crate_path.join("disk.svg"),
+                    title: format!("{} — Disk Usage", crate_name),
+                    y_label: "Disk Usage".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                &disk_trimmed,
+            )?;
+        }
+
+        if !memory_trimmed.is_empty() {
+            chart::generate_dual(
+                chart::ChartConfig {
+                    output_path: &crate_path.join("memory.svg"),
+                    title: format!("{} — Memory", crate_name),
+                    y_label: "Memory".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                &memory_trimmed,
+                "(current)",
+                "(peak)",
+            )?;
+        }
+
+        if !progress_runs.is_empty() {
+            let progress_trimmed = cutoffs.trim_runs(progress_runs);
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &crate_path.join("progress.svg"),
+                    title: format!("{} — Progress", crate_name),
+                    y_label: "Progress".to_string(),
+                    y_format: chart::YAxisFormat::Number,
+                },
+                &progress_trimmed,
+            )?;
+        }
+
+        if !io_trimmed.is_empty() {
+            // I/O Read (primary column)
+            let io_read: Vec<_> = io_trimmed
+                .iter()
+                .map(|r| Run {
+                    id: r.id.clone(),
+                    data: r.primary.clone(),
+                })
+                .collect();
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &crate_path.join("io_read.svg"),
+                    title: format!("{} — I/O Read", crate_name),
+                    y_label: "Bytes Read".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                &io_read,
+            )?;
+
+            // I/O Write (secondary column)
+            let io_write: Vec<_> = io_trimmed
+                .iter()
+                .map(|r| Run {
+                    id: r.id.clone(),
+                    data: r.secondary.clone(),
+                })
+                .collect();
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &crate_path.join("io_write.svg"),
+                    title: format!("{} — I/O Write", crate_name),
+                    y_label: "Bytes Written".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                &io_write,
+            )?;
+        }
+
+        Ok(())
+    }
+
+    fn generate_individual_charts(
+        &self,
+        crate_path: &Path,
+        crate_name: &str,
+        disk_runs: &[Run],
+        memory_runs: &[DualRun],
+        progress_runs: &[Run],
+        io_runs: &[DualRun],
+    ) -> Result<()> {
+        for run in disk_runs {
+            let run_path = crate_path.join(&run.id);
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &run_path.join("disk.svg"),
+                    title: format!("{} — Disk Usage", crate_name),
+                    y_label: "Disk Usage".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                std::slice::from_ref(run),
+            )?;
+        }
+
+        for run in memory_runs {
+            let run_path = crate_path.join(&run.id);
+            chart::generate_dual(
+                chart::ChartConfig {
+                    output_path: &run_path.join("memory.svg"),
+                    title: format!("{} — Memory", crate_name),
+                    y_label: "Memory".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                std::slice::from_ref(run),
+                "(current)",
+                "(peak)",
+            )?;
+        }
+
+        for run in progress_runs {
+            let run_path = crate_path.join(&run.id);
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &run_path.join("progress.svg"),
+                    title: format!("{} — Progress", crate_name),
+                    y_label: "Progress".to_string(),
+                    y_format: chart::YAxisFormat::Number,
+                },
+                std::slice::from_ref(run),
+            )?;
+        }
+
+        for run in io_runs {
+            let run_path = crate_path.join(&run.id);
+
+            let read_run = Run {
+                id: run.id.clone(),
+                data: run.primary.clone(),
+            };
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &run_path.join("io_read.svg"),
+                    title: format!("{} — I/O Read", crate_name),
+                    y_label: "Bytes Read".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                std::slice::from_ref(&read_run),
+            )?;
+
+            let write_run = Run {
+                id: run.id.clone(),
+                data: run.secondary.clone(),
+            };
+            chart::generate(
+                chart::ChartConfig {
+                    output_path: &run_path.join("io_write.svg"),
+                    title: format!("{} — I/O Write", crate_name),
+                    y_label: "Bytes Written".to_string(),
+                    y_format: chart::YAxisFormat::Bytes,
+                },
+                std::slice::from_ref(&write_run),
+            )?;
+        }
+
+        Ok(())
+    }
+}
@@ -0,0 +1,6 @@
+use brk_bencher_visualizer::Visualizer;
+
+fn main() {
+    let v = Visualizer::from_cargo_env().unwrap();
+    v.generate_all_charts().unwrap();
+}
@@ -1,14 +0,0 @@
-[package]
-name = "brk_binder"
-description = "A generator of binding files for other languages"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-homepage.workspace = true
-repository.workspace = true
-rust-version.workspace = true
-build = "build.rs"
-
-[dependencies]
-brk_interface = { workspace = true }
-brk_structs = { workspace = true }
@@ -1 +0,0 @@
-# brk_binder
@@ -1,8 +0,0 @@
-fn main() {
-    let profile = std::env::var("PROFILE").unwrap_or_default();
-
-    if profile == "release" {
-        println!("cargo:rustc-flag=-C");
-        println!("cargo:rustc-flag=target-cpu=native");
-    }
-}
@@ -1,250 +0,0 @@
-use std::{
-    collections::{BTreeMap, HashMap},
-    fs, io,
-    path::Path,
-};
-
-use brk_interface::{Index, Interface};
-use brk_structs::pools;
-
-use super::VERSION;
-
-const AUTO_GENERATED_DISCLAIMER: &str = "//
-// File auto-generated, any modifications will be overwritten
-//";
-
-#[allow(clippy::upper_case_acronyms)]
-pub trait Bridge {
-    fn generate_js_files(&self, modules_path: &Path) -> io::Result<()>;
-}
-
-impl Bridge for Interface<'static> {
-    fn generate_js_files(&self, modules_path: &Path) -> io::Result<()> {
-        let path = modules_path.join("brk-client");
-
-        if !fs::exists(&path)? {
-            return Ok(());
-        }
-
-        let path = path.join("generated");
-        fs::create_dir_all(&path)?;
-
-        generate_version_file(&path)?;
-        generate_metrics_file(self, &path)?;
-        generate_pools_file(&path)
-    }
-}
-
-fn generate_version_file(parent: &Path) -> io::Result<()> {
-    let path = parent.join(Path::new("version.js"));
-
-    let contents = format!(
-        "{AUTO_GENERATED_DISCLAIMER}
-
-export const VERSION = \"v{VERSION}\";
-"
-    );
-
-    fs::write(path, contents)
-}
-
-fn generate_pools_file(parent: &Path) -> io::Result<()> {
-    let path = parent.join(Path::new("pools.js"));
-
-    let pools = pools();
-
-    let mut contents = format!("{AUTO_GENERATED_DISCLAIMER}\n");
-
-    contents += "
-/**
- * @typedef {typeof POOL_ID_TO_POOL_NAME} PoolIdToPoolName
- * @typedef {keyof PoolIdToPoolName} PoolId
- */
-
-export const POOL_ID_TO_POOL_NAME = /** @type {const} */ ({
-";
-
-    let mut sorted_pools: Vec<_> = pools.iter().collect();
-    sorted_pools.sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase()));
-
-    contents += &sorted_pools
-        .iter()
-        .map(|pool| {
-            let id = pool.serialized_id();
-            format!("  {id}: \"{}\",", pool.name)
-        })
-        .collect::<Vec<_>>()
-        .join("\n");
-
-    contents += "\n});\n";
-
-    fs::write(path, contents)
-}
-
-fn generate_metrics_file(interface: &Interface<'static>, parent: &Path) -> io::Result<()> {
-    let path = parent.join(Path::new("metrics.js"));
-
-    let indexes = Index::all();
-
-    let mut contents = format!(
-        "{AUTO_GENERATED_DISCLAIMER}
-
-export const INDEXES = /** @type {{const}} */ ([
-{}
-]);
-
-/**
- * @typedef {{typeof INDEXES[number]}} IndexName
- */
-",
-        indexes
-            .iter()
-            .map(|i| format!("  \"{}\"", i.serialize_long()))
-            .collect::<Vec<_>>()
-            .join(",\n")
-    );
-
-    // contents += &indexes
-    //     .iter()
-    //     .map(|i| format!(" * @typedef {{\"{}\"}} {i}", i.serialize_long()))
-    //     .collect::<Vec<_>>()
-    //     .join("\n");
-
-    //     contents += &format!(
-    //         "
-    //  * @typedef {{{}}} Index
-    //  */
-    // ",
-    //         indexes
-    //             .iter()
-    //             .map(|i| i.to_string())
-    //             .collect::<Vec<_>>()
-    //             .join(" | ")
-    //     );
-
-    let mut unique_index_groups = BTreeMap::new();
-
-    let mut word_to_freq: BTreeMap<_, usize> = BTreeMap::new();
-    interface
-        .metric_to_index_to_vec()
-        .keys()
-        .for_each(|metric| {
-            metric.split("_").for_each(|word| {
-                *word_to_freq.entry(word).or_default() += 1;
-            });
-        });
-    let mut word_to_freq = word_to_freq.into_iter().collect::<Vec<_>>();
-    word_to_freq.sort_unstable_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(b.0)));
-    let words = word_to_freq
-        .into_iter()
-        .map(|(str, _)| str)
-        .collect::<Vec<_>>();
-
-    contents += &format!(
-        "
-export const INDEX_TO_WORD = [
-  {}
-];
-
-",
-        words
-            .iter()
-            .enumerate()
-            .map(|(index, word)| format!("\"{word}\", // {}", index_to_letters(index)))
-            .collect::<Vec<_>>()
-            .join("\n  ")
-    );
-
-    let word_to_base62 = words
-        .into_iter()
-        .enumerate()
-        .map(|(i, w)| (w, index_to_letters(i)))
-        .collect::<HashMap<_, _>>();
-
-    let mut ser_metric_to_indexes = "
-/** @type {Record<string, IndexName[]>} */
-export const COMPRESSED_METRIC_TO_INDEXES = {
-"
-    .to_string();
-
-    interface
-        .metric_to_index_to_vec()
-        .iter()
-        .for_each(|(metric, index_to_vec)| {
-            let indexes = index_to_vec
-                .keys()
-                .map(|i| format!("\"{}\"", i.serialize_long()))
-                .collect::<Vec<_>>()
-                .join(", ");
-            let indexes = format!("[{indexes}]");
-            let unique = unique_index_groups.len();
-            let index = index_to_letters(*unique_index_groups.entry(indexes).or_insert(unique));
-
-            let compressed_metric = metric.split('_').fold(String::new(), |mut acc, w| {
-                if !acc.is_empty() {
-                    acc.push('_');
-                }
-                acc.push_str(&word_to_base62[w]);
-                acc
-            });
-
-            ser_metric_to_indexes += &format!("  {compressed_metric}: {index},\n");
-        });
-
-    ser_metric_to_indexes += "};
-";
-
-    let mut sorted_groups: Vec<_> = unique_index_groups.into_iter().collect();
-    sorted_groups.sort_by_key(|(_, index)| *index);
-    sorted_groups.into_iter().for_each(|(group, index)| {
-        let index = index_to_letters(index);
-        contents += &format!("/** @type {{IndexName[]}} */\nconst {index} = {group};\n");
-    });
-
-    contents += &ser_metric_to_indexes;
-
-    fs::write(path, contents)
-}
-
-fn index_to_letters(mut index: usize) -> String {
-    if index < 52 {
-        return (index_to_char(index) as char).to_string();
-    }
-    let mut result = [0u8; 8];
-    let mut pos = 8;
-    loop {
-        pos -= 1;
-        result[pos] = index_to_char(index % 52);
-        index /= 52;
-        if index == 0 {
-            break;
-        }
-        index -= 1;
-    }
-    unsafe { String::from_utf8_unchecked(result[pos..].to_vec()) }
-}
-
-fn index_to_char(index: usize) -> u8 {
-    match index {
-        0..=25 => b'A' + index as u8,
-        26..=51 => b'a' + (index - 26) as u8,
-        _ => unreachable!(),
-    }
-}
-
-// fn letters_to_index(s: &str) -> usize {
-//     let mut result = 0;
-//     for byte in s.bytes() {
-//         let value = char_to_index(byte) as usize;
-//         result = result * 52 + value + 1;
-//     }
-//     result - 1
-// }
-
-// fn char_to_index(byte: u8) -> u8 {
-//     match byte {
-//         b'A'..=b'Z' => byte - b'A',
-//         b'a'..=b'z' => byte - b'a' + 26,
-//         _ => 255, // Invalid
-//     }
-// }
@@ -1,5 +0,0 @@
-mod js;
-
-pub use js::Bridge;
-
-pub const VERSION: &str = env!("CARGO_PKG_VERSION");
@@ -1 +0,0 @@
-// TODO ?
@@ -0,0 +1,6 @@
+clients/
+/*.json
+/*.js
+/*.rs
+/*.py
+tests/output/
@@ -0,0 +1,17 @@
+[package]
+name = "brk_bindgen"
+description = "A trait-based generator of client bindings for multiple languages"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[dependencies]
+brk_cohort = { workspace = true }
+brk_query = { workspace = true }
+brk_types = { workspace = true }
+indexmap = { workspace = true }
+oas3 = "0.21"
+serde = { workspace = true }
+serde_json = { workspace = true }
@@ -0,0 +1,46 @@
+# brk_bindgen
+
+Code generation for BRK client libraries.
+
+## What It Enables
+
+Generate typed client libraries for Rust, JavaScript, and Python from the OpenAPI specification. Keeps frontend code in sync with available metrics and API endpoints without manual maintenance.
+
+## Key Features
+
+- **Multi-language**: Generates Rust, JavaScript, and Python clients
+- **OpenAPI-driven**: Extracts endpoints and schemas from the OpenAPI spec
+- **Metric catalog**: Includes all metric IDs and their supported indexes
+- **Type definitions**: Generates types/interfaces from JSON Schema
+- **Selective output**: Generate only the languages you need
+
+## Core API
+
+```rust,ignore
+use brk_bindgen::{generate_clients, ClientOutputPaths};
+
+let paths = ClientOutputPaths::new()
+    .rust("crates/brk_client/src/lib.rs")
+    .javascript("modules/brk-client/index.js")
+    .python("packages/brk_client/brk_client/__init__.py");
+
+generate_clients(&vecs, &openapi_json, &paths)?;
+```
+
+## Generated Clients
+
+| Language | Contents |
+|----------|----------|
+| Rust | Typed API client using `brk_types`, metric catalog |
+| JavaScript | ES module with JSDoc types, metric catalog, fetch helpers |
+| Python | Typed client with dataclasses, metric catalog |
+
+Each client includes:
+- All REST API endpoints as typed functions
+- Complete metric catalog with index information
+- Type definitions for request/response schemas
+
+## Built On
+
+- `brk_query` for metric enumeration
+- `brk_types` for type schemas
@@ -0,0 +1,14 @@
+//! Analysis module for name deconstruction and pattern detection.
+//!
+//! This module implements bottom-up analysis of vec names to detect
+//! common denominators (prefixes/suffixes) and field positions.
+
+mod names;
+mod patterns;
+mod positions;
+mod tree;
+
+pub use names::*;
+pub use patterns::*;
+pub use positions::*;
+pub use tree::*;
@@ -0,0 +1,198 @@
+//! Common prefix/suffix detection for series names.
+//!
+//! This module provides utilities to find common prefixes and suffixes
+//! among series names, which is used to detect pattern mode (suffix vs prefix).
+
+/// Find the longest common prefix among all strings.
+/// Returns the prefix WITH trailing underscore if found at word boundary.
+/// Returns None if no common prefix exists.
+pub fn find_common_prefix(names: &[&str]) -> Option<String> {
+    if names.is_empty() || names.iter().any(|n| n.is_empty()) {
+        return None;
+    }
+
+    let first = names[0];
+
+    // Find character-by-character common prefix
+    let mut prefix_len = 0;
+    for (i, ch) in first.chars().enumerate() {
+        if names.iter().all(|n| n.chars().nth(i) == Some(ch)) {
+            prefix_len = i + 1;
+        } else {
+            break;
+        }
+    }
+
+    if prefix_len == 0 {
+        return None;
+    }
+
+    let raw_prefix = &first[..prefix_len];
+
+    // Must end at underscore boundary for semantic coherence
+    if raw_prefix.ends_with('_') {
+        return Some(raw_prefix.to_string());
+    }
+
+    // If raw_prefix equals one of the full names (one name is a prefix of all others),
+    // return it with trailing underscore for proper base detection
+    if names.contains(&raw_prefix) {
+        return Some(format!("{}_", raw_prefix));
+    }
+
+    // Find the last underscore position
+    if let Some(last_underscore) = raw_prefix.rfind('_') {
+        let clean_prefix = &first[..=last_underscore];
+        if names.iter().all(|n| n.starts_with(clean_prefix)) {
+            return Some(clean_prefix.to_string());
+        }
+    }
+
+    None
+}
+
+/// Find the longest common suffix among all strings.
+/// Returns the suffix WITH leading underscore if found at word boundary.
+/// Returns None if no common suffix exists.
+pub fn find_common_suffix(names: &[&str]) -> Option<String> {
+    if names.is_empty() || names.iter().any(|n| n.is_empty()) {
+        return None;
+    }
+
+    let first = names[0];
+    let first_chars: Vec<char> = first.chars().collect();
+
+    // Find character-by-character common suffix (from the end)
+    let mut suffix_len = 0;
+    for i in 0..first_chars.len() {
+        let idx_from_end = first_chars.len() - 1 - i;
+        let ch = first_chars[idx_from_end];
+
+        let all_match = names.iter().all(|n| {
+            let n_chars: Vec<char> = n.chars().collect();
+            if i >= n_chars.len() {
+                return false;
+            }
+            n_chars[n_chars.len() - 1 - i] == ch
+        });
+
+        if all_match {
+            suffix_len = i + 1;
+        } else {
+            break;
+        }
+    }
+
+    if suffix_len == 0 {
+        return None;
+    }
+
+    let raw_suffix = &first[first.len() - suffix_len..];
+
+    // Must start at underscore boundary for semantic coherence
+    if raw_suffix.starts_with('_') {
+        return Some(raw_suffix.to_string());
+    }
+
+    // Check if preceded by underscore in all names (word boundary)
+    let at_word_boundary = names.iter().all(|n| {
+        if *n == raw_suffix {
+            true // Suffix is the whole string
+        } else if let Some(prefix) = n.strip_suffix(raw_suffix) {
+            prefix.ends_with('_')
+        } else {
+            false
+        }
+    });
+
+    if at_word_boundary {
+        return Some(format!("_{}", raw_suffix));
+    }
+
+    // Find the first underscore position in suffix
+    if let Some(first_underscore) = raw_suffix.find('_') {
+        let clean_suffix = &raw_suffix[first_underscore..];
+        if names.iter().all(|n| n.ends_with(clean_suffix)) {
+            return Some(clean_suffix.to_string());
+        }
+    }
+
+    None
+}
+
+/// Normalize a prefix string by ensuring it ends with underscore.
+/// Returns empty string if input is empty.
+pub fn normalize_prefix(s: &str) -> String {
+    if s.is_empty() {
+        String::new()
+    } else if s.ends_with('_') {
+        s.to_string()
+    } else {
+        format!("{}_", s)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_common_prefix_basic() {
+        let names = vec!["addrs_0sats", "addrs_1sats", "addrs_2sats"];
+        assert_eq!(find_common_prefix(&names), Some("addrs_".to_string()));
+    }
+
+    #[test]
+    fn test_common_prefix_none() {
+        let names = vec!["foo", "bar", "baz"];
+        assert_eq!(find_common_prefix(&names), None);
+    }
+
+    #[test]
+    fn test_common_prefix_lth() {
+        let names = vec!["lth_cost_basis_max", "lth_cost_basis_min", "lth_cost_basis"];
+        assert_eq!(
+            find_common_prefix(&names),
+            Some("lth_cost_basis_".to_string())
+        );
+    }
+
+    #[test]
+    fn test_common_suffix_basic() {
+        let names = vec!["cumulative_supply", "net_supply", "total_supply"];
+        assert_eq!(find_common_suffix(&names), Some("_supply".to_string()));
+    }
+
+    #[test]
+    fn test_common_prefix_cost_basis() {
+        // With suffix naming convention, cost_basis variants share a common prefix
+        let names = vec!["cost_basis_max", "cost_basis_min", "cost_basis"];
+        assert_eq!(find_common_prefix(&names), Some("cost_basis_".to_string()));
+    }
+
+    #[test]
+    fn test_common_suffix_none() {
+        let names = vec!["foo", "bar", "baz"];
+        assert_eq!(find_common_suffix(&names), None);
+    }
+
+    #[test]
+    fn test_common_prefix_one_is_prefix_of_other() {
+        // When one name is a prefix of another (block_count vs block_count_cumulative)
+        let names = vec!["block_count_cumulative", "block_count"];
+        assert_eq!(find_common_prefix(&names), Some("block_count_".to_string()));
+    }
+
+    #[test]
+    fn test_common_suffix_realized_loss() {
+        let names = vec![
+            "cumulative_realized_loss",
+            "net_realized_loss",
+            "realized_loss",
+        ];
+        assert_eq!(
+            find_common_suffix(&names),
+            Some("_realized_loss".to_string())
+        );
+    }
+}
@@ -0,0 +1,379 @@
+//! Structural pattern detection using bottom-up analysis.
+//!
+//! This module detects repeating tree structures and analyzes them
+//! using the bottom-up name deconstruction algorithm.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use brk_types::{TreeNode, extract_json_type};
+
+use super::analyze_pattern_modes;
+use crate::{PatternBaseResult, PatternField, StructuralPattern, to_pascal_case};
+
+/// Context for pattern detection, holding all intermediate state.
+struct PatternContext {
+    /// Maps field signatures to pattern names
+    signature_to_pattern: BTreeMap<Vec<PatternField>, String>,
+    /// Counts how many times each signature appears
+    signature_counts: BTreeMap<Vec<PatternField>, usize>,
+    /// Maps normalized signatures to pattern names (for naming consistency)
+    normalized_to_name: BTreeMap<Vec<PatternField>, String>,
+    /// Counts pattern name usage (for unique naming)
+    name_counts: BTreeMap<String, usize>,
+    /// Maps signatures to their child field lists
+    signature_to_child_fields: BTreeMap<Vec<PatternField>, Vec<Vec<PatternField>>>,
+}
+
+impl PatternContext {
+    fn new() -> Self {
+        Self {
+            signature_to_pattern: BTreeMap::new(),
+            signature_counts: BTreeMap::new(),
+            normalized_to_name: BTreeMap::new(),
+            name_counts: BTreeMap::new(),
+            signature_to_child_fields: BTreeMap::new(),
+        }
+    }
+}
+
+/// Detect structural patterns in the tree using a bottom-up approach.
+///
+/// Returns (patterns, concrete_to_pattern, concrete_to_type_param, node_bases).
+/// Each pattern has its `mode` set based on analysis of all instances.
+/// `node_bases` maps tree paths to their computed PatternBaseResult for use during generation.
+pub fn detect_structural_patterns(
+    tree: &TreeNode,
+) -> (
+    Vec<StructuralPattern>,
+    BTreeMap<Vec<PatternField>, String>,
+    BTreeMap<Vec<PatternField>, String>,
+    BTreeMap<String, PatternBaseResult>,
+) {
+    let mut ctx = PatternContext::new();
+    resolve_branch_patterns(tree, &mut ctx);
+
+    let (generic_patterns, generic_mappings, type_mappings) =
+        detect_generic_patterns(&ctx.signature_to_pattern);
+
+    // Only include patterns that appear 2+ times for the patterns list
+    let mut patterns: Vec<StructuralPattern> = ctx
+        .signature_to_pattern
+        .iter()
+        .filter(|(sig, _)| {
+            ctx.signature_counts.get(*sig).copied().unwrap_or(0) >= 2
+                && !generic_mappings.contains_key(*sig)
+        })
+        .map(|(fields, name)| {
+            let child_fields_list = ctx.signature_to_child_fields.get(fields);
+            let fields_with_type_params = fields
+                .iter()
+                .enumerate()
+                .map(|(i, f)| {
+                    let type_param = child_fields_list
+                        .and_then(|list| list.get(i))
+                        .and_then(|cf| type_mappings.get(cf).cloned());
+                    PatternField {
+                        type_param,
+                        ..f.clone()
+                    }
+                })
+                .collect();
+            StructuralPattern {
+                name: name.clone(),
+                fields: fields_with_type_params,
+                mode: None, // Will be determined by analyze_pattern_modes
+                is_generic: false,
+            }
+        })
+        .collect();
+
+    // Deduplicate patterns by name - different signatures can map to the same name
+    // when their normalized forms match but they can't be unified as generics
+    {
+        let mut seen_names: BTreeSet<String> = BTreeSet::new();
+        patterns.retain(|p| seen_names.insert(p.name.clone()));
+    }
+
+    patterns.extend(generic_patterns);
+
+    // Build pattern lookup for mode analysis (patterns appearing 2+ times)
+    let mut pattern_lookup: BTreeMap<Vec<PatternField>, String> = BTreeMap::new();
+    for (sig, name) in &ctx.signature_to_pattern {
+        if ctx.signature_counts.get(sig).copied().unwrap_or(0) >= 2 {
+            pattern_lookup.insert(sig.clone(), name.clone());
+        }
+    }
+    pattern_lookup.extend(generic_mappings.clone());
+
+    let concrete_to_pattern = pattern_lookup.clone();
+
+    // Analyze pattern modes (suffix vs prefix) from all instances
+    // Also collects node bases for each tree path
+    let node_bases = analyze_pattern_modes(tree, &mut patterns, &pattern_lookup);
+
+    patterns.sort_by(|a, b| b.fields.len().cmp(&a.fields.len()));
+    (patterns, concrete_to_pattern, type_mappings, node_bases)
+}
+
+/// Detect generic patterns by grouping signatures by their normalized form.
+fn detect_generic_patterns(
+    signature_to_pattern: &BTreeMap<Vec<PatternField>, String>,
+) -> (
+    Vec<StructuralPattern>,
+    BTreeMap<Vec<PatternField>, String>,
+    BTreeMap<Vec<PatternField>, String>,
+) {
+    let mut normalized_groups: BTreeMap<
+        Vec<PatternField>,
+        Vec<(Vec<PatternField>, String, String)>,
+    > = BTreeMap::new();
+
+    for (fields, name) in signature_to_pattern {
+        if let Some((normalized, extracted_type)) = normalize_fields_for_generic(fields) {
+            normalized_groups.entry(normalized).or_default().push((
+                fields.clone(),
+                name.clone(),
+                extracted_type,
+            ));
+        }
+    }
+
+    let mut patterns = Vec::new();
+    let mut pattern_mappings: BTreeMap<Vec<PatternField>, String> = BTreeMap::new();
+    let mut type_mappings: BTreeMap<Vec<PatternField>, String> = BTreeMap::new();
+
+    for (normalized_fields, group) in normalized_groups {
+        if group.len() >= 2 {
+            let generic_name = group[0].1.clone();
+            for (concrete_fields, _, extracted_type) in &group {
+                pattern_mappings.insert(concrete_fields.clone(), generic_name.clone());
+                type_mappings.insert(concrete_fields.clone(), extracted_type.clone());
+            }
+            patterns.push(StructuralPattern {
+                name: generic_name,
+                fields: normalized_fields,
+                mode: None, // Will be determined by analyze_pattern_modes
+                is_generic: true,
+            });
+        }
+    }
+
+    (patterns, pattern_mappings, type_mappings)
+}
+
+/// Normalize fields by replacing concrete value types with "T".
+///
+/// Handles two cases:
+/// 1. All leaves have identical types (e.g., all `Sats`) -> normalize to `T`
+/// 2. All leaves have wrapper types with the same inner type (e.g., `Open<Sats>`, `High<Sats>`)
+///    -> normalize to `Open<T>`, `High<T>`, etc.
+fn normalize_fields_for_generic(fields: &[PatternField]) -> Option<(Vec<PatternField>, String)> {
+    let leaf_types: Vec<&str> = fields
+        .iter()
+        .filter(|f| f.is_leaf())
+        .map(|f| f.rust_type.as_str())
+        .collect();
+
+    if leaf_types.is_empty() {
+        return None;
+    }
+
+    let first_type = leaf_types[0];
+
+    // Case 1: All leaf types are identical
+    if leaf_types.iter().all(|t| *t == first_type) {
+        let normalized = fields
+            .iter()
+            .map(|f| {
+                if f.is_branch() {
+                    f.clone()
+                } else {
+                    PatternField {
+                        name: f.name.clone(),
+                        rust_type: "T".to_string(),
+                        json_type: "T".to_string(),
+                        indexes: f.indexes.clone(),
+                        type_param: None,
+                    }
+                }
+            })
+            .collect();
+        return Some((normalized, crate::extract_inner_type(first_type)));
+    }
+
+    // Case 2: Check if all leaves have wrapper types with the same inner type
+    // e.g., Open<Sats>, High<Sats>, Low<Sats>, Close<Sats> all have inner type Sats
+    let inner_types: Vec<String> = leaf_types
+        .iter()
+        .map(|t| crate::extract_inner_type(t))
+        .collect();
+
+    let first_inner = &inner_types[0];
+
+    // Only proceed if inner types differ from originals (meaning they had wrappers)
+    // and all inner types are the same
+    if inner_types.iter().all(|t| t == first_inner)
+        && inner_types
+            .iter()
+            .zip(leaf_types.iter())
+            .any(|(inner, orig)| inner != *orig)
+    {
+        let normalized = fields
+            .iter()
+            .map(|f| {
+                if f.is_branch() {
+                    f.clone()
+                } else {
+                    PatternField {
+                        name: f.name.clone(),
+                        rust_type: replace_inner_type(&f.rust_type, "T"),
+                        json_type: replace_inner_type(&f.json_type, "T"),
+                        indexes: f.indexes.clone(),
+                        type_param: None,
+                    }
+                }
+            })
+            .collect();
+        return Some((normalized, first_inner.clone()));
+    }
+
+    None
+}
+
+/// Replace the inner type of a wrapper generic with a new type.
+/// e.g., `Open<Sats>` with replacement `T` -> `Open<T>`
+fn replace_inner_type(type_str: &str, replacement: &str) -> String {
+    if let Some(start) = type_str.find('<')
+        && let Some(end) = type_str.rfind('>')
+        && start < end
+    {
+        format!("{}<{}>", &type_str[..start], replacement)
+    } else {
+        replacement.to_string()
+    }
+}
+
+/// Recursively resolve branch patterns bottom-up.
+fn resolve_branch_patterns(
+    node: &TreeNode,
+    ctx: &mut PatternContext,
+) -> Option<(String, Vec<PatternField>)> {
+    let TreeNode::Branch(children) = node else {
+        return None;
+    };
+
+    // Convert to sorted BTreeMap for consistent pattern detection
+    let sorted_children: BTreeMap<_, _> = children.iter().collect();
+
+    let mut fields: Vec<PatternField> = Vec::new();
+    let mut child_fields_vec: Vec<Vec<PatternField>> = Vec::new();
+
+    for (child_name, child_node) in sorted_children {
+        let (rust_type, json_type, indexes, child_fields) = match child_node {
+            TreeNode::Leaf(leaf) => (
+                leaf.kind().to_string(),
+                extract_json_type(&leaf.schema),
+                leaf.indexes().clone(),
+                Vec::new(),
+            ),
+            TreeNode::Branch(_) => {
+                let (pattern_name, child_pattern_fields) = resolve_branch_patterns(child_node, ctx)
+                    .unwrap_or_else(|| ("Unknown".to_string(), Vec::new()));
+                (
+                    pattern_name.clone(),
+                    pattern_name,
+                    BTreeSet::new(),
+                    child_pattern_fields,
+                )
+            }
+        };
+        fields.push(PatternField {
+            name: child_name.clone(),
+            rust_type,
+            json_type,
+            indexes,
+            type_param: None,
+        });
+        child_fields_vec.push(child_fields);
+    }
+
+    // Fields are already sorted since we iterated over BTreeMap
+    *ctx.signature_counts.entry(fields.clone()).or_insert(0) += 1;
+
+    ctx.signature_to_child_fields
+        .entry(fields.clone())
+        .or_insert(child_fields_vec);
+
+    let pattern_name = if let Some(existing) = ctx.signature_to_pattern.get(&fields) {
+        existing.clone()
+    } else {
+        let normalized = normalize_fields_for_naming(&fields);
+        // Generate stable name from first word of each field (deduped, sorted)
+        let first_words: BTreeSet<String> = fields
+            .iter()
+            .filter_map(|f| f.name.split('_').next())
+            .map(to_pascal_case)
+            .collect();
+        let combined: String = first_words.into_iter().collect();
+        let name = ctx
+            .normalized_to_name
+            .entry(normalized)
+            .or_insert_with(|| generate_pattern_name(&combined, &mut ctx.name_counts))
+            .clone();
+        ctx.signature_to_pattern
+            .insert(fields.clone(), name.clone());
+        name
+    };
+
+    Some((pattern_name, fields))
+}
+
+/// Normalize fields for naming (same structure = same name).
+/// Only erases leaf types when all leaves share the same type — this ensures
+/// mixed-type signatures (e.g., StoredU32 raw + StoredU64 cumulative) get a
+/// different name than same-type signatures that can be genericized.
+fn normalize_fields_for_naming(fields: &[PatternField]) -> Vec<PatternField> {
+    let leaf_types: Vec<&str> = fields
+        .iter()
+        .filter(|f| !f.is_branch())
+        .map(|f| f.rust_type.as_str())
+        .collect();
+    let all_same = !leaf_types.is_empty() && leaf_types.iter().all(|t| *t == leaf_types[0]);
+
+    fields
+        .iter()
+        .map(|f| {
+            if f.is_branch() || !all_same {
+                f.clone()
+            } else {
+                PatternField {
+                    name: f.name.clone(),
+                    rust_type: "_".to_string(),
+                    json_type: "_".to_string(),
+                    indexes: f.indexes.clone(),
+                    type_param: None,
+                }
+            }
+        })
+        .collect()
+}
+
+/// Generate a unique pattern name.
+fn generate_pattern_name(field_name: &str, name_counts: &mut BTreeMap<String, usize>) -> String {
+    let pascal = to_pascal_case(field_name);
+    let sanitized = if pascal.chars().next().is_some_and(|c| c.is_ascii_digit()) {
+        format!("_{}", pascal)
+    } else {
+        pascal
+    };
+
+    let base_name = format!("{}Pattern", sanitized);
+    let count = name_counts.entry(base_name.clone()).or_insert(0);
+    *count += 1;
+
+    if *count == 1 {
+        base_name
+    } else {
+        format!("{}{}", base_name, count)
+    }
+}
@@ -0,0 +1,573 @@
+//! Tree traversal helpers for pattern analysis.
+//!
+//! This module provides utilities for working with the TreeNode structure,
+//! including leaf name extraction and index pattern detection.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use brk_types::{Index, TreeNode, extract_json_type};
+use indexmap::IndexMap;
+
+use crate::{IndexSetPattern, PatternField, child_type_name};
+
+use super::{find_common_prefix, find_common_suffix, normalize_prefix};
+
+/// Get the shortest leaf name from a tree node.
+///
+/// This is useful for pattern base analysis where we want the "base" case
+/// (e.g., the leaf without suffix like `_btc` or `_usd`).
+pub(super) fn get_shortest_leaf_name(node: &TreeNode) -> Option<String> {
+    match node {
+        TreeNode::Leaf(leaf) => Some(leaf.name().to_string()),
+        TreeNode::Branch(children) => children
+            .values()
+            .filter_map(get_shortest_leaf_name)
+            .min_by_key(|name| name.len()),
+    }
+}
+
+/// Get the field signature for a branch node's children.
+/// Fields are sorted alphabetically for consistent pattern matching.
+pub fn get_node_fields(
+    children: &IndexMap<String, TreeNode>,
+    pattern_lookup: &BTreeMap<Vec<PatternField>, String>,
+) -> Vec<PatternField> {
+    let mut fields: Vec<PatternField> = children
+        .iter()
+        .map(|(name, node)| {
+            let (rust_type, json_type, indexes) = match node {
+                TreeNode::Leaf(leaf) => (
+                    leaf.kind().to_string(),
+                    extract_json_type(&leaf.schema),
+                    leaf.indexes().clone(),
+                ),
+                TreeNode::Branch(grandchildren) => {
+                    let child_fields = get_node_fields(grandchildren, pattern_lookup);
+                    let pattern_name = pattern_lookup
+                        .get(&child_fields)
+                        .cloned()
+                        .unwrap_or_else(|| "Unknown".to_string());
+                    (pattern_name.clone(), pattern_name, BTreeSet::new())
+                }
+            };
+            PatternField {
+                name: name.clone(),
+                rust_type,
+                json_type,
+                indexes,
+                type_param: None,
+            }
+        })
+        .collect();
+    // Sort for consistent pattern matching (display order preserved in IndexMap)
+    fields.sort_by(|a, b| a.name.cmp(&b.name));
+    fields
+}
+
+/// Detect index patterns (sets of indexes that appear together on series).
+pub fn detect_index_patterns(tree: &TreeNode) -> Vec<IndexSetPattern> {
+    let mut unique_index_sets: BTreeSet<BTreeSet<Index>> = BTreeSet::new();
+    collect_index_sets_from_tree(tree, &mut unique_index_sets);
+
+    // Sort by count (descending) then by first index name for deterministic ordering
+    let mut sorted_sets: Vec<_> = unique_index_sets
+        .into_iter()
+        .filter(|indexes| !indexes.is_empty())
+        .collect();
+    sorted_sets.sort_by(|a, b| {
+        b.len()
+            .cmp(&a.len())
+            .then_with(|| a.iter().next().cmp(&b.iter().next()))
+    });
+
+    // Assign unique sequential names
+    sorted_sets
+        .into_iter()
+        .enumerate()
+        .map(|(i, indexes)| IndexSetPattern {
+            name: format!("SeriesPattern{}", i + 1),
+            indexes,
+        })
+        .collect()
+}
+
+fn collect_index_sets_from_tree(
+    node: &TreeNode,
+    unique_index_sets: &mut BTreeSet<BTreeSet<Index>>,
+) {
+    match node {
+        TreeNode::Leaf(leaf) => {
+            unique_index_sets.insert(leaf.indexes().clone());
+        }
+        TreeNode::Branch(children) => {
+            for child in children.values() {
+                collect_index_sets_from_tree(child, unique_index_sets);
+            }
+        }
+    }
+}
+
+/// Result of analyzing a pattern instance's base.
+#[derive(Debug, Clone)]
+pub struct PatternBaseResult {
+    /// The computed base name for the pattern.
+    pub base: String,
+    /// Whether an outlier child was excluded to find the pattern.
+    /// If true, pattern factory should not be used.
+    pub has_outlier: bool,
+    /// Whether this instance uses suffix mode (common prefix) or prefix mode (common suffix).
+    /// Used to check compatibility with the pattern's mode.
+    pub is_suffix_mode: bool,
+    /// The field parts (suffix in suffix mode, prefix in prefix mode) for each field.
+    /// Used to check if instance field parts match the pattern's field parts.
+    pub field_parts: BTreeMap<String, String>,
+}
+
+impl PatternBaseResult {
+    /// Create a default result that forces inlining (has_outlier = true).
+    /// Use when no pattern base could be computed during lookup.
+    pub fn force_inline() -> Self {
+        Self {
+            base: String::new(),
+            has_outlier: true,
+            is_suffix_mode: true,
+            field_parts: BTreeMap::new(),
+        }
+    }
+
+    /// Create an empty result with no outlier.
+    /// Use for root-level patterns or when children have no common pattern.
+    pub fn empty() -> Self {
+        Self {
+            base: String::new(),
+            has_outlier: false,
+            is_suffix_mode: true,
+            field_parts: BTreeMap::new(),
+        }
+    }
+}
+
+/// Get the series base for a pattern instance by analyzing direct children.
+///
+/// Uses the shortest leaf names from direct children to find common prefix/suffix.
+///
+/// If the initial analysis fails to find a common pattern, it tries excluding
+/// each child one at a time to detect outliers (e.g., a mismatched "base" field
+/// from indexer/computed tree merging).
+///
+/// Returns both the base and whether an outlier was detected.
+pub fn get_pattern_instance_base(node: &TreeNode) -> PatternBaseResult {
+    let child_names = get_direct_children_for_analysis(node);
+    if child_names.is_empty() {
+        return PatternBaseResult::empty();
+    }
+
+    // Try to find common base from leaf names
+    if let Some(result) = try_find_base(&child_names, false) {
+        return PatternBaseResult {
+            base: result.base,
+            has_outlier: result.has_outlier,
+            is_suffix_mode: result.is_suffix_mode,
+            field_parts: result.field_parts,
+        };
+    }
+
+    // If no common pattern found and we have enough children, try excluding outliers
+    if child_names.len() > 2 {
+        for i in 0..child_names.len() {
+            let filtered: Vec<_> = child_names
+                .iter()
+                .enumerate()
+                .filter(|(j, _)| *j != i)
+                .map(|(_, v)| v.clone())
+                .collect();
+
+            if let Some(result) = try_find_base(&filtered, true) {
+                return PatternBaseResult {
+                    base: result.base,
+                    has_outlier: true,
+                    is_suffix_mode: result.is_suffix_mode,
+                    field_parts: result.field_parts,
+                };
+            }
+        }
+    }
+
+    // Fallback: no common prefix/suffix found - this is a root-level pattern
+    // Return empty base so series names are used directly
+    PatternBaseResult::empty()
+}
+
+/// Result of try_find_base: base name, has_outlier flag, is_suffix_mode flag, and field_parts.
+struct FindBaseResult {
+    base: String,
+    has_outlier: bool,
+    is_suffix_mode: bool,
+    field_parts: BTreeMap<String, String>,
+}
+
+/// Try to find a common base from child names using prefix/suffix detection.
+/// Returns Some(FindBaseResult) if found.
+fn try_find_base(
+    child_names: &[(String, String)],
+    is_outlier_attempt: bool,
+) -> Option<FindBaseResult> {
+    let leaf_names: Vec<&str> = child_names.iter().map(|(_, n)| n.as_str()).collect();
+
+    // Try common prefix first (suffix mode)
+    if let Some(prefix) = find_common_prefix(&leaf_names) {
+        let base = prefix.trim_end_matches('_').to_string();
+        let mut field_parts = BTreeMap::new();
+        for (field_name, leaf_name) in child_names {
+            // Compute the suffix part for this field
+            let suffix = if leaf_name == &base {
+                String::new()
+            } else {
+                leaf_name
+                    .strip_prefix(&prefix)
+                    .unwrap_or(leaf_name)
+                    .to_string()
+            };
+            field_parts.insert(field_name.clone(), suffix);
+        }
+        return Some(FindBaseResult {
+            base,
+            has_outlier: is_outlier_attempt,
+            is_suffix_mode: true,
+            field_parts,
+        });
+    }
+
+    // Try common suffix (prefix mode)
+    if let Some(suffix) = find_common_suffix(&leaf_names) {
+        let base = suffix.trim_start_matches('_').to_string();
+        let mut field_parts = BTreeMap::new();
+        for (field_name, leaf_name) in child_names {
+            // Compute the prefix part for this field, normalized to end with _
+            let prefix_part = leaf_name
+                .strip_suffix(&suffix)
+                .map(normalize_prefix)
+                .unwrap_or_default();
+            field_parts.insert(field_name.clone(), prefix_part);
+        }
+        return Some(FindBaseResult {
+            base,
+            has_outlier: is_outlier_attempt,
+            is_suffix_mode: false,
+            field_parts,
+        });
+    }
+
+    None
+}
+
+/// Get (field_name, shortest_leaf_name) pairs for direct children of a branch node.
+///
+/// Uses the shortest leaf name from each child subtree to find the "base" case
+/// (the leaf without suffix modifiers like `_btc` or `_usd`).
+fn get_direct_children_for_analysis(node: &TreeNode) -> Vec<(String, String)> {
+    match node {
+        TreeNode::Leaf(leaf) => vec![(leaf.name().to_string(), leaf.name().to_string())],
+        TreeNode::Branch(children) => children
+            .iter()
+            .filter_map(|(field_name, child)| {
+                get_shortest_leaf_name(child).map(|leaf_name| (field_name.clone(), leaf_name))
+            })
+            .collect(),
+    }
+}
+
+/// Infer the accumulated name for a child node based on a descendant leaf name.
+pub fn infer_accumulated_name(parent_acc: &str, field_name: &str, descendant_leaf: &str) -> String {
+    if let Some(pos) = descendant_leaf.find(field_name) {
+        if pos == 0 {
+            return field_name.to_string();
+        }
+        if pos > 0 && descendant_leaf.chars().nth(pos - 1) == Some('_') {
+            return if parent_acc.is_empty() {
+                field_name.to_string()
+            } else {
+                format!("{}_{}", parent_acc, field_name)
+            };
+        }
+    }
+
+    if parent_acc.is_empty() {
+        field_name.to_string()
+    } else {
+        format!("{}_{}", parent_acc, field_name)
+    }
+}
+
+/// Get fields with child field information for generic pattern lookup.
+pub fn get_fields_with_child_info(
+    children: &IndexMap<String, TreeNode>,
+    parent_name: &str,
+    pattern_lookup: &BTreeMap<Vec<PatternField>, String>,
+) -> Vec<(PatternField, Option<Vec<PatternField>>)> {
+    children
+        .iter()
+        .map(|(name, node)| {
+            let (rust_type, json_type, indexes, child_fields) = match node {
+                TreeNode::Leaf(leaf) => (
+                    leaf.kind().to_string(),
+                    extract_json_type(&leaf.schema),
+                    leaf.indexes().clone(),
+                    None,
+                ),
+                TreeNode::Branch(grandchildren) => {
+                    let child_fields = get_node_fields(grandchildren, pattern_lookup);
+                    let pattern_name = pattern_lookup
+                        .get(&child_fields)
+                        .cloned()
+                        .unwrap_or_else(|| child_type_name(parent_name, name));
+                    (
+                        pattern_name.clone(),
+                        pattern_name,
+                        BTreeSet::new(),
+                        Some(child_fields),
+                    )
+                }
+            };
+            (
+                PatternField {
+                    name: name.clone(),
+                    rust_type,
+                    json_type,
+                    indexes,
+                    type_param: None,
+                },
+                child_fields,
+            )
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use brk_types::{SeriesLeaf, SeriesLeafWithSchema, TreeNode};
+
+    fn make_leaf(name: &str) -> TreeNode {
+        let leaf = SeriesLeaf {
+            name: name.to_string(),
+            kind: "TestType".to_string(),
+            indexes: BTreeSet::new(),
+        };
+        TreeNode::Leaf(SeriesLeafWithSchema::new(leaf, serde_json::json!({})))
+    }
+
+    fn make_branch(children: Vec<(&str, TreeNode)>) -> TreeNode {
+        let map: IndexMap<String, TreeNode> = children
+            .into_iter()
+            .map(|(k, v)| (k.to_string(), v))
+            .collect();
+        TreeNode::Branch(map)
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_with_base_field() {
+        // Simulates vbytes tree: has base field with block_vbytes leaf
+        let tree = make_branch(vec![
+            (
+                "base",
+                make_branch(vec![("day1", make_leaf("block_vbytes"))]),
+            ),
+            (
+                "average",
+                make_branch(vec![("day1", make_leaf("block_vbytes_average"))]),
+            ),
+            (
+                "sum",
+                make_branch(vec![("day1", make_leaf("block_vbytes_sum"))]),
+            ),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        assert_eq!(result.base, "block_vbytes");
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_without_base_field() {
+        // Simulates weight tree: NO base field, only suffixed series
+        let tree = make_branch(vec![
+            (
+                "average",
+                make_branch(vec![("day1", make_leaf("block_weight_average"))]),
+            ),
+            (
+                "sum",
+                make_branch(vec![("day1", make_leaf("block_weight_sum"))]),
+            ),
+            (
+                "cumulative",
+                make_branch(vec![("day1", make_leaf("block_weight_cumulative"))]),
+            ),
+            (
+                "max",
+                make_branch(vec![("day1", make_leaf("block_weight_max"))]),
+            ),
+            (
+                "min",
+                make_branch(vec![("day1", make_leaf("block_weight_min"))]),
+            ),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        assert_eq!(result.base, "block_weight");
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_with_duplicate_base_field() {
+        // What if there's a "base" field that points to the same leaf as "average"?
+        // This could happen if the tree generation creates a base field that shares leaves with average
+        let tree = make_branch(vec![
+            (
+                "base",
+                make_branch(vec![("day1", make_leaf("block_weight_average"))]),
+            ),
+            (
+                "average",
+                make_branch(vec![("day1", make_leaf("block_weight_average"))]),
+            ),
+            (
+                "sum",
+                make_branch(vec![("day1", make_leaf("block_weight_sum"))]),
+            ),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        // Common prefix among all children is "block_weight_"
+        assert_eq!(result.base, "block_weight");
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_with_mismatched_base_name() {
+        // Simulates the actual bug: indexed tree's "base" field has name "weight"
+        // but computed tree's derived series use "block_weight_*" prefix.
+        // After tree merge, we get a base field with mismatched naming.
+        let tree = make_branch(vec![
+            ("base", make_leaf("weight")), // Outlier - doesn't match pattern
+            ("average", make_leaf("block_weight_average")),
+            ("sum", make_leaf("block_weight_sum")),
+            ("cumulative", make_leaf("block_weight_cumulative")),
+            ("max", make_leaf("block_weight_max")),
+            ("min", make_leaf("block_weight_min")),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        // Should detect "weight" as outlier and find common prefix from others
+        assert_eq!(result.base, "block_weight");
+        assert!(result.has_outlier); // Pattern factory should NOT be used
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_root_level_no_common_pattern() {
+        // Simulates root-level pattern with series that have no common prefix/suffix.
+        // These names have no shared prefix or suffix, even when excluding any one.
+        // In this case, we should return empty base so series names are used directly.
+        let tree = make_branch(vec![
+            ("alpha", make_leaf("foo_series")),
+            ("beta", make_leaf("bar_value")),
+            ("gamma", make_leaf("baz_count")),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        // No common prefix or suffix - return empty base
+        assert_eq!(result.base, "");
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_two_children_no_pattern() {
+        // Two children with no common pattern - should still return empty base
+        let tree = make_branch(vec![
+            ("foo", make_leaf("alpha")),
+            ("bar", make_leaf("beta")),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        assert_eq!(result.base, "");
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_with_outlier_excluded() {
+        // Simulates the realized pattern: adjusted_sopr, sopr, asopr.
+        // When "asopr" is excluded as outlier, "adjusted_sopr" and "sopr" share suffix "_sopr".
+        // The outlier detection should find base="sopr" with has_outlier=true.
+        let tree = make_branch(vec![
+            ("adjustedSopr", make_leaf("adjusted_sopr")),
+            ("sopr", make_leaf("sopr")),
+            ("asopr", make_leaf("asopr")),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        // Outlier detected - pattern base found by excluding "asopr"
+        assert_eq!(result.base, "sopr");
+        assert!(result.has_outlier); // Pattern factory should NOT be used (inline instead)
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_suffix_mode_price_ago() {
+        // Simulates price_ago pattern: price_24h_ago, price_1w_ago, price_10y_ago
+        // Common prefix is "price_", so this is suffix mode
+        let tree = make_branch(vec![
+            ("_24h", make_leaf("price_24h_ago")),
+            ("_1w", make_leaf("price_1w_ago")),
+            ("_1m", make_leaf("price_1m_ago")),
+            ("_10y", make_leaf("price_10y_ago")),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        assert_eq!(result.base, "price");
+        assert!(result.is_suffix_mode); // Suffix mode: _m(base, "24h_ago")
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_get_pattern_instance_base_prefix_mode_price_returns() {
+        // Simulates price_returns pattern: 24h_price_returns, 1w_price_returns, 10y_price_returns
+        // Common suffix is "_price_returns", so this is prefix mode
+        let tree = make_branch(vec![
+            ("_24h", make_leaf("24h_price_returns")),
+            ("_1w", make_leaf("1w_price_returns")),
+            ("_1m", make_leaf("1m_price_returns")),
+            ("_10y", make_leaf("10y_price_returns")),
+        ]);
+
+        let result = get_pattern_instance_base(&tree);
+        assert_eq!(result.base, "price_returns");
+        assert!(!result.is_suffix_mode); // Prefix mode: _p("24h_", base)
+        assert!(!result.has_outlier);
+    }
+
+    #[test]
+    fn test_mode_detection_distinguishes_similar_structures() {
+        // Two patterns with identical structure but different naming conventions
+        // should have different modes detected
+
+        // Suffix mode pattern
+        let suffix_tree = make_branch(vec![
+            ("_1y", make_leaf("lump_sum_1y")),
+            ("_2y", make_leaf("lump_sum_2y")),
+            ("_5y", make_leaf("lump_sum_5y")),
+        ]);
+        let suffix_result = get_pattern_instance_base(&suffix_tree);
+        assert_eq!(suffix_result.base, "lump_sum");
+        assert!(suffix_result.is_suffix_mode);
+
+        // Prefix mode pattern (same structure, different naming)
+        let prefix_tree = make_branch(vec![
+            ("_1y", make_leaf("1y_returns")),
+            ("_2y", make_leaf("2y_returns")),
+            ("_5y", make_leaf("5y_returns")),
+        ]);
+        let prefix_result = get_pattern_instance_base(&prefix_tree);
+        assert_eq!(prefix_result.base, "returns");
+        assert!(!prefix_result.is_suffix_mode);
+    }
+}
@@ -0,0 +1,109 @@
+//! JavaScript language syntax implementation.
+
+use crate::{GenericSyntax, LanguageSyntax, to_camel_case};
+
+/// JavaScript-specific code generation syntax.
+pub struct JavaScriptSyntax;
+
+impl LanguageSyntax for JavaScriptSyntax {
+    fn field_name(&self, name: &str) -> String {
+        to_camel_case(name)
+    }
+
+    fn path_expr(&self, base_var: &str, suffix: &str) -> String {
+        // Convert base_var to camelCase for JavaScript
+        let var_name = to_camel_case(base_var);
+        format!("`${{{}}}{}`", var_name, suffix)
+    }
+
+    fn suffix_expr(&self, acc_var: &str, relative: &str) -> String {
+        let var_name = to_camel_case(acc_var);
+        if relative.is_empty() {
+            // Identity: just return acc
+            var_name
+        } else {
+            // _m(acc, relative) -> acc ? `${acc}_relative` : 'relative'
+            format!("_m({}, '{}')", var_name, relative)
+        }
+    }
+
+    fn prefix_expr(&self, prefix: &str, acc_var: &str) -> String {
+        let var_name = to_camel_case(acc_var);
+        if prefix.is_empty() {
+            // Identity: just return acc
+            var_name
+        } else {
+            // _p(prefix, acc) -> acc ? `${prefix}${acc}` : 'prefix_without_underscore'
+            let prefix_base = prefix.trim_end_matches('_');
+            format!("_p('{}', {})", prefix_base, var_name)
+        }
+    }
+
+    fn constructor(&self, type_name: &str, path_expr: &str) -> String {
+        format!("create{}(client, {})", type_name, path_expr)
+    }
+
+    fn field_init(&self, indent: &str, name: &str, _type_ann: &str, value: &str) -> String {
+        // JavaScript uses object literal syntax; type is in JSDoc, not in assignment
+        format!("{}{}: {},", indent, name, value)
+    }
+
+    fn generic_syntax(&self) -> GenericSyntax {
+        GenericSyntax::JAVASCRIPT
+    }
+
+    fn string_literal(&self, value: &str) -> String {
+        format!("'{}'", value)
+    }
+
+    fn constructor_name(&self, type_name: &str) -> String {
+        format!("create{}", type_name)
+    }
+
+    fn disc_arg_expr(&self, template: &str) -> String {
+        if template == "{disc}" {
+            "disc".to_string()
+        } else if template.is_empty() {
+            "''".to_string()
+        } else if !template.contains("{disc}") {
+            format!("'{}'", template)
+        } else if template.ends_with("{disc}") {
+            let static_part = template.trim_end_matches("{disc}").trim_end_matches('_');
+            format!("_m('{}', disc)", static_part)
+        } else {
+            let js_template = template.replace("{disc}", "${disc}");
+            format!("`{}`", js_template)
+        }
+    }
+
+    fn template_expr(&self, acc_var: &str, template: &str) -> String {
+        let var_name = to_camel_case(acc_var);
+        if template.is_empty() {
+            // Identity — just pass disc
+            format!("_m({}, disc)", var_name)
+        } else if template == "{disc}" {
+            // Template IS the discriminator
+            format!("_m({}, disc)", var_name)
+        } else if !template.contains("{disc}") {
+            // Static suffix — no disc involved
+            format!("_m({}, '{}')", var_name, template)
+        } else {
+            // Template with {disc}: use nested _m for proper separator handling
+            // "ratio_{disc}_bps" → split on {disc} → _m(_m(acc, 'ratio'), disc) then _bps
+            // But this is complex. For embedded disc, use string interpolation.
+            // For suffix disc (ends with {disc}), use _m composition.
+            if let Some(static_part) = template.strip_suffix("{disc}") {
+                if static_part.is_empty() {
+                    format!("_m({}, disc)", var_name)
+                } else {
+                    let static_part = static_part.trim_end_matches('_');
+                    format!("_m(_m({}, '{}'), disc)", var_name, static_part)
+                }
+            } else {
+                // Embedded disc — use template literal
+                let js_template = template.replace("{disc}", "${disc}");
+                format!("_m({}, `{}`)", var_name, js_template)
+            }
+        }
+    }
+}
@@ -0,0 +1,12 @@
+//! Language-specific syntax backends.
+//!
+//! This module contains implementations of the `LanguageSyntax` trait
+//! for each supported target language.
+
+mod javascript;
+mod python;
+mod rust;
+
+pub use javascript::JavaScriptSyntax;
+pub use python::PythonSyntax;
+pub use rust::RustSyntax;
@@ -0,0 +1,82 @@
+//! Python language syntax implementation.
+
+use crate::{GenericSyntax, LanguageSyntax, escape_python_keyword, to_snake_case};
+
+/// Python-specific code generation syntax.
+pub struct PythonSyntax;
+
+impl LanguageSyntax for PythonSyntax {
+    fn field_name(&self, name: &str) -> String {
+        escape_python_keyword(&to_snake_case(name))
+    }
+
+    fn path_expr(&self, base_var: &str, suffix: &str) -> String {
+        format!("f'{{{}}}{}'", base_var, suffix)
+    }
+
+    fn suffix_expr(&self, acc_var: &str, relative: &str) -> String {
+        if relative.is_empty() {
+            // Identity: just return acc
+            acc_var.to_string()
+        } else {
+            // _m(acc, relative) -> f'{acc}_{relative}' if acc else 'relative'
+            format!("_m({}, '{}')", acc_var, relative)
+        }
+    }
+
+    fn prefix_expr(&self, prefix: &str, acc_var: &str) -> String {
+        if prefix.is_empty() {
+            // Identity: just return acc
+            acc_var.to_string()
+        } else {
+            // _p(prefix, acc) -> f'{prefix}{acc}' if acc else 'prefix_base'
+            let prefix_base = prefix.trim_end_matches('_');
+            format!("_p('{}', {})", prefix_base, acc_var)
+        }
+    }
+
+    fn constructor(&self, type_name: &str, path_expr: &str) -> String {
+        format!("{}(client, {})", type_name, path_expr)
+    }
+
+    fn field_init(&self, indent: &str, name: &str, type_ann: &str, value: &str) -> String {
+        format!("{}self.{}: {} = {}", indent, name, type_ann, value)
+    }
+
+    fn generic_syntax(&self) -> GenericSyntax {
+        GenericSyntax::PYTHON
+    }
+
+    fn string_literal(&self, value: &str) -> String {
+        format!("'{}'", value)
+    }
+
+    fn constructor_name(&self, type_name: &str) -> String {
+        type_name.to_string()
+    }
+
+    fn disc_arg_expr(&self, template: &str) -> String {
+        if template == "{disc}" {
+            "disc".to_string()
+        } else if template.is_empty() {
+            "''".to_string()
+        } else if !template.contains("{disc}") {
+            format!("'{}'", template)
+        } else if template.ends_with("{disc}") {
+            let static_part = template.trim_end_matches("{disc}").trim_end_matches('_');
+            format!("_m('{}', disc)", static_part)
+        } else {
+            format!("f'{}'", template)
+        }
+    }
+
+    fn template_expr(&self, acc_var: &str, template: &str) -> String {
+        if template == "{disc}" {
+            format!("_m({}, disc)", acc_var)
+        } else if !template.contains("{disc}") {
+            format!("_m({}, '{}')", acc_var, template)
+        } else {
+            format!("_m({}, f'{}')", acc_var, template)
+        }
+    }
+}
@@ -0,0 +1,97 @@
+//! Rust language syntax implementation.
+
+use crate::{GenericSyntax, LanguageSyntax, escape_rust_keyword, to_snake_case};
+
+/// Rust-specific code generation syntax.
+pub struct RustSyntax;
+
+/// Escape braces in a template string for use in `format!()`, preserving `{disc}`.
+fn escape_rust_format(template: &str) -> String {
+    template
+        .replace('{', "{{")
+        .replace('}', "}}")
+        .replace("{{disc}}", "{disc}")
+}
+
+impl LanguageSyntax for RustSyntax {
+    fn field_name(&self, name: &str) -> String {
+        escape_rust_keyword(&to_snake_case(name))
+    }
+
+    fn path_expr(&self, base_var: &str, suffix: &str) -> String {
+        format!("format!(\"{{{}}}{}\")", base_var, suffix)
+    }
+
+    fn suffix_expr(&self, acc_var: &str, relative: &str) -> String {
+        if relative.is_empty() {
+            self.owned_expr(acc_var)
+        } else {
+            format!("_m(&{}, \"{}\")", acc_var, relative)
+        }
+    }
+
+    fn owned_expr(&self, var: &str) -> String {
+        format!("{}.clone()", var)
+    }
+
+    fn prefix_expr(&self, prefix: &str, acc_var: &str) -> String {
+        if prefix.is_empty() {
+            self.owned_expr(acc_var)
+        } else {
+            let prefix_base = prefix.trim_end_matches('_');
+            format!("_p(\"{}\", &{})", prefix_base, acc_var)
+        }
+    }
+
+    fn constructor(&self, type_name: &str, path_expr: &str) -> String {
+        format!("{}::new(client.clone(), {})", type_name, path_expr)
+    }
+
+    fn field_init(&self, indent: &str, name: &str, _type_ann: &str, value: &str) -> String {
+        // Rust struct initialization; type is in struct definition, not in init
+        format!("{}{}: {},", indent, name, value)
+    }
+
+    fn generic_syntax(&self) -> GenericSyntax {
+        GenericSyntax::RUST
+    }
+
+    fn string_literal(&self, value: &str) -> String {
+        format!("\"{}\".to_string()", value)
+    }
+
+    fn constructor_name(&self, type_name: &str) -> String {
+        format!("{}::new", type_name)
+    }
+
+    fn disc_arg_expr(&self, template: &str) -> String {
+        if template == "{disc}" {
+            "disc.clone()".to_string()
+        } else if template.is_empty() {
+            "String::new()".to_string()
+        } else if !template.contains("{disc}") {
+            format!("\"{}\".to_string()", template)
+        } else if template.ends_with("{disc}") {
+            let static_part = template.trim_end_matches("{disc}").trim_end_matches('_');
+            format!("_m(\"{}\", &disc)", static_part)
+        } else {
+            format!("format!(\"{}\")", escape_rust_format(template))
+        }
+    }
+
+    fn template_expr(&self, acc_var: &str, template: &str) -> String {
+        if template == "{disc}" {
+            format!("_m(&{}, &disc)", acc_var)
+        } else if template.is_empty() {
+            acc_var.to_string()
+        } else if !template.contains("{disc}") {
+            format!("_m(&{}, \"{}\")", acc_var, template)
+        } else {
+            format!(
+                "_m(&{}, &format!(\"{}\", disc=disc))",
+                acc_var,
+                escape_rust_format(template)
+            )
+        }
+    }
+}
@@ -0,0 +1,94 @@
+//! Shared constant generation for static client data.
+//!
+//! Extracts common logic for generating INDEXES, POOL_ID_TO_POOL_NAME,
+//! and cohort name constants across JavaScript and Python clients.
+
+use std::collections::BTreeMap;
+
+use brk_cohort::{
+    AGE_RANGE_NAMES, AMOUNT_RANGE_NAMES, CLASS_NAMES, EPOCH_NAMES, LOSS_NAMES, OVER_AGE_NAMES,
+    OVER_AMOUNT_NAMES, PROFIT_NAMES, PROFITABILITY_RANGE_NAMES, SPENDABLE_TYPE_NAMES, TERM_NAMES,
+    UNDER_AGE_NAMES, UNDER_AMOUNT_NAMES,
+};
+use brk_types::{Index, PoolSlug, pools};
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::{VERSION, to_camel_case};
+
+/// Collected constant data for client generation.
+pub struct ClientConstants {
+    pub version: String,
+    pub indexes: Vec<&'static str>,
+    pub pool_map: BTreeMap<PoolSlug, &'static str>,
+}
+
+impl ClientConstants {
+    /// Collect all constant data.
+    pub fn collect() -> Self {
+        let indexes = Index::all();
+        let indexes: Vec<&'static str> = indexes.iter().map(|i| i.name()).collect();
+
+        let pools = pools();
+        let mut sorted_pools: Vec<_> = pools.iter().collect();
+        sorted_pools.sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase()));
+        let pool_map: BTreeMap<PoolSlug, &'static str> =
+            sorted_pools.iter().map(|p| (p.slug(), p.name)).collect();
+
+        Self {
+            version: format!("v{}", VERSION),
+            indexes,
+            pool_map,
+        }
+    }
+}
+
+/// Cohort name constants - shared data definitions.
+pub struct CohortConstants;
+
+impl CohortConstants {
+    /// Get all cohort constants as name-value pairs for iteration.
+    pub fn all() -> Vec<(&'static str, Value)> {
+        fn to_value<T: Serialize>(v: &T) -> Value {
+            serde_json::to_value(v).unwrap()
+        }
+
+        vec![
+            ("TERM_NAMES", to_value(&TERM_NAMES)),
+            ("EPOCH_NAMES", to_value(&EPOCH_NAMES)),
+            ("CLASS_NAMES", to_value(&CLASS_NAMES)),
+            ("SPENDABLE_TYPE_NAMES", to_value(&SPENDABLE_TYPE_NAMES)),
+            ("AGE_RANGE_NAMES", to_value(&AGE_RANGE_NAMES)),
+            ("UNDER_AGE_NAMES", to_value(&UNDER_AGE_NAMES)),
+            ("OVER_AGE_NAMES", to_value(&OVER_AGE_NAMES)),
+            ("AMOUNT_RANGE_NAMES", to_value(&AMOUNT_RANGE_NAMES)),
+            ("OVER_AMOUNT_NAMES", to_value(&OVER_AMOUNT_NAMES)),
+            ("UNDER_AMOUNT_NAMES", to_value(&UNDER_AMOUNT_NAMES)),
+            (
+                "PROFITABILITY_RANGE_NAMES",
+                to_value(&PROFITABILITY_RANGE_NAMES),
+            ),
+            ("PROFIT_NAMES", to_value(&PROFIT_NAMES)),
+            ("LOSS_NAMES", to_value(&LOSS_NAMES)),
+        ]
+    }
+}
+
+/// Convert top-level keys of a JSON object to camelCase.
+pub fn camel_case_keys(value: Value) -> Value {
+    match value {
+        Value::Object(map) => {
+            let new_map: serde_json::Map<String, Value> = map
+                .into_iter()
+                .map(|(k, v)| (to_camel_case(&k), v))
+                .collect();
+            Value::Object(new_map)
+        }
+        other => other,
+    }
+}
+
+/// Format a JSON value as a pretty-printed string.
+pub fn format_json<T: Serialize>(value: &T) -> String {
+    serde_json::to_string_pretty(value).unwrap()
+}
@@ -0,0 +1,186 @@
+//! Shared field generation logic.
+//!
+//! This module contains the core field generation logic that is shared
+//! across all language backends. The `LanguageSyntax` trait is used to
+//! abstract over language-specific formatting.
+
+use std::fmt::Write;
+
+use brk_types::SeriesLeafWithSchema;
+
+use crate::{
+    ClientMetadata, LanguageSyntax, PatternBaseResult, PatternField, PatternMode, StructuralPattern,
+};
+
+/// Create a path suffix from a name.
+fn path_suffix(name: &str) -> String {
+    if name.starts_with('_') {
+        name.to_string()
+    } else {
+        format!("_{}", name)
+    }
+}
+
+/// Compute the constructor value for a parameterized field (factory context).
+///
+/// Handles all three pattern modes (Suffix/Prefix/Templated) and the special
+/// case of templated child patterns that need (acc, disc) instead of a path.
+fn compute_parameterized_value<S: LanguageSyntax>(
+    syntax: &S,
+    field: &PatternField,
+    pattern: &StructuralPattern,
+    metadata: &ClientMetadata,
+) -> String {
+    // Templated child patterns receive acc and disc as separate arguments
+    if let Some(child_pattern) = metadata.find_pattern(&field.rust_type)
+        && child_pattern.is_templated()
+    {
+        let disc_template = pattern.get_field_part(&field.name).unwrap_or(&field.name);
+        let disc_arg = syntax.disc_arg_expr(disc_template);
+        let acc_arg = syntax.owned_expr("acc");
+        return syntax.constructor(&field.rust_type, &format!("{acc_arg}, {disc_arg}"));
+    }
+
+    // Compute path expression from pattern mode
+    let path_expr = match pattern.get_field_part(&field.name) {
+        Some(part) => match &pattern.mode {
+            Some(PatternMode::Templated { .. }) => syntax.template_expr("acc", part),
+            Some(PatternMode::Prefix { .. }) => syntax.prefix_expr(part, "acc"),
+            _ => syntax.suffix_expr("acc", part),
+        },
+        None => syntax.path_expr("acc", &path_suffix(&field.name)),
+    };
+
+    // Wrap in constructor — leaves use their index accessor, everything else uses the type name
+    if let Some(accessor) = metadata.find_index_set_pattern(&field.indexes) {
+        syntax.constructor(&accessor.name, &path_expr)
+    } else if field.is_leaf() {
+        panic!(
+            "Field '{}' has no matching index accessor. All series must be indexed.",
+            field.name
+        )
+    } else {
+        syntax.constructor(&field.rust_type, &path_expr)
+    }
+}
+
+/// Generate a parameterized field for a pattern factory.
+///
+/// Used for pattern instances where fields build series names from an accumulated base.
+pub fn generate_parameterized_field<S: LanguageSyntax>(
+    output: &mut String,
+    syntax: &S,
+    field: &PatternField,
+    pattern: &StructuralPattern,
+    metadata: &ClientMetadata,
+    indent: &str,
+) {
+    let field_name = syntax.field_name(&field.name);
+    let type_ann =
+        metadata.field_type_annotation(field, pattern.is_generic, None, syntax.generic_syntax());
+    let value = compute_parameterized_value(syntax, field, pattern, metadata);
+
+    writeln!(
+        output,
+        "{}",
+        syntax.field_init(indent, &field_name, &type_ann, &value)
+    )
+    .unwrap();
+}
+
+/// Generate a tree node field for a pattern-type child.
+///
+/// Called for non-inline branch children that match a parameterizable pattern.
+/// For templated patterns, extracts the discriminator from the base result.
+pub fn generate_tree_node_field<S: LanguageSyntax>(
+    output: &mut String,
+    syntax: &S,
+    field: &PatternField,
+    metadata: &ClientMetadata,
+    indent: &str,
+    client_expr: &str,
+    base_result: &PatternBaseResult,
+) {
+    let field_name = syntax.field_name(&field.name);
+    let type_ann = metadata.field_type_annotation(field, false, None, syntax.generic_syntax());
+    let base_arg = syntax.string_literal(&base_result.base);
+
+    let value = if let Some(pattern) = metadata.find_pattern(&field.rust_type)
+        && pattern.is_templated()
+    {
+        let disc = pattern
+            .extract_disc_from_instance(&base_result.field_parts)
+            .unwrap_or_default();
+        format!(
+            "{}({}, {}, {})",
+            syntax.constructor_name(&field.rust_type),
+            client_expr,
+            base_arg,
+            syntax.string_literal(&disc)
+        )
+    } else {
+        format!(
+            "{}({}, {})",
+            syntax.constructor_name(&field.rust_type),
+            client_expr,
+            base_arg
+        )
+    };
+
+    writeln!(
+        output,
+        "{}",
+        syntax.field_init(indent, &field_name, &type_ann, &value)
+    )
+    .unwrap();
+}
+
+/// Generate a leaf field using the actual series name from the TreeNode::Leaf.
+///
+/// This is the shared implementation for all language backends. It uses
+/// `leaf.name()` directly to get the correct series name, avoiding any
+/// path concatenation that could produce incorrect names.
+///
+/// # Arguments
+/// * `output` - The string buffer to write to
+/// * `syntax` - The language syntax implementation
+/// * `client_expr` - The client expression (e.g., "client.clone()", "this", "client")
+/// * `tree_field_name` - The field name from the tree structure
+/// * `leaf` - The Leaf node containing the actual series name and indexes
+/// * `metadata` - Client metadata for looking up index patterns
+/// * `indent` - Indentation string
+pub fn generate_leaf_field<S: LanguageSyntax>(
+    output: &mut String,
+    syntax: &S,
+    client_expr: &str,
+    tree_field_name: &str,
+    leaf: &SeriesLeafWithSchema,
+    metadata: &ClientMetadata,
+    indent: &str,
+) {
+    let field_name = syntax.field_name(tree_field_name);
+    let accessor = metadata
+        .find_index_set_pattern(leaf.indexes())
+        .unwrap_or_else(|| {
+            panic!(
+                "Series '{}' has no matching index pattern. All series must be indexed.",
+                leaf.name()
+            )
+        });
+
+    let type_ann = metadata.field_type_annotation_from_leaf(leaf, syntax.generic_syntax());
+    let series_name = syntax.string_literal(leaf.name());
+    let value = format!(
+        "{}({}, {})",
+        syntax.constructor_name(&accessor.name),
+        client_expr,
+        series_name
+    );
+
+    writeln!(
+        output,
+        "{}",
+        syntax.field_init(indent, &field_name, &type_ann, &value)
+    )
+    .unwrap();
+}
@@ -0,0 +1,13 @@
+//! Shared code generation logic.
+//!
+//! This module contains generation functions that are parameterized by
+//! the `LanguageSyntax` trait, allowing them to work across all supported
+//! language backends.
+
+mod constants;
+mod fields;
+mod tree;
+
+pub use constants::*;
+pub use fields::*;
+pub use tree::*;
@@ -0,0 +1,157 @@
+//! Shared tree generation helpers.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use brk_types::TreeNode;
+
+use crate::{
+    ClientMetadata, PatternBaseResult, PatternField, child_type_name, get_fields_with_child_info,
+};
+
+/// Build a child path by appending a child name to a parent path.
+/// Uses "/" as separator. If parent is empty, returns just the child name.
+#[inline]
+pub fn build_child_path(parent: &str, child: &str) -> String {
+    if parent.is_empty() {
+        child.to_string()
+    } else {
+        format!("{}/{}", parent, child)
+    }
+}
+
+/// Pre-computed context for a single child node.
+pub struct ChildContext<'a> {
+    /// The child's field name in the tree.
+    pub name: &'a str,
+    /// The child node.
+    pub node: &'a TreeNode,
+    /// The field info for this child (with type_param set for generic patterns).
+    pub field: PatternField,
+    /// Pattern analysis result.
+    pub base_result: PatternBaseResult,
+    /// Whether this is a leaf node.
+    pub is_leaf: bool,
+    /// Whether to use an inline type instead of a pattern type (only meaningful for branches).
+    pub should_inline: bool,
+    /// The type name to use for inline branches.
+    pub inline_type_name: String,
+}
+
+/// Context for generating a tree node, returned by `prepare_tree_node`.
+pub struct TreeNodeContext<'a> {
+    /// Pre-computed context for each child.
+    pub children: Vec<ChildContext<'a>>,
+}
+
+/// Prepare a tree node for generation.
+/// Returns None if the node should be skipped (not a branch, already generated,
+/// or matches a parameterizable pattern).
+///
+/// The `path` parameter is the tree path to this node (e.g., "distribution/utxoCohorts").
+/// It's used to look up pre-computed PatternBaseResult from the analysis phase.
+pub fn prepare_tree_node<'a>(
+    node: &'a TreeNode,
+    name: &str,
+    path: &str,
+    pattern_lookup: &BTreeMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+    generated: &mut BTreeSet<String>,
+) -> Option<TreeNodeContext<'a>> {
+    let TreeNode::Branch(branch_children) = node else {
+        return None;
+    };
+
+    let fields_with_child_info = get_fields_with_child_info(branch_children, name, pattern_lookup);
+    let fields: Vec<PatternField> = fields_with_child_info
+        .iter()
+        .map(|(f, _)| f.clone())
+        .collect();
+
+    // Look up the pre-computed base result, or use a default that forces inlining
+    let base_result = metadata
+        .get_node_base(path)
+        .cloned()
+        .unwrap_or_else(PatternBaseResult::force_inline);
+
+    // Skip if this matches a parameterizable pattern AND has no outlier AND field parts match
+    let pattern_compatible = pattern_lookup
+        .get(&fields)
+        .and_then(|name| metadata.find_pattern(name))
+        .is_none_or(|p| {
+            p.is_suffix_mode() == base_result.is_suffix_mode
+                && p.field_parts_match(&base_result.field_parts)
+        });
+    if let Some(pattern_name) = pattern_lookup.get(&fields)
+        && pattern_name != name
+        && metadata.is_parameterizable(pattern_name)
+        && !base_result.has_outlier
+        && pattern_compatible
+    {
+        return None;
+    }
+
+    // Skip if already generated
+    if generated.contains(name) {
+        return None;
+    }
+    generated.insert(name.to_string());
+
+    // Build child contexts with pre-computed decisions
+    let children: Vec<ChildContext<'a>> = branch_children
+        .iter()
+        .zip(fields_with_child_info)
+        .map(|((child_name, child_node), (mut field, child_fields))| {
+            let is_leaf = matches!(child_node, TreeNode::Leaf(_));
+
+            // Set type_param for generic patterns so field_type_annotation works directly
+            if let Some(cf) = &child_fields {
+                field.type_param = metadata.get_type_param(cf).cloned();
+            }
+
+            // Build child path and look up its pre-computed base result
+            let child_path = build_child_path(path, child_name);
+            let base_result = metadata
+                .get_node_base(&child_path)
+                .cloned()
+                .unwrap_or_else(PatternBaseResult::force_inline);
+
+            // Single lookup for the child's matching pattern (avoids repeated scans)
+            let matching_pattern = child_fields
+                .as_ref()
+                .and_then(|cf| metadata.find_pattern_by_fields(cf));
+
+            let matches_any_pattern = matching_pattern.is_some();
+            let pattern_compatible = matching_pattern.is_none_or(|p| {
+                p.is_suffix_mode() == base_result.is_suffix_mode
+                    && p.field_parts_match(&base_result.field_parts)
+            });
+            let is_parameterizable =
+                matching_pattern.is_none_or(|p| metadata.is_parameterizable(&p.name));
+
+            // should_inline determines if we generate an inline struct type
+            let should_inline = !is_leaf
+                && (!matches_any_pattern
+                    || !pattern_compatible
+                    || !is_parameterizable
+                    || base_result.has_outlier);
+
+            let inline_type_name = if should_inline {
+                child_type_name(name, child_name)
+            } else {
+                String::new()
+            };
+
+            ChildContext {
+                name: child_name,
+                node: child_node,
+                field,
+                base_result,
+                is_leaf,
+                should_inline,
+                inline_type_name,
+            }
+        })
+        .collect();
+
+    Some(TreeNodeContext { children })
+}
@@ -0,0 +1,160 @@
+//! JavaScript API method generation.
+
+use std::fmt::Write;
+
+use crate::{
+    Endpoint, Parameter,
+    generators::{normalize_return_type, write_description},
+    to_camel_case,
+};
+
+/// Generate API methods for the BrkClient class.
+pub fn generate_api_methods(output: &mut String, endpoints: &[Endpoint]) {
+    for endpoint in endpoints {
+        if !endpoint.should_generate() {
+            continue;
+        }
+
+        let method_name = endpoint_to_method_name(endpoint);
+        let base_return_type =
+            normalize_return_type(endpoint.response_type.as_deref().unwrap_or("*"));
+        let return_type = if endpoint.supports_csv {
+            format!("{} | string", base_return_type)
+        } else {
+            base_return_type
+        };
+
+        writeln!(output, "  /**").unwrap();
+        if let Some(summary) = &endpoint.summary {
+            writeln!(output, "   * {}", summary).unwrap();
+        }
+        if let Some(desc) = &endpoint.description
+            && endpoint.summary.as_ref() != Some(desc)
+        {
+            writeln!(output, "   *").unwrap();
+            write_description(output, desc, "   * ", "   *");
+        }
+
+        // Add endpoint path
+        writeln!(output, "   *").unwrap();
+        writeln!(
+            output,
+            "   * Endpoint: `{} {}`",
+            endpoint.method.to_uppercase(),
+            endpoint.path
+        )
+        .unwrap();
+
+        if !endpoint.path_params.is_empty() || !endpoint.query_params.is_empty() {
+            writeln!(output, "   *").unwrap();
+        }
+
+        for param in &endpoint.path_params {
+            let desc = format_param_desc(param.description.as_deref());
+            writeln!(
+                output,
+                "   * @param {{{}}} {}{}",
+                param.param_type, param.name, desc
+            )
+            .unwrap();
+        }
+        for param in &endpoint.query_params {
+            let optional = if param.required { "" } else { "=" };
+            let desc = format_param_desc(param.description.as_deref());
+            writeln!(
+                output,
+                "   * @param {{{}{}}} [{}]{}",
+                param.param_type, optional, param.name, desc
+            )
+            .unwrap();
+        }
+
+        writeln!(output, "   * @returns {{Promise<{}>}}", return_type).unwrap();
+        writeln!(output, "   */").unwrap();
+
+        let params = build_method_params(endpoint);
+        writeln!(output, "  async {}({}) {{", method_name, params).unwrap();
+
+        let path = build_path_template(&endpoint.path, &endpoint.path_params);
+
+        if endpoint.query_params.is_empty() {
+            writeln!(output, "    return this.getJson(`{}`);", path).unwrap();
+        } else {
+            writeln!(output, "    const params = new URLSearchParams();").unwrap();
+            for param in &endpoint.query_params {
+                let ident = sanitize_ident(&param.name);
+                if param.required {
+                    writeln!(
+                        output,
+                        "    params.set('{}', String({}));",
+                        param.name, ident
+                    )
+                    .unwrap();
+                } else {
+                    writeln!(
+                        output,
+                        "    if ({} !== undefined) params.set('{}', String({}));",
+                        ident, param.name, ident
+                    )
+                    .unwrap();
+                }
+            }
+            writeln!(output, "    const query = params.toString();").unwrap();
+            writeln!(
+                output,
+                "    const path = `{}${{query ? '?' + query : ''}}`;",
+                path
+            )
+            .unwrap();
+
+            if endpoint.supports_csv {
+                writeln!(output, "    if (format === 'csv') {{").unwrap();
+                writeln!(output, "      return this.getText(path);").unwrap();
+                writeln!(output, "    }}").unwrap();
+                writeln!(output, "    return this.getJson(path);").unwrap();
+            } else {
+                writeln!(output, "    return this.getJson(path);").unwrap();
+            }
+        }
+
+        writeln!(output, "  }}\n").unwrap();
+    }
+}
+
+fn endpoint_to_method_name(endpoint: &Endpoint) -> String {
+    to_camel_case(&endpoint.operation_name())
+}
+
+fn build_method_params(endpoint: &Endpoint) -> String {
+    let mut params = Vec::new();
+    for param in &endpoint.path_params {
+        params.push(sanitize_ident(&param.name));
+    }
+    for param in &endpoint.query_params {
+        params.push(sanitize_ident(&param.name));
+    }
+    params.join(", ")
+}
+
+/// Strip characters invalid in JS identifiers (e.g. `[]` from `txId[]`).
+fn sanitize_ident(name: &str) -> String {
+    name.replace(['[', ']'], "")
+}
+
+fn build_path_template(path: &str, path_params: &[Parameter]) -> String {
+    let mut result = path.to_string();
+    for param in path_params {
+        let placeholder = format!("{{{}}}", param.name);
+        let interpolation = format!("${{{}}}", param.name);
+        result = result.replace(&placeholder, &interpolation);
+    }
+    result
+}
+
+/// Format param description with dash prefix, or empty string if no description.
+fn format_param_desc(desc: Option<&str>) -> String {
+    match desc {
+        Some(d) if !d.is_empty() => format!(" - {}", d),
+        _ => String::new(),
+    }
+}
@@ -0,0 +1,762 @@
+//! JavaScript base client and pattern factory generation.
+
+use std::fmt::Write;
+
+use crate::{
+    ClientConstants, ClientMetadata, CohortConstants, GenericSyntax, IndexSetPattern,
+    JavaScriptSyntax, StructuralPattern, camel_case_keys, format_json,
+    generate_parameterized_field, to_camel_case,
+};
+
+/// Generate the base BrkClient class with HTTP functionality.
+pub fn generate_base_client(output: &mut String) {
+    writeln!(
+        output,
+        r#"/**
+ * @typedef {{Object}} BrkClientOptions
+ * @property {{string}} baseUrl - Base URL for the API
+ * @property {{number}} [timeout] - Request timeout in milliseconds
+ * @property {{string|boolean}} [cache] - Enable browser cache with default name (true), custom name (string), or disable (false). No effect in Node.js. Default: true
+ */
+
+const _isBrowser = typeof window !== 'undefined' && 'caches' in window;
+const _runIdle = (/** @type {{VoidFunction}} */ fn) => (globalThis.requestIdleCallback ?? setTimeout)(fn);
+const _defaultCacheName = '__BRK_CLIENT__';
+/** @param {{*}} v */
+const _addCamelGetters = (v) => {{
+  if (Array.isArray(v)) {{ v.forEach(_addCamelGetters); return v; }}
+  if (v && typeof v === 'object' && v.constructor === Object) {{
+    for (const k in v) {{
+      if (k.includes('_')) {{
+        const c = k.replace(/_([a-z])/g, (_, l) => l.toUpperCase());
+        if (!(c in v)) Object.defineProperty(v, c, {{ get() {{ return this[k]; }} }});
+      }}
+      _addCamelGetters(v[k]);
+    }}
+  }}
+  return v;
+}};
+
+/**
+ * @param {{string|boolean|undefined}} cache
+ * @returns {{Promise<Cache | null>}}
+ */
+const _openCache = (cache) => {{
+  if (!_isBrowser || cache === false) return Promise.resolve(null);
+  const name = typeof cache === 'string' ? cache : _defaultCacheName;
+  return caches.open(name).catch(() => null);
+}};
+
+/**
+ * Custom error class for BRK client errors
+ */
+class BrkError extends Error {{
+  /**
+   * @param {{string}} message
+   * @param {{number}} [status]
+   */
+  constructor(message, status) {{
+    super(message);
+    this.name = 'BrkError';
+    this.status = status;
+  }}
+}}
+
+// Date conversion constants and helpers
+const _GENESIS = new Date(2009, 0, 3);  // day1 0, week1 0
+const _DAY_ONE = new Date(2009, 0, 9);  // day1 1 (6 day gap after genesis)
+const _MS_PER_DAY = 86400000;
+const _MS_PER_WEEK = 7 * _MS_PER_DAY;
+const _EPOCH_MS = 1230768000000;
+const _DATE_INDEXES = new Set([
+  'minute10', 'minute30',
+  'hour1', 'hour4', 'hour12',
+  'day1', 'day3', 'week1',
+  'month1', 'month3', 'month6',
+  'year1', 'year10',
+]);
+
+/** @param {{number}} months @returns {{globalThis.Date}} */
+const _addMonths = (months) => new Date(2009, months, 1);
+
+/**
+ * Convert an index value to a Date for date-based indexes.
+ * @param {{Index}} index - The index type
+ * @param {{number}} i - The index value
+ * @returns {{globalThis.Date}}
+ */
+function indexToDate(index, i) {{
+  switch (index) {{
+    case 'minute10': return new Date(_EPOCH_MS + i * 600000);
+    case 'minute30': return new Date(_EPOCH_MS + i * 1800000);
+    case 'hour1': return new Date(_EPOCH_MS + i * 3600000);
+    case 'hour4': return new Date(_EPOCH_MS + i * 14400000);
+    case 'hour12': return new Date(_EPOCH_MS + i * 43200000);
+    case 'day1': return i === 0 ? _GENESIS : new Date(_DAY_ONE.getTime() + (i - 1) * _MS_PER_DAY);
+    case 'day3': return new Date(_EPOCH_MS - 86400000 + i * 259200000);
+    case 'week1': return new Date(_GENESIS.getTime() + i * _MS_PER_WEEK);
+    case 'month1': return _addMonths(i);
+    case 'month3': return _addMonths(i * 3);
+    case 'month6': return _addMonths(i * 6);
+    case 'year1': return new Date(2009 + i, 0, 1);
+    case 'year10': return new Date(2009 + i * 10, 0, 1);
+    default: throw new Error(`${{index}} is not a date-based index`);
+  }}
+}}
+
+/**
+ * Convert a Date to an index value for date-based indexes.
+ * Returns the floor index (latest index whose date is <= the given date).
+ * @param {{Index}} index - The index type
+ * @param {{globalThis.Date}} d - The date to convert
+ * @returns {{number}}
+ */
+function dateToIndex(index, d) {{
+  const ms = d.getTime();
+  switch (index) {{
+    case 'minute10': return Math.floor((ms - _EPOCH_MS) / 600000);
+    case 'minute30': return Math.floor((ms - _EPOCH_MS) / 1800000);
+    case 'hour1': return Math.floor((ms - _EPOCH_MS) / 3600000);
+    case 'hour4': return Math.floor((ms - _EPOCH_MS) / 14400000);
+    case 'hour12': return Math.floor((ms - _EPOCH_MS) / 43200000);
+    case 'day1': {{
+      if (ms < _DAY_ONE.getTime()) return 0;
+      return 1 + Math.floor((ms - _DAY_ONE.getTime()) / _MS_PER_DAY);
+    }}
+    case 'day3': return Math.floor((ms - _EPOCH_MS + 86400000) / 259200000);
+    case 'week1': return Math.floor((ms - _GENESIS.getTime()) / _MS_PER_WEEK);
+    case 'month1': return (d.getFullYear() - 2009) * 12 + d.getMonth();
+    case 'month3': return (d.getFullYear() - 2009) * 4 + Math.floor(d.getMonth() / 3);
+    case 'month6': return (d.getFullYear() - 2009) * 2 + Math.floor(d.getMonth() / 6);
+    case 'year1': return d.getFullYear() - 2009;
+    case 'year10': return Math.floor((d.getFullYear() - 2009) / 10);
+    default: throw new Error(`${{index}} is not a date-based index`);
+  }}
+}}
+
+/**
+ * Wrap raw series data with helper methods.
+ * @template T
+ * @param {{SeriesData<T>}} raw - Raw JSON response
+ * @returns {{DateSeriesData<T>}}
+ */
+function _wrapSeriesData(raw) {{
+  const {{ index, start, end, data }} = raw;
+  const _dateBased = _DATE_INDEXES.has(index);
+  return /** @type {{DateSeriesData<T>}} */ ({{
+    ...raw,
+    isDateBased: _dateBased,
+    indexes() {{
+      /** @type {{number[]}} */
+      const result = [];
+      for (let i = start; i < end; i++) result.push(i);
+      return result;
+    }},
+    keys() {{
+      return this.indexes();
+    }},
+    entries() {{
+      /** @type {{Array<[number, T]>}} */
+      const result = [];
+      for (let i = 0; i < data.length; i++) result.push([start + i, data[i]]);
+      return result;
+    }},
+    toMap() {{
+      /** @type {{Map<number, T>}} */
+      const map = new Map();
+      for (let i = 0; i < data.length; i++) map.set(start + i, data[i]);
+      return map;
+    }},
+    *[Symbol.iterator]() {{
+      for (let i = 0; i < data.length; i++) yield /** @type {{[number, T]}} */ ([start + i, data[i]]);
+    }},
+    // DateSeriesData methods (only meaningful for date-based indexes)
+    dates() {{
+      /** @type {{globalThis.Date[]}} */
+      const result = [];
+      for (let i = start; i < end; i++) result.push(indexToDate(index, i));
+      return result;
+    }},
+    dateEntries() {{
+      /** @type {{Array<[globalThis.Date, T]>}} */
+      const result = [];
+      for (let i = 0; i < data.length; i++) result.push([indexToDate(index, start + i), data[i]]);
+      return result;
+    }},
+    toDateMap() {{
+      /** @type {{Map<globalThis.Date, T>}} */
+      const map = new Map();
+      for (let i = 0; i < data.length; i++) map.set(indexToDate(index, start + i), data[i]);
+      return map;
+    }},
+  }});
+}}
+
+/**
+ * @template T
+ * @typedef {{Object}} SeriesDataBase
+ * @property {{number}} version - Version of the series data
+ * @property {{Index}} index - The index type used for this query
+ * @property {{string}} type - Value type (e.g. "f32", "u64", "Sats")
+ * @property {{number}} total - Total number of data points
+ * @property {{number}} start - Start index (inclusive)
+ * @property {{number}} end - End index (exclusive)
+ * @property {{string}} stamp - ISO 8601 timestamp of when the response was generated
+ * @property {{T[]}} data - The series data
+ * @property {{boolean}} isDateBased - Whether this series uses a date-based index
+ * @property {{() => number[]}} indexes - Get index numbers
+ * @property {{() => number[]}} keys - Get keys as index numbers (alias for indexes)
+ * @property {{() => Array<[number, T]>}} entries - Get [index, value] pairs
+ * @property {{() => Map<number, T>}} toMap - Convert to Map<index, value>
+ */
+
+/** @template T @typedef {{SeriesDataBase<T> & Iterable<[number, T]>}} SeriesData */
+
+/**
+ * @template T
+ * @typedef {{Object}} DateSeriesDataExtras
+ * @property {{() => globalThis.Date[]}} dates - Get dates for each data point
+ * @property {{() => Array<[globalThis.Date, T]>}} dateEntries - Get [date, value] pairs
+ * @property {{() => Map<globalThis.Date, T>}} toDateMap - Convert to Map<date, value>
+ */
+
+/** @template T @typedef {{SeriesData<T> & DateSeriesDataExtras<T>}} DateSeriesData */
+/** @typedef {{SeriesData<any>}} AnySeriesData */
+
+/** @template T @typedef {{(onfulfilled?: (value: SeriesData<T>) => any, onrejected?: (reason: Error) => never) => Promise<SeriesData<T>>}} Thenable */
+/** @template T @typedef {{(onfulfilled?: (value: DateSeriesData<T>) => any, onrejected?: (reason: Error) => never) => Promise<DateSeriesData<T>>}} DateThenable */
+
+/**
+ * @template T
+ * @typedef {{Object}} SeriesEndpoint
+ * @property {{(index: number) => SingleItemBuilder<T>}} get - Get single item at index
+ * @property {{(start?: number, end?: number) => RangeBuilder<T>}} slice - Slice by index
+ * @property {{(n: number) => RangeBuilder<T>}} first - Get first n items
+ * @property {{(n: number) => RangeBuilder<T>}} last - Get last n items
+ * @property {{(n: number) => SkippedBuilder<T>}} skip - Skip first n items, chain with take()
+ * @property {{(onUpdate?: (value: SeriesData<T>) => void) => Promise<SeriesData<T>>}} fetch - Fetch all data
+ * @property {{() => Promise<string>}} fetchCsv - Fetch all data as CSV
+ * @property {{Thenable<T>}} then - Thenable (await endpoint)
+ * @property {{string}} path - The endpoint path
+ */
+
+/**
+ * @template T
+ * @typedef {{Object}} DateSeriesEndpoint
+ * @property {{(index: number | globalThis.Date) => DateSingleItemBuilder<T>}} get - Get single item at index or Date
+ * @property {{(start?: number | globalThis.Date, end?: number | globalThis.Date) => DateRangeBuilder<T>}} slice - Slice by index or Date
+ * @property {{(n: number) => DateRangeBuilder<T>}} first - Get first n items
+ * @property {{(n: number) => DateRangeBuilder<T>}} last - Get last n items
+ * @property {{(n: number) => DateSkippedBuilder<T>}} skip - Skip first n items, chain with take()
+ * @property {{(onUpdate?: (value: DateSeriesData<T>) => void) => Promise<DateSeriesData<T>>}} fetch - Fetch all data
+ * @property {{() => Promise<string>}} fetchCsv - Fetch all data as CSV
+ * @property {{DateThenable<T>}} then - Thenable (await endpoint)
+ * @property {{string}} path - The endpoint path
+ */
+
+/** @typedef {{SeriesEndpoint<any>}} AnySeriesEndpoint */
+
+/** @template T @typedef {{Object}} SingleItemBuilder
+ * @property {{(onUpdate?: (value: SeriesData<T>) => void) => Promise<SeriesData<T>>}} fetch - Fetch the item
+ * @property {{() => Promise<string>}} fetchCsv - Fetch as CSV
+ * @property {{Thenable<T>}} then - Thenable
+ */
+
+/** @template T @typedef {{Object}} DateSingleItemBuilder
+ * @property {{(onUpdate?: (value: DateSeriesData<T>) => void) => Promise<DateSeriesData<T>>}} fetch - Fetch the item
+ * @property {{() => Promise<string>}} fetchCsv - Fetch as CSV
+ * @property {{DateThenable<T>}} then - Thenable
+ */
+
+/** @template T @typedef {{Object}} SkippedBuilder
+ * @property {{(n: number) => RangeBuilder<T>}} take - Take n items after skipped position
+ * @property {{(onUpdate?: (value: SeriesData<T>) => void) => Promise<SeriesData<T>>}} fetch - Fetch from skipped position to end
+ * @property {{() => Promise<string>}} fetchCsv - Fetch as CSV
+ * @property {{Thenable<T>}} then - Thenable
+ */
+
+/** @template T @typedef {{Object}} DateSkippedBuilder
+ * @property {{(n: number) => DateRangeBuilder<T>}} take - Take n items after skipped position
+ * @property {{(onUpdate?: (value: DateSeriesData<T>) => void) => Promise<DateSeriesData<T>>}} fetch - Fetch from skipped position to end
+ * @property {{() => Promise<string>}} fetchCsv - Fetch as CSV
+ * @property {{DateThenable<T>}} then - Thenable
+ */
+
+/** @template T @typedef {{Object}} RangeBuilder
+ * @property {{(onUpdate?: (value: SeriesData<T>) => void) => Promise<SeriesData<T>>}} fetch - Fetch the range
+ * @property {{() => Promise<string>}} fetchCsv - Fetch as CSV
+ * @property {{Thenable<T>}} then - Thenable
+ */
+
+/** @template T @typedef {{Object}} DateRangeBuilder
+ * @property {{(onUpdate?: (value: DateSeriesData<T>) => void) => Promise<DateSeriesData<T>>}} fetch - Fetch the range
+ * @property {{() => Promise<string>}} fetchCsv - Fetch as CSV
+ * @property {{DateThenable<T>}} then - Thenable
+ */
+
+/**
+ * @template T
+ * @typedef {{Object}} SeriesPattern
+ * @property {{string}} name - The series name
+ * @property {{Readonly<Partial<Record<Index, SeriesEndpoint<T>>>>}} by - Index endpoints as lazy getters
+ * @property {{() => readonly Index[]}} indexes - Get the list of available indexes
+ * @property {{(index: Index) => SeriesEndpoint<T>|undefined}} get - Get an endpoint for a specific index
+ */
+
+/** @typedef {{SeriesPattern<any>}} AnySeriesPattern */
+
+/**
+ * Create a series endpoint builder with typestate pattern.
+ * @template T
+ * @param {{BrkClientBase}} client
+ * @param {{string}} name - The series vec name
+ * @param {{Index}} index - The index name
+ * @returns {{DateSeriesEndpoint<T>}}
+ */
+function _endpoint(client, name, index) {{
+  const p = `/api/series/${{name}}/${{index}}`;
+
+  /**
+   * @param {{number}} [start]
+   * @param {{number}} [end]
+   * @param {{string}} [format]
+   * @returns {{string}}
+   */
+  const buildPath = (start, end, format) => {{
+    const params = new URLSearchParams();
+    if (start !== undefined) params.set('start', String(start));
+    if (end !== undefined) params.set('end', String(end));
+    if (format) params.set('format', format);
+    const query = params.toString();
+    return query ? `${{p}}?${{query}}` : p;
+  }};
+
+  /**
+   * @param {{number}} [start]
+   * @param {{number}} [end]
+   * @returns {{DateRangeBuilder<T>}}
+   */
+  const rangeBuilder = (start, end) => ({{
+    fetch(onUpdate) {{ return client._fetchSeriesData(buildPath(start, end), onUpdate); }},
+    fetchCsv() {{ return client.getText(buildPath(start, end, 'csv')); }},
+    then(resolve, reject) {{ return this.fetch().then(resolve, reject); }},
+  }});
+
+  /**
+   * @param {{number}} idx
+   * @returns {{DateSingleItemBuilder<T>}}
+   */
+  const singleItemBuilder = (idx) => ({{
+    fetch(onUpdate) {{ return client._fetchSeriesData(buildPath(idx, idx + 1), onUpdate); }},
+    fetchCsv() {{ return client.getText(buildPath(idx, idx + 1, 'csv')); }},
+    then(resolve, reject) {{ return this.fetch().then(resolve, reject); }},
+  }});
+
+  /**
+   * @param {{number}} start
+   * @returns {{DateSkippedBuilder<T>}}
+   */
+  const skippedBuilder = (start) => ({{
+    take(n) {{ return rangeBuilder(start, start + n); }},
+    fetch(onUpdate) {{ return client._fetchSeriesData(buildPath(start, undefined), onUpdate); }},
+    fetchCsv() {{ return client.getText(buildPath(start, undefined, 'csv')); }},
+    then(resolve, reject) {{ return this.fetch().then(resolve, reject); }},
+  }});
+
+  /** @type {{DateSeriesEndpoint<T>}} */
+  const endpoint = {{
+    get(idx) {{ if (idx instanceof Date) idx = dateToIndex(index, idx); return singleItemBuilder(idx); }},
+    slice(start, end) {{
+      if (start instanceof Date) start = dateToIndex(index, start);
+      if (end instanceof Date) end = dateToIndex(index, end);
+      return rangeBuilder(start, end);
+    }},
+    first(n) {{ return rangeBuilder(undefined, n); }},
+    last(n) {{ return n === 0 ? rangeBuilder(undefined, 0) : rangeBuilder(-n, undefined); }},
+    skip(n) {{ return skippedBuilder(n); }},
+    fetch(onUpdate) {{ return client._fetchSeriesData(buildPath(), onUpdate); }},
+    fetchCsv() {{ return client.getText(buildPath(undefined, undefined, 'csv')); }},
+    then(resolve, reject) {{ return this.fetch().then(resolve, reject); }},
+    get path() {{ return p; }},
+  }};
+
+  return endpoint;
+}}
+
+/**
+ * Base HTTP client for making requests with caching support
+ */
+class BrkClientBase {{
+  /**
+   * @param {{BrkClientOptions|string}} options
+   */
+  constructor(options) {{
+    const isString = typeof options === 'string';
+    const rawUrl = isString ? options : options.baseUrl;
+    this.baseUrl = rawUrl.endsWith('/') ? rawUrl.slice(0, -1) : rawUrl;
+    this.timeout = isString ? 5000 : (options.timeout ?? 5000);
+    /** @type {{Promise<Cache | null>}} */
+    this._cachePromise = _openCache(isString ? undefined : options.cache);
+    /** @type {{Cache | null}} */
+    this._cache = null;
+    this._cachePromise.then(c => this._cache = c);
+  }}
+
+  /**
+   * @param {{string}} path
+   * @returns {{Promise<Response>}}
+   */
+  async get(path) {{
+    const url = `${{this.baseUrl}}${{path}}`;
+    const res = await fetch(url, {{ signal: AbortSignal.timeout(this.timeout) }});
+    if (!res.ok) throw new BrkError(`HTTP ${{res.status}}: ${{url}}`, res.status);
+    return res;
+  }}
+
+  /**
+   * Make a GET request - races cache vs network, first to resolve calls onUpdate
+   * @template T
+   * @param {{string}} path
+   * @param {{(value: T) => void}} [onUpdate] - Called when data is available (may be called twice: cache then network)
+   * @returns {{Promise<T>}}
+   */
+  async getJson(path, onUpdate) {{
+    const url = `${{this.baseUrl}}${{path}}`;
+    const cache = this._cache ?? await this._cachePromise;
+
+    let resolved = false;
+    /** @type {{Response | null}} */
+    let cachedRes = null;
+
+    // Race cache vs network - first to resolve calls onUpdate
+    const cachePromise = cache?.match(url).then(async (res) => {{
+      cachedRes = res ?? null;
+      if (!res) return null;
+      const json = _addCamelGetters(await res.json());
+      if (!resolved && onUpdate) {{
+        resolved = true;
+        onUpdate(json);
+      }}
+      return json;
+    }});
+
+    const networkPromise = this.get(path).then(async (res) => {{
+      const cloned = res.clone();
+      const json = _addCamelGetters(await res.json());
+      // Skip update if ETag matches and cache already delivered
+      if (cachedRes?.headers.get('ETag') === res.headers.get('ETag')) {{
+        if (!resolved && onUpdate) {{
+          resolved = true;
+          onUpdate(json);
+        }}
+        return json;
+      }}
+      resolved = true;
+      if (onUpdate) {{
+        onUpdate(json);
+      }}
+      if (cache) _runIdle(() => cache.put(url, cloned));
+      return json;
+    }});
+
+    try {{
+      return await networkPromise;
+    }} catch (e) {{
+      // Network failed - wait for cache
+      const cachedJson = await cachePromise?.catch(() => null);
+      if (cachedJson) return cachedJson;
+      throw e;
+    }}
+  }}
+
+  /**
+   * Make a GET request and return raw text (for CSV responses)
+   * @param {{string}} path
+   * @returns {{Promise<string>}}
+   */
+  async getText(path) {{
+    const res = await this.get(path);
+    return res.text();
+  }}
+
+  /**
+   * Fetch series data and wrap with helper methods (internal)
+   * @template T
+   * @param {{string}} path
+   * @param {{(value: DateSeriesData<T>) => void}} [onUpdate]
+   * @returns {{Promise<DateSeriesData<T>>}}
+   */
+  async _fetchSeriesData(path, onUpdate) {{
+    const wrappedOnUpdate = onUpdate ? (/** @type {{SeriesData<T>}} */ raw) => onUpdate(_wrapSeriesData(raw)) : undefined;
+    const raw = await this.getJson(path, wrappedOnUpdate);
+    return _wrapSeriesData(raw);
+  }}
+}}
+
+/**
+ * Build series name with suffix.
+ * @param {{string}} acc - Accumulated prefix
+ * @param {{string}} s - Series suffix
+ * @returns {{string}}
+ */
+const _m = (acc, s) => s ? (acc ? `${{acc}}_${{s}}` : s) : acc;
+
+/**
+ * Build series name with prefix.
+ * @param {{string}} prefix - Prefix to prepend
+ * @param {{string}} acc - Accumulated name
+ * @returns {{string}}
+ */
+const _p = (prefix, acc) => acc ? `${{prefix}}_${{acc}}` : prefix;
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate static constants for the BrkClient class.
+pub fn generate_static_constants(output: &mut String) {
+    let constants = ClientConstants::collect();
+
+    // VERSION, INDEXES, POOL_ID_TO_POOL_NAME
+    writeln!(output, "  VERSION = \"{}\";\n", constants.version).unwrap();
+    write_static_const(output, "INDEXES", &format_json(&constants.indexes));
+    write_static_const(
+        output,
+        "POOL_ID_TO_POOL_NAME",
+        &format_json(&constants.pool_map),
+    );
+
+    // Cohort constants with camelCase keys
+    for (name, value) in CohortConstants::all() {
+        write_static_const(output, name, &format_json(&camel_case_keys(value)));
+    }
+
+    // Helper methods
+    writeln!(
+        output,
+        r#"  /**
+   * Convert an index value to a Date for date-based indexes.
+   * @param {{Index}} index - The index type
+   * @param {{number}} i - The index value
+   * @returns {{globalThis.Date}}
+   */
+  indexToDate(index, i) {{
+    return indexToDate(index, i);
+  }}
+
+  /**
+   * Convert a Date to an index value for date-based indexes.
+   * @param {{Index}} index - The index type
+   * @param {{globalThis.Date}} d - The date to convert
+   * @returns {{number}}
+   */
+  dateToIndex(index, d) {{
+    return dateToIndex(index, d);
+  }}
+
+"#
+    )
+    .unwrap();
+}
+
+fn indent_json_const(json: &str) -> String {
+    json.lines()
+        .enumerate()
+        .map(|(i, line)| {
+            if i == 0 {
+                line.to_string()
+            } else {
+                format!("  {}", line)
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn write_static_const(output: &mut String, name: &str, json: &str) {
+    writeln!(
+        output,
+        "  {} = /** @type {{const}} */ ({});\n",
+        name,
+        indent_json_const(json)
+    )
+    .unwrap();
+}
+
+/// Generate index accessor factory functions.
+pub fn generate_index_accessors(output: &mut String, patterns: &[IndexSetPattern]) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Index group constants and factory\n").unwrap();
+
+    // Generate index array constants (e.g., _i1 = ["day1", "height"])
+    for (i, pattern) in patterns.iter().enumerate() {
+        write!(output, "const _i{} = /** @type {{const}} */ ([", i + 1).unwrap();
+        for (j, index) in pattern.indexes.iter().enumerate() {
+            if j > 0 {
+                write!(output, ", ").unwrap();
+            }
+            write!(output, "\"{}\"", index.name()).unwrap();
+        }
+        writeln!(output, "]);").unwrap();
+    }
+    writeln!(output).unwrap();
+
+    // Generate ONE generic series pattern factory
+    writeln!(
+        output,
+        r#"/**
+ * Generic series pattern factory.
+ * @template T
+ * @param {{BrkClientBase}} client
+ * @param {{string}} name - The series vec name
+ * @param {{readonly Index[]}} indexes - The supported indexes
+ */
+function _mp(client, name, indexes) {{
+  const by = {{}};
+  for (const idx of indexes) {{
+    Object.defineProperty(by, idx, {{
+      get() {{ return _endpoint(client, name, idx); }},
+      enumerable: true,
+      configurable: true
+    }});
+  }}
+  return {{
+    name,
+    by,
+    /** @returns {{readonly Index[]}} */
+    indexes() {{ return indexes; }},
+    /** @param {{Index}} index @returns {{SeriesEndpoint<T>|undefined}} */
+    get(index) {{ return indexes.includes(index) ? _endpoint(client, name, index) : undefined; }}
+  }};
+}}
+"#
+    )
+    .unwrap();
+
+    // Generate typedefs and thin wrapper functions
+    for (i, pattern) in patterns.iter().enumerate() {
+        // Generate typedef for type safety
+        let by_fields: Vec<String> = pattern
+            .indexes
+            .iter()
+            .map(|idx| {
+                let builder = if idx.is_date_based() {
+                    "DateSeriesEndpoint"
+                } else {
+                    "SeriesEndpoint"
+                };
+                format!("readonly {}: {}<T>", idx.name(), builder)
+            })
+            .collect();
+        let by_type = format!("{{ {} }}", by_fields.join(", "));
+
+        writeln!(
+            output,
+            "/** @template T @typedef {{{{ name: string, by: {}, indexes: () => readonly Index[], get: (index: Index) => SeriesEndpoint<T>|undefined }}}} {} */",
+            by_type, pattern.name
+        )
+        .unwrap();
+
+        // Generate thin wrapper that calls the generic factory
+        writeln!(
+            output,
+            "/** @template T @param {{BrkClientBase}} client @param {{string}} name @returns {{{}<T>}} */",
+            pattern.name
+        )
+        .unwrap();
+        writeln!(
+            output,
+            "function create{}(client, name) {{ return /** @type {{{}<T>}} */ (_mp(client, name, _i{})); }}",
+            pattern.name,
+            pattern.name,
+            i + 1
+        )
+        .unwrap();
+    }
+    writeln!(output).unwrap();
+}
+
+/// Generate structural pattern factory functions.
+pub fn generate_structural_patterns(
+    output: &mut String,
+    patterns: &[StructuralPattern],
+    metadata: &ClientMetadata,
+) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Reusable structural pattern factories\n").unwrap();
+
+    for pattern in patterns {
+        // Generate typedef
+        writeln!(output, "/**").unwrap();
+        if pattern.is_generic {
+            writeln!(output, " * @template T").unwrap();
+        }
+        writeln!(output, " * @typedef {{Object}} {}", pattern.name).unwrap();
+        for field in &pattern.fields {
+            let js_type = metadata.field_type_annotation(
+                field,
+                pattern.is_generic,
+                None,
+                GenericSyntax::JAVASCRIPT,
+            );
+            writeln!(
+                output,
+                " * @property {{{}}} {}",
+                js_type,
+                to_camel_case(&field.name)
+            )
+            .unwrap();
+        }
+        writeln!(output, " */\n").unwrap();
+
+        // Skip factory for non-parameterizable patterns (inlined at tree level)
+        if !metadata.is_parameterizable(&pattern.name) {
+            continue;
+        }
+
+        writeln!(output, "/**").unwrap();
+        writeln!(output, " * Create a {} pattern node", pattern.name).unwrap();
+        if pattern.is_generic {
+            writeln!(output, " * @template T").unwrap();
+        }
+        writeln!(output, " * @param {{BrkClientBase}} client").unwrap();
+        writeln!(output, " * @param {{string}} acc - Accumulated series name").unwrap();
+        if pattern.is_templated() {
+            writeln!(output, " * @param {{string}} disc - Discriminator suffix").unwrap();
+        }
+        let return_type = if pattern.is_generic {
+            format!("{}<T>", pattern.name)
+        } else {
+            pattern.name.clone()
+        };
+        writeln!(output, " * @returns {{{}}}", return_type).unwrap();
+        writeln!(output, " */").unwrap();
+
+        if pattern.is_templated() {
+            writeln!(
+                output,
+                "function create{}(client, acc, disc) {{",
+                pattern.name
+            )
+            .unwrap();
+        } else {
+            writeln!(output, "function create{}(client, acc) {{", pattern.name).unwrap();
+        }
+        writeln!(output, "  return {{").unwrap();
+
+        let syntax = JavaScriptSyntax;
+        for field in &pattern.fields {
+            generate_parameterized_field(output, &syntax, field, pattern, metadata, "    ");
+        }
+
+        writeln!(output, "  }};").unwrap();
+        writeln!(output, "}}\n").unwrap();
+    }
+}
@@ -0,0 +1,66 @@
+//! JavaScript client generation.
+//!
+//! This module generates a JavaScript + JSDoc client for the BRK API.
+
+mod api;
+pub mod client;
+pub mod tree;
+pub mod types;
+
+use std::{fmt::Write, fs, io, path::Path};
+
+use serde_json::json;
+
+use super::write_if_changed;
+use crate::{ClientMetadata, Endpoint, TypeSchemas, VERSION};
+
+/// Generate JavaScript + JSDoc client from metadata and OpenAPI endpoints.
+///
+/// `output_path` is the full path to the output file (e.g., "modules/brk-client/index.js").
+pub fn generate_javascript_client(
+    metadata: &ClientMetadata,
+    endpoints: &[Endpoint],
+    schemas: &TypeSchemas,
+    output_path: &Path,
+) -> io::Result<()> {
+    let mut output = String::new();
+
+    writeln!(output, "// Auto-generated BRK JavaScript client").unwrap();
+    writeln!(output, "// Do not edit manually\n").unwrap();
+
+    types::generate_type_definitions(&mut output, schemas);
+    client::generate_base_client(&mut output);
+    client::generate_index_accessors(&mut output, &metadata.index_set_patterns);
+    client::generate_structural_patterns(&mut output, &metadata.structural_patterns, metadata);
+    tree::generate_tree_typedefs(&mut output, &metadata.catalog, metadata);
+    tree::generate_main_client(&mut output, &metadata.catalog, metadata, endpoints);
+
+    write_if_changed(output_path, &output)?;
+
+    // Update package.json version if it exists in the same directory
+    if let Some(parent) = output_path.parent() {
+        let package_json_path = parent.join("package.json");
+        if package_json_path.exists() {
+            update_package_json_version(&package_json_path)?;
+        }
+    }
+
+    Ok(())
+}
+
+fn update_package_json_version(package_json_path: &Path) -> io::Result<()> {
+    let content = fs::read_to_string(package_json_path)?;
+    let mut package: serde_json::Value = serde_json::from_str(&content)
+        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+
+    if let Some(obj) = package.as_object_mut() {
+        obj.insert("version".to_string(), json!(VERSION));
+    }
+
+    let updated = serde_json::to_string_pretty(&package)
+        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+
+    write_if_changed(package_json_path, &(updated + "\n"))?;
+
+    Ok(())
+}
@@ -0,0 +1,228 @@
+//! JavaScript tree structure generation.
+
+use std::collections::BTreeSet;
+use std::fmt::Write;
+
+use brk_types::TreeNode;
+
+use crate::{
+    ClientMetadata, Endpoint, GenericSyntax, JavaScriptSyntax, PatternField, build_child_path,
+    generate_leaf_field, generate_tree_node_field, prepare_tree_node, to_camel_case,
+};
+
+use super::api::generate_api_methods;
+use super::client::generate_static_constants;
+
+/// Generate JSDoc typedefs for the series tree.
+pub fn generate_tree_typedefs(output: &mut String, catalog: &TreeNode, metadata: &ClientMetadata) {
+    writeln!(output, "// Catalog tree typedefs\n").unwrap();
+
+    let pattern_lookup = metadata.pattern_lookup();
+    let mut generated = BTreeSet::new();
+    generate_tree_typedef(
+        output,
+        "SeriesTree",
+        "",
+        catalog,
+        pattern_lookup,
+        metadata,
+        &mut generated,
+    );
+}
+
+fn generate_tree_typedef(
+    output: &mut String,
+    name: &str,
+    path: &str,
+    node: &TreeNode,
+    pattern_lookup: &std::collections::BTreeMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+    generated: &mut BTreeSet<String>,
+) {
+    let Some(ctx) = prepare_tree_node(node, name, path, pattern_lookup, metadata, generated) else {
+        return;
+    };
+
+    writeln!(output, "/**").unwrap();
+    writeln!(output, " * @typedef {{Object}} {}", name).unwrap();
+
+    for child in &ctx.children {
+        let js_type = if child.should_inline {
+            child.inline_type_name.clone()
+        } else {
+            metadata.field_type_annotation(&child.field, false, None, GenericSyntax::JAVASCRIPT)
+        };
+
+        writeln!(
+            output,
+            " * @property {{{}}} {}",
+            js_type,
+            to_camel_case(&child.field.name)
+        )
+        .unwrap();
+    }
+
+    writeln!(output, " */\n").unwrap();
+
+    // Generate child typedefs
+    for child in &ctx.children {
+        if child.should_inline {
+            let child_path = build_child_path(path, child.name);
+            generate_tree_typedef(
+                output,
+                &child.inline_type_name,
+                &child_path,
+                child.node,
+                pattern_lookup,
+                metadata,
+                generated,
+            );
+        }
+    }
+}
+
+/// Generate the main BrkClient class.
+pub fn generate_main_client(
+    output: &mut String,
+    catalog: &TreeNode,
+    metadata: &ClientMetadata,
+    endpoints: &[Endpoint],
+) {
+    let pattern_lookup = metadata.pattern_lookup();
+
+    writeln!(output, "/**").unwrap();
+    writeln!(
+        output,
+        " * Main BRK client with series tree and API methods"
+    )
+    .unwrap();
+    writeln!(output, " * @extends BrkClientBase").unwrap();
+    writeln!(output, " */").unwrap();
+    writeln!(output, "class BrkClient extends BrkClientBase {{").unwrap();
+
+    generate_static_constants(output);
+
+    writeln!(output, "  /**").unwrap();
+    writeln!(output, "   * @param {{BrkClientOptions|string}} options").unwrap();
+    writeln!(output, "   */").unwrap();
+    writeln!(output, "  constructor(options) {{").unwrap();
+    writeln!(output, "    super(options);").unwrap();
+    writeln!(output, "    /** @type {{SeriesTree}} */").unwrap();
+    writeln!(output, "    this.series = this._buildTree('');").unwrap();
+    writeln!(output, "  }}\n").unwrap();
+
+    writeln!(output, "  /**").unwrap();
+    writeln!(output, "   * @private").unwrap();
+    writeln!(output, "   * @param {{string}} basePath").unwrap();
+    writeln!(output, "   * @returns {{SeriesTree}}").unwrap();
+    writeln!(output, "   */").unwrap();
+    writeln!(output, "  _buildTree(basePath) {{").unwrap();
+    writeln!(output, "    return {{").unwrap();
+    let mut generated = BTreeSet::new();
+    generate_tree_initializer(
+        output,
+        catalog,
+        "SeriesTree",
+        "",
+        3,
+        pattern_lookup,
+        metadata,
+        &mut generated,
+    );
+    writeln!(output, "    }};").unwrap();
+    writeln!(output, "  }}\n").unwrap();
+
+    writeln!(output, "  /**").unwrap();
+    writeln!(
+        output,
+        "   * Create a dynamic series endpoint builder for any series/index combination."
+    )
+    .unwrap();
+    writeln!(output, "   *").unwrap();
+    writeln!(
+        output,
+        "   * Use this for programmatic access when the series name is determined at runtime."
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "   * For type-safe access, use the `series` tree instead."
+    )
+    .unwrap();
+    writeln!(output, "   *").unwrap();
+    writeln!(output, "   * @param {{string}} series - The series name").unwrap();
+    writeln!(output, "   * @param {{Index}} index - The index name").unwrap();
+    writeln!(output, "   * @returns {{SeriesEndpoint<unknown>}}").unwrap();
+    writeln!(output, "   */").unwrap();
+    writeln!(output, "  seriesEndpoint(series, index) {{").unwrap();
+    writeln!(output, "    return _endpoint(this, series, index);").unwrap();
+    writeln!(output, "  }}\n").unwrap();
+
+    generate_api_methods(output, endpoints);
+
+    writeln!(output, "}}\n").unwrap();
+
+    writeln!(output, "export {{ BrkClient, BrkError }};").unwrap();
+}
+
+#[allow(clippy::too_many_arguments)]
+fn generate_tree_initializer(
+    output: &mut String,
+    node: &TreeNode,
+    name: &str,
+    path: &str,
+    indent: usize,
+    pattern_lookup: &std::collections::BTreeMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+    generated: &mut BTreeSet<String>,
+) {
+    let indent_str = "  ".repeat(indent);
+
+    let Some(ctx) = prepare_tree_node(node, name, path, pattern_lookup, metadata, generated) else {
+        return;
+    };
+
+    let syntax = JavaScriptSyntax;
+    for child in &ctx.children {
+        let field_name = to_camel_case(child.name);
+
+        if child.is_leaf {
+            if let TreeNode::Leaf(leaf) = child.node {
+                generate_leaf_field(
+                    output,
+                    &syntax,
+                    "this",
+                    child.name,
+                    leaf,
+                    metadata,
+                    &indent_str,
+                );
+            }
+        } else if child.should_inline {
+            // Inline object
+            let child_path = build_child_path(path, child.name);
+            writeln!(output, "{}{}: {{", indent_str, field_name).unwrap();
+            generate_tree_initializer(
+                output,
+                child.node,
+                &child.inline_type_name,
+                &child_path,
+                indent + 1,
+                pattern_lookup,
+                metadata,
+                generated,
+            );
+            writeln!(output, "{}}},", indent_str).unwrap();
+        } else {
+            generate_tree_node_field(
+                output,
+                &syntax,
+                &child.field,
+                metadata,
+                &indent_str,
+                "this",
+                &child.base_result,
+            );
+        }
+    }
+}
@@ -0,0 +1,201 @@
+//! JavaScript type definitions generation.
+
+use std::fmt::Write;
+
+use serde_json::Value;
+
+use crate::{
+    TypeSchemas,
+    generators::{MANUAL_GENERIC_TYPES, write_description},
+    get_union_variants, ref_to_type_name, to_camel_case,
+};
+
+/// Generate JSDoc type definitions from OpenAPI schemas.
+pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
+    if schemas.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Type definitions\n").unwrap();
+
+    for (name, schema) in schemas {
+        if MANUAL_GENERIC_TYPES.contains(&name.as_str()) {
+            continue;
+        }
+
+        let js_type = schema_to_js_type(schema, Some(name));
+
+        let type_desc = schema.get("description").and_then(|d| d.as_str());
+
+        if is_primitive_alias(schema) {
+            if let Some(desc) = type_desc {
+                writeln!(output, "/**").unwrap();
+                write_description(output, desc, " * ", " *");
+                writeln!(output, " *").unwrap();
+                writeln!(output, " * @typedef {{{}}} {}", js_type, name).unwrap();
+                writeln!(output, " */").unwrap();
+            } else {
+                writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
+            }
+        } else if let Some(props) = schema.get("properties").and_then(|p| p.as_object()) {
+            writeln!(output, "/**").unwrap();
+            if let Some(desc) = type_desc {
+                write_description(output, desc, " * ", " *");
+                writeln!(output, " *").unwrap();
+            }
+            writeln!(output, " * @typedef {{Object}} {}", name).unwrap();
+            for (prop_name, prop_schema) in props {
+                let prop_type = schema_to_js_type(prop_schema, Some(name));
+                let required = schema
+                    .get("required")
+                    .and_then(|r| r.as_array())
+                    .map(|arr| arr.iter().any(|v| v.as_str() == Some(prop_name)))
+                    .unwrap_or(false);
+                let optional = if required { "" } else { "=" };
+                let safe_name = to_camel_case(prop_name);
+                let prop_desc = prop_schema
+                    .get("description")
+                    .and_then(|d| d.as_str())
+                    .map(|d| format!(" - {}", d))
+                    .unwrap_or_default();
+                writeln!(
+                    output,
+                    " * @property {{{}{}}} {}{}",
+                    prop_type, optional, safe_name, prop_desc
+                )
+                .unwrap();
+            }
+            writeln!(output, " */").unwrap();
+        } else if let Some(desc) = type_desc {
+            writeln!(output, "/**").unwrap();
+            write_description(output, desc, " * ", " *");
+            writeln!(output, " *").unwrap();
+            writeln!(output, " * @typedef {{{}}} {}", js_type, name).unwrap();
+            writeln!(output, " */").unwrap();
+        } else {
+            writeln!(output, "/** @typedef {{{}}} {} */", js_type, name).unwrap();
+        }
+    }
+    writeln!(output).unwrap();
+}
+
+fn is_primitive_alias(schema: &Value) -> bool {
+    schema.get("properties").is_none()
+        && schema.get("items").is_none()
+        && schema.get("anyOf").is_none()
+        && schema.get("oneOf").is_none()
+        && schema.get("enum").is_none()
+}
+
+fn json_type_to_js(ty: &str, schema: &Value, current_type: Option<&str>) -> String {
+    match ty {
+        "integer" | "number" => "number".to_string(),
+        "boolean" => "boolean".to_string(),
+        "string" => "string".to_string(),
+        "null" => "null".to_string(),
+        "array" => {
+            let item_type = schema
+                .get("items")
+                .map(|s| schema_to_js_type(s, current_type))
+                .unwrap_or_else(|| "*".to_string());
+            format!("{}[]", item_type)
+        }
+        "object" => {
+            if let Some(add_props) = schema.get("additionalProperties") {
+                let value_type = schema_to_js_type(add_props, current_type);
+                return format!("{{ [key: string]: {} }}", value_type);
+            }
+            "Object".to_string()
+        }
+        _ => "*".to_string(),
+    }
+}
+
+/// Convert a JSON schema to a JavaScript type string.
+pub fn schema_to_js_type(schema: &Value, current_type: Option<&str>) -> String {
+    if let Some(all_of) = schema.get("allOf").and_then(|v| v.as_array()) {
+        for item in all_of {
+            let resolved = schema_to_js_type(item, current_type);
+            if resolved != "*" {
+                return resolved;
+            }
+        }
+    }
+
+    if let Some(ref_path) = schema.get("$ref").and_then(|r| r.as_str()) {
+        return ref_to_type_name(ref_path).unwrap_or("*").to_string();
+    }
+
+    if let Some(enum_values) = schema.get("enum").and_then(|e| e.as_array()) {
+        let literals: Vec<String> = enum_values
+            .iter()
+            .filter_map(|v| v.as_str())
+            .map(|s| format!("\"{}\"", s))
+            .collect();
+        if !literals.is_empty() {
+            return format!("({})", literals.join("|"));
+        }
+    }
+
+    if let Some(ty) = schema.get("type") {
+        if let Some(type_array) = ty.as_array() {
+            let types: Vec<String> = type_array
+                .iter()
+                .filter_map(|t| t.as_str())
+                .filter(|t| *t != "null")
+                .map(|t| json_type_to_js(t, schema, current_type))
+                .collect();
+            let has_null = type_array.iter().any(|t| t.as_str() == Some("null"));
+
+            if types.len() == 1 {
+                let base_type = &types[0];
+                return if has_null {
+                    format!("?{}", base_type)
+                } else {
+                    base_type.clone()
+                };
+            } else if !types.is_empty() {
+                let union = format!("({})", types.join("|"));
+                return if has_null {
+                    format!("?{}", union)
+                } else {
+                    union
+                };
+            }
+        }
+
+        if let Some(ty_str) = ty.as_str() {
+            return json_type_to_js(ty_str, schema, current_type);
+        }
+    }
+
+    if let Some(variants) = get_union_variants(schema) {
+        let types: Vec<String> = variants
+            .iter()
+            .map(|v| schema_to_js_type(v, current_type))
+            .collect();
+        let filtered: Vec<_> = types.iter().filter(|t| *t != "*").collect();
+        if !filtered.is_empty() {
+            return format!(
+                "({})",
+                filtered
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join("|")
+            );
+        }
+        return format!("({})", types.join("|"));
+    }
+
+    if let Some(format) = schema.get("format").and_then(|f| f.as_str()) {
+        return match format {
+            "int32" | "int64" => "number".to_string(),
+            "float" | "double" => "number".to_string(),
+            "date" | "date-time" => "string".to_string(),
+            _ => "*".to_string(),
+        };
+    }
+
+    "*".to_string()
+}
@@ -0,0 +1,54 @@
+//! Code generators for client libraries.
+//!
+//! Each language has its own submodule with focused files:
+//! - `types.rs` - Type definitions
+//! - `client.rs` - Base client and pattern factories
+//! - `tree.rs` - Tree structure generation
+//! - `api.rs` - API method generation
+//! - `mod.rs` - Entry point
+
+use std::{fmt::Write, fs, io, path::Path};
+
+pub mod javascript;
+pub mod python;
+pub mod rust;
+
+pub use javascript::generate_javascript_client;
+pub use python::generate_python_client;
+pub use rust::generate_rust_client;
+
+/// Types that are manually defined as generics in client code, not from schema.
+pub const MANUAL_GENERIC_TYPES: &[&str] = &["SeriesData", "SeriesEndpoint"];
+
+/// Write a multi-line description with the given prefix for each line.
+/// `empty_prefix` is used for blank lines (e.g., "   *" without trailing space).
+pub fn write_description(output: &mut String, desc: &str, prefix: &str, empty_prefix: &str) {
+    for line in desc.lines() {
+        if line.is_empty() {
+            writeln!(output, "{}", empty_prefix).unwrap();
+        } else {
+            writeln!(output, "{}{}", prefix, line).unwrap();
+        }
+    }
+}
+
+/// Replace generic types with their Any variants in return types.
+/// Used by JS and Python generators.
+pub fn normalize_return_type(return_type: &str) -> String {
+    let mut result = return_type.to_string();
+    for type_name in MANUAL_GENERIC_TYPES {
+        result = result.replace(type_name, &format!("Any{}", type_name));
+    }
+    result
+}
+
+/// Write content to a file only if it differs from existing content.
+/// Preserves mtime when unchanged, avoiding unnecessary cargo rebuilds.
+pub fn write_if_changed(path: &Path, content: &str) -> io::Result<()> {
+    if let Ok(existing) = fs::read_to_string(path)
+        && existing == content
+    {
+        return Ok(());
+    }
+    fs::write(path, content)
+}
@@ -0,0 +1,256 @@
+//! Python API method generation.
+
+use std::fmt::Write;
+
+use crate::{
+    Endpoint, Parameter, escape_python_keyword,
+    generators::{normalize_return_type, write_description},
+    to_snake_case,
+};
+
+use super::client::generate_class_constants;
+use super::types::js_type_to_python;
+
+/// Generate the main client class
+pub fn generate_main_client(output: &mut String, endpoints: &[Endpoint]) {
+    writeln!(output, "class BrkClient(BrkClientBase):").unwrap();
+    writeln!(
+        output,
+        "    \"\"\"Main BRK client with series tree and API methods.\"\"\""
+    )
+    .unwrap();
+    writeln!(output).unwrap();
+
+    // Generate class-level constants
+    generate_class_constants(output);
+
+    writeln!(
+        output,
+        "    def __init__(self, base_url: str = 'http://localhost:3000', timeout: float = 30.0):"
+    )
+    .unwrap();
+    writeln!(output, "        super().__init__(base_url, timeout)").unwrap();
+    writeln!(output, "        self.series = SeriesTree(self)").unwrap();
+    writeln!(output).unwrap();
+
+    // Generate series_endpoint() method for dynamic series access
+    writeln!(
+        output,
+        "    def series_endpoint(self, series: str, index: Index) -> SeriesEndpoint[Any]:"
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "        \"\"\"Create a dynamic series endpoint builder for any series/index combination."
+    )
+    .unwrap();
+    writeln!(output).unwrap();
+    writeln!(
+        output,
+        "        Use this for programmatic access when the series name is determined at runtime."
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "        For type-safe access, use the `series` tree instead."
+    )
+    .unwrap();
+    writeln!(output, "        \"\"\"").unwrap();
+    writeln!(output, "        return SeriesEndpoint(self, series, index)").unwrap();
+    writeln!(output).unwrap();
+
+    // Generate helper methods
+    writeln!(
+        output,
+        "    def index_to_date(self, index: Index, i: int) -> Union[date, datetime]:"
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "        \"\"\"Convert an index value to a date/datetime for date-based indexes.\"\"\""
+    )
+    .unwrap();
+    writeln!(output, "        return _index_to_date(index, i)").unwrap();
+    writeln!(output).unwrap();
+    writeln!(
+        output,
+        "    def date_to_index(self, index: Index, d: Union[date, datetime]) -> int:"
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "        \"\"\"Convert a date/datetime to an index value for date-based indexes.\"\"\""
+    )
+    .unwrap();
+    writeln!(output, "        return _date_to_index(index, d)").unwrap();
+    writeln!(output).unwrap();
+    // Generate API methods
+    generate_api_methods(output, endpoints);
+}
+
+/// Generate API methods from OpenAPI endpoints
+pub fn generate_api_methods(output: &mut String, endpoints: &[Endpoint]) {
+    for endpoint in endpoints {
+        if !endpoint.should_generate() {
+            continue;
+        }
+
+        let method_name = endpoint_to_method_name(endpoint);
+        let base_return_type = normalize_return_type(
+            &endpoint
+                .response_type
+                .as_deref()
+                .map(js_type_to_python)
+                .unwrap_or_else(|| "str".to_string()),
+        );
+
+        let return_type = if endpoint.supports_csv {
+            format!("Union[{}, str]", base_return_type)
+        } else {
+            base_return_type
+        };
+
+        // Build method signature
+        let params = build_method_params(endpoint);
+        writeln!(
+            output,
+            "    def {}(self{}) -> {}:",
+            method_name, params, return_type
+        )
+        .unwrap();
+
+        // Docstring
+        match (&endpoint.summary, &endpoint.description) {
+            (Some(summary), Some(desc)) if summary != desc => {
+                writeln!(output, "        \"\"\"{}.", summary.trim_end_matches('.')).unwrap();
+                writeln!(output).unwrap();
+                write_description(output, desc, "        ", "");
+            }
+            (Some(summary), _) => {
+                writeln!(output, "        \"\"\"{}", summary).unwrap();
+            }
+            (None, Some(desc)) => {
+                // First line includes opening quotes
+                let mut lines = desc.lines();
+                if let Some(first) = lines.next() {
+                    writeln!(output, "        \"\"\"{}", first).unwrap();
+                }
+                for line in lines {
+                    if line.is_empty() {
+                        writeln!(output).unwrap();
+                    } else {
+                        writeln!(output, "        {}", line).unwrap();
+                    }
+                }
+            }
+            (None, None) => {
+                write!(output, "        \"\"\"").unwrap();
+            }
+        }
+        writeln!(output).unwrap();
+        writeln!(
+            output,
+            "        Endpoint: `{} {}`\"\"\"",
+            endpoint.method.to_uppercase(),
+            endpoint.path
+        )
+        .unwrap();
+
+        // Build path
+        let path = build_path_template(&endpoint.path, &endpoint.path_params);
+
+        let fetch_method = if endpoint.returns_json() {
+            "get_json"
+        } else {
+            "get_text"
+        };
+
+        if endpoint.query_params.is_empty() {
+            if endpoint.path_params.is_empty() {
+                writeln!(output, "        return self.{}('{}')", fetch_method, path).unwrap();
+            } else {
+                writeln!(output, "        return self.{}(f'{}')", fetch_method, path).unwrap();
+            }
+        } else {
+            writeln!(output, "        params = []").unwrap();
+            for param in &endpoint.query_params {
+                // Use safe name for Python variable, original name for API query parameter
+                let safe_name = escape_python_keyword(&param.name);
+                if param.required {
+                    writeln!(
+                        output,
+                        "        params.append(f'{}={{{}}}')",
+                        param.name, safe_name
+                    )
+                    .unwrap();
+                } else {
+                    writeln!(
+                        output,
+                        "        if {} is not None: params.append(f'{}={{{}}}')",
+                        safe_name, param.name, safe_name
+                    )
+                    .unwrap();
+                }
+            }
+            writeln!(output, "        query = '&'.join(params)").unwrap();
+            writeln!(
+                output,
+                "        path = f'{}{{\"?\" + query if query else \"\"}}'",
+                path
+            )
+            .unwrap();
+
+            if endpoint.supports_csv {
+                writeln!(output, "        if format == 'csv':").unwrap();
+                writeln!(output, "            return self.get_text(path)").unwrap();
+                writeln!(output, "        return self.{}(path)", fetch_method).unwrap();
+            } else {
+                writeln!(output, "        return self.{}(path)", fetch_method).unwrap();
+            }
+        }
+
+        writeln!(output).unwrap();
+    }
+}
+
+fn endpoint_to_method_name(endpoint: &Endpoint) -> String {
+    to_snake_case(&endpoint.operation_name())
+}
+
+fn build_method_params(endpoint: &Endpoint) -> String {
+    let mut params = Vec::new();
+    // Path params are always required
+    for param in &endpoint.path_params {
+        let safe_name = escape_python_keyword(&param.name);
+        let py_type = js_type_to_python(&param.param_type);
+        params.push(format!(", {}: {}", safe_name, py_type));
+    }
+    // Required query params must come before optional ones (Python syntax requirement)
+    for param in &endpoint.query_params {
+        if param.required {
+            let safe_name = escape_python_keyword(&param.name);
+            let py_type = js_type_to_python(&param.param_type);
+            params.push(format!(", {}: {}", safe_name, py_type));
+        }
+    }
+    for param in &endpoint.query_params {
+        if !param.required {
+            let safe_name = escape_python_keyword(&param.name);
+            let py_type = js_type_to_python(&param.param_type);
+            params.push(format!(", {}: Optional[{}] = None", safe_name, py_type));
+        }
+    }
+    params.join("")
+}
+
+fn build_path_template(path: &str, path_params: &[Parameter]) -> String {
+    let mut result = path.to_string();
+    for param in path_params {
+        let placeholder = format!("{{{}}}", param.name);
+        // Use escaped name for Python variable interpolation in f-string
+        let safe_name = escape_python_keyword(&param.name);
+        let interpolation = format!("{{{}}}", safe_name);
+        result = result.replace(&placeholder, &interpolation);
+    }
+    result
+}
@@ -0,0 +1,732 @@
+//! Python base client and pattern factory generation.
+
+use std::fmt::Write;
+
+use crate::{
+    ClientConstants, ClientMetadata, CohortConstants, IndexSetPattern, PythonSyntax,
+    StructuralPattern, format_json, generate_parameterized_field, index_to_field_name,
+};
+
+/// Generate class-level constants for the BrkClient class.
+pub fn generate_class_constants(output: &mut String) {
+    let constants = ClientConstants::collect();
+
+    // VERSION
+    writeln!(output, "    VERSION = \"{}\"\n", constants.version).unwrap();
+
+    // INDEXES, POOL_ID_TO_POOL_NAME
+    write_class_const(output, "INDEXES", &format_json(&constants.indexes));
+    // Python needs string keys for pool map
+    let pool_map: std::collections::BTreeMap<String, &str> = constants
+        .pool_map
+        .iter()
+        .map(|(k, v)| (k.to_string(), *v))
+        .collect();
+    write_class_const(output, "POOL_ID_TO_POOL_NAME", &format_json(&pool_map));
+
+    // Cohort constants (no camelCase conversion for Python)
+    for (name, value) in CohortConstants::all() {
+        write_class_const(output, name, &format_json(&value));
+    }
+}
+
+fn write_class_const(output: &mut String, name: &str, json: &str) {
+    let indented = json
+        .lines()
+        .enumerate()
+        .map(|(i, line)| {
+            if i == 0 {
+                format!("    {} = {}", name, line)
+            } else {
+                format!("    {}", line)
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    writeln!(output, "{}\n", indented).unwrap();
+}
+
+/// Generate the base BrkClient class with HTTP functionality
+pub fn generate_base_client(output: &mut String) {
+    writeln!(
+        output,
+        r#"class BrkError(Exception):
+    """Custom error class for BRK client errors."""
+
+    def __init__(self, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+
+
+class BrkClientBase:
+    """Base HTTP client for making requests."""
+
+    def __init__(self, base_url: str, timeout: float = 30.0):
+        parsed = urlparse(base_url)
+        self._host = parsed.netloc
+        self._secure = parsed.scheme == 'https'
+        self._timeout = timeout
+        self._conn: Optional[Union[HTTPSConnection, HTTPConnection]] = None
+
+    def _connect(self) -> Union[HTTPSConnection, HTTPConnection]:
+        """Get or create HTTP connection."""
+        if self._conn is None:
+            if self._secure:
+                self._conn = HTTPSConnection(self._host, timeout=self._timeout)
+            else:
+                self._conn = HTTPConnection(self._host, timeout=self._timeout)
+        return self._conn
+
+    def get(self, path: str) -> bytes:
+        """Make a GET request and return raw bytes."""
+        try:
+            conn = self._connect()
+            conn.request("GET", path)
+            res = conn.getresponse()
+            data = res.read()
+            if res.status >= 400:
+                raise BrkError(f"HTTP error: {{res.status}}", res.status)
+            return data
+        except (ConnectionError, OSError, TimeoutError) as e:
+            self._conn = None
+            raise BrkError(str(e))
+
+    def get_json(self, path: str) -> Any:
+        """Make a GET request and return JSON."""
+        return json.loads(self.get(path))
+
+    def get_text(self, path: str) -> str:
+        """Make a GET request and return text."""
+        return self.get(path).decode()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def __enter__(self) -> BrkClientBase:
+        return self
+
+    def __exit__(self, exc_type: Optional[type], exc_val: Optional[BaseException], exc_tb: Optional[Any]) -> None:
+        self.close()
+
+
+def _m(acc: str, s: str) -> str:
+    """Build series name with suffix."""
+    if not s: return acc
+    return f"{{acc}}_{{s}}" if acc else s
+
+
+def _p(prefix: str, acc: str) -> str:
+    """Build series name with prefix."""
+    return f"{{prefix}}_{{acc}}" if acc else prefix
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate the SeriesData and SeriesEndpoint classes
+pub fn generate_endpoint_class(output: &mut String) {
+    writeln!(
+        output,
+        r#"# Date conversion constants
+_GENESIS = date(2009, 1, 3)  # day1 0, week1 0
+_DAY_ONE = date(2009, 1, 9)  # day1 1 (6 day gap after genesis)
+_EPOCH = datetime(2009, 1, 1, tzinfo=timezone.utc)
+_DATE_INDEXES = frozenset([
+    'minute10', 'minute30',
+    'hour1', 'hour4', 'hour12',
+    'day1', 'day3', 'week1',
+    'month1', 'month3', 'month6',
+    'year1', 'year10',
+])
+
+def _index_to_date(index: str, i: int) -> Union[date, datetime]:
+    """Convert an index value to a date/datetime for date-based indexes."""
+    if index == 'minute10':
+        return _EPOCH + timedelta(minutes=i * 10)
+    elif index == 'minute30':
+        return _EPOCH + timedelta(minutes=i * 30)
+    elif index == 'hour1':
+        return _EPOCH + timedelta(hours=i)
+    elif index == 'hour4':
+        return _EPOCH + timedelta(hours=i * 4)
+    elif index == 'hour12':
+        return _EPOCH + timedelta(hours=i * 12)
+    elif index == 'day1':
+        return _GENESIS if i == 0 else _DAY_ONE + timedelta(days=i - 1)
+    elif index == 'day3':
+        return _EPOCH.date() - timedelta(days=1) + timedelta(days=i * 3)
+    elif index == 'week1':
+        return _GENESIS + timedelta(weeks=i)
+    elif index == 'month1':
+        return date(2009 + i // 12, i % 12 + 1, 1)
+    elif index == 'month3':
+        m = i * 3
+        return date(2009 + m // 12, m % 12 + 1, 1)
+    elif index == 'month6':
+        m = i * 6
+        return date(2009 + m // 12, m % 12 + 1, 1)
+    elif index == 'year1':
+        return date(2009 + i, 1, 1)
+    elif index == 'year10':
+        return date(2009 + i * 10, 1, 1)
+    else:
+        raise ValueError(f"{{index}} is not a date-based index")
+
+
+def _date_to_index(index: str, d: Union[date, datetime]) -> int:
+    """Convert a date/datetime to an index value for date-based indexes.
+
+    Returns the floor index (latest index whose date is <= the given date).
+    For sub-day indexes (minute*, hour*), a plain date is treated as midnight UTC.
+    """
+    if index in ('minute10', 'minute30', 'hour1', 'hour4', 'hour12'):
+        if isinstance(d, datetime):
+            dt = d if d.tzinfo else d.replace(tzinfo=timezone.utc)
+        else:
+            dt = datetime(d.year, d.month, d.day, tzinfo=timezone.utc)
+        secs = int((dt - _EPOCH).total_seconds())
+        div = {{'minute10': 600, 'minute30': 1800,
+               'hour1': 3600, 'hour4': 14400, 'hour12': 43200}}
+        return secs // div[index]
+    dd = d.date() if isinstance(d, datetime) else d
+    if index == 'day1':
+        if dd < _DAY_ONE:
+            return 0
+        return 1 + (dd - _DAY_ONE).days
+    elif index == 'day3':
+        return (dd - date(2008, 12, 31)).days // 3
+    elif index == 'week1':
+        return (dd - _GENESIS).days // 7
+    elif index == 'month1':
+        return (dd.year - 2009) * 12 + (dd.month - 1)
+    elif index == 'month3':
+        return (dd.year - 2009) * 4 + (dd.month - 1) // 3
+    elif index == 'month6':
+        return (dd.year - 2009) * 2 + (dd.month - 1) // 6
+    elif index == 'year1':
+        return dd.year - 2009
+    elif index == 'year10':
+        return (dd.year - 2009) // 10
+    else:
+        raise ValueError(f"{{index}} is not a date-based index")
+
+
+@dataclass
+class SeriesData(Generic[T]):
+    """Series data with range information. Always int-indexed."""
+    version: int
+    index: Index
+    type: str
+    total: int
+    start: int
+    end: int
+    stamp: str
+    data: List[T]
+
+    @property
+    def is_date_based(self) -> bool:
+        """Whether this series uses a date-based index."""
+        return self.index in _DATE_INDEXES
+
+    def indexes(self) -> List[int]:
+        """Get raw index numbers."""
+        return list(range(self.start, self.end))
+
+    def keys(self) -> List[int]:
+        """Get keys as index numbers."""
+        return self.indexes()
+
+    def items(self) -> List[Tuple[int, T]]:
+        """Get (index, value) pairs."""
+        return list(zip(self.indexes(), self.data))
+
+    def to_dict(self) -> Dict[int, T]:
+        """Return {{index: value}} dict."""
+        return dict(zip(self.indexes(), self.data))
+
+    def __iter__(self) -> Iterator[Tuple[int, T]]:
+        """Iterate over (index, value) pairs."""
+        return iter(zip(self.indexes(), self.data))
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def to_polars(self) -> pl.DataFrame:
+        """Convert to Polars DataFrame with 'index' and 'value' columns."""
+        try:
+            import polars as pl  # type: ignore[import-not-found]
+        except ImportError:
+            raise ImportError("polars is required: pip install polars")
+        return pl.DataFrame({{"index": self.indexes(), "value": self.data}})
+
+    def to_pandas(self) -> pd.DataFrame:
+        """Convert to Pandas DataFrame with 'index' and 'value' columns."""
+        try:
+            import pandas as pd  # type: ignore[import-not-found]
+        except ImportError:
+            raise ImportError("pandas is required: pip install pandas")
+        return pd.DataFrame({{"index": self.indexes(), "value": self.data}})
+
+
+@dataclass
+class DateSeriesData(SeriesData[T]):
+    """Series data with date-based index. Extends SeriesData with date methods."""
+
+    def dates(self) -> List[Union[date, datetime]]:
+        """Get dates for the index range. Returns datetime for sub-daily indexes, date for daily+."""
+        return [_index_to_date(self.index, i) for i in range(self.start, self.end)]
+
+    def date_items(self) -> List[Tuple[Union[date, datetime], T]]:
+        """Get (date, value) pairs."""
+        return list(zip(self.dates(), self.data))
+
+    def to_date_dict(self) -> Dict[Union[date, datetime], T]:
+        """Return {{date: value}} dict."""
+        return dict(zip(self.dates(), self.data))
+
+    def to_polars(self, with_dates: bool = True) -> pl.DataFrame:
+        """Convert to Polars DataFrame.
+
+        Returns a DataFrame with columns:
+        - 'date' and 'value' if with_dates=True (default)
+        - 'index' and 'value' otherwise
+        """
+        try:
+            import polars as pl  # type: ignore[import-not-found]
+        except ImportError:
+            raise ImportError("polars is required: pip install polars")
+        if with_dates:
+            return pl.DataFrame({{"date": self.dates(), "value": self.data}})
+        return pl.DataFrame({{"index": self.indexes(), "value": self.data}})
+
+    def to_pandas(self, with_dates: bool = True) -> pd.DataFrame:
+        """Convert to Pandas DataFrame.
+
+        Returns a DataFrame with columns:
+        - 'date' and 'value' if with_dates=True (default)
+        - 'index' and 'value' otherwise
+        """
+        try:
+            import pandas as pd  # type: ignore[import-not-found]
+        except ImportError:
+            raise ImportError("pandas is required: pip install pandas")
+        if with_dates:
+            return pd.DataFrame({{"date": self.dates(), "value": self.data}})
+        return pd.DataFrame({{"index": self.indexes(), "value": self.data}})
+
+
+# Type aliases for non-generic usage
+AnySeriesData = SeriesData[Any]
+AnyDateSeriesData = DateSeriesData[Any]
+
+
+class _EndpointConfig:
+    """Shared endpoint configuration."""
+    client: BrkClientBase
+    name: str
+    index: Index
+    start: Optional[int]
+    end: Optional[int]
+
+    def __init__(self, client: BrkClientBase, name: str, index: Index,
+                 start: Optional[int] = None, end: Optional[int] = None):
+        self.client = client
+        self.name = name
+        self.index = index
+        self.start = start
+        self.end = end
+
+    def path(self) -> str:
+        return f"/api/series/{{self.name}}/{{self.index}}"
+
+    def _build_path(self, format: Optional[str] = None) -> str:
+        params = []
+        if self.start is not None:
+            params.append(f"start={{self.start}}")
+        if self.end is not None:
+            params.append(f"end={{self.end}}")
+        if format is not None:
+            params.append(f"format={{format}}")
+        query = "&".join(params)
+        p = self.path()
+        return f"{{p}}?{{query}}" if query else p
+
+    def _new(self, start: Optional[int] = None, end: Optional[int] = None) -> _EndpointConfig:
+        return _EndpointConfig(self.client, self.name, self.index, start, end)
+
+    def get_series(self) -> SeriesData[Any]:
+        return SeriesData(**self.client.get_json(self._build_path()))
+
+    def get_date_series(self) -> DateSeriesData[Any]:
+        return DateSeriesData(**self.client.get_json(self._build_path()))
+
+    def get_csv(self) -> str:
+        return self.client.get_text(self._build_path(format='csv'))
+
+
+class RangeBuilder(Generic[T]):
+    """Builder with range specified."""
+
+    def __init__(self, config: _EndpointConfig):
+        self._config = config
+
+    def fetch(self) -> SeriesData[T]:
+        """Fetch the range as parsed JSON."""
+        return self._config.get_series()
+
+    def fetch_csv(self) -> str:
+        """Fetch the range as CSV string."""
+        return self._config.get_csv()
+
+
+class SingleItemBuilder(Generic[T]):
+    """Builder for single item access."""
+
+    def __init__(self, config: _EndpointConfig):
+        self._config = config
+
+    def fetch(self) -> SeriesData[T]:
+        """Fetch the single item."""
+        return self._config.get_series()
+
+    def fetch_csv(self) -> str:
+        """Fetch as CSV."""
+        return self._config.get_csv()
+
+
+class SkippedBuilder(Generic[T]):
+    """Builder after calling skip(n). Chain with take() to specify count."""
+
+    def __init__(self, config: _EndpointConfig):
+        self._config = config
+
+    def take(self, n: int) -> RangeBuilder[T]:
+        """Take n items after the skipped position."""
+        start = self._config.start or 0
+        return RangeBuilder(self._config._new(start, start + n))
+
+    def fetch(self) -> SeriesData[T]:
+        """Fetch from skipped position to end."""
+        return self._config.get_series()
+
+    def fetch_csv(self) -> str:
+        """Fetch as CSV."""
+        return self._config.get_csv()
+
+
+class DateRangeBuilder(RangeBuilder[T]):
+    """Range builder that returns DateSeriesData."""
+    def fetch(self) -> DateSeriesData[T]:
+        return self._config.get_date_series()
+
+
+class DateSingleItemBuilder(SingleItemBuilder[T]):
+    """Single item builder that returns DateSeriesData."""
+    def fetch(self) -> DateSeriesData[T]:
+        return self._config.get_date_series()
+
+
+class DateSkippedBuilder(SkippedBuilder[T]):
+    """Skipped builder that returns DateSeriesData."""
+    def take(self, n: int) -> DateRangeBuilder[T]:
+        start = self._config.start or 0
+        return DateRangeBuilder(self._config._new(start, start + n))
+    def fetch(self) -> DateSeriesData[T]:
+        return self._config.get_date_series()
+
+
+class SeriesEndpoint(Generic[T]):
+    """Builder for series endpoint queries with int-based indexing.
+
+    Examples:
+        data = endpoint.fetch()
+        data = endpoint[5].fetch()
+        data = endpoint[:10].fetch()
+        data = endpoint.head(20).fetch()
+        data = endpoint.skip(100).take(10).fetch()
+    """
+
+    def __init__(self, client: BrkClientBase, name: str, index: Index):
+        self._config = _EndpointConfig(client, name, index)
+
+    @overload
+    def __getitem__(self, key: int) -> SingleItemBuilder[T]: ...
+    @overload
+    def __getitem__(self, key: slice) -> RangeBuilder[T]: ...
+
+    def __getitem__(self, key: Union[int, slice]) -> Union[SingleItemBuilder[T], RangeBuilder[T]]:
+        """Access single item or slice by integer index."""
+        if isinstance(key, int):
+            return SingleItemBuilder(self._config._new(key, key + 1))
+        return RangeBuilder(self._config._new(key.start, key.stop))
+
+    def head(self, n: int = 10) -> RangeBuilder[T]:
+        """Get the first n items."""
+        return RangeBuilder(self._config._new(end=n))
+
+    def tail(self, n: int = 10) -> RangeBuilder[T]:
+        """Get the last n items."""
+        return RangeBuilder(self._config._new(end=0) if n == 0 else self._config._new(start=-n))
+
+    def skip(self, n: int) -> SkippedBuilder[T]:
+        """Skip the first n items."""
+        return SkippedBuilder(self._config._new(start=n))
+
+    def fetch(self) -> SeriesData[T]:
+        """Fetch all data."""
+        return self._config.get_series()
+
+    def fetch_csv(self) -> str:
+        """Fetch all data as CSV."""
+        return self._config.get_csv()
+
+    def path(self) -> str:
+        """Get the base endpoint path."""
+        return self._config.path()
+
+
+class DateSeriesEndpoint(Generic[T]):
+    """Builder for series endpoint queries with date-based indexing.
+
+    Accepts dates in __getitem__ and returns DateSeriesData from fetch().
+
+    Examples:
+        data = endpoint.fetch()
+        data = endpoint[date(2020, 1, 1)].fetch()
+        data = endpoint[date(2020, 1, 1):date(2023, 1, 1)].fetch()
+        data = endpoint[:10].fetch()
+    """
+
+    def __init__(self, client: BrkClientBase, name: str, index: Index):
+        self._config = _EndpointConfig(client, name, index)
+
+    @overload
+    def __getitem__(self, key: int) -> DateSingleItemBuilder[T]: ...
+    @overload
+    def __getitem__(self, key: datetime) -> DateSingleItemBuilder[T]: ...
+    @overload
+    def __getitem__(self, key: date) -> DateSingleItemBuilder[T]: ...
+    @overload
+    def __getitem__(self, key: slice) -> DateRangeBuilder[T]: ...
+
+    def __getitem__(self, key: Union[int, slice, date, datetime]) -> Union[DateSingleItemBuilder[T], DateRangeBuilder[T]]:
+        """Access single item or slice. Accepts int, date, or datetime."""
+        if isinstance(key, (date, datetime)):
+            idx = _date_to_index(self._config.index, key)
+            return DateSingleItemBuilder(self._config._new(idx, idx + 1))
+        if isinstance(key, int):
+            return DateSingleItemBuilder(self._config._new(key, key + 1))
+        start, stop = key.start, key.stop
+        if isinstance(start, (date, datetime)):
+            start = _date_to_index(self._config.index, start)
+        if isinstance(stop, (date, datetime)):
+            stop = _date_to_index(self._config.index, stop)
+        return DateRangeBuilder(self._config._new(start, stop))
+
+    def head(self, n: int = 10) -> DateRangeBuilder[T]:
+        """Get the first n items."""
+        return DateRangeBuilder(self._config._new(end=n))
+
+    def tail(self, n: int = 10) -> DateRangeBuilder[T]:
+        """Get the last n items."""
+        return DateRangeBuilder(self._config._new(end=0) if n == 0 else self._config._new(start=-n))
+
+    def skip(self, n: int) -> DateSkippedBuilder[T]:
+        """Skip the first n items."""
+        return DateSkippedBuilder(self._config._new(start=n))
+
+    def fetch(self) -> DateSeriesData[T]:
+        """Fetch all data."""
+        return self._config.get_date_series()
+
+    def fetch_csv(self) -> str:
+        """Fetch all data as CSV."""
+        return self._config.get_csv()
+
+    def path(self) -> str:
+        """Get the base endpoint path."""
+        return self._config.path()
+
+
+# Type aliases for non-generic usage
+AnySeriesEndpoint = SeriesEndpoint[Any]
+AnyDateSeriesEndpoint = DateSeriesEndpoint[Any]
+
+
+class SeriesPattern(Protocol[T]):
+    """Protocol for series patterns with different index sets."""
+
+    @property
+    def name(self) -> str:
+        """Get the series name."""
+        ...
+
+    def indexes(self) -> List[str]:
+        """Get the list of available indexes for this series."""
+        ...
+
+    def get(self, index: Index) -> Optional[SeriesEndpoint[T]]:
+        """Get an endpoint builder for a specific index, if supported."""
+        ...
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate index accessor classes
+pub fn generate_index_accessors(output: &mut String, patterns: &[IndexSetPattern]) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    // Generate static index tuples
+    writeln!(output, "# Static index tuples").unwrap();
+    for (i, pattern) in patterns.iter().enumerate() {
+        write!(output, "_i{} = (", i + 1).unwrap();
+        for (j, index) in pattern.indexes.iter().enumerate() {
+            if j > 0 {
+                write!(output, ", ").unwrap();
+            }
+            write!(output, "'{}'", index.name()).unwrap();
+        }
+        // Single-element tuple needs trailing comma
+        if pattern.indexes.len() == 1 {
+            write!(output, ",").unwrap();
+        }
+        writeln!(output, ")").unwrap();
+    }
+    writeln!(output).unwrap();
+
+    // Generate helper functions
+    writeln!(
+        output,
+        r#"def _ep(c: BrkClientBase, n: str, i: Index) -> SeriesEndpoint[Any]:
+    return SeriesEndpoint(c, n, i)
+
+def _dep(c: BrkClientBase, n: str, i: Index) -> DateSeriesEndpoint[Any]:
+    return DateSeriesEndpoint(c, n, i)
+"#
+    )
+    .unwrap();
+
+    writeln!(output, "# Index accessor classes\n").unwrap();
+
+    for (i, pattern) in patterns.iter().enumerate() {
+        let by_class_name = format!("_{}By", pattern.name);
+        let idx_var = format!("_i{}", i + 1);
+
+        // Generate the By class with compact methods
+        writeln!(output, "class {}(Generic[T]):", by_class_name).unwrap();
+        writeln!(
+            output,
+            "    def __init__(self, c: BrkClientBase, n: str): self._c, self._n = c, n"
+        )
+        .unwrap();
+        for index in &pattern.indexes {
+            let method_name = index_to_field_name(index);
+            let index_name = index.name();
+            let (builder_type, helper) = if index.is_date_based() {
+                ("DateSeriesEndpoint", "_dep")
+            } else {
+                ("SeriesEndpoint", "_ep")
+            };
+            writeln!(
+                output,
+                "    def {}(self) -> {}[T]: return {}(self._c, self._n, '{}')",
+                method_name, builder_type, helper, index_name
+            )
+            .unwrap();
+        }
+        writeln!(output).unwrap();
+
+        // Generate the main accessor class
+        writeln!(output, "class {}(Generic[T]):", pattern.name).unwrap();
+        writeln!(output, "    by: {}[T]", by_class_name).unwrap();
+        writeln!(
+            output,
+            "    def __init__(self, c: BrkClientBase, n: str): self._n, self.by = n, {}(c, n)",
+            by_class_name
+        )
+        .unwrap();
+        writeln!(output, "    @property").unwrap();
+        writeln!(output, "    def name(self) -> str: return self._n").unwrap();
+        writeln!(
+            output,
+            "    def indexes(self) -> List[str]: return list({})",
+            idx_var
+        )
+        .unwrap();
+        writeln!(
+            output,
+            "    def get(self, index: Index) -> Optional[SeriesEndpoint[T]]: return _ep(self.by._c, self._n, index) if index in {} else None",
+            idx_var
+        )
+        .unwrap();
+        writeln!(output).unwrap();
+    }
+}
+
+/// Generate structural pattern classes
+pub fn generate_structural_patterns(
+    output: &mut String,
+    patterns: &[StructuralPattern],
+    metadata: &ClientMetadata,
+) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    writeln!(output, "# Reusable structural pattern classes\n").unwrap();
+
+    for pattern in patterns {
+        // Generate class
+        if pattern.is_generic {
+            writeln!(output, "class {}(Generic[T]):", pattern.name).unwrap();
+        } else {
+            writeln!(output, "class {}:", pattern.name).unwrap();
+        }
+        writeln!(
+            output,
+            "    \"\"\"Pattern struct for repeated tree structure.\"\"\""
+        )
+        .unwrap();
+
+        // Skip constructor for non-parameterizable patterns (inlined at tree level)
+        if !metadata.is_parameterizable(&pattern.name) {
+            writeln!(output, "    pass\n").unwrap();
+            continue;
+        }
+
+        writeln!(output, "    ").unwrap();
+        if pattern.is_templated() {
+            writeln!(
+                output,
+                "    def __init__(self, client: BrkClientBase, acc: str, disc: str):"
+            )
+            .unwrap();
+        } else {
+            writeln!(
+                output,
+                "    def __init__(self, client: BrkClientBase, acc: str):"
+            )
+            .unwrap();
+        }
+        writeln!(
+            output,
+            "        \"\"\"Create pattern node with accumulated series name.\"\"\""
+        )
+        .unwrap();
+
+        let syntax = PythonSyntax;
+        for field in &pattern.fields {
+            generate_parameterized_field(output, &syntax, field, pattern, metadata, "        ");
+        }
+
+        writeln!(output).unwrap();
+    }
+}
@@ -0,0 +1,71 @@
+//! Python client generation.
+//!
+//! This module generates a Python client with type hints for the BRK API.
+
+pub mod api;
+pub mod client;
+pub mod tree;
+pub mod types;
+
+use std::{fmt::Write, io, path::Path};
+
+use super::write_if_changed;
+use crate::{ClientMetadata, Endpoint, TypeSchemas};
+
+/// Generate Python client from metadata and OpenAPI endpoints.
+///
+/// `output_path` is the full path to the output file (e.g., "packages/brk_client/__init__.py").
+pub fn generate_python_client(
+    metadata: &ClientMetadata,
+    endpoints: &[Endpoint],
+    schemas: &TypeSchemas,
+    output_path: &Path,
+) -> io::Result<()> {
+    let mut output = String::new();
+
+    writeln!(output, "# Auto-generated BRK Python client").unwrap();
+    writeln!(output, "# Do not edit manually\n").unwrap();
+    writeln!(output, "from __future__ import annotations").unwrap();
+    writeln!(output, "from dataclasses import dataclass").unwrap();
+    writeln!(
+        output,
+        "from typing import TypeVar, Generic, Any, Dict, Optional, List, Iterator, Literal, TypedDict, Union, Protocol, overload, Tuple, TYPE_CHECKING"
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "from http.client import HTTPSConnection, HTTPConnection"
+    )
+    .unwrap();
+    writeln!(output, "from urllib.parse import urlparse").unwrap();
+    writeln!(
+        output,
+        "from datetime import date, datetime, timedelta, timezone"
+    )
+    .unwrap();
+    writeln!(output, "import json\n").unwrap();
+    writeln!(output, "if TYPE_CHECKING:").unwrap();
+    writeln!(
+        output,
+        "    import pandas as pd  # type: ignore[import-not-found]"
+    )
+    .unwrap();
+    writeln!(
+        output,
+        "    import polars as pl  # type: ignore[import-not-found]\n"
+    )
+    .unwrap();
+    writeln!(output, "T = TypeVar('T')\n").unwrap();
+
+    types::generate_type_definitions(&mut output, schemas);
+    client::generate_base_client(&mut output);
+    client::generate_endpoint_class(&mut output);
+    client::generate_index_accessors(&mut output, &metadata.index_set_patterns);
+    client::generate_structural_patterns(&mut output, &metadata.structural_patterns, metadata);
+    tree::generate_tree_classes(&mut output, &metadata.catalog, metadata);
+    api::generate_main_client(&mut output, endpoints);
+
+    write_if_changed(output_path, &output)?;
+
+    Ok(())
+}
@@ -0,0 +1,105 @@
+//! Python tree structure generation.
+
+use std::collections::BTreeSet;
+use std::fmt::Write;
+
+use brk_types::TreeNode;
+
+use crate::{
+    ClientMetadata, LanguageSyntax, PatternField, PythonSyntax, build_child_path,
+    generate_leaf_field, generate_tree_node_field, prepare_tree_node,
+};
+
+/// Generate tree classes
+pub fn generate_tree_classes(output: &mut String, catalog: &TreeNode, metadata: &ClientMetadata) {
+    writeln!(output, "# Series tree classes\n").unwrap();
+
+    let pattern_lookup = metadata.pattern_lookup();
+    let mut generated = BTreeSet::new();
+    generate_tree_class(
+        output,
+        "SeriesTree",
+        "",
+        catalog,
+        pattern_lookup,
+        metadata,
+        &mut generated,
+    );
+}
+
+/// Recursively generate tree classes
+fn generate_tree_class(
+    output: &mut String,
+    name: &str,
+    path: &str,
+    node: &TreeNode,
+    pattern_lookup: &std::collections::BTreeMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+    generated: &mut BTreeSet<String>,
+) {
+    let Some(ctx) = prepare_tree_node(node, name, path, pattern_lookup, metadata, generated) else {
+        return;
+    };
+
+    // Generate child classes FIRST (post-order traversal)
+    // This ensures children are defined before parent references them
+    for child in &ctx.children {
+        if child.should_inline {
+            let child_path = build_child_path(path, child.name);
+            generate_tree_class(
+                output,
+                &child.inline_type_name,
+                &child_path,
+                child.node,
+                pattern_lookup,
+                metadata,
+                generated,
+            );
+        }
+    }
+
+    // THEN generate the current class (after all children are defined)
+    writeln!(output, "class {}:", name).unwrap();
+    writeln!(output, "    \"\"\"Series tree node.\"\"\"").unwrap();
+    writeln!(output, "    ").unwrap();
+    writeln!(
+        output,
+        "    def __init__(self, client: BrkClientBase, base_path: str = ''):"
+    )
+    .unwrap();
+
+    if ctx.children.is_empty() {
+        writeln!(output, "        pass").unwrap();
+    }
+
+    let syntax = PythonSyntax;
+    for child in &ctx.children {
+        if child.is_leaf {
+            if let TreeNode::Leaf(leaf) = child.node {
+                generate_leaf_field(
+                    output, &syntax, "client", child.name, leaf, metadata, "        ",
+                );
+            }
+        } else if child.should_inline {
+            let field_name = syntax.field_name(child.name);
+            writeln!(
+                output,
+                "        self.{}: {} = {}(client)",
+                field_name, child.inline_type_name, child.inline_type_name
+            )
+            .unwrap();
+        } else {
+            generate_tree_node_field(
+                output,
+                &syntax,
+                &child.field,
+                metadata,
+                "        ",
+                "client",
+                &child.base_result,
+            );
+        }
+    }
+
+    writeln!(output).unwrap();
+}
@@ -0,0 +1,339 @@
+//! Python type definitions generation.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fmt::Write;
+
+use serde_json::Value;
+
+use crate::{
+    TypeSchemas, escape_python_keyword, generators::MANUAL_GENERIC_TYPES, get_union_variants,
+    ref_to_type_name,
+};
+
+/// Generate type definitions from schemas.
+pub fn generate_type_definitions(output: &mut String, schemas: &TypeSchemas) {
+    if schemas.is_empty() {
+        return;
+    }
+
+    writeln!(output, "# Type definitions\n").unwrap();
+
+    let sorted_names = topological_sort_schemas(schemas);
+
+    // Partition into simple type aliases and TypedDict classes
+    // Generate type aliases first to avoid forward reference issues
+    let (type_aliases, typed_dicts): (Vec<_>, Vec<_>) = sorted_names
+        .into_iter()
+        .filter(|name| !MANUAL_GENERIC_TYPES.contains(&name.as_str()))
+        .filter(|name| schemas.contains_key(name))
+        .partition(|name| {
+            schemas
+                .get(name)
+                .map(|s| s.get("properties").is_none())
+                .unwrap_or(false)
+        });
+
+    // Generate simple type aliases first
+    // Quote references to TypedDicts since they're defined after
+    let typed_dict_set: BTreeSet<_> = typed_dicts.iter().cloned().collect();
+    for name in type_aliases {
+        let schema = &schemas[&name];
+        let type_desc = schema.get("description").and_then(|d| d.as_str());
+        let py_type = schema_to_python_type(schema, Some(&name), Some(&typed_dict_set));
+        if let Some(desc) = type_desc {
+            for line in desc.lines() {
+                writeln!(output, "# {}", line).unwrap();
+            }
+        }
+        writeln!(output, "{} = {}", name, py_type).unwrap();
+    }
+
+    // Then generate TypedDict classes
+    for name in typed_dicts {
+        let schema = &schemas[&name];
+        let type_desc = schema.get("description").and_then(|d| d.as_str());
+        let props = schema
+            .get("properties")
+            .and_then(|p| p.as_object())
+            .unwrap();
+
+        writeln!(output, "class {}(TypedDict):", name).unwrap();
+
+        // Collect field descriptions for Attributes section
+        let field_docs: Vec<(String, Option<&str>)> = props
+            .iter()
+            .map(|(prop_name, prop_schema)| {
+                let safe_name = escape_python_keyword(prop_name);
+                let desc = prop_schema.get("description").and_then(|d| d.as_str());
+                (safe_name, desc)
+            })
+            .collect();
+        let has_field_docs = field_docs.iter().any(|(_, d)| d.is_some());
+
+        // Generate docstring if we have type description or field descriptions
+        if type_desc.is_some() || has_field_docs {
+            writeln!(output, "    \"\"\"").unwrap();
+            if let Some(desc) = type_desc {
+                for line in desc.lines() {
+                    writeln!(output, "    {}", line).unwrap();
+                }
+            }
+            if has_field_docs {
+                if type_desc.is_some() {
+                    writeln!(output).unwrap();
+                }
+                writeln!(output, "    Attributes:").unwrap();
+                for (field_name, desc) in &field_docs {
+                    if let Some(d) = desc {
+                        writeln!(output, "        {}: {}", field_name, d).unwrap();
+                    }
+                }
+            }
+            writeln!(output, "    \"\"\"").unwrap();
+        }
+
+        for (prop_name, prop_schema) in props {
+            let prop_type = schema_to_python_type(prop_schema, Some(&name), None);
+            let safe_name = escape_python_keyword(prop_name);
+            writeln!(output, "    {}: {}", safe_name, prop_type).unwrap();
+        }
+        writeln!(output).unwrap();
+    }
+    writeln!(output).unwrap();
+}
+
+/// Topologically sort schema names so dependencies come before dependents (avoids forward references).
+/// Types that reference other types (via $ref) must be defined after their dependencies.
+fn topological_sort_schemas(schemas: &TypeSchemas) -> Vec<String> {
+    // Build dependency graph
+    let mut deps: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
+    for (name, schema) in schemas {
+        let mut type_deps = BTreeSet::new();
+        collect_schema_refs(schema, &mut type_deps);
+        // Only keep deps that are in our schemas
+        type_deps.retain(|d| schemas.contains_key(d));
+        deps.insert(name.clone(), type_deps);
+    }
+
+    // Kahn's algorithm for topological sort
+    let mut in_degree: BTreeMap<String, usize> = BTreeMap::new();
+    for name in schemas.keys() {
+        in_degree.insert(name.clone(), 0);
+    }
+    for type_deps in deps.values() {
+        for dep in type_deps {
+            *in_degree.entry(dep.clone()).or_insert(0) += 1;
+        }
+    }
+
+    // Start with types that have no dependents (are not referenced by others)
+    let mut queue: Vec<String> = in_degree
+        .iter()
+        .filter(|(_, count)| **count == 0)
+        .map(|(name, _)| name.clone())
+        .collect();
+    queue.sort(); // Deterministic order
+
+    let mut result = Vec::new();
+    while let Some(name) = queue.pop() {
+        result.push(name.clone());
+        if let Some(type_deps) = deps.get(&name) {
+            for dep in type_deps {
+                if let Some(count) = in_degree.get_mut(dep) {
+                    *count = count.saturating_sub(1);
+                    if *count == 0 {
+                        queue.push(dep.clone());
+                        queue.sort(); // Keep sorted for determinism
+                    }
+                }
+            }
+        }
+    }
+
+    // Reverse so dependencies come first
+    result.reverse();
+
+    // Add any types that weren't processed (e.g., due to circular refs or other edge cases)
+    let result_set: BTreeSet<_> = result.iter().cloned().collect();
+    let mut missing: Vec<_> = schemas
+        .keys()
+        .filter(|k| !result_set.contains(*k))
+        .cloned()
+        .collect();
+    missing.sort();
+    result.extend(missing);
+
+    result
+}
+
+/// Collect all type references ($ref) from a schema
+fn collect_schema_refs(schema: &Value, refs: &mut BTreeSet<String>) {
+    match schema {
+        Value::Object(map) => {
+            if let Some(ref_path) = map.get("$ref").and_then(|r| r.as_str())
+                && let Some(type_name) = ref_to_type_name(ref_path)
+            {
+                refs.insert(type_name.to_string());
+            }
+            for value in map.values() {
+                collect_schema_refs(value, refs);
+            }
+        }
+        Value::Array(arr) => {
+            for item in arr {
+                collect_schema_refs(item, refs);
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Convert a single JSON type string to Python type
+fn json_type_to_python(ty: &str, schema: &Value, current_type: Option<&str>) -> String {
+    match ty {
+        "integer" => "int".to_string(),
+        "number" => "float".to_string(),
+        "boolean" => "bool".to_string(),
+        "string" => "str".to_string(),
+        "null" => "None".to_string(),
+        "array" => {
+            let item_type = schema
+                .get("items")
+                .map(|s| schema_to_python_type(s, current_type, None))
+                .unwrap_or_else(|| "Any".to_string());
+            format!("List[{}]", item_type)
+        }
+        "object" => {
+            if let Some(add_props) = schema.get("additionalProperties") {
+                let value_type = schema_to_python_type(add_props, current_type, None);
+                return format!("dict[str, {}]", value_type);
+            }
+            "dict".to_string()
+        }
+        _ => "Any".to_string(),
+    }
+}
+
+/// Convert JSON Schema to Python type.
+///
+/// - `current_type`: Used to detect and quote self-references for recursive types
+/// - `quote_types`: Optional set of additional type names that should be quoted
+pub fn schema_to_python_type(
+    schema: &Value,
+    current_type: Option<&str>,
+    quote_types: Option<&BTreeSet<String>>,
+) -> String {
+    if let Some(all_of) = schema.get("allOf").and_then(|v| v.as_array()) {
+        for item in all_of {
+            let resolved = schema_to_python_type(item, current_type, quote_types);
+            if resolved != "Any" {
+                return resolved;
+            }
+        }
+    }
+
+    // Handle $ref
+    if let Some(ref_path) = schema.get("$ref").and_then(|r| r.as_str()) {
+        let type_name = ref_to_type_name(ref_path).unwrap_or("Any");
+        // Quote self-references or types in quote_types set
+        let should_quote =
+            current_type == Some(type_name) || quote_types.is_some_and(|qt| qt.contains(type_name));
+        if should_quote {
+            return format!("\"{}\"", type_name);
+        }
+        return type_name.to_string();
+    }
+
+    // Handle enum (array of string values)
+    if let Some(enum_values) = schema.get("enum").and_then(|e| e.as_array()) {
+        let literals: Vec<String> = enum_values
+            .iter()
+            .filter_map(|v| v.as_str())
+            .map(|s| format!("\"{}\"", s))
+            .collect();
+        if !literals.is_empty() {
+            return format!("Literal[{}]", literals.join(", "));
+        }
+    }
+
+    if let Some(ty) = schema.get("type") {
+        if let Some(type_array) = ty.as_array() {
+            let types: Vec<String> = type_array
+                .iter()
+                .filter_map(|t| t.as_str())
+                .filter(|t| *t != "null")
+                .map(|t| json_type_to_python(t, schema, current_type))
+                .collect();
+            let has_null = type_array.iter().any(|t| t.as_str() == Some("null"));
+
+            if types.len() == 1 {
+                let base_type = &types[0];
+                return if has_null {
+                    format!("Optional[{}]", base_type)
+                } else {
+                    base_type.clone()
+                };
+            } else if !types.is_empty() {
+                let union = format!("Union[{}]", types.join(", "));
+                return if has_null {
+                    format!("Optional[{}]", union)
+                } else {
+                    union
+                };
+            }
+        }
+
+        if let Some(ty_str) = ty.as_str() {
+            return json_type_to_python(ty_str, schema, current_type);
+        }
+    }
+
+    if let Some(variants) = get_union_variants(schema) {
+        let types: Vec<String> = variants
+            .iter()
+            .map(|v| schema_to_python_type(v, current_type, quote_types))
+            .collect();
+        let filtered: Vec<_> = types.iter().filter(|t| *t != "Any").collect();
+        if !filtered.is_empty() {
+            return format!(
+                "Union[{}]",
+                filtered
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+        }
+        return format!("Union[{}]", types.join(", "));
+    }
+
+    // Check for format hint without type (common in OpenAPI)
+    if let Some(format) = schema.get("format").and_then(|f| f.as_str()) {
+        return match format {
+            "int32" | "int64" => "int".to_string(),
+            "float" | "double" => "float".to_string(),
+            "date" | "date-time" => "str".to_string(),
+            _ => "Any".to_string(),
+        };
+    }
+
+    "Any".to_string()
+}
+
+/// Convert JS-style type to Python type (e.g., "Txid[]" -> "List[Txid]", "integer" -> "int")
+pub fn js_type_to_python(js_type: &str) -> String {
+    if let Some(inner) = js_type.strip_suffix("[]") {
+        format!("List[{}]", js_type_to_python(inner))
+    } else {
+        match js_type {
+            "integer" => "int".to_string(),
+            "number" => "float".to_string(),
+            "boolean" => "bool".to_string(),
+            "string" => "str".to_string(),
+            "null" => "None".to_string(),
+            "Object" | "object" => "dict".to_string(),
+            "*" => "Any".to_string(),
+            _ => js_type.to_string(),
+        }
+    }
+}
@@ -0,0 +1,259 @@
+//! Rust API method generation.
+
+use std::fmt::Write;
+
+use crate::{Endpoint, VERSION, generators::write_description, to_snake_case};
+
+use super::types::js_type_to_rust;
+
+/// Generate the main BrkClient struct.
+pub fn generate_main_client(output: &mut String, endpoints: &[Endpoint]) {
+    writeln!(
+        output,
+        r#"/// Main BRK client with series tree and API methods.
+pub struct BrkClient {{
+    base: Arc<BrkClientBase>,
+    series: SeriesTree,
+}}
+
+impl BrkClient {{
+    /// Client version.
+    pub const VERSION: &'static str = "v{VERSION}";
+
+    /// Create a new client with the given base URL.
+    pub fn new(base_url: impl Into<String>) -> Self {{
+        let base = Arc::new(BrkClientBase::new(base_url));
+        let series = SeriesTree::new(base.clone(), String::new());
+        Self {{ base, series }}
+    }}
+
+    /// Create a new client with options.
+    pub fn with_options(options: BrkClientOptions) -> Self {{
+        let base = Arc::new(BrkClientBase::with_options(options));
+        let series = SeriesTree::new(base.clone(), String::new());
+        Self {{ base, series }}
+    }}
+
+    /// Get the series tree for navigating series.
+    pub fn series(&self) -> &SeriesTree {{
+        &self.series
+    }}
+
+    /// Create a dynamic series endpoint builder for any series/index combination.
+    ///
+    /// Use this for programmatic access when the series name is determined at runtime.
+    /// For type-safe access, use the `series()` tree instead.
+    ///
+    /// # Example
+    /// ```ignore
+    /// let data = client.series("realized_price", Index::Height)
+    ///     .last(10)
+    ///     .json::<f64>()?;
+    /// ```
+    pub fn series_endpoint(&self, series: impl Into<SeriesName>, index: Index) -> SeriesEndpoint<serde_json::Value> {{
+        SeriesEndpoint::new(
+            self.base.clone(),
+            Arc::from(series.into().as_str()),
+            index,
+        )
+    }}
+
+    /// Create a dynamic date-based series endpoint builder.
+    ///
+    /// Returns `Err` if the index is not date-based.
+    pub fn date_series_endpoint(&self, series: impl Into<SeriesName>, index: Index) -> Result<DateSeriesEndpoint<serde_json::Value>> {{
+        if !index.is_date_based() {{
+            return Err(BrkError {{ message: format!("{{}} is not a date-based index", index.name()) }});
+        }}
+        Ok(DateSeriesEndpoint::new(
+            self.base.clone(),
+            Arc::from(series.into().as_str()),
+            index,
+        ))
+    }}
+"#,
+        VERSION = VERSION
+    )
+    .unwrap();
+
+    generate_api_methods(output, endpoints);
+
+    writeln!(output, "}}").unwrap();
+}
+
+/// Generate API methods from OpenAPI endpoints.
+pub fn generate_api_methods(output: &mut String, endpoints: &[Endpoint]) {
+    for endpoint in endpoints {
+        if !endpoint.should_generate() {
+            continue;
+        }
+
+        let method_name = endpoint_to_method_name(endpoint);
+        let base_return_type = endpoint
+            .response_type
+            .as_deref()
+            .map(js_type_to_rust)
+            .unwrap_or_else(|| "String".to_string());
+
+        let return_type = if endpoint.supports_csv {
+            format!("FormatResponse<{}>", base_return_type)
+        } else {
+            base_return_type.clone()
+        };
+
+        writeln!(
+            output,
+            "    /// {}",
+            endpoint.summary.as_deref().unwrap_or(&method_name)
+        )
+        .unwrap();
+        if let Some(desc) = &endpoint.description
+            && endpoint.summary.as_ref() != Some(desc)
+        {
+            writeln!(output, "    ///").unwrap();
+            write_description(output, desc, "    /// ", "    ///");
+        }
+        // Add endpoint path
+        writeln!(output, "    ///").unwrap();
+        writeln!(
+            output,
+            "    /// Endpoint: `{} {}`",
+            endpoint.method.to_uppercase(),
+            endpoint.path
+        )
+        .unwrap();
+
+        let params = build_method_params(endpoint);
+        writeln!(
+            output,
+            "    pub fn {}(&self{}) -> Result<{}> {{",
+            method_name, params, return_type
+        )
+        .unwrap();
+
+        let (path, index_arg) = build_path_template(endpoint);
+        let fetch_method = if endpoint.returns_json() {
+            "get_json"
+        } else {
+            "get_text"
+        };
+
+        if endpoint.query_params.is_empty() {
+            writeln!(
+                output,
+                "        self.base.{}(&format!(\"{}\"{}))",
+                fetch_method, path, index_arg
+            )
+            .unwrap();
+        } else {
+            writeln!(output, "        let mut query = Vec::new();").unwrap();
+            for param in &endpoint.query_params {
+                let ident = sanitize_ident(&param.name);
+                let is_array = param.param_type.ends_with("[]");
+                if is_array {
+                    writeln!(
+                        output,
+                        "        for v in {} {{ query.push(format!(\"{}={{}}\", v)); }}",
+                        ident, param.name
+                    )
+                    .unwrap();
+                } else if param.required {
+                    writeln!(
+                        output,
+                        "        query.push(format!(\"{}={{}}\", {}));",
+                        param.name, ident
+                    )
+                    .unwrap();
+                } else {
+                    writeln!(
+                        output,
+                        "        if let Some(v) = {} {{ query.push(format!(\"{}={{}}\", v)); }}",
+                        ident, param.name
+                    )
+                    .unwrap();
+                }
+            }
+            writeln!(output, "        let query_str = if query.is_empty() {{ String::new() }} else {{ format!(\"?{{}}\", query.join(\"&\")) }};").unwrap();
+            writeln!(
+                output,
+                "        let path = format!(\"{}{{}}\"{}, query_str);",
+                path, index_arg
+            )
+            .unwrap();
+
+            if endpoint.supports_csv {
+                writeln!(output, "        if format == Some(Format::CSV) {{").unwrap();
+                writeln!(
+                    output,
+                    "            self.base.get_text(&path).map(FormatResponse::Csv)"
+                )
+                .unwrap();
+                writeln!(output, "        }} else {{").unwrap();
+                writeln!(
+                    output,
+                    "            self.base.{}(&path).map(FormatResponse::Json)",
+                    fetch_method
+                )
+                .unwrap();
+                writeln!(output, "        }}").unwrap();
+            } else {
+                writeln!(output, "        self.base.{}(&path)", fetch_method).unwrap();
+            }
+        }
+
+        writeln!(output, "    }}\n").unwrap();
+    }
+}
+
+fn endpoint_to_method_name(endpoint: &Endpoint) -> String {
+    to_snake_case(&endpoint.operation_name())
+}
+
+fn build_method_params(endpoint: &Endpoint) -> String {
+    let mut params = Vec::new();
+    for param in &endpoint.path_params {
+        let rust_type = param_type_to_rust(&param.param_type);
+        params.push(format!(", {}: {}", sanitize_ident(&param.name), rust_type));
+    }
+    for param in &endpoint.query_params {
+        let rust_type = param_type_to_rust(&param.param_type);
+        let name = sanitize_ident(&param.name);
+        if param.required {
+            params.push(format!(", {}: {}", name, rust_type));
+        } else {
+            params.push(format!(", {}: Option<{}>", name, rust_type));
+        }
+    }
+    params.join("")
+}
+
+/// Strip characters invalid in Rust identifiers (e.g. `[]` from `txId[]`).
+fn sanitize_ident(name: &str) -> String {
+    name.replace(['[', ']'], "")
+}
+
+/// Convert parameter type to Rust type for function signatures.
+fn param_type_to_rust(param_type: &str) -> String {
+    if let Some(inner) = param_type.strip_suffix("[]") {
+        return format!("&[{}]", param_type_to_rust(inner));
+    }
+    match param_type {
+        "string" | "*" => "&str".to_string(),
+        "integer" | "number" => "i64".to_string(),
+        "boolean" => "bool".to_string(),
+        other => other.to_string(),
+    }
+}
+
+/// Build path template and extra format args for Index params.
+fn build_path_template(endpoint: &Endpoint) -> (String, &'static str) {
+    let has_index_param = endpoint
+        .path_params
+        .iter()
+        .any(|p| p.name == "index" && p.param_type == "Index");
+    if has_index_param {
+        (endpoint.path.replace("{index}", "{}"), ", index.name()")
+    } else {
+        (endpoint.path.clone(), "")
+    }
+}
@@ -0,0 +1,572 @@
+//! Rust base client and pattern factory generation.
+
+use std::fmt::Write;
+
+use crate::{
+    ClientMetadata, GenericSyntax, IndexSetPattern, RustSyntax, StructuralPattern,
+    escape_rust_keyword, generate_parameterized_field, index_to_field_name, to_snake_case,
+};
+
+/// Generate import statements.
+pub fn generate_imports(output: &mut String) {
+    writeln!(
+        output,
+        r#"use std::sync::Arc;
+use std::ops::{{Bound, RangeBounds}};
+use serde::de::DeserializeOwned;
+pub use brk_cohort::*;
+pub use brk_types::*;
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate the base BrkClientBase struct and error types.
+pub fn generate_base_client(output: &mut String) {
+    writeln!(
+        output,
+        r#"/// Error type for BRK client operations.
+#[derive(Debug)]
+pub struct BrkError {{
+    pub message: String,
+}}
+
+impl std::fmt::Display for BrkError {{
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {{
+        write!(f, "{{}}", self.message)
+    }}
+}}
+
+impl std::error::Error for BrkError {{}}
+
+/// Result type for BRK client operations.
+pub type Result<T> = std::result::Result<T, BrkError>;
+
+/// Options for configuring the BRK client.
+#[derive(Debug, Clone)]
+pub struct BrkClientOptions {{
+    pub base_url: String,
+    pub timeout_secs: u64,
+}}
+
+impl Default for BrkClientOptions {{
+    fn default() -> Self {{
+        Self {{
+            base_url: "http://localhost:3000".to_string(),
+            timeout_secs: 30,
+        }}
+    }}
+}}
+
+/// Base HTTP client for making requests. Reuses connections via ureq::Agent.
+#[derive(Debug, Clone)]
+pub struct BrkClientBase {{
+    agent: ureq::Agent,
+    base_url: String,
+}}
+
+impl BrkClientBase {{
+    /// Create a new client with the given base URL.
+    pub fn new(base_url: impl Into<String>) -> Self {{
+        Self::with_options(BrkClientOptions {{ base_url: base_url.into(), ..Default::default() }})
+    }}
+
+    /// Create a new client with options.
+    pub fn with_options(options: BrkClientOptions) -> Self {{
+        let agent = ureq::Agent::config_builder()
+            .timeout_global(Some(std::time::Duration::from_secs(options.timeout_secs)))
+            .build()
+            .into();
+        Self {{
+            agent,
+            base_url: options.base_url.trim_end_matches('/').to_string(),
+        }}
+    }}
+
+    fn url(&self, path: &str) -> String {{
+        format!("{{}}{{}}", self.base_url, path)
+    }}
+
+    /// Make a GET request and deserialize JSON response.
+    pub fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T> {{
+        self.agent.get(&self.url(path))
+            .call()
+            .and_then(|mut r| r.body_mut().read_json())
+            .map_err(|e| BrkError {{ message: e.to_string() }})
+    }}
+
+    /// Make a GET request and return raw text response.
+    pub fn get_text(&self, path: &str) -> Result<String> {{
+        self.agent.get(&self.url(path))
+            .call()
+            .and_then(|mut r| r.body_mut().read_to_string())
+            .map_err(|e| BrkError {{ message: e.to_string() }})
+    }}
+}}
+
+/// Build series name with suffix.
+#[inline]
+fn _m(acc: &str, s: &str) -> String {{
+    if s.is_empty() {{ acc.to_string() }}
+    else if acc.is_empty() {{ s.to_string() }}
+    else {{ format!("{{acc}}_{{s}}") }}
+}}
+
+/// Build series name with prefix.
+#[inline]
+fn _p(prefix: &str, acc: &str) -> String {{
+    if acc.is_empty() {{ prefix.to_string() }} else {{ format!("{{prefix}}_{{acc}}") }}
+}}
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate the SeriesPattern trait.
+pub fn generate_series_pattern_trait(output: &mut String) {
+    writeln!(
+        output,
+        r#"/// Non-generic trait for series patterns (usable in collections).
+pub trait AnySeriesPattern {{
+    /// Get the series name.
+    fn name(&self) -> &str;
+
+    /// Get the list of available indexes for this series.
+    fn indexes(&self) -> &'static [Index];
+}}
+
+/// Generic trait for series patterns with endpoint access.
+pub trait SeriesPattern<T>: AnySeriesPattern {{
+    /// Get an endpoint builder for a specific index, if supported.
+    fn get(&self, index: Index) -> Option<SeriesEndpoint<T>>;
+}}
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate the SeriesEndpoint structs with typestate pattern.
+pub fn generate_endpoint(output: &mut String) {
+    writeln!(
+        output,
+        r#"/// Shared endpoint configuration.
+#[derive(Clone)]
+struct EndpointConfig {{
+    client: Arc<BrkClientBase>,
+    name: Arc<str>,
+    index: Index,
+    start: Option<i64>,
+    end: Option<i64>,
+}}
+
+impl EndpointConfig {{
+    fn new(client: Arc<BrkClientBase>, name: Arc<str>, index: Index) -> Self {{
+        Self {{ client, name, index, start: None, end: None }}
+    }}
+
+    fn path(&self) -> String {{
+        format!("/api/series/{{}}/{{}}", self.name, self.index.name())
+    }}
+
+    fn build_path(&self, format: Option<&str>) -> String {{
+        let mut params = Vec::new();
+        if let Some(s) = self.start {{ params.push(format!("start={{}}", s)); }}
+        if let Some(e) = self.end {{ params.push(format!("end={{}}", e)); }}
+        if let Some(fmt) = format {{ params.push(format!("format={{}}", fmt)); }}
+        let p = self.path();
+        if params.is_empty() {{ p }} else {{ format!("{{}}?{{}}", p, params.join("&")) }}
+    }}
+
+    fn get_json<T: DeserializeOwned>(&self, format: Option<&str>) -> Result<T> {{
+        self.client.get_json(&self.build_path(format))
+    }}
+
+    fn get_text(&self, format: Option<&str>) -> Result<String> {{
+        self.client.get_text(&self.build_path(format))
+    }}
+}}
+
+/// Builder for series endpoint queries.
+///
+/// Parameterized by element type `T` and response type `D` (defaults to `SeriesData<T>`).
+/// For date-based indexes, use `DateSeriesEndpoint<T>` which sets `D = DateSeriesData<T>`.
+///
+/// # Examples
+/// ```ignore
+/// let data = endpoint.fetch()?;                   // all data
+/// let data = endpoint.get(5).fetch()?;             // single item
+/// let data = endpoint.range(..10).fetch()?;        // first 10
+/// let data = endpoint.range(100..200).fetch()?;    // range [100, 200)
+/// let data = endpoint.take(10).fetch()?;           // first 10 (convenience)
+/// let data = endpoint.last(10).fetch()?;           // last 10
+/// let data = endpoint.skip(100).take(10).fetch()?; // iterator-style
+/// ```
+pub struct SeriesEndpoint<T, D = SeriesData<T>> {{
+    config: EndpointConfig,
+    _marker: std::marker::PhantomData<fn() -> (T, D)>,
+}}
+
+/// Builder for date-based series endpoint queries.
+///
+/// Like `SeriesEndpoint` but returns `DateSeriesData` and provides
+/// date-based access methods (`get_date`, `date_range`).
+pub type DateSeriesEndpoint<T> = SeriesEndpoint<T, DateSeriesData<T>>;
+
+impl<T: DeserializeOwned, D: DeserializeOwned> SeriesEndpoint<T, D> {{
+    pub fn new(client: Arc<BrkClientBase>, name: Arc<str>, index: Index) -> Self {{
+        Self {{ config: EndpointConfig::new(client, name, index), _marker: std::marker::PhantomData }}
+    }}
+
+    /// Select a specific index position.
+    pub fn get(mut self, index: usize) -> SingleItemBuilder<T, D> {{
+        self.config.start = Some(index as i64);
+        self.config.end = Some(index as i64 + 1);
+        SingleItemBuilder {{ config: self.config, _marker: std::marker::PhantomData }}
+    }}
+
+    /// Select a range using Rust range syntax.
+    ///
+    /// # Examples
+    /// ```ignore
+    /// endpoint.range(..10)      // first 10
+    /// endpoint.range(100..110)  // indices 100-109
+    /// endpoint.range(100..)     // from 100 to end
+    /// ```
+    pub fn range<R: RangeBounds<usize>>(mut self, range: R) -> RangeBuilder<T, D> {{
+        self.config.start = match range.start_bound() {{
+            Bound::Included(&n) => Some(n as i64),
+            Bound::Excluded(&n) => Some(n as i64 + 1),
+            Bound::Unbounded => None,
+        }};
+        self.config.end = match range.end_bound() {{
+            Bound::Included(&n) => Some(n as i64 + 1),
+            Bound::Excluded(&n) => Some(n as i64),
+            Bound::Unbounded => None,
+        }};
+        RangeBuilder {{ config: self.config, _marker: std::marker::PhantomData }}
+    }}
+
+    /// Take the first n items.
+    pub fn take(self, n: usize) -> RangeBuilder<T, D> {{
+        self.range(..n)
+    }}
+
+    /// Take the last n items.
+    pub fn last(mut self, n: usize) -> RangeBuilder<T, D> {{
+        if n == 0 {{
+            self.config.end = Some(0);
+        }} else {{
+            self.config.start = Some(-(n as i64));
+        }}
+        RangeBuilder {{ config: self.config, _marker: std::marker::PhantomData }}
+    }}
+
+    /// Skip the first n items. Chain with `take(n)` to get a range.
+    pub fn skip(mut self, n: usize) -> SkippedBuilder<T, D> {{
+        self.config.start = Some(n as i64);
+        SkippedBuilder {{ config: self.config, _marker: std::marker::PhantomData }}
+    }}
+
+    /// Fetch all data as parsed JSON.
+    pub fn fetch(self) -> Result<D> {{
+        self.config.get_json(None)
+    }}
+
+    /// Fetch all data as CSV string.
+    pub fn fetch_csv(self) -> Result<String> {{
+        self.config.get_text(Some("csv"))
+    }}
+
+    /// Get the base endpoint path.
+    pub fn path(&self) -> String {{
+        self.config.path()
+    }}
+}}
+
+/// Date-specific methods available only on `DateSeriesEndpoint`.
+impl<T: DeserializeOwned> SeriesEndpoint<T, DateSeriesData<T>> {{
+    /// Select a specific date position (for day-precision or coarser indexes).
+    pub fn get_date(self, date: Date) -> SingleItemBuilder<T, DateSeriesData<T>> {{
+        let index = self.config.index.date_to_index(date).unwrap_or(0);
+        self.get(index)
+    }}
+
+    /// Select a date range (for day-precision or coarser indexes).
+    pub fn date_range(self, start: Date, end: Date) -> RangeBuilder<T, DateSeriesData<T>> {{
+        let s = self.config.index.date_to_index(start).unwrap_or(0);
+        let e = self.config.index.date_to_index(end).unwrap_or(0);
+        self.range(s..e)
+    }}
+
+    /// Select a specific timestamp position (works for all date-based indexes including sub-daily).
+    pub fn get_timestamp(self, ts: Timestamp) -> SingleItemBuilder<T, DateSeriesData<T>> {{
+        let index = self.config.index.timestamp_to_index(ts).unwrap_or(0);
+        self.get(index)
+    }}
+
+    /// Select a timestamp range (works for all date-based indexes including sub-daily).
+    pub fn timestamp_range(self, start: Timestamp, end: Timestamp) -> RangeBuilder<T, DateSeriesData<T>> {{
+        let s = self.config.index.timestamp_to_index(start).unwrap_or(0);
+        let e = self.config.index.timestamp_to_index(end).unwrap_or(0);
+        self.range(s..e)
+    }}
+}}
+
+/// Builder for single item access.
+pub struct SingleItemBuilder<T, D = SeriesData<T>> {{
+    config: EndpointConfig,
+    _marker: std::marker::PhantomData<fn() -> (T, D)>,
+}}
+
+/// Date-aware single item builder.
+pub type DateSingleItemBuilder<T> = SingleItemBuilder<T, DateSeriesData<T>>;
+
+impl<T: DeserializeOwned, D: DeserializeOwned> SingleItemBuilder<T, D> {{
+    /// Fetch the single item.
+    pub fn fetch(self) -> Result<D> {{
+        self.config.get_json(None)
+    }}
+
+    /// Fetch the single item as CSV.
+    pub fn fetch_csv(self) -> Result<String> {{
+        self.config.get_text(Some("csv"))
+    }}
+}}
+
+/// Builder after calling `skip(n)`. Chain with `take(n)` to specify count.
+pub struct SkippedBuilder<T, D = SeriesData<T>> {{
+    config: EndpointConfig,
+    _marker: std::marker::PhantomData<fn() -> (T, D)>,
+}}
+
+/// Date-aware skipped builder.
+pub type DateSkippedBuilder<T> = SkippedBuilder<T, DateSeriesData<T>>;
+
+impl<T: DeserializeOwned, D: DeserializeOwned> SkippedBuilder<T, D> {{
+    /// Take n items after the skipped position.
+    pub fn take(mut self, n: usize) -> RangeBuilder<T, D> {{
+        let start = self.config.start.unwrap_or(0);
+        self.config.end = Some(start + n as i64);
+        RangeBuilder {{ config: self.config, _marker: std::marker::PhantomData }}
+    }}
+
+    /// Fetch from the skipped position to the end.
+    pub fn fetch(self) -> Result<D> {{
+        self.config.get_json(None)
+    }}
+
+    /// Fetch from the skipped position to the end as CSV.
+    pub fn fetch_csv(self) -> Result<String> {{
+        self.config.get_text(Some("csv"))
+    }}
+}}
+
+/// Builder with range fully specified.
+pub struct RangeBuilder<T, D = SeriesData<T>> {{
+    config: EndpointConfig,
+    _marker: std::marker::PhantomData<fn() -> (T, D)>,
+}}
+
+/// Date-aware range builder.
+pub type DateRangeBuilder<T> = RangeBuilder<T, DateSeriesData<T>>;
+
+impl<T: DeserializeOwned, D: DeserializeOwned> RangeBuilder<T, D> {{
+    /// Fetch the range as parsed JSON.
+    pub fn fetch(self) -> Result<D> {{
+        self.config.get_json(None)
+    }}
+
+    /// Fetch the range as CSV string.
+    pub fn fetch_csv(self) -> Result<String> {{
+        self.config.get_text(Some("csv"))
+    }}
+}}
+
+"#
+    )
+    .unwrap();
+}
+
+/// Generate index accessor structs.
+pub fn generate_index_accessors(output: &mut String, patterns: &[IndexSetPattern]) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    // Generate static index arrays
+    writeln!(output, "// Static index arrays").unwrap();
+    for (i, pattern) in patterns.iter().enumerate() {
+        write!(output, "const _I{}: &[Index] = &[", i + 1).unwrap();
+        for (j, index) in pattern.indexes.iter().enumerate() {
+            if j > 0 {
+                write!(output, ", ").unwrap();
+            }
+            write!(output, "Index::{}", index).unwrap();
+        }
+        writeln!(output, "];").unwrap();
+    }
+    writeln!(output).unwrap();
+
+    // Generate helper functions
+    writeln!(
+        output,
+        r#"#[inline]
+fn _ep<T: DeserializeOwned>(c: &Arc<BrkClientBase>, n: &Arc<str>, i: Index) -> SeriesEndpoint<T> {{
+    SeriesEndpoint::new(c.clone(), n.clone(), i)
+}}
+
+#[inline]
+fn _dep<T: DeserializeOwned>(c: &Arc<BrkClientBase>, n: &Arc<str>, i: Index) -> DateSeriesEndpoint<T> {{
+    DateSeriesEndpoint::new(c.clone(), n.clone(), i)
+}}
+"#
+    )
+    .unwrap();
+
+    // Generate index accessor structs
+    writeln!(output, "// Index accessor structs\n").unwrap();
+
+    for (i, pattern) in patterns.iter().enumerate() {
+        let by_name = format!("{}By", pattern.name);
+        let idx_const = format!("_I{}", i + 1);
+
+        // Generate the "By" struct
+        writeln!(output, "pub struct {}<T> {{ client: Arc<BrkClientBase>, name: Arc<str>, _marker: std::marker::PhantomData<T> }}", by_name).unwrap();
+        writeln!(output, "impl<T: DeserializeOwned> {}<T> {{", by_name).unwrap();
+        for index in &pattern.indexes {
+            let method_name = index_to_field_name(index);
+            if index.is_date_based() {
+                writeln!(
+                    output,
+                    "    pub fn {}(&self) -> DateSeriesEndpoint<T> {{ _dep(&self.client, &self.name, Index::{}) }}",
+                    method_name, index
+                )
+                .unwrap();
+            } else {
+                writeln!(
+                    output,
+                    "    pub fn {}(&self) -> SeriesEndpoint<T> {{ _ep(&self.client, &self.name, Index::{}) }}",
+                    method_name, index
+                )
+                .unwrap();
+            }
+        }
+        writeln!(output, "}}\n").unwrap();
+
+        // Generate the main accessor struct
+        writeln!(
+            output,
+            "pub struct {}<T> {{ name: Arc<str>, pub by: {}<T> }}",
+            pattern.name, by_name
+        )
+        .unwrap();
+        writeln!(output, "impl<T: DeserializeOwned> {}<T> {{", pattern.name).unwrap();
+        writeln!(
+            output,
+            "    pub fn new(client: Arc<BrkClientBase>, name: String) -> Self {{ let name: Arc<str> = name.into(); Self {{ name: name.clone(), by: {} {{ client, name, _marker: std::marker::PhantomData }} }} }}",
+            by_name
+        )
+        .unwrap();
+        writeln!(output, "    pub fn name(&self) -> &str {{ &self.name }}").unwrap();
+        writeln!(output, "}}\n").unwrap();
+
+        // Implement AnySeriesPattern trait
+        writeln!(
+            output,
+            "impl<T> AnySeriesPattern for {}<T> {{ fn name(&self) -> &str {{ &self.name }} fn indexes(&self) -> &'static [Index] {{ {} }} }}",
+            pattern.name, idx_const
+        )
+        .unwrap();
+
+        // Implement SeriesPattern<T> trait
+        writeln!(
+            output,
+            "impl<T: DeserializeOwned> SeriesPattern<T> for {}<T> {{ fn get(&self, index: Index) -> Option<SeriesEndpoint<T>> {{ {}.contains(&index).then(|| _ep(&self.by.client, &self.by.name, index)) }} }}\n",
+            pattern.name, idx_const
+        )
+        .unwrap();
+    }
+}
+
+/// Generate structural pattern structs.
+pub fn generate_pattern_structs(
+    output: &mut String,
+    patterns: &[StructuralPattern],
+    metadata: &ClientMetadata,
+) {
+    if patterns.is_empty() {
+        return;
+    }
+
+    writeln!(output, "// Reusable pattern structs\n").unwrap();
+
+    for pattern in patterns {
+        let generic_params = if pattern.is_generic { "<T>" } else { "" };
+
+        // Generate struct definition
+        writeln!(output, "/// Pattern struct for repeated tree structure.").unwrap();
+        writeln!(output, "pub struct {}{} {{", pattern.name, generic_params).unwrap();
+
+        for field in &pattern.fields {
+            let field_name = escape_rust_keyword(&to_snake_case(&field.name));
+            let type_annotation = metadata.field_type_annotation(
+                field,
+                pattern.is_generic,
+                None,
+                GenericSyntax::RUST,
+            );
+            writeln!(output, "    pub {}: {},", field_name, type_annotation).unwrap();
+        }
+
+        writeln!(output, "}}\n").unwrap();
+
+        // Skip constructor for non-parameterizable patterns (inlined at tree level)
+        if !metadata.is_parameterizable(&pattern.name) {
+            continue;
+        }
+
+        let impl_generic = if pattern.is_generic {
+            "<T: DeserializeOwned>"
+        } else {
+            ""
+        };
+        writeln!(
+            output,
+            "impl{} {}{} {{",
+            impl_generic, pattern.name, generic_params
+        )
+        .unwrap();
+
+        writeln!(
+            output,
+            "    /// Create a new pattern node with accumulated series name."
+        )
+        .unwrap();
+        if pattern.is_templated() {
+            writeln!(
+                output,
+                "    pub fn new(client: Arc<BrkClientBase>, acc: String, disc: String) -> Self {{"
+            )
+            .unwrap();
+        } else {
+            writeln!(
+                output,
+                "    pub fn new(client: Arc<BrkClientBase>, acc: String) -> Self {{"
+            )
+            .unwrap();
+        }
+        writeln!(output, "        Self {{").unwrap();
+
+        let syntax = RustSyntax;
+        for field in &pattern.fields {
+            generate_parameterized_field(output, &syntax, field, pattern, metadata, "            ");
+        }
+
+        writeln!(output, "        }}").unwrap();
+        writeln!(output, "    }}").unwrap();
+        writeln!(output, "}}\n").unwrap();
+    }
+}
@@ -0,0 +1,45 @@
+//! Rust client generation.
+//!
+//! This module generates a Rust client with full type safety for the BRK API.
+
+pub mod api;
+pub mod client;
+pub mod tree;
+mod types;
+
+use std::{fmt::Write, io, path::Path};
+
+use super::write_if_changed;
+use crate::{ClientMetadata, Endpoint};
+
+/// Generate Rust client from metadata and OpenAPI endpoints.
+///
+/// `output_path` is the full path to the output file (e.g., "crates/brk_client/src/lib.rs").
+pub fn generate_rust_client(
+    metadata: &ClientMetadata,
+    endpoints: &[Endpoint],
+    output_path: &Path,
+) -> io::Result<()> {
+    let mut output = String::new();
+
+    writeln!(output, "// Auto-generated BRK Rust client").unwrap();
+    writeln!(output, "// Do not edit manually\n").unwrap();
+    writeln!(output, "#![allow(non_camel_case_types)]").unwrap();
+    writeln!(output, "#![allow(dead_code)]").unwrap();
+    writeln!(output, "#![allow(unused_variables)]").unwrap();
+    writeln!(output, "#![allow(clippy::useless_format)]").unwrap();
+    writeln!(output, "#![allow(clippy::unnecessary_to_owned)]\n").unwrap();
+
+    client::generate_imports(&mut output);
+    client::generate_base_client(&mut output);
+    client::generate_series_pattern_trait(&mut output);
+    client::generate_endpoint(&mut output);
+    client::generate_index_accessors(&mut output, &metadata.index_set_patterns);
+    client::generate_pattern_structs(&mut output, &metadata.structural_patterns, metadata);
+    tree::generate_tree(&mut output, &metadata.catalog, metadata);
+    api::generate_main_client(&mut output, endpoints);
+
+    write_if_changed(output_path, &output)?;
+
+    Ok(())
+}
@@ -0,0 +1,126 @@
+//! Rust tree structure generation.
+
+use std::collections::BTreeSet;
+use std::fmt::Write;
+
+use brk_types::TreeNode;
+
+use crate::{
+    ClientMetadata, GenericSyntax, LanguageSyntax, PatternField, RustSyntax, build_child_path,
+    escape_rust_keyword, generate_leaf_field, generate_tree_node_field, prepare_tree_node,
+    to_snake_case,
+};
+
+/// Generate tree structs.
+pub fn generate_tree(output: &mut String, catalog: &TreeNode, metadata: &ClientMetadata) {
+    writeln!(output, "// Series tree\n").unwrap();
+
+    let pattern_lookup = metadata.pattern_lookup();
+    let mut generated = BTreeSet::new();
+    generate_tree_node(
+        output,
+        "SeriesTree",
+        "",
+        catalog,
+        pattern_lookup,
+        metadata,
+        &mut generated,
+    );
+}
+
+fn generate_tree_node(
+    output: &mut String,
+    name: &str,
+    path: &str,
+    node: &TreeNode,
+    pattern_lookup: &std::collections::BTreeMap<Vec<PatternField>, String>,
+    metadata: &ClientMetadata,
+    generated: &mut BTreeSet<String>,
+) {
+    let Some(ctx) = prepare_tree_node(node, name, path, pattern_lookup, metadata, generated) else {
+        return;
+    };
+
+    // Generate struct definition
+    writeln!(output, "/// Series tree node.").unwrap();
+    writeln!(output, "pub struct {} {{", name).unwrap();
+
+    for child in &ctx.children {
+        let field_name = escape_rust_keyword(&to_snake_case(child.name));
+        let type_annotation = if child.should_inline {
+            child.inline_type_name.clone()
+        } else {
+            metadata.field_type_annotation(&child.field, false, None, GenericSyntax::RUST)
+        };
+        writeln!(output, "    pub {}: {},", field_name, type_annotation).unwrap();
+    }
+
+    writeln!(output, "}}\n").unwrap();
+
+    // Generate impl block
+    writeln!(output, "impl {} {{", name).unwrap();
+    writeln!(
+        output,
+        "    pub fn new(client: Arc<BrkClientBase>, base_path: String) -> Self {{"
+    )
+    .unwrap();
+    writeln!(output, "        Self {{").unwrap();
+
+    let syntax = RustSyntax;
+    for child in &ctx.children {
+        let field_name = escape_rust_keyword(&to_snake_case(child.name));
+
+        if child.is_leaf {
+            if let TreeNode::Leaf(leaf) = child.node {
+                generate_leaf_field(
+                    output,
+                    &syntax,
+                    "client.clone()",
+                    child.name,
+                    leaf,
+                    metadata,
+                    "            ",
+                );
+            }
+        } else if child.should_inline {
+            // Inline struct type - only for nodes that don't match any pattern
+            let path_expr = syntax.path_expr("base_path", &format!("_{}", child.name));
+            writeln!(
+                output,
+                "            {}: {}::new(client.clone(), {}),",
+                field_name, child.inline_type_name, path_expr
+            )
+            .unwrap();
+        } else {
+            generate_tree_node_field(
+                output,
+                &syntax,
+                &child.field,
+                metadata,
+                "            ",
+                "client.clone()",
+                &child.base_result,
+            );
+        }
+    }
+
+    writeln!(output, "        }}").unwrap();
+    writeln!(output, "    }}").unwrap();
+    writeln!(output, "}}\n").unwrap();
+
+    // Generate child structs
+    for child in &ctx.children {
+        if child.should_inline {
+            let child_path = build_child_path(path, child.name);
+            generate_tree_node(
+                output,
+                &child.inline_type_name,
+                &child_path,
+                child.node,
+                pattern_lookup,
+                metadata,
+                generated,
+            );
+        }
+    }
+}
@@ -0,0 +1,17 @@
+//! Rust type conversion utilities.
+
+/// Convert JS-style type to Rust type.
+pub fn js_type_to_rust(js_type: &str) -> String {
+    if let Some(inner) = js_type.strip_suffix("[]") {
+        format!("Vec<{}>", js_type_to_rust(inner))
+    } else {
+        match js_type {
+            "string" => "String".to_string(),
+            "integer" => "i64".to_string(),
+            "number" => "f64".to_string(),
+            "boolean" => "bool".to_string(),
+            "*" | "Object" => "serde_json::Value".to_string(),
+            other => other.to_string(),
+        }
+    }
+}
@@ -0,0 +1,187 @@
+#![allow(clippy::type_complexity)]
+
+use std::{collections::btree_map::Entry, fs::create_dir_all, io, path::PathBuf};
+
+use brk_query::Vecs;
+
+/// Output path configuration for each language client.
+///
+/// Each path should be the full path to the output file, not just a directory.
+/// Parent directories will be created automatically if they don't exist.
+///
+/// # Example
+/// ```ignore
+/// let paths = ClientOutputPaths::new()
+///     .rust("crates/brk_client/src/lib.rs")
+///     .javascript("modules/brk-client/index.js")
+///     .python("packages/brk_client/__init__.py");
+/// ```
+#[derive(Debug, Clone, Default)]
+pub struct ClientOutputPaths {
+    /// Full path to Rust client file (e.g., "crates/brk_client/src/lib.rs")
+    pub rust: Option<PathBuf>,
+    /// Full path to JavaScript client file (e.g., "modules/brk-client/index.js")
+    pub javascript: Option<PathBuf>,
+    /// Full path to Python client file (e.g., "packages/brk_client/__init__.py")
+    pub python: Option<PathBuf>,
+}
+
+impl ClientOutputPaths {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn rust(mut self, path: impl Into<PathBuf>) -> Self {
+        self.rust = Some(path.into());
+        self
+    }
+
+    pub fn javascript(mut self, path: impl Into<PathBuf>) -> Self {
+        self.javascript = Some(path.into());
+        self
+    }
+
+    pub fn python(mut self, path: impl Into<PathBuf>) -> Self {
+        self.python = Some(path.into());
+        self
+    }
+}
+
+mod analysis;
+mod backends;
+mod generate;
+mod generators;
+mod openapi;
+mod syntax;
+mod types;
+
+pub use analysis::*;
+pub use backends::*;
+pub use generate::*;
+pub use generators::*;
+pub use openapi::*;
+pub use syntax::*;
+pub use types::*;
+
+pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// Generate all client libraries from the query vecs and OpenAPI JSON.
+///
+/// Uses `ClientOutputPaths` to specify the output file path for each language.
+/// Only languages with a configured path will be generated.
+///
+/// # Example
+/// ```ignore
+/// let paths = ClientOutputPaths::new()
+///     .rust("crates/brk_client/src/lib.rs")
+///     .javascript("modules/brk-client/index.js")
+///     .python("packages/brk_client/__init__.py");
+///
+/// generate_clients(&vecs, &openapi_json, &paths)?;
+/// ```
+pub fn generate_clients(
+    vecs: &Vecs,
+    openapi_json: &str,
+    output_paths: &ClientOutputPaths,
+) -> io::Result<()> {
+    let metadata = ClientMetadata::from_vecs(vecs);
+
+    // Parse OpenAPI spec
+    let spec = parse_openapi_json(openapi_json)?;
+    let endpoints = extract_endpoints(&spec);
+    let mut schemas = extract_schemas(openapi_json);
+
+    // Collect leaf type schemas from the catalog and merge into schemas
+    collect_leaf_type_schemas(&metadata.catalog, &mut schemas);
+
+    // Also collect definitions from all schemas (including OpenAPI schemas)
+    // We need to do this after collecting leaf schemas so we process everything
+    let schema_values: Vec<_> = schemas.values().cloned().collect();
+    for schema in &schema_values {
+        collect_schema_definitions(schema, &mut schemas);
+    }
+
+    // Generate Rust client (uses real brk_types, no schema conversion needed)
+    if let Some(rust_path) = &output_paths.rust {
+        if let Some(parent) = rust_path.parent() {
+            create_dir_all(parent)?;
+        }
+        generate_rust_client(&metadata, &endpoints, rust_path)?;
+    }
+
+    // Generate JavaScript client (needs schemas for type definitions)
+    if let Some(js_path) = &output_paths.javascript {
+        if let Some(parent) = js_path.parent() {
+            create_dir_all(parent)?;
+        }
+        generate_javascript_client(&metadata, &endpoints, &schemas, js_path)?;
+    }
+
+    // Generate Python client (needs schemas for type definitions)
+    if let Some(python_path) = &output_paths.python {
+        if let Some(parent) = python_path.parent() {
+            create_dir_all(parent)?;
+        }
+        generate_python_client(&metadata, &endpoints, &schemas, python_path)?;
+    }
+
+    Ok(())
+}
+
+use brk_types::TreeNode;
+use serde_json::Value;
+
+/// Recursively collect leaf type schemas from the tree and add to schemas map.
+/// Only adds schemas that aren't already present (OpenAPI schemas take precedence).
+/// Collects definitions from schemars-generated schemas (for referenced types).
+fn collect_leaf_type_schemas(node: &TreeNode, schemas: &mut TypeSchemas) {
+    match node {
+        TreeNode::Leaf(leaf) => {
+            // Collect definitions from the schema (schemars puts type schemas here)
+            // This includes the inner types like `Bitcoin` from `Close<Bitcoin>`
+            collect_schema_definitions(&leaf.schema, schemas);
+
+            // Get the type name for this leaf
+            let type_name = extract_inner_type(leaf.kind());
+
+            if let Entry::Vacant(e) = schemas.entry(type_name) {
+                // Unwrap single-element allOf
+                let schema = unwrap_allof(&leaf.schema);
+
+                // Add the schema if it's usable:
+                // - Simple type (has "type")
+                // - Object type with properties (complex types like OHLCCents, EmptyAddressData)
+                // - Enum type (has "enum" or "oneOf")
+                // - Or a $ref to another type
+                let has_type = schema.get("type").is_some();
+                let has_properties = schema.get("properties").is_some();
+                let has_enum = schema.get("enum").is_some() || schema.get("oneOf").is_some();
+                let is_ref = schema.get("$ref").is_some();
+
+                if has_type || has_properties || has_enum || is_ref {
+                    e.insert(schema.clone());
+                }
+            }
+        }
+        TreeNode::Branch(children) => {
+            for child in children.values() {
+                collect_leaf_type_schemas(child, schemas);
+            }
+        }
+    }
+}
+
+/// Collect type definitions from schemars-generated schema's definitions section.
+/// Schemars uses `definitions` or `$defs` to store referenced types.
+fn collect_schema_definitions(schema: &Value, schemas: &mut TypeSchemas) {
+    // Check both JSON Schema draft-07 style ("definitions") and draft 2019-09+ style ("$defs")
+    for key in ["definitions", "$defs"] {
+        if let Some(defs) = schema.get(key).and_then(|d| d.as_object()) {
+            for (name, def_schema) in defs {
+                if !schemas.contains_key(name) {
+                    schemas.insert(name.clone(), def_schema.clone());
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,379 @@
+use std::{collections::BTreeMap, io};
+
+use crate::ref_to_type_name;
+use oas3::Spec;
+use oas3::spec::{
+    ObjectOrReference, ObjectSchema, Operation, ParameterIn, PathItem, Schema, SchemaType,
+    SchemaTypeSet,
+};
+use serde_json::Value;
+
+/// Type schema extracted from OpenAPI components
+pub type TypeSchemas = BTreeMap<String, Value>;
+
+/// Endpoint information extracted from OpenAPI spec
+#[derive(Debug, Clone)]
+pub struct Endpoint {
+    /// HTTP method (GET, POST, etc.)
+    pub method: String,
+    /// Path template (e.g., "/blocks/{hash}")
+    pub path: String,
+    /// Operation ID (e.g., "getBlockByHash")
+    pub operation_id: Option<String>,
+    /// Short summary
+    pub summary: Option<String>,
+    /// Detailed description
+    pub description: Option<String>,
+    /// Path parameters
+    pub path_params: Vec<Parameter>,
+    /// Query parameters
+    pub query_params: Vec<Parameter>,
+    /// Response type (simplified)
+    pub response_type: Option<String>,
+    /// Whether this endpoint is deprecated
+    pub deprecated: bool,
+    /// Whether this endpoint supports CSV format (text/csv content type)
+    pub supports_csv: bool,
+}
+
+impl Endpoint {
+    /// Returns true if this endpoint should be included in client generation.
+    /// Only non-deprecated GET endpoints are included.
+    pub fn should_generate(&self) -> bool {
+        self.method == "GET" && !self.deprecated
+    }
+
+    /// Returns true if this endpoint returns JSON (has a response_type extracted from application/json).
+    pub fn returns_json(&self) -> bool {
+        self.response_type.is_some()
+    }
+
+    /// Returns the operation ID or generates one from the path.
+    /// The returned string uses the raw case from the spec (typically camelCase).
+    pub fn operation_name(&self) -> String {
+        if let Some(op_id) = &self.operation_id {
+            return op_id.clone();
+        }
+        // Generate from path: /api/block/{hash} -> "get_block"
+        // Skip "api" prefix, convert hyphens to underscores, avoid redundant param names
+        let mut parts: Vec<String> = Vec::new();
+        let mut prev_segment = "";
+
+        for segment in self.path.split('/').filter(|s| !s.is_empty()) {
+            if segment == "api" {
+                continue;
+            }
+            if let Some(param) = segment.strip_prefix('{').and_then(|s| s.strip_suffix('}')) {
+                // Only add "by_{param}" if the previous segment doesn't already contain the param name
+                let prev_normalized = prev_segment.replace('-', "_");
+                if !prev_normalized.ends_with(param) {
+                    parts.push(format!("by_{}", param));
+                }
+            } else {
+                let normalized = segment.replace('-', "_");
+                parts.push(normalized);
+                prev_segment = segment;
+            }
+        }
+        format!("get_{}", parts.join("_"))
+    }
+}
+
+/// Parameter information
+#[derive(Debug, Clone)]
+pub struct Parameter {
+    pub name: String,
+    pub required: bool,
+    pub param_type: String,
+    pub description: Option<String>,
+}
+
+/// Parse OpenAPI spec from JSON string
+///
+/// Pre-processes the JSON to handle oas3 limitations:
+/// - Removes unsupported siblings from `$ref` objects (oas3 only supports `summary` and `description`)
+pub fn parse_openapi_json(json: &str) -> io::Result<Spec> {
+    let mut value: Value =
+        serde_json::from_str(json).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+
+    // Clean up for oas3 compatibility
+    clean_for_oas3(&mut value);
+
+    let cleaned_json =
+        serde_json::to_string(&value).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+
+    oas3::from_json(&cleaned_json).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
+}
+
+/// Extract type schemas from OpenAPI JSON
+pub fn extract_schemas(json: &str) -> TypeSchemas {
+    let Ok(value) = serde_json::from_str::<Value>(json) else {
+        return BTreeMap::new();
+    };
+
+    value
+        .get("components")
+        .and_then(|c| c.get("schemas"))
+        .and_then(|s| s.as_object())
+        .map(|schemas| {
+            schemas
+                .iter()
+                .map(|(name, schema)| (name.clone(), schema.clone()))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+/// Clean up OpenAPI spec for oas3 compatibility.
+/// - Removes unsupported siblings from $ref objects (oas3 only supports summary and description)
+/// - Converts boolean schemas to object schemas (oas3 doesn't handle `"schema": true`)
+fn clean_for_oas3(value: &mut Value) {
+    match value {
+        Value::Object(map) => {
+            // Handle $ref with unsupported siblings
+            if map.contains_key("$ref") {
+                map.retain(|k, _| k == "$ref" || k == "summary" || k == "description");
+            } else {
+                // Convert boolean schemas to empty object schemas
+                if let Some(schema) = map.get_mut("schema")
+                    && schema.is_boolean()
+                {
+                    *schema = Value::Object(serde_json::Map::new());
+                }
+                for v in map.values_mut() {
+                    clean_for_oas3(v);
+                }
+            }
+        }
+        Value::Array(arr) => {
+            for v in arr {
+                clean_for_oas3(v);
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Extract all endpoints from OpenAPI spec
+pub fn extract_endpoints(spec: &Spec) -> Vec<Endpoint> {
+    let mut endpoints = Vec::new();
+
+    let Some(paths) = &spec.paths else {
+        return endpoints;
+    };
+
+    for (path, path_item) in paths {
+        for (method, operation) in get_operations(path_item) {
+            if let Some(endpoint) = extract_endpoint(path, method, operation) {
+                endpoints.push(endpoint);
+            }
+        }
+    }
+
+    endpoints
+}
+
+fn get_operations(path_item: &PathItem) -> Vec<(&'static str, &Operation)> {
+    [
+        ("GET", &path_item.get),
+        ("POST", &path_item.post),
+        ("PUT", &path_item.put),
+        ("DELETE", &path_item.delete),
+        ("PATCH", &path_item.patch),
+    ]
+    .into_iter()
+    .filter_map(|(method, op)| op.as_ref().map(|o| (method, o)))
+    .collect()
+}
+
+fn extract_endpoint(path: &str, method: &str, operation: &Operation) -> Option<Endpoint> {
+    let path_params = extract_path_parameters(path, operation);
+    let query_params = extract_parameters(operation, ParameterIn::Query);
+
+    let response_type = extract_response_type(operation);
+    let supports_csv = check_csv_support(operation);
+
+    Some(Endpoint {
+        method: method.to_string(),
+        path: path.to_string(),
+        operation_id: operation.operation_id.clone(),
+        summary: operation.summary.clone(),
+        description: operation.description.clone(),
+        path_params,
+        query_params,
+        response_type,
+        deprecated: operation.deprecated.unwrap_or(false),
+        supports_csv,
+    })
+}
+
+/// Check if the endpoint supports CSV format (has text/csv in 200 response content types).
+fn check_csv_support(operation: &Operation) -> bool {
+    let Some(responses) = operation.responses.as_ref() else {
+        return false;
+    };
+    let Some(response) = responses.get("200") else {
+        return false;
+    };
+    match response {
+        ObjectOrReference::Object(response) => response.content.contains_key("text/csv"),
+        ObjectOrReference::Ref { .. } => false,
+    }
+}
+
+/// Extract path parameters in the order they appear in the path URL.
+fn extract_path_parameters(path: &str, operation: &Operation) -> Vec<Parameter> {
+    // Extract parameter names from the path in order (e.g., "/api/series/{series}/{index}" -> ["series", "index"])
+    let path_order: Vec<&str> = path
+        .split('/')
+        .filter_map(|segment| segment.strip_prefix('{').and_then(|s| s.strip_suffix('}')))
+        .collect();
+
+    // Get all path parameters from the operation
+    let params = extract_parameters(operation, ParameterIn::Path);
+
+    // Sort by position in the path
+    let mut sorted_params: Vec<Parameter> = params;
+    sorted_params.sort_by_key(|p| {
+        path_order
+            .iter()
+            .position(|&name| name == p.name)
+            .unwrap_or(usize::MAX)
+    });
+
+    sorted_params
+}
+
+fn extract_parameters(operation: &Operation, location: ParameterIn) -> Vec<Parameter> {
+    operation
+        .parameters
+        .iter()
+        .filter_map(|p| match p {
+            ObjectOrReference::Object(param) if param.location == location => {
+                let param_type = param
+                    .schema
+                    .as_ref()
+                    .and_then(|s| match s {
+                        ObjectOrReference::Ref { ref_path, .. } => {
+                            ref_to_type_name(ref_path).map(|s| s.to_string())
+                        }
+                        ObjectOrReference::Object(obj_schema) => schema_to_type_name(obj_schema),
+                    })
+                    .unwrap_or_else(|| "string".to_string());
+                Some(Parameter {
+                    name: param.name.clone(),
+                    required: param.required.unwrap_or(false),
+                    param_type,
+                    description: param.description.clone(),
+                })
+            }
+            _ => None,
+        })
+        .collect()
+}
+
+fn extract_response_type(operation: &Operation) -> Option<String> {
+    let responses = operation.responses.as_ref()?;
+
+    // Look for 200 OK response
+    let response = responses.get("200")?;
+
+    match response {
+        ObjectOrReference::Object(response) => {
+            // Look for JSON content
+            let content = response.content.get("application/json")?;
+
+            match &content.schema {
+                Some(ObjectOrReference::Ref { ref_path, .. }) => {
+                    // Extract type name from reference like "#/components/schemas/Block"
+                    Some(ref_to_type_name(ref_path)?.to_string())
+                }
+                Some(ObjectOrReference::Object(schema)) => schema_to_type_name(schema),
+                None => None,
+            }
+        }
+        ObjectOrReference::Ref { .. } => None,
+    }
+}
+
+fn schema_type_from_schema(schema: &Schema) -> Option<String> {
+    match schema {
+        Schema::Boolean(_) => Some("boolean".to_string()),
+        Schema::Object(obj_or_ref) => match obj_or_ref.as_ref() {
+            ObjectOrReference::Object(obj_schema) => schema_to_type_name(obj_schema),
+            ObjectOrReference::Ref { ref_path, .. } => {
+                // Return the type name as-is (e.g., "Height", "Address")
+                // These should have definitions generated from schemas
+                ref_to_type_name(ref_path).map(|s| s.to_string())
+            }
+        },
+    }
+}
+
+fn schema_to_type_name(schema: &ObjectSchema) -> Option<String> {
+    if let Some(schema_type) = schema.schema_type.as_ref() {
+        return match schema_type {
+            SchemaTypeSet::Single(t) => single_type_to_name(t, schema),
+            SchemaTypeSet::Multiple(types) => {
+                // For nullable types like ["integer", "null"], return the non-null type
+                types
+                    .iter()
+                    .find(|t| !matches!(t, SchemaType::Null))
+                    .and_then(|t| single_type_to_name(t, schema))
+                    .or(Some("*".to_string()))
+            }
+        };
+    }
+
+    // Handle anyOf/oneOf unions (e.g., Option<RangeIndex> → anyOf: [$ref, null])
+    let variants = if !schema.any_of.is_empty() {
+        &schema.any_of
+    } else if !schema.one_of.is_empty() {
+        &schema.one_of
+    } else {
+        return None;
+    };
+
+    let types: Vec<String> = variants
+        .iter()
+        .filter_map(|v| match v {
+            ObjectOrReference::Ref { ref_path, .. } => {
+                ref_to_type_name(ref_path).map(|s| s.to_string())
+            }
+            ObjectOrReference::Object(obj) => {
+                // Skip null variants
+                if matches!(
+                    obj.schema_type.as_ref(),
+                    Some(SchemaTypeSet::Single(SchemaType::Null))
+                ) {
+                    return None;
+                }
+                schema_to_type_name(obj)
+            }
+        })
+        .collect();
+
+    match types.len() {
+        0 => None,
+        1 => Some(types.into_iter().next().unwrap()),
+        _ => Some(types.join(" | ")),
+    }
+}
+
+fn single_type_to_name(t: &SchemaType, schema: &ObjectSchema) -> Option<String> {
+    match t {
+        SchemaType::String => Some("string".to_string()),
+        SchemaType::Number => Some("number".to_string()),
+        SchemaType::Integer => Some("number".to_string()),
+        SchemaType::Boolean => Some("boolean".to_string()),
+        SchemaType::Array => {
+            let inner = match &schema.items {
+                Some(boxed_schema) => schema_type_from_schema(boxed_schema),
+                None => Some("*".to_string()),
+            };
+            inner.map(|t| format!("{}[]", t))
+        }
+        SchemaType::Object => Some("Object".to_string()),
+        SchemaType::Null => Some("null".to_string()),
+    }
+}
@@ -0,0 +1,122 @@
+//! Language-specific syntax traits for code generation.
+//!
+//! This module defines the `LanguageSyntax` trait that abstracts over
+//! language-specific code generation patterns, allowing shared generation
+//! logic to work across Python, JavaScript, and Rust backends.
+
+use crate::GenericSyntax;
+
+/// Language-specific syntax for code generation.
+///
+/// Implementations of this trait provide the language-specific formatting
+/// for generated client code. This allows the core generation logic to be
+/// written once and reused across all supported languages.
+pub trait LanguageSyntax {
+    /// Convert a field name to the language's naming convention.
+    ///
+    /// - Python/Rust: `snake_case`
+    /// - JavaScript: `camelCase`
+    fn field_name(&self, name: &str) -> String;
+
+    /// Format an interpolated path expression.
+    ///
+    /// # Arguments
+    /// * `base_var` - The variable name to interpolate (e.g., "acc", "base_path")
+    /// * `suffix` - The suffix to append (e.g., "_field_name")
+    ///
+    /// # Returns
+    /// - Python: `f'{acc}_suffix'`
+    /// - JavaScript: `` `${acc}_suffix` ``
+    /// - Rust: `format!("{acc}_suffix")`
+    fn path_expr(&self, base_var: &str, suffix: &str) -> String;
+
+    /// Format a suffix mode expression: `_m(acc, relative)`.
+    ///
+    /// Suffix mode appends the relative name to the accumulator.
+    /// - If relative is empty, returns just acc (identity)
+    /// - Otherwise: `{acc}_{relative}` or `{relative}` if acc is empty
+    ///
+    /// # Arguments
+    /// * `acc_var` - The accumulator variable name (e.g., "acc")
+    /// * `relative` - The relative name to append (e.g., "max_cost_basis")
+    fn suffix_expr(&self, acc_var: &str, relative: &str) -> String;
+
+    /// Format a prefix mode expression: `_p(prefix, acc)`.
+    ///
+    /// Prefix mode prepends the prefix to the accumulator.
+    /// - If prefix is empty, returns just acc (identity)
+    /// - Otherwise: `{prefix}{acc}` (prefix includes trailing underscore)
+    ///
+    /// # Arguments
+    /// * `prefix` - The prefix to prepend (e.g., "cumulative_")
+    /// * `acc_var` - The accumulator variable name (e.g., "acc")
+    fn prefix_expr(&self, prefix: &str, acc_var: &str) -> String;
+
+    /// Generate a constructor call for patterns and accessors.
+    ///
+    /// - Python: `TypeName(client, path)`
+    /// - JavaScript: `createTypeName(client, path)`
+    /// - Rust: `TypeName::new(client.clone(), path)`
+    fn constructor(&self, type_name: &str, path_expr: &str) -> String;
+
+    /// Generate a field initialization line.
+    ///
+    /// # Arguments
+    /// * `indent` - The indentation string
+    /// * `name` - The field name (already converted to language convention)
+    /// * `type_ann` - The type annotation (may be ignored by some languages)
+    /// * `value` - The initialization value/expression
+    ///
+    /// # Returns
+    /// - Python: `{indent}self.{name}: {type_ann} = {value}`
+    /// - JavaScript: `{indent}{name}: {value},`
+    /// - Rust: `{indent}{name}: {value},`
+    fn field_init(&self, indent: &str, name: &str, type_ann: &str, value: &str) -> String;
+
+    /// Get the generic type syntax for this language.
+    ///
+    /// - Python: `[T]` with default `Any`
+    /// - JavaScript: `<T>` with default `unknown`
+    /// - Rust: `<T>` with default `_`
+    fn generic_syntax(&self) -> GenericSyntax;
+
+    /// Format a string literal.
+    ///
+    /// - Python/JavaScript: `'value'` (single quotes)
+    /// - Rust: `"value"` (double quotes)
+    fn string_literal(&self, value: &str) -> String;
+
+    /// Get the constructor name/prefix for a type.
+    ///
+    /// - Python: `TypeName`
+    /// - JavaScript: `createTypeName`
+    /// - Rust: `TypeName::new`
+    fn constructor_name(&self, type_name: &str) -> String;
+
+    /// Return a variable as an owned value expression.
+    ///
+    /// - Rust: `var.clone()` (String needs explicit cloning)
+    /// - JavaScript/Python: `var` (no ownership)
+    fn owned_expr(&self, var: &str) -> String {
+        var.to_string()
+    }
+
+    /// Format a discriminator argument for passing to a templated child.
+    ///
+    /// Returns an expression computing the disc value from a template.
+    /// - `"pct99"` (static) → `'pct99'` (JS) / `"pct99".to_string()` (Rust)
+    /// - `""` (empty) → `disc` (pass parent's disc through)
+    /// - `"p1sd{disc}"` (suffix) → `_m('p1sd', disc)` (composed)
+    /// - `"ratio_{disc}_bps"` (embedded) → `` `ratio_${disc}_bps` `` (template literal)
+    fn disc_arg_expr(&self, template: &str) -> String;
+
+    /// Format a templated mode expression: substitute `{disc}` at runtime.
+    ///
+    /// The template contains `{disc}` placeholder. The generated code should
+    /// construct `_m(acc, template_with_disc_substituted)` at runtime.
+    ///
+    /// # Arguments
+    /// * `acc_var` - The accumulator variable (e.g., "acc")
+    /// * `template` - Template like `"ratio_{disc}_bps"` or `"{disc}"`
+    fn template_expr(&self, acc_var: &str, template: &str) -> String;
+}
@@ -0,0 +1,93 @@
+use brk_types::Index;
+
+/// Convert a string to PascalCase (e.g., "fee_rate" -> "FeeRate").
+pub fn to_pascal_case(s: &str) -> String {
+    s.replace('-', "_")
+        .split('_')
+        .map(|word| {
+            let mut chars = word.chars();
+            match chars.next() {
+                None => String::new(),
+                Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
+            }
+        })
+        .collect()
+}
+
+/// Convert a string to snake_case (no keyword escaping — backends handle that).
+pub fn to_snake_case(s: &str) -> String {
+    let sanitized = s.to_lowercase().replace('-', "_");
+
+    if sanitized.chars().next().is_some_and(|c| c.is_ascii_digit()) {
+        format!("_{}", sanitized)
+    } else {
+        sanitized
+    }
+}
+
+/// Escape Rust reserved keywords with `_` suffix (consistent with Python).
+pub fn escape_rust_keyword(name: &str) -> String {
+    match name {
+        "type" | "const" | "static" | "match" | "if" | "else" | "loop" | "while" | "for"
+        | "break" | "continue" | "return" | "fn" | "let" | "mut" | "ref" | "self" | "super"
+        | "mod" | "use" | "pub" | "crate" | "extern" | "impl" | "trait" | "struct" | "enum"
+        | "where" | "async" | "await" | "dyn" | "move" => format!("{}_", name),
+        _ => name.to_string(),
+    }
+}
+
+/// Convert a string to camelCase (e.g., "fee_rate" -> "feeRate").
+pub fn to_camel_case(s: &str) -> String {
+    let pascal = to_pascal_case(s);
+    let mut chars = pascal.chars();
+
+    let result = match chars.next() {
+        None => String::new(),
+        Some(first) => first.to_lowercase().collect::<String>() + chars.as_str(),
+    };
+
+    // Prefix with _ if starts with digit
+    if result.chars().next().is_some_and(|c| c.is_ascii_digit()) {
+        format!("_{}", result)
+    } else {
+        result
+    }
+}
+
+/// Convert an Index to a snake_case field name (e.g., Day1 -> day1).
+pub fn index_to_field_name(index: &Index) -> String {
+    to_snake_case(index.name())
+}
+
+/// Generate a child type/struct/class name (e.g., ParentName + child_name -> ParentName_ChildName).
+pub fn child_type_name(parent: &str, child: &str) -> String {
+    format!("{}_{}", parent, to_pascal_case(child))
+}
+
+/// Escape Python reserved keywords by appending an underscore.
+/// Also prefixes names starting with digits with an underscore.
+pub fn escape_python_keyword(name: &str) -> String {
+    const PYTHON_KEYWORDS: &[&str] = &[
+        "False", "None", "True", "and", "as", "assert", "async", "await", "break", "class",
+        "continue", "def", "del", "elif", "else", "except", "finally", "for", "from", "global",
+        "if", "import", "in", "is", "lambda", "nonlocal", "not", "or", "pass", "raise", "return",
+        "try", "while", "with", "yield",
+    ];
+
+    // Strip characters invalid in identifiers (e.g. `[]` from `txId[]`)
+    let name = name.replace(['[', ']'], "");
+
+    // Prefix with underscore if starts with digit
+    let name = if name.starts_with(|c: char| c.is_ascii_digit()) {
+        format!("_{}", name)
+    } else {
+        name.to_string()
+    };
+
+    // Append underscore if it's a keyword
+    if PYTHON_KEYWORDS.contains(&name.as_str()) {
+        format!("{}_", name)
+    } else {
+        name
+    }
+}
@@ -0,0 +1,158 @@
+//! Client metadata extracted from brk_query.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use brk_query::Vecs;
+use brk_types::{Index, SeriesLeafWithSchema};
+
+use super::{GenericSyntax, IndexSetPattern, PatternField, StructuralPattern, extract_inner_type};
+use crate::{PatternBaseResult, analysis};
+
+/// Metadata extracted from brk_query for client generation.
+#[derive(Debug)]
+pub struct ClientMetadata {
+    /// The catalog tree structure (with schemas in leaves)
+    pub catalog: brk_types::TreeNode,
+    /// Structural patterns - tree node shapes that repeat
+    pub structural_patterns: Vec<StructuralPattern>,
+    /// Index set patterns - sets of indexes that appear together on series
+    pub index_set_patterns: Vec<IndexSetPattern>,
+    /// Maps field signatures to pattern names (merged from concrete instances + pattern definitions)
+    pattern_lookup: BTreeMap<Vec<PatternField>, String>,
+    /// Maps concrete field signatures to their type parameter (for generic patterns)
+    concrete_to_type_param: BTreeMap<Vec<PatternField>, String>,
+    /// Maps tree paths to their computed PatternBaseResult
+    node_bases: BTreeMap<String, PatternBaseResult>,
+}
+
+impl ClientMetadata {
+    /// Extract metadata from brk_query::Vecs.
+    pub fn from_vecs(vecs: &Vecs) -> Self {
+        Self::from_catalog(vecs.catalog().clone())
+    }
+
+    /// Extract metadata from a catalog TreeNode directly.
+    pub fn from_catalog(catalog: brk_types::TreeNode) -> Self {
+        let (structural_patterns, concrete_to_pattern, concrete_to_type_param, node_bases) =
+            analysis::detect_structural_patterns(&catalog);
+        let index_set_patterns = analysis::detect_index_patterns(&catalog);
+
+        // Build merged pattern lookup: concrete instances + pattern definitions
+        let mut pattern_lookup = concrete_to_pattern;
+        for p in &structural_patterns {
+            pattern_lookup.insert(p.fields.clone(), p.name.clone());
+        }
+
+        ClientMetadata {
+            catalog,
+            structural_patterns,
+            index_set_patterns,
+            pattern_lookup,
+            concrete_to_type_param,
+            node_bases,
+        }
+    }
+
+    /// Find an index set pattern that matches the given indexes.
+    pub fn find_index_set_pattern(&self, indexes: &BTreeSet<Index>) -> Option<&IndexSetPattern> {
+        self.index_set_patterns
+            .iter()
+            .find(|p| &p.indexes == indexes)
+    }
+
+    /// Find a pattern by name.
+    pub fn find_pattern(&self, name: &str) -> Option<&StructuralPattern> {
+        self.structural_patterns.iter().find(|p| p.name == name)
+    }
+
+    /// Check if a pattern is fully parameterizable (recursively).
+    /// Returns false if the pattern or any nested branch pattern has no mode.
+    pub fn is_parameterizable(&self, name: &str) -> bool {
+        self.find_pattern(name).is_some_and(|p| {
+            p.is_parameterizable()
+                && p.fields.iter().all(|f| {
+                    !f.is_branch()
+                        || self.find_pattern(&f.rust_type).is_none()
+                        || self.is_parameterizable(&f.rust_type)
+                })
+        })
+    }
+
+    /// Find a pattern by its concrete fields.
+    pub fn find_pattern_by_fields(&self, fields: &[PatternField]) -> Option<&StructuralPattern> {
+        self.pattern_lookup
+            .get(fields)
+            .and_then(|name| self.find_pattern(name))
+    }
+
+    /// Get the type parameter for a generic pattern given its concrete fields.
+    pub fn get_type_param(&self, fields: &[PatternField]) -> Option<&String> {
+        self.concrete_to_type_param.get(fields)
+    }
+
+    /// Get the pre-computed pattern lookup map.
+    pub fn pattern_lookup(&self) -> &BTreeMap<Vec<PatternField>, String> {
+        &self.pattern_lookup
+    }
+
+    /// Get the pre-computed PatternBaseResult for a tree path.
+    pub fn get_node_base(&self, path: &str) -> Option<&PatternBaseResult> {
+        self.node_bases.get(path)
+    }
+
+    /// Generate type annotation for a field with language-specific syntax.
+    pub fn field_type_annotation(
+        &self,
+        field: &PatternField,
+        is_generic: bool,
+        generic_value_type: Option<&str>,
+        syntax: GenericSyntax,
+    ) -> String {
+        // Pattern type — single lookup instead of is_pattern_type + is_pattern_generic
+        if let Some(pattern) = self.find_pattern(&field.rust_type) {
+            if pattern.is_generic {
+                let type_param = field
+                    .type_param
+                    .as_deref()
+                    .or(generic_value_type)
+                    .unwrap_or(if is_generic { "T" } else { syntax.default_type });
+                return syntax.wrap(&field.rust_type, type_param);
+            }
+            return field.rust_type.clone();
+        }
+
+        // Branch type (non-pattern)
+        if field.is_branch() {
+            return field.rust_type.clone();
+        }
+
+        // Leaf type
+        let value_type = if is_generic && field.rust_type == "T" {
+            "T".to_string()
+        } else {
+            extract_inner_type(&field.rust_type)
+        };
+        if let Some(accessor) = self.find_index_set_pattern(&field.indexes) {
+            syntax.wrap(&accessor.name, &value_type)
+        } else {
+            syntax.wrap("SeriesNode", &value_type)
+        }
+    }
+
+    /// Generate type annotation for a leaf node with language-specific syntax.
+    ///
+    /// This is a simpler version of `field_type_annotation` that works directly
+    /// with a `SeriesLeafWithSchema` node instead of a `PatternField`.
+    pub fn field_type_annotation_from_leaf(
+        &self,
+        leaf: &SeriesLeafWithSchema,
+        syntax: GenericSyntax,
+    ) -> String {
+        let value_type = leaf.kind().to_string();
+        if let Some(accessor) = self.find_index_set_pattern(leaf.indexes()) {
+            syntax.wrap(&accessor.name, &value_type)
+        } else {
+            syntax.wrap("SeriesNode", &value_type)
+        }
+    }
+}
@@ -0,0 +1,68 @@
+//! Core types for client generation.
+
+mod case;
+mod metadata;
+mod positions;
+mod schema;
+mod structs;
+
+pub use case::*;
+pub use metadata::*;
+pub use positions::*;
+pub use schema::*;
+pub use structs::*;
+
+/// Language-specific syntax for generic type annotations.
+#[derive(Clone, Copy)]
+pub struct GenericSyntax {
+    pub open: char,
+    pub close: char,
+    pub default_type: &'static str,
+}
+
+impl GenericSyntax {
+    pub const PYTHON: Self = Self {
+        open: '[',
+        close: ']',
+        default_type: "Any",
+    };
+    pub const JAVASCRIPT: Self = Self {
+        open: '<',
+        close: '>',
+        default_type: "unknown",
+    };
+    pub const RUST: Self = Self {
+        open: '<',
+        close: '>',
+        default_type: "_",
+    };
+
+    pub fn wrap(&self, name: &str, type_param: &str) -> String {
+        // Convert the type_param from Rust syntax to target syntax
+        let converted = self.convert(type_param);
+        format!("{}{}{}{}", name, self.open, converted, self.close)
+    }
+
+    /// Convert a type string from Rust generic syntax to target language syntax.
+    ///
+    /// For Python, wrapper newtypes like `Close<Cents>` are flattened to just `Cents`
+    /// because Python type aliases can't be parameterized. This matches JS behavior.
+    pub fn convert(&self, type_str: &str) -> String {
+        // Flatten nested generics to innermost type (e.g., Close<Cents> -> Cents)
+        // This is needed because wrapper types like Close, Open, High, Low are
+        // just type aliases in generated code, not actual generic classes.
+        extract_inner_type_recursive(type_str)
+    }
+}
+
+/// Extract the innermost type from nested generics.
+/// E.g., `Close<Cents>` -> `Cents`, `Foo<Bar<Baz>>` -> `Baz`
+fn extract_inner_type_recursive(type_str: &str) -> String {
+    if let Some(start) = type_str.find('<')
+        && let Some(end) = type_str.rfind('>')
+    {
+        let inner = &type_str[start + 1..end];
+        return extract_inner_type_recursive(inner);
+    }
+    type_str.to_string()
+}
@@ -0,0 +1,34 @@
+//! Pattern mode and field parts for series name reconstruction.
+//!
+//! Patterns are either suffix mode or prefix mode:
+//! - Suffix mode: `_m(acc, relative)` → `acc_relative` or just `relative` if acc empty
+//! - Prefix mode: `_p(prefix, acc)` → `prefix_acc` or just `acc` if prefix empty
+
+use std::collections::BTreeMap;
+
+/// How a pattern constructs series names from the accumulator.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PatternMode {
+    /// Fields append their relative name to acc.
+    /// Formula: `_m(acc, relative)` → `{acc}_{relative}` or `{relative}` if acc empty
+    /// Example: `_m("lth", "max_cost_basis")` → `"lth_max_cost_basis"`
+    Suffix {
+        /// Maps field name to its relative name (full series name when acc = "")
+        relatives: BTreeMap<String, String>,
+    },
+    /// Fields prepend their prefix to acc.
+    /// Formula: `_p(prefix, acc)` → `{prefix}_{acc}` or `{acc}` if prefix empty
+    /// Example: `_p("cumulative", "lth_realized_loss")` → `"cumulative_lth_realized_loss"`
+    Prefix {
+        /// Maps field name to its prefix (empty string for identity)
+        prefixes: BTreeMap<String, String>,
+    },
+    /// Fields construct series names using a template with a discriminator placeholder.
+    /// Factory takes two params: `acc` (base) and `disc` (discriminator).
+    /// Formula: `_m(acc, template.replace("{disc}", disc))`
+    /// Example: template `"ratio_{disc}_bps"` with disc `"pct99"` → `_m(acc, "ratio_pct99_bps")`
+    Templated {
+        /// Maps field name to its template string containing `{disc}` placeholder
+        templates: BTreeMap<String, String>,
+    },
+}
@@ -0,0 +1,43 @@
+use serde_json::Value;
+
+/// Unwrap allOf with a single element, returning the inner schema.
+/// Schemars uses allOf for composition, but often with just one $ref.
+pub fn unwrap_allof(schema: &Value) -> &Value {
+    if let Some(all_of) = schema.get("allOf").and_then(|v| v.as_array())
+        && all_of.len() == 1
+    {
+        return &all_of[0];
+    }
+    schema
+}
+
+/// Extract inner type from a wrapper generic like `Close<Dollars>` -> `Dollars`.
+/// Also handles malformed types like `Dollars>` (from vecdb's short_type_name).
+pub fn extract_inner_type(type_str: &str) -> String {
+    // Handle proper generic wrappers like `Close<Dollars>` -> `Dollars`
+    if let Some(start) = type_str.find('<')
+        && let Some(end) = type_str.rfind('>')
+        && start < end
+    {
+        return type_str[start + 1..end].to_string();
+    }
+    // Handle malformed types like `Dollars>` (trailing > without <)
+    if type_str.ends_with('>') && !type_str.contains('<') {
+        return type_str.trim_end_matches('>').to_string();
+    }
+    type_str.to_string()
+}
+
+/// Extract type name from a JSON Schema $ref path.
+/// E.g., "#/definitions/MyType" -> "MyType", "#/$defs/Foo" -> "Foo"
+pub fn ref_to_type_name(ref_path: &str) -> Option<&str> {
+    ref_path.rsplit('/').next()
+}
+
+/// Get union variants from anyOf or oneOf schema.
+pub fn get_union_variants(schema: &Value) -> Option<&Vec<Value>> {
+    schema
+        .get("anyOf")
+        .or_else(|| schema.get("oneOf"))
+        .and_then(|v| v.as_array())
+}
@@ -0,0 +1,188 @@
+//! Structural pattern and field types.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use brk_types::Index;
+
+use super::PatternMode;
+
+/// A pattern of indexes that appear together on multiple series.
+#[derive(Debug, Clone)]
+pub struct IndexSetPattern {
+    /// Pattern name (e.g., "DateHeightIndexes")
+    pub name: String,
+    /// The set of indexes
+    pub indexes: BTreeSet<Index>,
+}
+
+/// A structural pattern - a branch structure that appears multiple times.
+#[derive(Debug, Clone)]
+pub struct StructuralPattern {
+    /// Pattern name
+    pub name: String,
+    /// Ordered list of child fields
+    pub fields: Vec<PatternField>,
+    /// How fields construct series names from acc (None = not parameterizable)
+    pub mode: Option<PatternMode>,
+    /// If true, all leaf fields use a type parameter T
+    pub is_generic: bool,
+}
+
+impl StructuralPattern {
+    /// Returns true if this pattern can be parameterized with an accumulator.
+    pub fn is_parameterizable(&self) -> bool {
+        self.mode.is_some()
+    }
+
+    /// Get the field part (relative name or prefix) for a given field.
+    pub fn get_field_part(&self, field_name: &str) -> Option<&str> {
+        match &self.mode {
+            Some(PatternMode::Suffix { relatives }) => {
+                relatives.get(field_name).map(|s| s.as_str())
+            }
+            Some(PatternMode::Prefix { prefixes }) => prefixes.get(field_name).map(|s| s.as_str()),
+            Some(PatternMode::Templated { templates }) => {
+                templates.get(field_name).map(|s| s.as_str())
+            }
+            None => None,
+        }
+    }
+
+    /// Returns true if this pattern is in suffix mode.
+    pub fn is_suffix_mode(&self) -> bool {
+        matches!(
+            &self.mode,
+            Some(PatternMode::Suffix { .. } | PatternMode::Templated { .. })
+        )
+    }
+
+    /// Returns true if this pattern uses templated mode with a discriminator.
+    pub fn is_templated(&self) -> bool {
+        matches!(&self.mode, Some(PatternMode::Templated { .. }))
+    }
+
+    /// Extract the discriminator value from a concrete instance's field_parts.
+    /// Uses the pattern's templates to reverse-match and find the disc.
+    pub fn extract_disc_from_instance(
+        &self,
+        instance_field_parts: &BTreeMap<String, String>,
+    ) -> Option<String> {
+        let templates = match &self.mode {
+            Some(PatternMode::Templated { templates }) => templates,
+            _ => return None,
+        };
+        // Find a template with {disc} and extract the disc from the instance value.
+        // Strip leading underscore since _m() handles separators.
+        for (field_name, template) in templates {
+            if let Some(value) = instance_field_parts.get(field_name)
+                && let Some(disc) = extract_disc(template, value)
+            {
+                return Some(disc.trim_start_matches('_').to_string());
+            }
+        }
+        // If no template matched (all empty templates), disc is empty
+        Some(String::new())
+    }
+
+    /// Check if the given instance field parts match this pattern's field parts.
+    pub fn field_parts_match(&self, instance_field_parts: &BTreeMap<String, String>) -> bool {
+        match &self.mode {
+            Some(PatternMode::Suffix { relatives }) => {
+                relatives.iter().all(|(field_name, pattern_suffix)| {
+                    instance_field_parts
+                        .get(field_name)
+                        .is_some_and(|instance_suffix| instance_suffix == pattern_suffix)
+                })
+            }
+            Some(PatternMode::Prefix { prefixes }) => {
+                prefixes.iter().all(|(field_name, pattern_prefix)| {
+                    instance_field_parts
+                        .get(field_name)
+                        .is_some_and(|instance_prefix| instance_prefix == pattern_prefix)
+                })
+            }
+            Some(PatternMode::Templated { templates }) => {
+                // For templated patterns, check if the instance's field_parts
+                // can be produced by substituting some discriminator into the templates
+                let first_template_field = templates.iter().next();
+                let Some((ref_field, ref_template)) = first_template_field else {
+                    return false;
+                };
+                let Some(ref_value) = instance_field_parts.get(ref_field) else {
+                    return false;
+                };
+                // Extract discriminator from the reference field
+                let Some(disc) = extract_disc(ref_template, ref_value) else {
+                    return false;
+                };
+                // Verify all fields match with this discriminator
+                templates.iter().all(|(field_name, template)| {
+                    instance_field_parts
+                        .get(field_name)
+                        .is_some_and(|value| *value == template.replace("{disc}", &disc))
+                })
+            }
+            None => false,
+        }
+    }
+}
+
+/// Extract the discriminator value by matching a template against a concrete string.
+/// E.g., template `"ratio_{disc}_bps"` matched against `"ratio_pct99_bps"` yields `"pct99"`.
+fn extract_disc(template: &str, value: &str) -> Option<String> {
+    let (prefix, suffix) = template.split_once("{disc}")?;
+    if value.starts_with(prefix) && value.ends_with(suffix) {
+        let disc = &value[prefix.len()..value.len() - suffix.len()];
+        if !disc.is_empty() {
+            return Some(disc.to_string());
+        }
+    }
+    None
+}
+
+/// A field in a structural pattern.
+#[derive(Debug, Clone, PartialOrd, Ord)]
+pub struct PatternField {
+    /// Field name
+    pub name: String,
+    /// Rust type for leaves or pattern name for branches
+    pub rust_type: String,
+    /// JSON type from schema
+    pub json_type: String,
+    /// For leaves: the set of supported indexes. Empty for branches.
+    pub indexes: BTreeSet<Index>,
+    /// For branches referencing generic patterns: the concrete type parameter
+    pub type_param: Option<String>,
+}
+
+impl PatternField {
+    /// Returns true if this is a leaf field (has indexes).
+    pub fn is_leaf(&self) -> bool {
+        !self.indexes.is_empty()
+    }
+
+    /// Returns true if this is a branch field (no indexes).
+    pub fn is_branch(&self) -> bool {
+        self.indexes.is_empty()
+    }
+}
+
+impl std::hash::Hash for PatternField {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.name.hash(state);
+        self.rust_type.hash(state);
+        self.json_type.hash(state);
+        self.indexes.hash(state);
+    }
+}
+
+impl PartialEq for PatternField {
+    fn eq(&self, other: &Self) -> bool {
+        self.name == other.name
+            && self.rust_type == other.rust_type
+            && self.json_type == other.json_type
+            && self.indexes == other.indexes
+    }
+}
+
+impl Eq for PatternField {}
@@ -0,0 +1,917 @@
+// //! Tests that verify pattern analysis using the real catalog.
+
+// use std::collections::{BTreeMap, BTreeSet};
+// use std::fmt::Write;
+
+// use brk_bindgen::ClientMetadata;
+// use brk_types::TreeNode;
+
+// /// Load the catalog from the JSON file.
+// fn load_catalog() -> TreeNode {
+//     let path = concat!(env!("CARGO_MANIFEST_DIR"), "/catalog.json");
+//     let catalog_json = std::fs::read_to_string(path).expect("Failed to read catalog.json");
+//     serde_json::from_str(&catalog_json).expect("Failed to parse catalog.json")
+// }
+
+// /// Load OpenAPI spec from openapi.json.
+// fn load_openapi_json() -> String {
+//     let path = concat!(env!("CARGO_MANIFEST_DIR"), "/openapi.json");
+//     std::fs::read_to_string(path).expect("Failed to read openapi.json")
+// }
+
+// /// Load metadata from the catalog.
+// #[allow(unused)]
+// fn load_metadata() -> ClientMetadata {
+//     ClientMetadata::from_catalog(load_catalog())
+// }
+
+// /// Collect all leaf metric names from a tree.
+// fn collect_leaf_names(node: &TreeNode, names: &mut BTreeSet<String>) {
+//     match node {
+//         TreeNode::Leaf(leaf) => {
+//             names.insert(leaf.name().to_string());
+//         }
+//         TreeNode::Branch(children) => {
+//             for child in children.values() {
+//                 collect_leaf_names(child, names);
+//             }
+//         }
+//     }
+// }
+
+// #[test]
+// fn test_catalog_loads() {
+//     let catalog = load_catalog();
+
+//     // Should be a branch with top-level categories
+//     let TreeNode::Branch(categories) = &catalog else {
+//         panic!("Expected catalog to be a branch");
+//     };
+
+//     // Check some expected top-level categories exist
+//     assert!(
+//         categories.contains_key("addresses"),
+//         "Missing addresses category"
+//     );
+//     assert!(categories.contains_key("blocks"), "Missing blocks category");
+//     assert!(categories.contains_key("market"), "Missing market category");
+//     assert!(categories.contains_key("supply"), "Missing supply category");
+
+//     println!("Catalog has {} top-level categories", categories.len());
+// }
+
+// #[test]
+// fn test_all_leaves_have_names() {
+//     let catalog = load_catalog();
+//     let mut names = BTreeSet::new();
+//     collect_leaf_names(&catalog, &mut names);
+
+//     println!("Catalog has {} unique metric names", names.len());
+//     assert!(!names.is_empty(), "Should have at least some metrics");
+
+//     // All names should be non-empty
+//     for name in &names {
+//         assert!(!name.is_empty(), "Found empty metric name");
+//     }
+// }
+
+// #[test]
+// fn test_pattern_detection() {
+//     let catalog = load_catalog();
+
+//     let (patterns, concrete_to_pattern, concrete_to_type_param, _node_bases) =
+//         brk_bindgen::detect_structural_patterns(&catalog);
+
+//     println!("Detected {} structural patterns", patterns.len());
+//     println!(
+//         "Concrete to pattern mappings: {}",
+//         concrete_to_pattern.len()
+//     );
+//     println!("Type parameter mappings: {}", concrete_to_type_param.len());
+
+//     // Print pattern details
+//     for pattern in &patterns {
+//         let mode_str = match &pattern.mode {
+//             Some(brk_bindgen::PatternMode::Suffix { relatives }) => {
+//                 format!("Suffix({})", relatives.len())
+//             }
+//             Some(brk_bindgen::PatternMode::Prefix { prefixes }) => {
+//                 format!("Prefix({})", prefixes.len())
+//             }
+//             None => "None".to_string(),
+//         };
+//         println!(
+//             "  {} (fields: {}, generic: {}, mode: {})",
+//             pattern.name,
+//             pattern.fields.len(),
+//             pattern.is_generic,
+//             mode_str
+//         );
+//     }
+
+//     // Should have detected some patterns
+//     assert!(!patterns.is_empty(), "Should detect at least some patterns");
+
+//     // Check that parameterizable patterns have valid modes
+//     for pattern in &patterns {
+//         if pattern.is_parameterizable() {
+//             let mode = pattern.mode.as_ref().unwrap();
+//             match mode {
+//                 brk_bindgen::PatternMode::Suffix { relatives } => {
+//                     assert_eq!(
+//                         relatives.len(),
+//                         pattern.fields.len(),
+//                         "Pattern {} should have relative for each field",
+//                         pattern.name
+//                     );
+//                 }
+//                 brk_bindgen::PatternMode::Prefix { prefixes } => {
+//                     assert_eq!(
+//                         prefixes.len(),
+//                         pattern.fields.len(),
+//                         "Pattern {} should have prefix for each field",
+//                         pattern.name
+//                     );
+//                 }
+//             }
+//         }
+//     }
+// }
+
+// #[test]
+// fn test_cost_basis_pattern() {
+//     let catalog = load_catalog();
+
+//     let (patterns, _, _, _) = brk_bindgen::detect_structural_patterns(&catalog);
+
+//     // Find CostBasisPattern2 and inspect it
+//     let cost_basis = patterns
+//         .iter()
+//         .find(|p| p.name == "CostBasisPattern2")
+//         .expect("CostBasisPattern2 should exist");
+
+//     println!("CostBasisPattern2:");
+//     println!(
+//         "  Fields: {:?}",
+//         cost_basis
+//             .fields
+//             .iter()
+//             .map(|f| &f.name)
+//             .collect::<Vec<_>>()
+//     );
+//     println!("  Mode: {:?}", cost_basis.mode);
+//     println!("  Is generic: {}", cost_basis.is_generic);
+
+//     // With suffix naming convention (cost_basis_max, cost_basis_min, cost_basis):
+//     //
+//     // At root level: common prefix is "cost_basis_" -> suffix mode
+//     //   max -> "max"
+//     //   min -> "min"
+//     //   percentiles -> "" (identity)
+//     //
+//     // At lth_ level: common prefix is "lth_cost_basis_" -> suffix mode
+//     //   max -> "max"
+//     //   min -> "min"
+//     //   percentiles -> "" (identity)
+//     //
+//     // Both use suffix mode with same relatives, so pattern IS parameterizable!
+//     assert!(
+//         cost_basis.is_parameterizable(),
+//         "CostBasisPattern2 should be parameterizable with consistent suffix mode"
+//     );
+// }
+
+// #[test]
+// fn test_realized_pattern3_fields() {
+//     let catalog = load_catalog();
+//     let metadata = ClientMetadata::from_catalog(catalog);
+
+//     let pattern = metadata
+//         .find_pattern("RealizedPattern3")
+//         .expect("RealizedPattern3 should exist");
+
+//     println!("RealizedPattern3 fields:");
+//     for field in &pattern.fields {
+//         let is_branch = field.is_branch();
+//         let is_pattern = metadata.find_pattern(&field.rust_type).is_some();
+//         let is_param = metadata.is_parameterizable(&field.rust_type);
+//         println!(
+//             "  {} -> {} (branch={}, pattern={}, param={})",
+//             field.name, field.rust_type, is_branch, is_pattern, is_param
+//         );
+//     }
+
+//     // Check if RealizedPattern3 is considered parameterizable
+//     println!(
+//         "\nRealizedPattern3 is_parameterizable (metadata): {}",
+//         metadata.is_parameterizable("RealizedPattern3")
+//     );
+// }
+
+// #[test]
+// fn test_parameterizable_patterns_have_mode() {
+//     let catalog = load_catalog();
+//     let (patterns, _, _, _) = brk_bindgen::detect_structural_patterns(&catalog);
+
+//     // All patterns that appear 2+ times should either:
+//     // 1. Be parameterizable (have a mode)
+//     // 2. Or have inconsistent instances (mode = None)
+//     //
+//     // Patterns with mode = None should be inlined, not generate factories
+
+//     let parameterizable: Vec<_> = patterns.iter().filter(|p| p.is_parameterizable()).collect();
+//     let non_parameterizable: Vec<_> = patterns
+//         .iter()
+//         .filter(|p| !p.is_parameterizable())
+//         .collect();
+
+//     println!("\nParameterizable patterns ({}):", parameterizable.len());
+//     for p in &parameterizable {
+//         let mode = p.mode.as_ref().unwrap();
+//         let mode_type = match mode {
+//             brk_bindgen::PatternMode::Suffix { .. } => "Suffix",
+//             brk_bindgen::PatternMode::Prefix { .. } => "Prefix",
+//         };
+//         println!("  {} ({} fields, {})", p.name, p.fields.len(), mode_type);
+//     }
+
+//     println!(
+//         "\nNon-parameterizable patterns ({}):",
+//         non_parameterizable.len()
+//     );
+//     for p in &non_parameterizable {
+//         println!("  {} ({} fields)", p.name, p.fields.len());
+//     }
+
+//     // Verify all parameterizable patterns have valid modes with all fields
+//     for pattern in &parameterizable {
+//         let mode = pattern.mode.as_ref().unwrap();
+//         let field_names: BTreeSet<_> = pattern.fields.iter().map(|f| f.name.clone()).collect();
+
+//         match mode {
+//             brk_bindgen::PatternMode::Suffix { relatives } => {
+//                 let mode_fields: BTreeSet<_> = relatives.keys().cloned().collect();
+//                 assert_eq!(
+//                     field_names, mode_fields,
+//                     "Pattern {} suffix mode should have all fields",
+//                     pattern.name
+//                 );
+//             }
+//             brk_bindgen::PatternMode::Prefix { prefixes } => {
+//                 let mode_fields: BTreeSet<_> = prefixes.keys().cloned().collect();
+//                 assert_eq!(
+//                     field_names, mode_fields,
+//                     "Pattern {} prefix mode should have all fields",
+//                     pattern.name
+//                 );
+//             }
+//         }
+//     }
+// }
+
+// #[test]
+// fn test_fee_rate_pattern_relatives() {
+//     let catalog = load_catalog();
+//     let (patterns, _, _, _) = brk_bindgen::detect_structural_patterns(&catalog);
+
+//     let fee_rate_pattern = patterns
+//         .iter()
+//         .find(|p| p.name == "FeeRatePattern")
+//         .expect("FeeRatePattern should exist");
+
+//     println!("FeeRatePattern mode:");
+//     if let Some(mode) = &fee_rate_pattern.mode {
+//         match mode {
+//             brk_bindgen::PatternMode::Suffix { relatives } => {
+//                 println!("  Suffix mode:");
+//                 for (field, relative) in relatives {
+//                     println!("    {} -> '{}'", field, relative);
+//                 }
+//             }
+//             brk_bindgen::PatternMode::Prefix { prefixes } => {
+//                 println!("  Prefix mode:");
+//                 for (field, prefix) in prefixes {
+//                     println!("    {} -> '{}'", field, prefix);
+//                 }
+//             }
+//         }
+//     } else {
+//         println!("  No mode (not parameterizable)");
+//     }
+
+//     // Check that relatives are correct - should be "average", "max", etc.
+//     // NOT "tx_weight_average", "tx_weight_max", etc.
+//     if let Some(brk_bindgen::PatternMode::Suffix { relatives }) = &fee_rate_pattern.mode {
+//         assert_eq!(
+//             relatives.get("average"),
+//             Some(&"average".to_string()),
+//             "average relative should be 'average', not 'tx_weight_average'"
+//         );
+//     }
+// }
+
+// #[test]
+// fn test_index_patterns() {
+//     let catalog = load_catalog();
+
+//     let index_patterns = brk_bindgen::detect_index_patterns(&catalog);
+
+//     // println!("Used indexes: {:?}", used_indexes);
+//     println!("Index set patterns: {}", index_patterns.len());
+
+//     for pattern in &index_patterns {
+//         println!("  {} -> {:?}", pattern.name, pattern.indexes);
+//     }
+
+//     // Should have detected some index patterns
+//     assert!(!index_patterns.is_empty(), "Should detect index patterns");
+// }
+
+// #[test]
+// fn test_generated_rust_output() {
+//     let catalog = load_catalog();
+//     let metadata = ClientMetadata::from_catalog(catalog.clone());
+
+//     // Collect all metric names from the catalog
+//     let mut all_metrics = BTreeSet::new();
+//     collect_leaf_names(&catalog, &mut all_metrics);
+
+//     // Generate Rust client output
+//     let mut rust_output = String::new();
+//     brk_bindgen::rust::client::generate_imports(&mut rust_output);
+//     brk_bindgen::rust::client::generate_base_client(&mut rust_output);
+//     brk_bindgen::rust::client::generate_metric_pattern_trait(&mut rust_output);
+//     brk_bindgen::rust::client::generate_endpoint(&mut rust_output);
+//     brk_bindgen::rust::client::generate_index_accessors(
+//         &mut rust_output,
+//         &metadata.index_set_patterns,
+//     );
+//     brk_bindgen::rust::client::generate_pattern_structs(
+//         &mut rust_output,
+//         &metadata.structural_patterns,
+//         &metadata,
+//     );
+//     brk_bindgen::rust::tree::generate_tree(&mut rust_output, &metadata.catalog, &metadata);
+//     brk_bindgen::rust::api::generate_main_client(&mut rust_output, &[]);
+
+//     // Count metrics that appear as direct string literals
+//     let mut direct_metrics = 0;
+//     for metric in &all_metrics {
+//         if rust_output.contains(&format!("\"{}\"", metric)) {
+//             direct_metrics += 1;
+//         }
+//     }
+
+//     println!("\nGenerated Rust output stats:");
+//     println!("  Total metrics in catalog: {}", all_metrics.len());
+//     println!("  Direct string literals: {}", direct_metrics);
+//     println!(
+//         "  Via pattern factories: {}",
+//         all_metrics.len() - direct_metrics
+//     );
+//     println!("  Output size: {} bytes", rust_output.len());
+
+//     // Write output to test directory (not actual client)
+//     let output_dir = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/output");
+//     std::fs::create_dir_all(output_dir).ok();
+//     let output_path = format!("{}/rust_client.rs", output_dir);
+//     std::fs::write(&output_path, &rust_output).expect("Failed to write client output");
+//     println!("  Wrote output to: {}", output_path);
+
+//     // Verify the output contains the key components
+//     assert!(rust_output.contains("fn _m("), "Should define _m helper");
+//     assert!(
+//         rust_output.contains("pub struct MetricsTree"),
+//         "Should have MetricsTree"
+//     );
+//     assert!(
+//         rust_output.contains("impl MetricsTree"),
+//         "Should have MetricsTree impl"
+//     );
+
+//     // Count parameterizable patterns (these use _m for dynamic metric names)
+//     // Use metadata.is_parameterizable() for full recursive check
+//     let parameterizable_count = metadata
+//         .structural_patterns
+//         .iter()
+//         .filter(|p| metadata.is_parameterizable(&p.name))
+//         .count();
+//     println!("  Parameterizable patterns: {}", parameterizable_count);
+
+//     // Verify all pattern structs are generated (parameterizable and non)
+//     for pattern in &metadata.structural_patterns {
+//         assert!(
+//             rust_output.contains(&format!("pub struct {}", pattern.name)),
+//             "Missing pattern struct: {}",
+//             pattern.name
+//         );
+//     }
+
+//     println!("\nGenerated Rust client is complete!");
+// }
+
+// #[test]
+// fn test_generated_javascript_output() {
+//     let catalog = load_catalog();
+//     let metadata = ClientMetadata::from_catalog(catalog.clone());
+
+//     // Collect all metric names from the catalog
+//     let mut all_metrics = BTreeSet::new();
+//     collect_leaf_names(&catalog, &mut all_metrics);
+
+//     // Load schemas from OpenAPI spec only (catalog schemas require runtime data)
+//     let openapi_json = load_openapi_json();
+//     let schemas = brk_bindgen::extract_schemas(&openapi_json);
+
+//     // Generate JavaScript client output
+//     let mut js_output = String::new();
+//     writeln!(js_output, "// Auto-generated BRK JavaScript client").unwrap();
+//     writeln!(js_output, "// Do not edit manually\n").unwrap();
+//     brk_bindgen::javascript::types::generate_type_definitions(&mut js_output, &schemas);
+//     brk_bindgen::javascript::client::generate_base_client(&mut js_output);
+//     brk_bindgen::javascript::client::generate_index_accessors(
+//         &mut js_output,
+//         &metadata.index_set_patterns,
+//     );
+//     brk_bindgen::javascript::client::generate_structural_patterns(
+//         &mut js_output,
+//         &metadata.structural_patterns,
+//         &metadata,
+//     );
+//     brk_bindgen::javascript::tree::generate_tree_typedefs(
+//         &mut js_output,
+//         &metadata.catalog,
+//         &metadata,
+//     );
+//     brk_bindgen::javascript::tree::generate_main_client(
+//         &mut js_output,
+//         &metadata.catalog,
+//         &metadata,
+//         &[],
+//     );
+
+//     // Count metrics that appear as direct string literals
+//     let mut direct_metrics = 0;
+//     for metric in &all_metrics {
+//         if js_output.contains(&format!("'{}'", metric))
+//             || js_output.contains(&format!("\"{}\"", metric))
+//         {
+//             direct_metrics += 1;
+//         }
+//     }
+
+//     println!("\nGenerated JavaScript output stats:");
+//     println!("  Total metrics in catalog: {}", all_metrics.len());
+//     println!("  Direct string literals: {}", direct_metrics);
+//     println!(
+//         "  Via pattern factories: {}",
+//         all_metrics.len() - direct_metrics
+//     );
+//     println!("  Output size: {} bytes", js_output.len());
+//     println!("  Output lines: {}", js_output.lines().count());
+
+//     // Write output to test directory (not actual client)
+//     let output_dir = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/output");
+//     std::fs::create_dir_all(output_dir).ok();
+//     let output_path = format!("{}/js_client.js", output_dir);
+//     std::fs::write(&output_path, &js_output).expect("Failed to write JS client output");
+//     println!("  Wrote output to: {}", output_path);
+
+//     // Verify the output contains key components
+//     assert!(js_output.contains("const _m ="), "Should define _m helper");
+//     assert!(js_output.contains("const _p ="), "Should define _p helper");
+//     assert!(
+//         js_output.contains("@typedef {Object} MetricsTree"),
+//         "Should have MetricsTree typedef"
+//     );
+//     assert!(
+//         js_output.contains("class BrkClient"),
+//         "Should have BrkClient class"
+//     );
+
+//     // Verify all pattern factories are generated
+//     for pattern in &metadata.structural_patterns {
+//         assert!(
+//             js_output.contains(&format!("function create{}(", pattern.name)),
+//             "Missing pattern factory: {}",
+//             pattern.name
+//         );
+//     }
+
+//     println!("\nGenerated JavaScript client is complete!");
+// }
+
+// #[test]
+// fn test_generated_python_output() {
+//     let catalog = load_catalog();
+//     let metadata = ClientMetadata::from_catalog(catalog.clone());
+
+//     // Collect all metric names from the catalog
+//     let mut all_metrics = BTreeSet::new();
+//     collect_leaf_names(&catalog, &mut all_metrics);
+
+//     // Load schemas from OpenAPI spec only (catalog schemas require runtime data)
+//     let openapi_json = load_openapi_json();
+//     let schemas = brk_bindgen::extract_schemas(&openapi_json);
+
+//     // Generate Python client output
+//     let mut py_output = String::new();
+//     writeln!(py_output, "# Auto-generated BRK Python client").unwrap();
+//     writeln!(py_output, "# Do not edit manually\n").unwrap();
+//     writeln!(py_output, "from typing import TypeVar, Generic, Any, Optional, List, Literal, TypedDict, Union, Protocol, overload, Iterator, Tuple, TYPE_CHECKING").unwrap();
+//     writeln!(py_output, "\nif TYPE_CHECKING:").unwrap();
+//     writeln!(py_output, "    import pandas as pd  # type: ignore[import-not-found]").unwrap();
+//     writeln!(py_output, "    import polars as pl  # type: ignore[import-not-found]").unwrap();
+//     writeln!(
+//         py_output,
+//         "from http.client import HTTPSConnection, HTTPConnection"
+//     )
+//     .unwrap();
+//     writeln!(py_output, "from urllib.parse import urlparse").unwrap();
+//     writeln!(py_output, "from datetime import date, timedelta").unwrap();
+//     writeln!(py_output, "from dataclasses import dataclass").unwrap();
+//     writeln!(py_output, "import json\n").unwrap();
+//     writeln!(py_output, "T = TypeVar('T')\n").unwrap();
+
+//     brk_bindgen::python::types::generate_type_definitions(&mut py_output, &schemas);
+//     brk_bindgen::python::client::generate_base_client(&mut py_output);
+//     brk_bindgen::python::client::generate_endpoint_class(&mut py_output);
+//     brk_bindgen::python::client::generate_index_accessors(
+//         &mut py_output,
+//         &metadata.index_set_patterns,
+//     );
+//     brk_bindgen::python::client::generate_structural_patterns(
+//         &mut py_output,
+//         &metadata.structural_patterns,
+//         &metadata,
+//     );
+//     brk_bindgen::python::tree::generate_tree_classes(&mut py_output, &metadata.catalog, &metadata);
+//     brk_bindgen::python::api::generate_main_client(&mut py_output, &[]);
+
+//     // Count metrics that appear as direct string literals
+//     let mut direct_metrics = 0;
+//     for metric in &all_metrics {
+//         if py_output.contains(&format!("'{}'", metric))
+//             || py_output.contains(&format!("\"{}\"", metric))
+//         {
+//             direct_metrics += 1;
+//         }
+//     }
+
+//     println!("\nGenerated Python output stats:");
+//     println!("  Total metrics in catalog: {}", all_metrics.len());
+//     println!("  Direct string literals: {}", direct_metrics);
+//     println!(
+//         "  Via pattern factories: {}",
+//         all_metrics.len() - direct_metrics
+//     );
+//     println!("  Output size: {} bytes", py_output.len());
+//     println!("  Output lines: {}", py_output.lines().count());
+
+//     // Write output to test directory (not actual client)
+//     let output_dir = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/output");
+//     std::fs::create_dir_all(output_dir).ok();
+//     let output_path = format!("{}/python_client.py", output_dir);
+//     std::fs::write(&output_path, &py_output).expect("Failed to write Python client output");
+//     println!("  Wrote output to: {}", output_path);
+
+//     // Verify the output contains key components
+//     assert!(py_output.contains("def _m("), "Should define _m helper");
+//     assert!(py_output.contains("def _p("), "Should define _p helper");
+//     assert!(
+//         py_output.contains("class MetricsTree:"),
+//         "Should have MetricsTree class"
+//     );
+//     assert!(
+//         py_output.contains("class BrkClient"),
+//         "Should have BrkClient class"
+//     );
+
+//     // Verify all pattern classes have constructors
+//     for pattern in &metadata.structural_patterns {
+//         assert!(
+//             py_output.contains(&format!("class {}:", pattern.name))
+//                 || py_output.contains(&format!("class {}(", pattern.name)),
+//             "Missing pattern class: {}",
+//             pattern.name
+//         );
+//     }
+
+//     println!("\nGenerated Python client is complete!");
+// }
+
+// #[test]
+// fn test_cost_basis_relatives() {
+//     let catalog = load_catalog();
+
+//     // Find cost_basis branches that have 3 direct children (max, min, percentiles)
+//     fn find_cost_basis_with_percentiles(
+//         node: &TreeNode,
+//         path: &str,
+//     ) -> Vec<(String, Vec<(String, String)>)> {
+//         let mut results = Vec::new();
+//         if let TreeNode::Branch(children) = node {
+//             for (name, child) in children {
+//                 let child_path = if path.is_empty() {
+//                     name.clone()
+//                 } else {
+//                     format!("{}.{}", path, name)
+//                 };
+
+//                 if name == "cost_basis"
+//                     && let TreeNode::Branch(cb_children) = child
+//                     && cb_children.contains_key("percentiles")
+//                 {
+//                     // Found a cost_basis with percentiles
+//                     let mut metrics = Vec::new();
+//                     for (field_name, field_node) in cb_children {
+//                         match field_node {
+//                             TreeNode::Leaf(leaf) => {
+//                                 metrics.push((field_name.clone(), leaf.name().to_string()));
+//                             }
+//                             TreeNode::Branch(pct_children) => {
+//                                 // Get first percentile as example
+//                                 if let Some((_, TreeNode::Leaf(first))) = pct_children.iter().next()
+//                                 {
+//                                     metrics.push((
+//                                         format!("{}.first", field_name),
+//                                         first.name().to_string(),
+//                                     ));
+//                                 }
+//                             }
+//                         }
+//                     }
+//                     results.push((child_path.clone(), metrics));
+//                 }
+//                 results.extend(find_cost_basis_with_percentiles(child, &child_path));
+//             }
+//         }
+//         results
+//     }
+
+//     let instances = find_cost_basis_with_percentiles(&catalog, "");
+
+//     println!("\nCostBasisPattern2 instances (with percentiles):");
+//     for (path, metrics) in instances.iter().take(10) {
+//         println!("  {}:", path);
+//         for (field, metric) in metrics {
+//             println!("    {} -> {}", field, metric);
+//         }
+//     }
+
+//     // Now compute what relatives the pattern detection would see
+//     // The key is: percentiles returns its BASE (common prefix of pct05, pct10, etc.)
+//     // not the individual percentile metrics
+//     use brk_bindgen::find_common_prefix;
+
+//     println!("\nComputing relatives (simulating branch base returns):");
+//     for (path, metrics) in instances.iter().take(5) {
+//         println!("  Instance: {}", path);
+
+//         // For leaves (max, min), the base is the metric name
+//         // For branches (percentiles), the base is the common prefix of its children
+//         let mut child_bases: std::collections::BTreeMap<String, String> =
+//             std::collections::BTreeMap::new();
+//         for (field, metric) in metrics {
+//             if field.starts_with("percentiles.") {
+//                 // This is a percentile metric - compute what the percentiles branch would return
+//                 // The base is the metric name with the pct suffix stripped
+//                 let base = metric
+//                     .strip_suffix("_pct05")
+//                     .or_else(|| metric.strip_suffix("_pct10"))
+//                     .unwrap_or(metric)
+//                     .to_string();
+//                 child_bases.insert("percentiles".to_string(), base);
+//             } else {
+//                 child_bases.insert(field.clone(), metric.clone());
+//             }
+//         }
+
+//         let bases: Vec<&str> = child_bases.values().map(|s| s.as_str()).collect();
+//         println!("    Child bases:");
+//         for (field, base) in &child_bases {
+//             println!("      {} -> {}", field, base);
+//         }
+
+//         if let Some(prefix) = find_common_prefix(&bases) {
+//             println!("    Common prefix: '{}'", prefix);
+//             for (field, base) in &child_bases {
+//                 let relative = base.strip_prefix(&prefix).unwrap_or(base);
+//                 println!("      {} -> relative '{}'", field, relative);
+//             }
+//         } else {
+//             println!("    No common prefix found!");
+//         }
+//     }
+// }
+
+// #[test]
+// fn test_debug_cost_basis_pattern2_mode() {
+//     // Debug why CostBasisPattern2 has mode=None
+//     let catalog = load_catalog();
+//     let metadata = brk_bindgen::ClientMetadata::from_catalog(catalog.clone());
+//     let pattern_lookup = metadata.pattern_lookup();
+
+//     let pattern = metadata
+//         .find_pattern("CostBasisPattern2")
+//         .expect("CostBasisPattern2 should exist");
+
+//     println!("\nCostBasisPattern2 fields:");
+//     for field in &pattern.fields {
+//         println!("  {} (type: {})", field.name, field.rust_type);
+//     }
+//     println!("Mode: {:?}", pattern.mode);
+
+//     // Now debug the instance collection
+//     #[derive(Debug, Clone)]
+//     struct DebugInstanceAnalysis {
+//         base: String,
+//         field_parts: std::collections::BTreeMap<String, String>,
+//         is_suffix_mode: bool,
+//     }
+
+//     fn collect_debug(
+//         node: &TreeNode,
+//         pattern_lookup: &std::collections::BTreeMap<Vec<brk_bindgen::PatternField>, String>,
+//         all_analyses: &mut std::collections::BTreeMap<String, Vec<DebugInstanceAnalysis>>,
+//     ) -> Option<String> {
+//         match node {
+//             TreeNode::Leaf(leaf) => Some(leaf.name().to_string()),
+//             TreeNode::Branch(children) => {
+//                 let mut child_bases: std::collections::BTreeMap<String, String> =
+//                     std::collections::BTreeMap::new();
+//                 for (field_name, child_node) in children {
+//                     if let Some(base) = collect_debug(child_node, pattern_lookup, all_analyses) {
+//                         child_bases.insert(field_name.clone(), base);
+//                     }
+//                 }
+
+//                 if child_bases.is_empty() {
+//                     return None;
+//                 }
+
+//                 // Analyze this instance
+//                 let bases: Vec<&str> = child_bases.values().map(|s| s.as_str()).collect();
+//                 let (base, field_parts, is_suffix_mode) =
+//                     if let Some(common_prefix) = brk_bindgen::find_common_prefix(&bases) {
+//                         let base = common_prefix.trim_end_matches('_').to_string();
+//                         let mut parts = std::collections::BTreeMap::new();
+//                         for (field_name, child_base) in &child_bases {
+//                             let relative = if *child_base == base {
+//                                 String::new()
+//                             } else {
+//                                 child_base
+//                                     .strip_prefix(&common_prefix)
+//                                     .unwrap_or(child_base)
+//                                     .to_string()
+//                             };
+//                             parts.insert(field_name.clone(), relative);
+//                         }
+//                         (base, parts, true)
+//                     } else {
+//                         let base = child_bases.values().next().cloned().unwrap_or_default();
+//                         let parts = child_bases
+//                             .iter()
+//                             .map(|(k, v)| (k.clone(), v.clone()))
+//                             .collect();
+//                         (base, parts, true)
+//                     };
+
+//                 let analysis = DebugInstanceAnalysis {
+//                     base: base.clone(),
+//                     field_parts,
+//                     is_suffix_mode,
+//                 };
+
+//                 // Get the pattern name for this node
+//                 let fields = brk_bindgen::get_node_fields(children, pattern_lookup);
+//                 if let Some(pattern_name) = pattern_lookup.get(&fields) {
+//                     all_analyses
+//                         .entry(pattern_name.clone())
+//                         .or_default()
+//                         .push(analysis);
+//                 }
+
+//                 Some(base)
+//             }
+//         }
+//     }
+
+//     let mut all_analyses: BTreeMap<String, Vec<DebugInstanceAnalysis>> = BTreeMap::new();
+//     collect_debug(&catalog, &pattern_lookup, &mut all_analyses);
+
+//     if let Some(analyses) = all_analyses.get("CostBasisPattern2") {
+//         println!(
+//             "\nCollected {} instances of CostBasisPattern2:",
+//             analyses.len()
+//         );
+//         for (i, a) in analyses.iter().enumerate() {
+//             println!("  Instance {}:", i);
+//             println!("    base: {}", a.base);
+//             println!("    is_suffix: {}", a.is_suffix_mode);
+//             println!("    field_parts:");
+//             for (f, p) in &a.field_parts {
+//                 println!("      {} -> '{}'", f, p);
+//             }
+//         }
+
+//         // Check consistency
+//         if analyses.len() >= 2 {
+//             let first = &analyses[0];
+//             for (i, a) in analyses.iter().enumerate().skip(1) {
+//                 if a.is_suffix_mode != first.is_suffix_mode {
+//                     println!("  INCONSISTENT: Instance {} has different mode", i);
+//                 }
+//                 for (field, part) in &a.field_parts {
+//                     if first.field_parts.get(field) != Some(part) {
+//                         println!(
+//                             "  INCONSISTENT: Instance {} field '{}' has part '{}' vs '{}'",
+//                             i,
+//                             field,
+//                             part,
+//                             first
+//                                 .field_parts
+//                                 .get(field)
+//                                 .unwrap_or(&"<missing>".to_string())
+//                         );
+//                     }
+//                 }
+//             }
+//         }
+//     } else {
+//         println!("\nNo instances collected for CostBasisPattern2!");
+//     }
+// }
+
+// #[test]
+// fn test_root_cost_basis_prefix() {
+//     use brk_bindgen::find_common_prefix;
+
+//     // Root-level cost_basis has:
+//     // max -> "max_cost_basis"
+//     // min -> "min_cost_basis"
+//     // percentiles -> "cost_basis" (base of pct05, pct10, etc.)
+
+//     let bases = vec!["max_cost_basis", "min_cost_basis", "cost_basis"];
+//     let prefix = find_common_prefix(&bases);
+//     println!("Root cost_basis prefix: {:?}", prefix);
+
+//     // Compare with nested cost_basis
+//     let nested_bases = vec![
+//         "utxos_at_least_15y_old_max_cost_basis",
+//         "utxos_at_least_15y_old_min_cost_basis",
+//         "utxos_at_least_15y_old_cost_basis",
+//     ];
+//     let nested_prefix = find_common_prefix(&nested_bases);
+//     println!("Nested cost_basis prefix: {:?}", nested_prefix);
+// }
+
+// #[test]
+// fn test_utxo_cohorts_all_activity_base() {
+//     // Test that distribution.utxo_cohorts.all.activity uses empty base
+//     // because its children (coinblocks_destroyed, coindays_destroyed, etc.)
+//     // have no common prefix or suffix.
+//     let catalog = load_catalog();
+//     let metadata = ClientMetadata::from_catalog(catalog.clone());
+
+//     // Generate JavaScript output
+//     let mut js_output = String::new();
+//     writeln!(js_output, "// Test output").unwrap();
+//     brk_bindgen::javascript::client::generate_base_client(&mut js_output);
+//     brk_bindgen::javascript::client::generate_index_accessors(
+//         &mut js_output,
+//         &metadata.index_set_patterns,
+//     );
+//     brk_bindgen::javascript::client::generate_structural_patterns(
+//         &mut js_output,
+//         &metadata.structural_patterns,
+//         &metadata,
+//     );
+//     brk_bindgen::javascript::tree::generate_tree_typedefs(
+//         &mut js_output,
+//         &metadata.catalog,
+//         &metadata,
+//     );
+//     brk_bindgen::javascript::tree::generate_main_client(
+//         &mut js_output,
+//         &metadata.catalog,
+//         &metadata,
+//         &[],
+//     );
+
+//     // The all.activity should use empty base, so metrics don't get duplicated
+//     // Look for: activity: createActivityPattern2(this, '')
+//     // NOT: activity: createActivityPattern2(this, 'coinblocks_destroyed')
+//     assert!(
+//         !js_output.contains("createActivityPattern2(this, 'coinblocks_destroyed')"),
+//         "all.activity should NOT use 'coinblocks_destroyed' as base (causes duplication)"
+//     );
+
+//     // Check that it uses empty string as base
+//     assert!(
+//         js_output.contains("activity: createActivityPattern2(this, '')"),
+//         "all.activity should use empty base"
+//     );
+
+//     println!("utxo_cohorts.all.activity base test passed!");
+// }
@@ -1,18 +0,0 @@
-[package]
-name = "brk_bundler"
-description = "A thin wrapper around rolldown"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-homepage.workspace = true
-repository.workspace = true
-rust-version.workspace = true
-build = "build.rs"
-
-[dependencies]
-log = { workspace = true }
-notify = "8.2.0"
-brk_rolldown = "0.2.3"
-# brk_rolldown = { path = "../../../rolldown/crates/rolldown"}
-sugar_path = "1.2.0"
-tokio = { workspace = true }
@@ -1,278 +0,0 @@
-# brk_bundler
-
-Asset bundling and development server for BRK web interfaces with hot reloading and file watching.
-
-[![Crates.io](https://img.shields.io/crates/v/brk_bundler.svg)](https://crates.io/crates/brk_bundler)
-[![Documentation](https://docs.rs/brk_bundler/badge.svg)](https://docs.rs/brk_bundler)
-
-## Overview
-
-This crate provides a thin wrapper around the Rolldown JavaScript bundler specifically designed for BRK web interface development. It handles asset bundling, file copying, template processing, and development-mode file watching with automatic rebuilds and hot reloading for efficient web development workflows.
-
-**Key Features:**
-
- JavaScript bundling with Rolldown (Rust-based bundler)
- Automatic file watching and hot reloading in development mode
- Template processing with version injection and asset hash replacement
- Service worker generation with version management
- Source map generation for debugging
- Minification for production builds
- Async/await support with Tokio integration
-
-**Target Use Cases:**
-
- BRK blockchain explorer web interfaces
- Development of Bitcoin analytics dashboards
- Building responsive web applications for blockchain data visualization
- Hot reloading development environment for rapid iteration
-
-## Installation
-
-```bash
-cargo add brk_bundler
-```
-
-## Quick Start
-
-```rust
-use brk_bundler::bundle;
-use std::path::Path;
-
-#[tokio::main]
-async fn main() -> std::io::Result<()> {
-    let websites_path = Path::new("./web");
-    let source_folder = "src";
-    let watch = true; // Enable hot reloading
-
-    // Bundle assets and start development server
-    let dist_path = bundle(websites_path, source_folder, watch).await?;
-
-    println!("Assets bundled to: {}", dist_path.display());
-
-    // Keep running for file watching (in watch mode)
-    if watch {
-        tokio::signal::ctrl_c().await?;
-    }
-
-    Ok(())
-}
-```
-
-## API Overview
-
-### Core Functions
-
-**`bundle(websites_path: &Path, source_folder: &str, watch: bool) -> io::Result<PathBuf>`**
-Main bundling function that processes web assets and optionally starts file watching.
-
-### Bundling Process
-
-1. **Directory Setup**: Creates `dist/` directory and copies source files
-2. **JavaScript Bundling**: Processes `scripts/entry.js` with Rolldown bundler
-3. **Template Processing**: Updates `index.html` with hashed asset references
-4. **Service Worker**: Generates service worker with version injection
-5. **File Watching**: Optionally monitors source files for changes
-
-### Configuration
-
-**Rolldown Bundler Options:**
-
- **Input**: `./src/scripts/entry.js` (main JavaScript entry point)
- **Output**: `./dist/scripts/` directory
- **Minification**: Enabled for production builds
- **Source Maps**: File-based source maps for debugging
- **Asset Hashing**: Automatic hash generation for cache busting
-
-## Examples
-
-### Development Mode with Hot Reloading
-
-```rust
-use brk_bundler::bundle;
-use std::path::Path;
-
-#[tokio::main]
-async fn main() -> std::io::Result<()> {
-    let web_root = Path::new("./websites");
-
-    // Start development server with file watching
-    let _dist_path = bundle(web_root, "explorer", true).await?;
-
-    println!("Development server started!");
-    println!("Hot reloading enabled - edit files to see changes");
-
-    // Keep server running
-    loop {
-        tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;
-    }
-}
-```
-
-### Production Build
-
-```rust
-use brk_bundler::bundle;
-use std::path::Path;
-
-#[tokio::main]
-async fn main() -> std::io::Result<()> {
-    let web_root = Path::new("./websites");
-
-    // Build for production (no watching)
-    let dist_path = bundle(web_root, "dashboard", false).await?;
-
-    println!("Production build completed: {}", dist_path.display());
-
-    // Assets are minified and ready for deployment
-    Ok(())
-}
-```
-
-### Custom Web Application Structure
-
-```rust
-use brk_bundler::bundle;
-use std::path::Path;
-
-// Expected directory structure:
-// websites/
-// ├── my_app/
-// │   ├── index.html          // Main HTML template
-// │   ├── service-worker.js   // Service worker template
-// │   ├── scripts/
-// │   │   └── entry.js        // JavaScript entry point
-// │   ├── styles/
-// │   │   └── main.css        // CSS files
-// │   └── assets/
-// │       └── images/         // Static assets
-// └── dist/                   // Generated output
-
-#[tokio::main]
-async fn main() -> std::io::Result<()> {
-    let websites_path = Path::new("./websites");
-    let source_folder = "my_app";
-
-    let dist_path = bundle(websites_path, source_folder, false).await?;
-
-    // Result: dist/ contains bundled and processed files
-    // - dist/index.html (with updated script references)
-    // - dist/service-worker.js (with version injection)
-    // - dist/scripts/main.[hash].js (minified and hashed)
-    // - dist/styles/ (copied CSS files)
-    // - dist/assets/ (copied static assets)
-
-    Ok(())
-}
-```
-
-## Architecture
-
-### File Processing Pipeline
-
-1. **Source Copying**: Recursively copies all source files to dist directory
-2. **JavaScript Bundling**: Rolldown processes entry.js with dependencies
-3. **Asset Hashing**: Generates content-based hashes for cache busting
-4. **Template Updates**: Replaces placeholders in HTML templates
-5. **Version Injection**: Updates service worker with current package version
-
-### File Watching System
-
-**Development Mode Watchers:**
-
- **Source File Watcher**: Monitors non-script files for changes
- **Bundle Watcher**: Watches JavaScript files and triggers rebuilds
- **Template Watcher**: Updates HTML when bundled assets change
-
-**Event Handling:**
-
- **File Creation/Modification**: Automatic copying to dist directory
- **Script Changes**: Triggers Rolldown rebuild and template update
- **Template Changes**: Processes HTML and updates asset references
-
-### Template Processing
-
-**index.html Processing:**
-
- Scans bundled JavaScript for asset hash
- Replaces `/scripts/main.js` with `/scripts/main.[hash].js`
- Maintains cache busting while preserving template structure
-
-**service-worker.js Processing:**
-
- Replaces `__VERSION__` placeholder with current crate version
- Enables version-based cache invalidation
- Maintains service worker functionality
-
-### Async Architecture
-
-Built on Tokio async runtime:
-
- **Non-blocking I/O**: Efficient file operations and watching
- **Concurrent Tasks**: Parallel file watching and bundle processing
- **Background Processing**: Development server runs in background task
-
-## Configuration Options
-
-### Rolldown Configuration
-
-The bundler uses optimized Rolldown settings:
-
-```rust
-BundlerOptions {
-    input: Some(vec!["./src/scripts/entry.js".into()]),
-    dir: Some("./dist/scripts".to_string()),
-    minify: Some(RawMinifyOptions::Bool(true)),
-    sourcemap: Some(SourceMapType::File),
-    // ... other default options
-}
-```
-
-### File Structure Requirements
-
-**Required Files:**
-
- `src/scripts/entry.js` - JavaScript entry point
- `src/index.html` - HTML template
- `src/service-worker.js` - Service worker template
-
-**Optional Directories:**
-
- `src/styles/` - CSS stylesheets
- `src/assets/` - Static assets (images, fonts, etc.)
- `src/components/` - Additional JavaScript modules
-
-## Development Workflow
-
-### Setup
-
-1. Create web application in `websites/app_name/`
-2. Add required files (index.html, entry.js, service-worker.js)
-3. Run bundler in watch mode for development
-
-### Hot Reloading
-
- **Script Changes**: Automatic bundle rebuild and browser refresh
- **Template Changes**: Immediate HTML update with asset hash replacement
- **Asset Changes**: Instant copy to dist directory
- **Style Changes**: Direct copy without bundling
-
-### Production Deployment
-
-1. Run bundler without watch mode
-2. Deploy `dist/` directory contents
-3. Assets include content hashes for cache busting
-4. Service worker includes version for cache management
-
-## Code Analysis Summary
-
-**Main Function**: `bundle()` async function coordinating Rolldown bundler with file processing and watching \
-**File Operations**: Recursive directory copying with `copy_dir_all()` and selective file processing \
-**Templating**: String replacement for asset hash injection and version management \
-**File Watching**: Multi-watcher system using `notify` crate for real-time development feedback \
-**Async Integration**: Tokio-based async architecture with background task spawning \
-**Bundler Integration**: Rolldown wrapper with optimized configuration for web development \
-**Architecture**: Development-focused asset pipeline with hot reloading and production optimization
-
---
-
-_This README was generated by Claude Code_
@@ -1,8 +0,0 @@
-fn main() {
-    let profile = std::env::var("PROFILE").unwrap_or_default();
-
-    if profile == "release" {
-        println!("cargo:rustc-flag=-C");
-        println!("cargo:rustc-flag=target-cpu=native");
-    }
-}
@@ -1,194 +0,0 @@
-#![doc = include_str!("../README.md")]
-
-use std::{
-    fs, io,
-    path::{Path, PathBuf},
-    sync::Arc,
-};
-
-use brk_rolldown::{
-    Bundler, BundlerOptions, InlineConstConfig, InlineConstMode, InlineConstOption,
-    OptimizationOption, RawMinifyOptions, SourceMapType,
-};
-use log::error;
-use notify::{EventKind, RecursiveMode, Watcher};
-use sugar_path::SugarPath;
-use tokio::sync::Mutex;
-
-const VERSION: &str = env!("CARGO_PKG_VERSION");
-
-pub async fn bundle(
-    modules_path: &Path,
-    websites_path: &Path,
-    source_folder: &str,
-    watch: bool,
-) -> io::Result<PathBuf> {
-    let relative_modules_path = modules_path;
-    let relative_source_path = websites_path.join(source_folder);
-    let relative_dist_path = websites_path.join("dist");
-
-    let absolute_modules_path = relative_modules_path.absolutize();
-    let absolute_modules_path_clone = absolute_modules_path.clone();
-    let absolute_websites_path = websites_path.absolutize();
-    let absolute_websites_path_clone = absolute_websites_path.clone();
-
-    let absolute_source_path = relative_source_path.absolutize();
-    let absolute_source_index_path = absolute_source_path.join("index.html");
-    let absolute_source_index_path_clone = absolute_source_index_path.clone();
-    let absolute_source_scripts_path = absolute_source_path.join("scripts");
-    let absolute_source_scripts_modules_path = absolute_source_scripts_path.join("modules");
-    let absolute_source_sw_path = absolute_source_path.join("service-worker.js");
-    let absolute_source_sw_path_clone = absolute_source_sw_path.clone();
-
-    let absolute_dist_path = relative_dist_path.absolutize();
-    let absolute_dist_scripts_path = absolute_dist_path.join("scripts");
-    let absolute_dist_scripts_entry_path = absolute_dist_scripts_path.join("entry.js");
-    let absolute_dist_scripts_entry_path_clone = absolute_dist_scripts_entry_path.clone();
-    let absolute_dist_index_path = absolute_dist_path.join("index.html");
-    let absolute_dist_sw_path = absolute_dist_path.join("service-worker.js");
-
-    let _ = fs::remove_dir_all(&absolute_dist_path);
-    let _ = fs::remove_dir_all(&absolute_source_scripts_modules_path);
-    copy_dir_all(
-        &absolute_modules_path,
-        &absolute_source_scripts_modules_path,
-    )?;
-    copy_dir_all(&absolute_source_path, &absolute_dist_path)?;
-    fs::remove_dir_all(&absolute_dist_scripts_path)?;
-    fs::create_dir(&absolute_dist_scripts_path)?;
-
-    // dbg!(BundlerOptions::default());
-
-    let mut bundler = Bundler::new(BundlerOptions {
-        input: Some(vec![format!("./{source_folder}/scripts/entry.js").into()]),
-        dir: Some("./dist/scripts".to_string()),
-        cwd: Some(absolute_websites_path),
-        minify: Some(RawMinifyOptions::Bool(true)),
-        sourcemap: Some(SourceMapType::File),
-        // advanced_chunks: Some(AdvancedChunksOptions {
-        //     // min_size: Some(1000.0),
-        //     min_share_count: Some(20),
-        //     // min_module_size: S
-        //     // include_dependencies_recursively: Some(true),
-        //     ..Default::default()
-        // }),
-        //
-        // inline_dynamic_imports
-        // experimental: Some(ExperimentalOptions {
-        //     strict_execution_order: Some(true),
-        //     ..Default::default()
-        // }),
-        optimization: Some(OptimizationOption {
-            inline_const: Some(InlineConstOption::Config(InlineConstConfig {
-                mode: Some(InlineConstMode::All),
-                ..Default::default()
-            })),
-            // Needs benchmarks
-            // pife_for_module_wrappers: Some(true),
-            ..Default::default()
-        }),
-        ..Default::default()
-    })
-    .unwrap();
-
-    if let Err(error) = bundler.write().await {
-        error!("{error:?}");
-    }
-
-    let update_dist_index = move || {
-        let mut contents = fs::read_to_string(&absolute_source_index_path).unwrap();
-
-        if let Ok(entry) = fs::read_to_string(&absolute_dist_scripts_entry_path_clone)
-            && let Some(start) = entry.find("main")
-            && let Some(end) = entry.find(".js")
-        {
-            let main_hashed = &entry[start..end];
-            contents = contents.replace("/scripts/main.js", &format!("/scripts/{main_hashed}.js"));
-        }
-
-        let _ = fs::write(&absolute_dist_index_path, contents);
-    };
-
-    let update_source_sw = move || {
-        let contents = fs::read_to_string(&absolute_source_sw_path)
-            .unwrap()
-            .replace("__VERSION__", &format!("v{VERSION}"));
-        let _ = fs::write(&absolute_dist_sw_path, contents);
-    };
-
-    update_dist_index();
-    update_source_sw();
-
-    if !watch {
-        return Ok(relative_dist_path);
-    }
-
-    tokio::spawn(async move {
-        let mut event_watcher = notify::recommended_watcher(
-            move |res: Result<notify::Event, notify::Error>| match res {
-                Ok(event) => match event.kind {
-                    EventKind::Create(_) => event.paths,
-                    EventKind::Modify(_) => event.paths,
-                    _ => vec![],
-                }
-                .into_iter()
-                .for_each(|path| {
-                    let path = path.absolutize();
-
-                    if path == absolute_dist_scripts_entry_path
-                        || path == absolute_source_index_path_clone
-                    {
-                        update_dist_index();
-                    } else if path == absolute_source_sw_path_clone {
-                        update_source_sw();
-                    } else if let Ok(suffix) = path.strip_prefix(&absolute_modules_path) {
-                        let source_modules_path = absolute_source_scripts_modules_path.join(suffix);
-                        if path.is_file() {
-                            let _ = fs::create_dir_all(path.parent().unwrap());
-                            let _ = fs::copy(&path, &source_modules_path);
-                        }
-                    } else if let Ok(suffix) = path.strip_prefix(&absolute_source_path)
-                        // scripts are handled by rolldown
-                        && !path.starts_with(&absolute_source_scripts_path)
-                    {
-                        let dist_path = absolute_dist_path.join(suffix);
-                        if path.is_file() {
-                            let _ = fs::create_dir_all(path.parent().unwrap());
-                            let _ = fs::copy(&path, &dist_path);
-                        }
-                    }
-                }),
-                Err(e) => error!("watch error: {e:?}"),
-            },
-        )
-        .unwrap();
-
-        event_watcher
-            .watch(&absolute_websites_path_clone, RecursiveMode::Recursive)
-            .unwrap();
-        event_watcher
-            .watch(&absolute_modules_path_clone, RecursiveMode::Recursive)
-            .unwrap();
-
-        let watcher =
-            brk_rolldown::Watcher::new(vec![Arc::new(Mutex::new(bundler))], None).unwrap();
-
-        watcher.start().await;
-    });
-
-    Ok(relative_dist_path)
-}
-
-fn copy_dir_all(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
-    fs::create_dir_all(&dst)?;
-    for entry in fs::read_dir(src)? {
-        let entry = entry?;
-        let ty = entry.file_type()?;
-        if ty.is_dir() {
-            copy_dir_all(entry.path(), dst.as_ref().join(entry.file_name()))?;
-        } else {
-            fs::copy(entry.path(), dst.as_ref().join(entry.file_name()))?;
-        }
-    }
-    Ok(())
-}
@@ -6,34 +6,31 @@ edition.workspace = true
 license.workspace = true
 homepage.workspace = true
 repository.workspace = true
-rust-version.workspace = true
-build = "build.rs"

 [dependencies]
-bitcoincore-rpc = { workspace = true }
-brk_binder = { workspace = true }
-brk_bundler = { workspace = true }
+anyhow = "1.0"
+brk_alloc = { workspace = true }
 brk_computer = { workspace = true }
-brk_error = { workspace = true }
-brk_fetcher = { workspace = true }
+brk_error = { workspace = true, features = ["tokio", "vecdb"] }
 brk_indexer = { workspace = true }
-brk_interface = { workspace = true }
 brk_logger = { workspace = true }
-brk_parser = { workspace = true }
+brk_mempool = { workspace = true }
+brk_query = { workspace = true }
+brk_reader = { workspace = true }
+brk_rpc = { workspace = true, features = ["corepc"] }
 brk_server = { workspace = true }
-vecdb = { workspace = true }
-clap = { version = "4.5.48", features = ["derive", "string"] }
-color-eyre = "0.6.5"
-log = { workspace = true }
-minreq = { workspace = true }
+brk_types = { workspace = true }
+lexopt = "0.3"
+owo-colors = { workspace = true }
+tracing = { workspace = true }
 serde = { workspace = true }
 tokio = { workspace = true }
-toml = "0.9.7"
-zip = { version = "5.1.1", default-features = false, features = ["deflate"] }
+toml = "1.1.2"
+vecdb = { workspace = true }

 [[bin]]
 name = "brk"
 path = "src/main.rs"

 [package.metadata.dist]
-dist = false
+dist = true
@@ -1,232 +1,75 @@
-# brk_cli
+# BRK CLI

-Command-line interface orchestrating complete Bitcoin Research Kit instances with automatic configuration and continuous blockchain processing.
+Run your own Bitcoin Research Kit instance. One binary, one command. Full sync in ~4-7h depending on hardware. ~44% disk overhead vs 250% for mempool/electrs.

-[![Crates.io](https://img.shields.io/crates/v/brk_cli.svg)](https://crates.io/crates/brk_cli)
-[![Documentation](https://docs.rs/brk_cli/badge.svg)](https://docs.rs/brk_cli)
+[bitview.space](https://bitview.space) is the official free hosted instance.

-## Overview
+## Requirements

-This crate provides the primary command-line interface for running Bitcoin Research Kit instances. It orchestrates the entire data processing pipeline from Bitcoin Core block parsing through analytics computation to HTTP API serving, with persistent configuration management, automatic error recovery, and continuous blockchain synchronization.
+- Linux or macOS
+- Bitcoin Core with `server=1` in `bitcoin.conf`
+- Access to `blk*.dat` files
+- [~400 GB disk space](https://bitview.space/api/server/disk) (see [Disk usage](#disk-usage))
+- [12+ GB RAM](https://github.com/bitcoinresearchkit/benches#benchmarks)

-**Key Features:**
+## Disk usage

- Complete BRK pipeline orchestration with parser, indexer, computer, and server coordination
- Persistent configuration system with TOML-based auto-save functionality
- Continuous blockchain processing with new block detection and incremental updates
- Flexible Bitcoin Core RPC authentication with cookie file and user/password support
- Configurable web interface options including auto-downloading from GitHub releases
- Large stack allocation (512MB) for handling complex blockchain processing workloads
- Graceful shutdown handling with proper cleanup and state preservation
+BRK uses [sparse files](https://en.wikipedia.org/wiki/Sparse_file). Tools like `ls -l` or Finder report the logical file size (>1 TB), not actual disk usage (~350 GB). Use `du -sh` to see real usage.

-**Target Use Cases:**
-
- Production Bitcoin analytics deployments requiring full pipeline operation
- Development environments for Bitcoin research and analysis
- Continuous blockchain monitoring with real-time data updates
- Academic research requiring comprehensive historical blockchain datasets
-
-## Installation
+## Install

 ```bash
-cargo install brk # or cargo install brk_cli
+rustup update
+RUSTFLAGS="-C target-cpu=native" cargo install --locked brk_cli
 ```

-## Quick Start
+Portable build (without native CPU optimizations):

 ```bash
-# First run - configure and start processing
-brk --brkdir ./data --bitcoindir ~/.bitcoin --fetch true
+cargo install --locked brk_cli
+```

-# Subsequent runs use saved configuration
+## Run
+
+```bash
 brk
-
-# Override specific options
-brk --website none --fetch false
 ```

-## API Overview
+Indexes the blockchain, computes datasets, starts the server on `localhost:3110`, and waits for new blocks.

-### Core Structure
+## First sync

- **`Config`**: Persistent configuration with clap-based CLI parsing and TOML serialization
- **`Bridge`**: Interface trait for generating JavaScript bridge files for web interfaces
- **`Website`**: Enum for web interface options (None, Bitview, Custom)
- **Path Functions**: Cross-platform default path resolution for Bitcoin and BRK directories
+The initial sync processes the entire blockchain and can take several hours. During this time (more than 10,000 blocks behind), indexing completes before the server starts to free up memory. The web interface at `localhost:3110` won't be available until sync finishes.

-### Main Operations
-
-**`main() -> color_eyre::Result<()>`**
-Entry point with error handling setup, directory creation, logging initialization, and high-stack thread spawning.
-
-**`run() -> color_eyre::Result<()>`**
-Core processing loop handling configuration, RPC connection, component initialization, and continuous blockchain monitoring.
-
-### Configuration Management
-
-**Persistent Settings:**
-
- All CLI arguments automatically saved to `~/.brk/config.toml`
- Argument overrides update saved configuration on each run
- Cross-platform path resolution with tilde and $HOME expansion
- Validation of Bitcoin directory, blocks directory, and RPC authentication
-
-**CLI Parameters:**
-
- `--bitcoindir`, `--blocksdir`, `--brkdir`: Directory configuration
- `--fetch`, `--exchanges`: Data source configuration
- `--website`: Web interface selection
- `--rpcconnect`, `--rpcport`, `--rpccookiefile`, `--rpcuser`, `--rpcpassword`: RPC settings
-
-## Examples
-
-### Basic Usage
+## Options

 ```bash
-# Initialize with custom directories
-brk --bitcoindir /data/bitcoin --brkdir /data/brk
-
-# Enable all features with custom RPC
-brk --fetch true --exchanges true --website bitview \
-    --rpcuser myuser --rpcpassword mypass
-
-# Minimal setup with API only
-brk --website none --fetch false
+brk -h       # Show all options
+brk -V       # Show version
 ```

-### Configuration File Example
-
-After first run, settings are saved to `~/.brk/config.toml`:
+Command-line options override `~/.brk/config.toml` for that run only. Edit the file directly to persist settings:

 ```toml
-bitcoindir = "/home/user/.bitcoin"
-blocksdir = "/home/user/.bitcoin/blocks"
-brkdir = "/home/user/brk_data"
-fetch = true
-exchanges = true
-website = "bitview"
-rpcconnect = "localhost"
-rpcport = 8332
-rpccookiefile = "/home/user/.bitcoin/.cookie"
+brkdir = "/path/to/data"
+bitcoindir = "/path/to/.bitcoin"
 ```

-### Web Interface Configuration
+All fields are optional. See `brk -h` for the full list.
+
+## Environment Variables

 ```bash
-# Use built-in Bitview interface
-brk --website bitview
-
-# Use custom web interface
-brk --website custom
-
-# API only, no web interface
-brk --website none
+LOG=debug brk    # Enable debug logging (keeps noise filters)
+RUST_LOG=... brk # Full control over log filtering (overrides all defaults)
 ```

-### Development Mode
+## Files

-```bash
-# Development with local website directory
-# Looks for ../../websites directory first
-brk --website bitview
-
-# Production with auto-download from GitHub
-# Downloads websites from release artifacts
-brk --website bitview
 ```
+~/.brk/
+├── config.toml   Configuration
+└── log           Logs

-## Architecture
-
-### Startup Sequence
-
-1. **Environment Setup**: Color eyre error handling, directory creation, logging initialization
-2. **High-Stack Thread**: 512MB stack for complex blockchain processing operations
-3. **Configuration Loading**: CLI parsing, TOML reading, argument merging, validation
-4. **Component Initialization**: Parser, indexer, computer, interface creation with proper dependencies
-
-### Processing Pipeline
-
-**Continuous Operation Loop:**
-
-1. **Bitcoin Core Sync Wait**: Monitors `headers == blocks` for full node synchronization
-2. **Block Count Detection**: Compares current and previous block counts for new block detection
-3. **Indexing Phase**: Processes new blocks through parser with collision detection option
-4. **Computing Phase**: Runs analytics computations on newly indexed data
-5. **Server Operation**: Serves HTTP API with optional web interface throughout processing
-
-### Web Interface Integration
-
-**Website Handling:**
-
- **Development Mode**: Uses local `../../websites` directory if available
- **Production Mode**: Downloads release artifacts from GitHub using semantic versioning
- **Bundle Generation**: Creates optimized JavaScript bundles using `brk_bundler`
- **Bridge Files**: Generates JavaScript bridge files for vector IDs and pool data
-
-**Download and Bundle Process:**
-
-```rust
-// Automatic website download and bundling
-let url = format!("https://github.com/bitcoinresearchkit/brk/archive/refs/tags/v{VERSION}.zip");
-let response = minreq::get(url).send()?;
-zip::ZipArchive::new(cursor).extract(downloads_path)?;
-bundle(&websites_path, website.to_folder_name(), true).await?
+<brkdir>/         Indexed data (default: ~/.brk)
 ```
-
-### RPC Authentication
-
-**Flexible Authentication Methods:**
-
- **Cookie File**: Automatic detection at `--bitcoindir/.cookie`
- **User/Password**: Manual configuration with `--rpcuser` and `--rpcpassword`
- **Connection Validation**: Startup checks ensure proper Bitcoin Core connectivity
-
-### Configuration System
-
-**TOML Persistence:**
-
- Automatic serialization/deserialization with `serde` and `toml`
- Error-tolerant parsing with `default_on_error` deserializer
- Argument consumption validation ensuring all CLI options are processed
- Path expansion supporting `~` and `$HOME` environment variables
-
-## Configuration
-
-### Default Paths
-
-**Cross-Platform Path Resolution:**
-
- **Linux**: `~/.bitcoin` for Bitcoin Core, `~/.brk` for BRK data
- **macOS**: `~/Library/Application Support/Bitcoin` for Bitcoin Core
- **Logs**: `~/.brk/log` for application logging
- **Downloads**: `~/.brk/downloads` for temporary website artifacts
-
-### Performance Settings
-
-**Memory Management:**
-
- 512MB stack size for main processing thread
- Multi-threaded tokio runtime with all features enabled
- Persistent configuration caching to minimize I/O operations
-
-### Error Handling
-
-**Comprehensive Validation:**
-
- Directory existence checks with user-friendly error messages
- RPC authentication verification before processing begins
- Graceful exit with help suggestions for configuration issues
-
-## Code Analysis Summary
-
-**Main Structure**: `Config` struct with clap-derived CLI parsing and persistent TOML configuration management \
-**Processing Loop**: Continuous Bitcoin Core monitoring with sync detection and incremental block processing \
-**Web Integration**: Automatic website download from GitHub releases with JavaScript bundle generation \
-**Component Orchestration**: Coordination of parser, indexer, computer, and server with proper dependency management \
-**Error Handling**: `color_eyre` integration with comprehensive validation and user-friendly error messages \
-**Threading**: High-stack thread allocation (512MB) with tokio multi-threaded runtime for complex operations \
-**Architecture**: Complete BRK pipeline orchestration with persistent configuration and continuous blockchain synchronization
-
---
-
-_This README was generated by Claude Code_
@@ -1,8 +0,0 @@
-fn main() {
-    let profile = std::env::var("PROFILE").unwrap_or_default();
-
-    if profile == "release" {
-        println!("cargo:rustc-flag=-C");
-        println!("cargo:rustc-flag=target-cpu=native");
-    }
-}
@@ -3,83 +3,51 @@ use std::{
    path::{Path, PathBuf},
 };

-use bitcoincore_rpc::{self, Auth, Client};
-use brk_fetcher::Fetcher;
-use clap::Parser;
-use color_eyre::eyre::eyre;
+use brk_error::{Error, Result};
+use brk_rpc::{Auth, Client};
+use brk_server::Website;
+use brk_types::Port;
+use owo_colors::OwoColorize;
 use serde::{Deserialize, Deserializer, Serialize};

-use crate::{default_bitcoin_path, default_brk_path, dot_brk_path, website::Website};
+use crate::{default_brk_path, dot_brk_path, fix_user_path};

-const DOWNLOADS: &str = "downloads";
-
-#[derive(Parser, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize)]
-#[command(version, about)]
+#[derive(Debug, Default, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize)]
 pub struct Config {
-    /// Bitcoin main directory path, defaults: ~/.bitcoin, ~/Library/Application\ Support/Bitcoin, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "PATH")]
-    bitcoindir: Option<String>,
-
-    /// Bitcoin blocks directory path, default: --bitcoindir/blocks, saved
-    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "PATH")]
-    blocksdir: Option<String>,
-
-    /// Bitcoin Research Kit outputs directory path, default: ~/.brk, saved
-    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "PATH")]
    brkdir: Option<String>,

-    /// Activate fetching prices from BRK's API and the computation of all price related datasets, default: true, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(short = 'F', long, value_name = "BOOL")]
-    fetch: Option<bool>,
+    brkport: Option<Port>,

-    /// Activate fetching prices from exchanges APIs if `fetch` is also set to `true`, default: true, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "BOOL")]
-    exchanges: Option<bool>,
-
-    /// Website served by the server, default: default, saved
-    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(short, long)]
    website: Option<Website>,

-    /// Bitcoin RPC ip, default: localhost, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "IP")]
+    bitcoindir: Option<String>,
+
+    #[serde(default, deserialize_with = "default_on_error")]
+    blocksdir: Option<String>,
+
+    #[serde(default, deserialize_with = "default_on_error")]
    rpcconnect: Option<String>,

-    /// Bitcoin RPC port, default: 8332, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "PORT")]
    rpcport: Option<u16>,

-    /// Bitcoin RPC cookie file, default: --bitcoindir/.cookie, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "PATH")]
    rpccookiefile: Option<String>,

-    /// Bitcoin RPC username, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "USERNAME")]
    rpcuser: Option<String>,

-    /// Bitcoin RPC password, saved
    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(long, value_name = "PASSWORD")]
    rpcpassword: Option<String>,
-
-    /// DEV: Activate checking address hashes for collisions when indexing, default: false, saved
-    #[serde(default, deserialize_with = "default_on_error")]
-    #[arg(skip)]
-    check_collisions: Option<bool>,
 }

 impl Config {
-    pub fn import() -> color_eyre::Result<Self> {
-        let config_args = Some(Config::parse());
+    pub fn import() -> Result<Self> {
+        let config_args = Self::parse_args();

        let path = dot_brk_path();

@@ -87,72 +55,181 @@ impl Config {

        let path = path.join("config.toml");

-        let mut config_saved = Self::read(&path);
+        let mut config = Self::read(&path);

-        if let Some(mut config_args) = config_args {
-            if let Some(bitcoindir) = config_args.bitcoindir.take() {
-                config_saved.bitcoindir = Some(bitcoindir);
-            }
-
-            if let Some(blocksdir) = config_args.blocksdir.take() {
-                config_saved.blocksdir = Some(blocksdir);
-            }
-
-            if let Some(brkdir) = config_args.brkdir.take() {
-                config_saved.brkdir = Some(brkdir);
-            }
-
-            if let Some(fetch) = config_args.fetch.take() {
-                config_saved.fetch = Some(fetch);
-            }
-
-            if let Some(exchanges) = config_args.exchanges.take() {
-                config_saved.exchanges = Some(exchanges);
-            }
-
-            if let Some(website) = config_args.website.take() {
-                config_saved.website = Some(website);
-            }
-
-            if let Some(rpcconnect) = config_args.rpcconnect.take() {
-                config_saved.rpcconnect = Some(rpcconnect);
-            }
-
-            if let Some(rpcport) = config_args.rpcport.take() {
-                config_saved.rpcport = Some(rpcport);
-            }
-
-            if let Some(rpccookiefile) = config_args.rpccookiefile.take() {
-                config_saved.rpccookiefile = Some(rpccookiefile);
-            }
-
-            if let Some(rpcuser) = config_args.rpcuser.take() {
-                config_saved.rpcuser = Some(rpcuser);
-            }
-
-            if let Some(rpcpassword) = config_args.rpcpassword.take() {
-                config_saved.rpcpassword = Some(rpcpassword);
-            }
-
-            if let Some(check_collisions) = config_args.check_collisions.take() {
-                config_saved.check_collisions = Some(check_collisions);
-            }
-
-            if config_args != Config::default() {
-                dbg!(config_args);
-                panic!("Didn't consume the full config")
-            }
+        if let Some(v) = config_args.brkdir {
+            config.brkdir = Some(v);
+        }
+        if let Some(v) = config_args.brkport {
+            config.brkport = Some(v);
+        }
+        if let Some(v) = config_args.website {
+            config.website = Some(v);
+        }
+        if let Some(v) = config_args.bitcoindir {
+            config.bitcoindir = Some(v);
+        }
+        if let Some(v) = config_args.blocksdir {
+            config.blocksdir = Some(v);
+        }
+        if let Some(v) = config_args.rpcconnect {
+            config.rpcconnect = Some(v);
+        }
+        if let Some(v) = config_args.rpcport {
+            config.rpcport = Some(v);
+        }
+        if let Some(v) = config_args.rpccookiefile {
+            config.rpccookiefile = Some(v);
+        }
+        if let Some(v) = config_args.rpcuser {
+            config.rpcuser = Some(v);
+        }
+        if let Some(v) = config_args.rpcpassword {
+            config.rpcpassword = Some(v);
        }
-
-        let config = config_saved;

        config.check();

-        config.write(&path)?;
-
        Ok(config)
    }

+    fn parse_args() -> Self {
+        use lexopt::prelude::*;
+
+        let mut config = Self::default();
+        let mut parser = lexopt::Parser::from_env();
+
+        while let Some(arg) = parser.next().unwrap() {
+            match arg {
+                Short('h') | Long("help") => {
+                    Self::print_help();
+                    std::process::exit(0);
+                }
+                Short('V') | Long("version") => {
+                    println!("brk {}", env!("CARGO_PKG_VERSION"));
+                    std::process::exit(0);
+                }
+                Long("brkdir") => config.brkdir = Some(parser.value().unwrap().parse().unwrap()),
+                Long("brkport") => config.brkport = Some(parser.value().unwrap().parse().unwrap()),
+                Long("website") => config.website = Some(parser.value().unwrap().parse().unwrap()),
+                Long("bitcoindir") => {
+                    config.bitcoindir = Some(parser.value().unwrap().parse().unwrap())
+                }
+                Long("blocksdir") => {
+                    config.blocksdir = Some(parser.value().unwrap().parse().unwrap())
+                }
+                Long("rpcconnect") => {
+                    config.rpcconnect = Some(parser.value().unwrap().parse().unwrap())
+                }
+                Long("rpcport") => config.rpcport = Some(parser.value().unwrap().parse().unwrap()),
+                Long("rpccookiefile") => {
+                    config.rpccookiefile = Some(parser.value().unwrap().parse().unwrap())
+                }
+                Long("rpcuser") => config.rpcuser = Some(parser.value().unwrap().parse().unwrap()),
+                Long("rpcpassword") => {
+                    config.rpcpassword = Some(parser.value().unwrap().parse().unwrap())
+                }
+                _ => {
+                    eprintln!("{}", arg.unexpected());
+                    std::process::exit(1);
+                }
+            }
+        }
+
+        config
+    }
+
+    fn print_help() {
+        let v = env!("CARGO_PKG_VERSION");
+
+        println!("{} {}", "brk".bold(), v.bright_black());
+        println!("Bitcoin Research Kit");
+        println!();
+        println!("{}", "USAGE:".bold());
+        println!(
+            "    {} brk {}",
+            "[ENV]".bright_black(),
+            "[OPTIONS]".bright_black()
+        );
+        println!();
+        println!("{}", "OPTIONS:".bold());
+        println!("    -h, --help                Print help");
+        println!("    -V, --version             Print version");
+        println!();
+        println!(
+            "    --brkdir {}           Output directory {}",
+            "<PATH>".bright_black(),
+            "[~/.brk]".bright_black()
+        );
+        println!(
+            "    --brkport {}          Server port {}",
+            "<PORT>".bright_black(),
+            "[3110]".bright_black()
+        );
+        println!(
+            "    --website {}     Website {}",
+            "<BOOL|PATH>".bright_black(),
+            "[true]".bright_black()
+        );
+        println!();
+        println!(
+            "    --bitcoindir {}       Bitcoin directory {}",
+            "<PATH>".bright_black(),
+            "[OS default]".bright_black()
+        );
+        println!(
+            "    --blocksdir {}        Blocks directory {}",
+            "<PATH>".bright_black(),
+            "[<bitcoindir>/blocks]".bright_black()
+        );
+        println!();
+        println!(
+            "    --rpcconnect {}         RPC host {}",
+            "<IP>".bright_black(),
+            "[localhost]".bright_black()
+        );
+        println!(
+            "    --rpcport {}          RPC port {}",
+            "<PORT>".bright_black(),
+            "[8332]".bright_black()
+        );
+        println!(
+            "    --rpccookiefile {}    RPC cookie file {}",
+            "<PATH>".bright_black(),
+            "[<bitcoindir>/.cookie]".bright_black()
+        );
+        println!(
+            "    --rpcuser {}      RPC username",
+            "<USERNAME>".bright_black()
+        );
+        println!(
+            "    --rpcpassword {}  RPC password",
+            "<PASSWORD>".bright_black()
+        );
+        println!();
+        println!("{}", "ENVIRONMENT:".bold());
+        println!(
+            "    LOG={}               Log level {}",
+            "<LEVEL>".bright_black(),
+            "[info]".bright_black()
+        );
+        println!(
+            "    RUST_LOG={}          Full log filter",
+            "<RULES>".bright_black()
+        );
+        println!();
+        println!("{}", "CONFIG:".bold());
+        println!(
+            "    Edit {} to persist settings:",
+            "~/.brk/config.toml".bright_black()
+        );
+        println!("    {}", "brkdir = \"/path/to/data\"".bright_black());
+        println!(
+            "    {}",
+            "bitcoindir = \"/path/to/.bitcoin\"".bright_black()
+        );
+    }
+
    fn check(&self) {
        if !self.bitcoindir().is_dir() {
            println!("{:?} isn't a valid directory", self.bitcoindir());
@@ -192,22 +269,18 @@ Finally, you can run the program with '-h' for help."
        )
    }

-    fn write(&self, path: &Path) -> std::io::Result<()> {
-        fs::write(path, toml::to_string(self).unwrap())
-    }
-
-    pub fn rpc(&self) -> color_eyre::Result<&'static Client> {
-        Ok(Box::leak(Box::new(Client::new(
+    pub fn rpc(&self) -> Result<Client> {
+        Client::new(
            &format!(
                "http://{}:{}",
                self.rpcconnect().unwrap_or(&"localhost".to_string()),
                self.rpcport().unwrap_or(8332)
            ),
-            self.rpc_auth().unwrap(),
-        )?)))
+            self.rpc_auth()?,
+        )
    }

-    fn rpc_auth(&self) -> color_eyre::Result<Auth> {
+    fn rpc_auth(&self) -> Result<Auth> {
        let cookie = self.path_cookiefile();

        if cookie.is_file() {
@@ -218,7 +291,7 @@ Finally, you can run the program with '-h' for help."
                self.rpcpassword.clone().unwrap(),
            ))
        } else {
-            Err(eyre!("Failed to find correct auth"))
+            Err(Error::AuthFailed)
        }
    }

@@ -233,74 +306,35 @@ Finally, you can run the program with '-h' for help."
    pub fn bitcoindir(&self) -> PathBuf {
        self.bitcoindir
            .as_ref()
-            .map_or_else(default_bitcoin_path, |s| Self::fix_user_path(s.as_ref()))
+            .map_or_else(Client::default_bitcoin_path, |s| fix_user_path(s.as_ref()))
    }

    pub fn blocksdir(&self) -> PathBuf {
        self.blocksdir.as_ref().map_or_else(
            || self.bitcoindir().join("blocks"),
-            |blocksdir| Self::fix_user_path(blocksdir.as_str()),
+            |blocksdir| fix_user_path(blocksdir.as_str()),
        )
    }

    pub fn brkdir(&self) -> PathBuf {
        self.brkdir
            .as_ref()
-            .map_or_else(default_brk_path, |s| Self::fix_user_path(s.as_ref()))
-    }
-
-    pub fn harsdir(&self) -> PathBuf {
-        self.brkdir().join("hars")
-    }
-
-    pub fn downloads_dir(&self) -> PathBuf {
-        dot_brk_path().join(DOWNLOADS)
+            .map_or_else(default_brk_path, |s| fix_user_path(s.as_ref()))
    }

    fn path_cookiefile(&self) -> PathBuf {
        self.rpccookiefile.as_ref().map_or_else(
            || self.bitcoindir().join(".cookie"),
-            |p| Self::fix_user_path(p.as_str()),
+            |p| fix_user_path(p.as_str()),
        )
    }

-    fn fix_user_path(path: &str) -> PathBuf {
-        let fix = move |pattern: &str| {
-            if path.starts_with(pattern) {
-                let path = &path
-                    .replace(&format!("{pattern}/"), "")
-                    .replace(pattern, "");
-
-                let home = std::env::var("HOME").unwrap();
-
-                Some(Path::new(&home).join(path))
-            } else {
-                None
-            }
-        };
-
-        fix("~").unwrap_or_else(|| fix("$HOME").unwrap_or_else(|| PathBuf::from(&path)))
-    }
-
    pub fn website(&self) -> Website {
-        self.website.unwrap_or(Website::Bitview)
+        self.website.clone().unwrap_or_default()
    }

-    pub fn fetch(&self) -> bool {
-        self.fetch.is_none_or(|b| b)
-    }
-
-    pub fn exchanges(&self) -> bool {
-        self.exchanges.is_none_or(|b| b)
-    }
-
-    pub fn fetcher(&self) -> Option<Fetcher> {
-        self.fetch()
-            .then(|| Fetcher::import(self.exchanges(), Some(self.harsdir().as_path())).unwrap())
-    }
-
-    pub fn check_collisions(&self) -> bool {
-        self.check_collisions.is_some_and(|b| b)
+    pub fn brkport(&self) -> Option<Port> {
+        self.brkport
    }
 }

@@ -1,167 +0,0 @@
-#![doc = include_str!("../README.md")]
-
-use std::{
-    fs,
-    io::Cursor,
-    path::Path,
-    thread::{self, sleep},
-    time::Duration,
-};
-
-use bitcoincore_rpc::{self, RpcApi};
-use brk_binder::Bridge;
-use brk_bundler::bundle;
-use brk_computer::Computer;
-use brk_error::Result;
-use brk_indexer::Indexer;
-use brk_interface::Interface;
-use brk_parser::Parser;
-use brk_server::{Server, VERSION};
-use log::info;
-use vecdb::Exit;
-
-mod config;
-mod paths;
-mod website;
-
-use crate::{config::Config, paths::*};
-
-pub fn main() -> color_eyre::Result<()> {
-    color_eyre::install()?;
-
-    fs::create_dir_all(dot_brk_path())?;
-
-    brk_logger::init(Some(&dot_brk_log_path()))?;
-
-    thread::Builder::new()
-        .stack_size(512 * 1024 * 1024)
-        .spawn(run)?
-        .join()
-        .unwrap()
-}
-
-pub fn run() -> color_eyre::Result<()> {
-    let config = Config::import()?;
-
-    let rpc = config.rpc()?;
-
-    let exit = Exit::new();
-    exit.set_ctrlc_handler();
-
-    let parser = Parser::new(config.blocksdir(), rpc);
-
-    let mut indexer = Indexer::forced_import(&config.brkdir())?;
-
-    let mut computer = Computer::forced_import(&config.brkdir(), &indexer, config.fetcher())?;
-
-    let interface = Interface::build(&parser, &indexer, &computer);
-
-    let website = config.website();
-
-    let downloads_path = config.downloads_dir();
-
-    let future = async move {
-        let bundle_path = if website.is_some() {
-            let websites_dev_path = Path::new("../../websites");
-            let modules_dev_path = Path::new("../../modules");
-
-            let websites_path;
-            let modules_path;
-
-            if fs::exists(websites_dev_path)? && fs::exists(modules_dev_path)? {
-                websites_path = websites_dev_path.to_path_buf();
-                modules_path = modules_dev_path.to_path_buf();
-            } else {
-                let downloaded_brk_path = downloads_path.join(format!("brk-{VERSION}"));
-
-                let downloaded_websites_path = downloaded_brk_path.join("websites");
-                let downloaded_modules_path = downloaded_brk_path.join("modules");
-
-                if !fs::exists(&downloaded_websites_path)? {
-                    info!("Downloading source from Github...");
-
-                    let url = format!(
-                        "https://github.com/bitcoinresearchkit/brk/archive/refs/tags/v{VERSION}.zip",
-                    );
-
-                    let response = minreq::get(url).send()?;
-                    let bytes = response.as_bytes();
-                    let cursor = Cursor::new(bytes);
-
-                    let mut zip = zip::ZipArchive::new(cursor).unwrap();
-
-                    zip.extract(downloads_path).unwrap();
-                }
-
-                websites_path = downloaded_websites_path;
-                modules_path = downloaded_modules_path;
-            }
-
-            interface.generate_js_files(&modules_path)?;
-
-            Some(
-                bundle(
-                    &modules_path,
-                    &websites_path,
-                    website.to_folder_name(),
-                    true,
-                )
-                .await?,
-            )
-        } else {
-            None
-        };
-
-        let server = Server::new(interface, bundle_path);
-
-        tokio::spawn(async move {
-            server.serve(true).await.unwrap();
-        });
-
-        Ok(()) as Result<()>
-    };
-
-    let runtime = tokio::runtime::Builder::new_multi_thread()
-        .enable_all()
-        .build()?;
-
-    let _handle = runtime.spawn(future);
-
-    loop {
-        wait_for_synced_node(rpc)?;
-
-        let block_count = rpc.get_block_count()?;
-
-        info!("{} blocks found.", block_count + 1);
-
-        let starting_indexes = indexer
-            .index(&parser, rpc, &exit, config.check_collisions())
-            .unwrap();
-
-        computer
-            .compute(&indexer, starting_indexes, &parser, &exit)
-            .unwrap();
-
-        info!("Waiting for new blocks...");
-
-        while block_count == rpc.get_block_count()? {
-            sleep(Duration::from_secs(1))
-        }
-    }
-}
-
-fn wait_for_synced_node(rpc_client: &bitcoincore_rpc::Client) -> color_eyre::Result<()> {
-    let is_synced = || -> color_eyre::Result<bool> {
-        let info = rpc_client.get_blockchain_info()?;
-        Ok(info.headers == info.blocks)
-    };
-
-    if !is_synced()? {
-        info!("Waiting for node to sync...");
-        while !is_synced()? {
-            sleep(Duration::from_secs(1))
-        }
-    }
-
-    Ok(())
-}
@@ -1 +1,118 @@
-use brk_cli::main;
+#![doc = include_str!("../README.md")]
+
+use std::{
+    fs,
+    thread::{self, sleep},
+    time::{Duration, Instant},
+};
+
+use brk_alloc::Mimalloc;
+use brk_computer::Computer;
+use brk_error::Result;
+use brk_indexer::Indexer;
+use brk_mempool::Mempool;
+use brk_query::AsyncQuery;
+use brk_reader::Reader;
+use brk_server::Server;
+use tracing::info;
+use vecdb::Exit;
+
+mod config;
+mod paths;
+
+use crate::{config::Config, paths::*};
+
+pub fn main() -> anyhow::Result<()> {
+    fs::create_dir_all(dot_brk_path())?;
+
+    brk_logger::init(Some(&dot_brk_log_path()))?;
+
+    let config = Config::import()?;
+
+    let client = config.rpc()?;
+
+    let exit = Exit::new();
+    exit.set_ctrlc_handler();
+
+    let reader = Reader::new(config.blocksdir(), &client);
+
+    let mut indexer = Indexer::forced_import(&config.brkdir())?;
+
+    #[cfg(not(debug_assertions))]
+    {
+        // Pre-run indexer if too far behind, then drop and reimport to reduce memory
+        let chain_height = client.get_last_height()?;
+        let indexed_height = indexer.vecs.starting_height();
+        let blocks_behind = chain_height.saturating_sub(*indexed_height);
+        if blocks_behind > 10_000 {
+            info!("---");
+            info!("Indexing {blocks_behind} blocks before starting server...");
+            info!("---");
+            sleep(Duration::from_secs(10));
+            indexer.index(&reader, &client, &exit)?;
+            drop(indexer);
+            Mimalloc::collect();
+            indexer = Indexer::forced_import(&config.brkdir())?;
+        }
+    }
+
+    let mut computer = Computer::forced_import(&config.brkdir(), &indexer)?;
+
+    let mempool = Mempool::new(&client);
+
+    let mempool_clone = mempool.clone();
+    thread::spawn(move || {
+        mempool_clone.start();
+    });
+
+    let query = AsyncQuery::build(&reader, &indexer, &computer, Some(mempool));
+
+    let data_path = config.brkdir();
+
+    let website = config.website();
+
+    let port = config.brkport();
+
+    let future = async move {
+        let server = Server::new(&query, data_path, website);
+
+        tokio::spawn(async move {
+            server.serve(port).await.unwrap();
+        });
+
+        Ok(()) as Result<()>
+    };
+
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()?;
+
+    let _handle = runtime.spawn(future);
+
+    loop {
+        client.wait_for_synced_node()?;
+
+        let last_height = client.get_last_height()?;
+
+        info!("{} blocks found.", u32::from(last_height) + 1);
+
+        let total_start = Instant::now();
+
+        let starting_indexes = if cfg!(debug_assertions) {
+            indexer.checked_index(&reader, &client, &exit)?
+        } else {
+            indexer.index(&reader, &client, &exit)?
+        };
+
+        Mimalloc::collect();
+
+        computer.compute(&indexer, starting_indexes, &exit)?;
+
+        info!("Total time: {:?}", total_start.elapsed());
+        info!("Waiting for new blocks...");
+
+        while last_height == client.get_last_height()? {
+            sleep(Duration::from_secs(1))
+        }
+    }
+}
@@ -1,7 +1,4 @@
-use std::{
-    env,
-    path::{Path, PathBuf},
-};
+use std::path::{Path, PathBuf};

 pub fn dot_brk_path() -> PathBuf {
    let home = std::env::var("HOME").unwrap();
@@ -16,21 +13,11 @@ pub fn default_brk_path() -> PathBuf {
    dot_brk_path()
 }

-pub fn default_bitcoin_path() -> PathBuf {
-    if env::consts::OS == "macos" {
-        default_mac_bitcoin_path()
-    } else {
-        default_linux_bitcoin_path()
+pub fn fix_user_path(path: &str) -> PathBuf {
+    if let Some(rest) = path.strip_prefix("~/").or(path.strip_prefix("$HOME/"))
+        && let Ok(home) = std::env::var("HOME")
+    {
+        return PathBuf::from(home).join(rest);
    }
-}
-
-pub fn default_linux_bitcoin_path() -> PathBuf {
-    Path::new(&std::env::var("HOME").unwrap()).join(".bitcoin")
-}
-
-pub fn default_mac_bitcoin_path() -> PathBuf {
-    Path::new(&std::env::var("HOME").unwrap())
-        .join("Library")
-        .join("Application Support")
-        .join("Bitcoin")
+    PathBuf::from(path)
 }
@@ -1,28 +0,0 @@
-use clap::ValueEnum;
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize, ValueEnum)]
-#[serde(rename_all = "lowercase")]
-pub enum Website {
-    None,
-    Bitview,
-    Custom,
-}
-
-impl Website {
-    pub fn is_none(&self) -> bool {
-        self == &Self::None
-    }
-
-    pub fn is_some(&self) -> bool {
-        !self.is_none()
-    }
-
-    pub fn to_folder_name(self) -> &'static str {
-        match self {
-            Self::Custom => "custom",
-            Self::Bitview => "bitview",
-            Self::None => unreachable!(),
-        }
-    }
-}
@@ -0,0 +1,18 @@
+[package]
+name = "brk_client"
+description = "Rust client for the Bitcoin Research Kit API"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords = ["bitcoin", "blockchain", "analytics", "on-chain"]
+categories = ["api-bindings", "cryptography::cryptocurrencies"]
+exclude = ["examples/"]
+
+[dependencies]
+brk_cohort = { workspace = true }
+brk_types = { workspace = true }
+ureq = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
@@ -0,0 +1,53 @@
+# brk_client
+
+Rust client for the [Bitcoin Research Kit](https://github.com/bitcoinresearchkit/brk) API.
+
+[crates.io](https://crates.io/crates/brk_client) | [docs.rs](https://docs.rs/brk_client)
+
+## Installation
+
+```toml
+[dependencies]
+brk_client = "0.1"
+```
+
+## Quick Start
+
+```rust
+use brk_client::{BrkClient, Index};
+
+fn main() -> brk_client::Result<()> {
+    let client = BrkClient::new("http://localhost:3110");
+
+    // Blockchain data (mempool.space compatible)
+    let block = client.get_block_by_height(800000)?;
+    let tx = client.get_tx("a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d")?;
+    let address = client.get_address("bc1q...")?;
+
+    // Metrics API - typed, chainable
+    let prices = client.metrics()
+        .price.usd.split.close
+        .by.dateindex()
+        .range(Some(-30), None)?; // Last 30 days
+
+    // Generic metric fetching
+    let data = client.get_metric(
+        "price_close".into(),
+        Index::DateIndex,
+        Some(-30), None, None, None,
+    )?;
+
+    Ok(())
+}
+```
+
+## Configuration
+
+```rust
+use brk_client::{BrkClient, BrkClientOptions};
+
+let client = BrkClient::with_options(BrkClientOptions {
+    base_url: "http://localhost:3110".to_string(),
+    timeout_secs: 60,
+});
+```
@@ -0,0 +1,95 @@
+//! Basic example of using the BRK client.
+
+use brk_client::{BrkClient, BrkClientOptions};
+use brk_types::{FormatResponse, Index, RangeIndex};
+
+fn main() -> brk_client::Result<()> {
+    // Create client with default options
+    let client = BrkClient::new("http://localhost:3110");
+
+    // Or with custom options
+    let _client_with_options = BrkClient::with_options(BrkClientOptions {
+        base_url: "http://localhost:3110".to_string(),
+        timeout_secs: 60,
+    });
+
+    // Fetch price data using the typed metrics API
+    // day1() returns DateMetricEndpointBuilder, so fetch() returns DateMetricData
+    let price_close = client
+        .series()
+        .prices
+        .split
+        .close
+        .usd
+        .by
+        .day1()
+        .last(3)
+        .fetch()?;
+    println!("Last 3 price close values:");
+    // iter_dates() returns Option (None for sub-daily indexes)
+    for (date, value) in price_close.iter_dates().unwrap() {
+        println!("  {}: {}", date, value);
+    }
+    // iter_timestamps() works for all date-based indexes including sub-daily
+    for (ts, value) in price_close.iter_timestamps() {
+        println!("  {}: {}", ts, value);
+    }
+
+    // Fetch block data with height index (non-date, returns MetricData)
+    let block_count = client
+        .series()
+        .blocks
+        .count
+        .total
+        .sum
+        ._24h
+        .by
+        .day1()
+        .last(3)
+        .fetch()?;
+    println!("Last 3 block count values:");
+    for (date, value) in block_count.iter_dates().unwrap() {
+        println!("  {}: {}", date, value);
+    }
+
+    // Fetch supply data as CSV
+    dbg!(client.series().supply.circulating.btc.by.day1().path());
+    let circulating = client
+        .series()
+        .supply
+        .circulating
+        .btc
+        .by
+        .day1()
+        .last(3)
+        .fetch_csv()?;
+    println!("Last 3 circulating supply (CSV): {:?}", circulating);
+
+    // Using dynamic metric fetching with date_metric() for date-based indexes
+    let date_metric = client
+        .date_series_endpoint("price_close", Index::Day1)?
+        .last(3)
+        .fetch()?;
+    println!("Dynamic date metric fetch:");
+    for (date, value) in date_metric.iter_dates().unwrap() {
+        println!("  {}: {}", date, value);
+    }
+
+    // Using generic metric fetching (returns FormatResponse)
+    let metricdata = client.get_series(
+        "price_close".into(),
+        Index::Day1,
+        Some(RangeIndex::Int(-3)),
+        None,
+        None,
+        None,
+    )?;
+    match metricdata {
+        FormatResponse::Json(m) => {
+            println!("Generic fetch result count: {}", m.data.len());
+        }
+        FormatResponse::Csv(_) => panic!(),
+    };
+
+    Ok(())
+}
@@ -0,0 +1,85 @@
+//! Comprehensive test that fetches all endpoints in the tree.
+//!
+//! This example demonstrates how to recursively traverse the metrics catalog tree
+//! and fetch data from each endpoint. Run with: cargo run --example tree
+
+use brk_client::BrkClient;
+use brk_types::{Index, RangeIndex, TreeNode};
+use std::collections::BTreeSet;
+
+/// A collected metric with its path and available indexes.
+struct CollectedMetric {
+    path: String,
+    name: String,
+    indexes: BTreeSet<Index>,
+}
+
+/// Recursively collect all metrics from the tree.
+fn collect_metrics(node: &TreeNode, path: &str) -> Vec<CollectedMetric> {
+    let mut metrics = Vec::new();
+
+    match node {
+        TreeNode::Branch(children) => {
+            for (key, child) in children {
+                let child_path = if path.is_empty() {
+                    key.clone()
+                } else {
+                    format!("{}.{}", path, key)
+                };
+                metrics.extend(collect_metrics(child, &child_path));
+            }
+        }
+        TreeNode::Leaf(leaf) => {
+            metrics.push(CollectedMetric {
+                path: path.to_string(),
+                name: leaf.name().to_string(),
+                indexes: leaf.indexes().clone(),
+            });
+        }
+    }
+
+    metrics
+}
+
+fn main() -> brk_client::Result<()> {
+    let client = BrkClient::new("http://localhost:3110");
+
+    // Get the metrics catalog tree
+    let tree = client.get_series_tree()?;
+
+    // Recursively collect all metrics
+    let metrics = collect_metrics(&tree, "");
+    println!("\nFound {} metrics", metrics.len());
+
+    let mut success = 0;
+
+    for metric in &metrics {
+        for index in &metric.indexes {
+            let index_str = index.name();
+            let full_path = format!("{}.by.{}", metric.path, index_str);
+
+            match client.get_series(
+                metric.name.as_str().into(),
+                *index,
+                None,
+                Some(RangeIndex::Int(0)),
+                None,
+                None,
+            ) {
+                Ok(_) => {
+                    success += 1;
+                    println!("OK: {}", full_path);
+                }
+                Err(e) => {
+                    println!("FAIL: {} -> {}", full_path, e);
+                    return Err(e);
+                }
+            }
+        }
+    }
+
+    println!("\n=== Results ===");
+    println!("Success: {}", success);
+
+    Ok(())
+}
@@ -0,0 +1,19 @@
+[package]
+name = "brk_cohort"
+description = "Cohort definitions used throughout BRK"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[dependencies]
+brk_error = { workspace = true, features = ["vecdb"] }
+brk_types = { workspace = true }
+brk_traversable = { workspace = true }
+vecdb = { workspace = true }
+rayon = { workspace = true }
+serde = { workspace = true }
+
+[package.metadata.cargo-machete]
+ignored = ["vecdb"]
@@ -0,0 +1,52 @@
+# brk_cohort
+
+UTXO and address cohort filtering for on-chain analytics.
+
+## What It Enables
+
+Slice the UTXO set and address population by age, amount, output type, halving epoch, or holder classification (STH/LTH). Build complex cohorts by combining filters for metrics like "realized cap of 1+ BTC UTXOs older than 150 days."
+
+## Key Features
+
+- **Age-based**: `TimeFilter::GreaterOrEqual(hours)`, `TimeFilter::Range(hours..hours)`, `TimeFilter::LowerThan(hours)`
+- **Amount-based**: `AmountFilter::GreaterOrEqual(Sats::_1BTC)`, `AmountFilter::Range(Sats::_100K..Sats::_1M)`
+- **Term classification**: `Term::Sth` (short-term holders, <150 days), `Term::Lth` (long-term holders)
+- **Epoch filters**: Group by halving epoch
+- **Type filters**: Segment by output type (P2PKH, P2TR, etc.)
+- **Context-aware naming**: Automatic prefix generation (`utxos_`, `addrs_`) based on cohort context
+- **Inclusion logic**: Filter hierarchy for aggregation (`Filter::includes`)
+
+## Filter Types
+
+```rust,ignore
+pub enum Filter {
+    All,
+    Term(Term),           // STH/LTH
+    Time(TimeFilter),     // Age-based
+    Amount(AmountFilter), // Value-based
+    Epoch(Halving),  // Halving epoch
+    Year(Year),           // Calendar year
+    Type(OutputType),     // P2PKH, P2TR, etc.
+}
+```
+
+## Core API
+
+```rust,ignore
+// TimeFilter values are in hours (e.g., 3600 hours = 150 days)
+let filter = Filter::Time(TimeFilter::GreaterOrEqual(3600));
+
+// Check membership
+filter.contains_time(4000);  // true (4000 hours > 3600 hours)
+filter.contains_amount(sats);
+
+// Generate metric names (via CohortContext)
+let ctx = CohortContext::Utxo;
+ctx.full_name(&filter, "min_age_150d");  // "utxos_min_age_150d"
+```
+
+## Built On
+
+- `brk_error` for error handling
+- `brk_types` for `Sats`, `Halving`, `OutputType`
+- `brk_traversable` for data structure traversal
@@ -0,0 +1,82 @@
+use brk_traversable::Traversable;
+use rayon::prelude::*;
+
+use crate::Filter;
+
+use super::{AmountRange, OverAmount, UnderAmount};
+
+#[derive(Default, Clone, Traversable)]
+pub struct AddrGroups<T> {
+    pub over_amount: OverAmount<T>,
+    pub amount_range: AmountRange<T>,
+    pub under_amount: UnderAmount<T>,
+}
+
+impl<T> AddrGroups<T> {
+    pub fn new<F>(mut create: F) -> Self
+    where
+        F: FnMut(Filter, &'static str) -> T,
+    {
+        Self {
+            over_amount: OverAmount::new(&mut create),
+            amount_range: AmountRange::new(&mut create),
+            under_amount: UnderAmount::new(&mut create),
+        }
+    }
+
+    pub fn try_new<F, E>(create: &F) -> Result<Self, E>
+    where
+        F: Fn(Filter, &'static str) -> Result<T, E>,
+    {
+        Ok(Self {
+            over_amount: OverAmount::try_new(create)?,
+            amount_range: AmountRange::try_new(create)?,
+            under_amount: UnderAmount::try_new(create)?,
+        })
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = &T> {
+        self.over_amount
+            .iter()
+            .chain(self.amount_range.iter())
+            .chain(self.under_amount.iter())
+    }
+
+    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.over_amount
+            .iter_mut()
+            .chain(self.amount_range.iter_mut())
+            .chain(self.under_amount.iter_mut())
+    }
+
+    pub fn par_iter_mut(&mut self) -> impl ParallelIterator<Item = &mut T>
+    where
+        T: Send + Sync,
+    {
+        self.over_amount
+            .par_iter_mut()
+            .chain(self.amount_range.par_iter_mut())
+            .chain(self.under_amount.par_iter_mut())
+    }
+
+    pub fn iter_separate(&self) -> impl Iterator<Item = &T> {
+        self.amount_range.iter()
+    }
+
+    pub fn iter_separate_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.amount_range.iter_mut()
+    }
+
+    pub fn par_iter_separate_mut(&mut self) -> impl ParallelIterator<Item = &mut T>
+    where
+        T: Send + Sync,
+    {
+        self.amount_range.par_iter_mut()
+    }
+
+    pub fn iter_overlapping_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.under_amount
+            .iter_mut()
+            .chain(self.over_amount.iter_mut())
+    }
+}
@@ -0,0 +1,397 @@
+use std::ops::Range;
+
+use brk_traversable::Traversable;
+use brk_types::Age;
+use rayon::iter::{IntoParallelIterator, ParallelIterator};
+use serde::Serialize;
+
+use super::{CohortName, Filter, TimeFilter};
+
+// Age boundary constants in hours
+pub const HOURS_1H: usize = 1;
+pub const HOURS_1D: usize = 24;
+pub const HOURS_1W: usize = 24 * 7;
+pub const HOURS_1M: usize = 24 * 30;
+pub const HOURS_2M: usize = 24 * 2 * 30;
+pub const HOURS_3M: usize = 24 * 3 * 30;
+pub const HOURS_4M: usize = 24 * 4 * 30;
+pub const HOURS_5M: usize = 24 * 5 * 30; // STH/LTH threshold
+pub const HOURS_6M: usize = 24 * 6 * 30;
+pub const HOURS_1Y: usize = 24 * 365;
+pub const HOURS_2Y: usize = 24 * 2 * 365;
+pub const HOURS_3Y: usize = 24 * 3 * 365;
+pub const HOURS_4Y: usize = 24 * 4 * 365;
+pub const HOURS_5Y: usize = 24 * 5 * 365;
+pub const HOURS_6Y: usize = 24 * 6 * 365;
+pub const HOURS_7Y: usize = 24 * 7 * 365;
+pub const HOURS_8Y: usize = 24 * 8 * 365;
+pub const HOURS_10Y: usize = 24 * 10 * 365;
+pub const HOURS_12Y: usize = 24 * 12 * 365;
+pub const HOURS_15Y: usize = 24 * 15 * 365;
+
+/// Age boundaries in hours. Defines the cohort ranges:
+/// [0, 1h), [1h, 1d), [1d, 1w), [1w, 1m), ..., [15y, ∞)
+pub const AGE_BOUNDARIES: [usize; 20] = [
+    HOURS_1H, HOURS_1D, HOURS_1W, HOURS_1M, HOURS_2M, HOURS_3M, HOURS_4M, HOURS_5M, HOURS_6M,
+    HOURS_1Y, HOURS_2Y, HOURS_3Y, HOURS_4Y, HOURS_5Y, HOURS_6Y, HOURS_7Y, HOURS_8Y, HOURS_10Y,
+    HOURS_12Y, HOURS_15Y,
+];
+
+/// Age range bounds (end = usize::MAX means unbounded)
+pub const AGE_RANGE_BOUNDS: AgeRange<Range<usize>> = AgeRange {
+    under_1h: 0..HOURS_1H,
+    _1h_to_1d: HOURS_1H..HOURS_1D,
+    _1d_to_1w: HOURS_1D..HOURS_1W,
+    _1w_to_1m: HOURS_1W..HOURS_1M,
+    _1m_to_2m: HOURS_1M..HOURS_2M,
+    _2m_to_3m: HOURS_2M..HOURS_3M,
+    _3m_to_4m: HOURS_3M..HOURS_4M,
+    _4m_to_5m: HOURS_4M..HOURS_5M,
+    _5m_to_6m: HOURS_5M..HOURS_6M,
+    _6m_to_1y: HOURS_6M..HOURS_1Y,
+    _1y_to_2y: HOURS_1Y..HOURS_2Y,
+    _2y_to_3y: HOURS_2Y..HOURS_3Y,
+    _3y_to_4y: HOURS_3Y..HOURS_4Y,
+    _4y_to_5y: HOURS_4Y..HOURS_5Y,
+    _5y_to_6y: HOURS_5Y..HOURS_6Y,
+    _6y_to_7y: HOURS_6Y..HOURS_7Y,
+    _7y_to_8y: HOURS_7Y..HOURS_8Y,
+    _8y_to_10y: HOURS_8Y..HOURS_10Y,
+    _10y_to_12y: HOURS_10Y..HOURS_12Y,
+    _12y_to_15y: HOURS_12Y..HOURS_15Y,
+    over_15y: HOURS_15Y..usize::MAX,
+};
+
+/// Age range filters
+pub const AGE_RANGE_FILTERS: AgeRange<Filter> = AgeRange {
+    under_1h: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS.under_1h)),
+    _1h_to_1d: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._1h_to_1d)),
+    _1d_to_1w: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._1d_to_1w)),
+    _1w_to_1m: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._1w_to_1m)),
+    _1m_to_2m: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._1m_to_2m)),
+    _2m_to_3m: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._2m_to_3m)),
+    _3m_to_4m: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._3m_to_4m)),
+    _4m_to_5m: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._4m_to_5m)),
+    _5m_to_6m: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._5m_to_6m)),
+    _6m_to_1y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._6m_to_1y)),
+    _1y_to_2y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._1y_to_2y)),
+    _2y_to_3y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._2y_to_3y)),
+    _3y_to_4y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._3y_to_4y)),
+    _4y_to_5y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._4y_to_5y)),
+    _5y_to_6y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._5y_to_6y)),
+    _6y_to_7y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._6y_to_7y)),
+    _7y_to_8y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._7y_to_8y)),
+    _8y_to_10y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._8y_to_10y)),
+    _10y_to_12y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._10y_to_12y)),
+    _12y_to_15y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS._12y_to_15y)),
+    over_15y: Filter::Time(TimeFilter::Range(AGE_RANGE_BOUNDS.over_15y)),
+};
+
+/// Age range names
+pub const AGE_RANGE_NAMES: AgeRange<CohortName> = AgeRange {
+    under_1h: CohortName::new("under_1h_old", "<1h", "Under 1 Hour Old"),
+    _1h_to_1d: CohortName::new("1h_to_1d_old", "1h-1d", "1 Hour to 1 Day Old"),
+    _1d_to_1w: CohortName::new("1d_to_1w_old", "1d-1w", "1 Day to 1 Week Old"),
+    _1w_to_1m: CohortName::new("1w_to_1m_old", "1w-1m", "1 Week to 1 Month Old"),
+    _1m_to_2m: CohortName::new("1m_to_2m_old", "1m-2m", "1 to 2 Months Old"),
+    _2m_to_3m: CohortName::new("2m_to_3m_old", "2m-3m", "2 to 3 Months Old"),
+    _3m_to_4m: CohortName::new("3m_to_4m_old", "3m-4m", "3 to 4 Months Old"),
+    _4m_to_5m: CohortName::new("4m_to_5m_old", "4m-5m", "4 to 5 Months Old"),
+    _5m_to_6m: CohortName::new("5m_to_6m_old", "5m-6m", "5 to 6 Months Old"),
+    _6m_to_1y: CohortName::new("6m_to_1y_old", "6m-1y", "6 Months to 1 Year Old"),
+    _1y_to_2y: CohortName::new("1y_to_2y_old", "1y-2y", "1 to 2 Years Old"),
+    _2y_to_3y: CohortName::new("2y_to_3y_old", "2y-3y", "2 to 3 Years Old"),
+    _3y_to_4y: CohortName::new("3y_to_4y_old", "3y-4y", "3 to 4 Years Old"),
+    _4y_to_5y: CohortName::new("4y_to_5y_old", "4y-5y", "4 to 5 Years Old"),
+    _5y_to_6y: CohortName::new("5y_to_6y_old", "5y-6y", "5 to 6 Years Old"),
+    _6y_to_7y: CohortName::new("6y_to_7y_old", "6y-7y", "6 to 7 Years Old"),
+    _7y_to_8y: CohortName::new("7y_to_8y_old", "7y-8y", "7 to 8 Years Old"),
+    _8y_to_10y: CohortName::new("8y_to_10y_old", "8y-10y", "8 to 10 Years Old"),
+    _10y_to_12y: CohortName::new("10y_to_12y_old", "10y-12y", "10 to 12 Years Old"),
+    _12y_to_15y: CohortName::new("12y_to_15y_old", "12y-15y", "12 to 15 Years Old"),
+    over_15y: CohortName::new("over_15y_old", "15y+", "15+ Years Old"),
+};
+
+impl AgeRange<CohortName> {
+    pub const fn names() -> &'static Self {
+        &AGE_RANGE_NAMES
+    }
+}
+
+#[derive(Default, Clone, Traversable, Serialize)]
+pub struct AgeRange<T> {
+    pub under_1h: T,
+    pub _1h_to_1d: T,
+    pub _1d_to_1w: T,
+    pub _1w_to_1m: T,
+    pub _1m_to_2m: T,
+    pub _2m_to_3m: T,
+    pub _3m_to_4m: T,
+    pub _4m_to_5m: T,
+    pub _5m_to_6m: T,
+    pub _6m_to_1y: T,
+    pub _1y_to_2y: T,
+    pub _2y_to_3y: T,
+    pub _3y_to_4y: T,
+    pub _4y_to_5y: T,
+    pub _5y_to_6y: T,
+    pub _6y_to_7y: T,
+    pub _7y_to_8y: T,
+    pub _8y_to_10y: T,
+    pub _10y_to_12y: T,
+    pub _12y_to_15y: T,
+    pub over_15y: T,
+}
+
+impl<T> AgeRange<T> {
+    /// Get mutable reference by Age. O(1).
+    #[inline]
+    pub fn get_mut(&mut self, age: Age) -> &mut T {
+        match age.hours() {
+            0..HOURS_1H => &mut self.under_1h,
+            HOURS_1H..HOURS_1D => &mut self._1h_to_1d,
+            HOURS_1D..HOURS_1W => &mut self._1d_to_1w,
+            HOURS_1W..HOURS_1M => &mut self._1w_to_1m,
+            HOURS_1M..HOURS_2M => &mut self._1m_to_2m,
+            HOURS_2M..HOURS_3M => &mut self._2m_to_3m,
+            HOURS_3M..HOURS_4M => &mut self._3m_to_4m,
+            HOURS_4M..HOURS_5M => &mut self._4m_to_5m,
+            HOURS_5M..HOURS_6M => &mut self._5m_to_6m,
+            HOURS_6M..HOURS_1Y => &mut self._6m_to_1y,
+            HOURS_1Y..HOURS_2Y => &mut self._1y_to_2y,
+            HOURS_2Y..HOURS_3Y => &mut self._2y_to_3y,
+            HOURS_3Y..HOURS_4Y => &mut self._3y_to_4y,
+            HOURS_4Y..HOURS_5Y => &mut self._4y_to_5y,
+            HOURS_5Y..HOURS_6Y => &mut self._5y_to_6y,
+            HOURS_6Y..HOURS_7Y => &mut self._6y_to_7y,
+            HOURS_7Y..HOURS_8Y => &mut self._7y_to_8y,
+            HOURS_8Y..HOURS_10Y => &mut self._8y_to_10y,
+            HOURS_10Y..HOURS_12Y => &mut self._10y_to_12y,
+            HOURS_12Y..HOURS_15Y => &mut self._12y_to_15y,
+            _ => &mut self.over_15y,
+        }
+    }
+
+    /// Get reference by Age. O(1).
+    #[inline]
+    pub fn get(&self, age: Age) -> &T {
+        match age.hours() {
+            0..HOURS_1H => &self.under_1h,
+            HOURS_1H..HOURS_1D => &self._1h_to_1d,
+            HOURS_1D..HOURS_1W => &self._1d_to_1w,
+            HOURS_1W..HOURS_1M => &self._1w_to_1m,
+            HOURS_1M..HOURS_2M => &self._1m_to_2m,
+            HOURS_2M..HOURS_3M => &self._2m_to_3m,
+            HOURS_3M..HOURS_4M => &self._3m_to_4m,
+            HOURS_4M..HOURS_5M => &self._4m_to_5m,
+            HOURS_5M..HOURS_6M => &self._5m_to_6m,
+            HOURS_6M..HOURS_1Y => &self._6m_to_1y,
+            HOURS_1Y..HOURS_2Y => &self._1y_to_2y,
+            HOURS_2Y..HOURS_3Y => &self._2y_to_3y,
+            HOURS_3Y..HOURS_4Y => &self._3y_to_4y,
+            HOURS_4Y..HOURS_5Y => &self._4y_to_5y,
+            HOURS_5Y..HOURS_6Y => &self._5y_to_6y,
+            HOURS_6Y..HOURS_7Y => &self._6y_to_7y,
+            HOURS_7Y..HOURS_8Y => &self._7y_to_8y,
+            HOURS_8Y..HOURS_10Y => &self._8y_to_10y,
+            HOURS_10Y..HOURS_12Y => &self._10y_to_12y,
+            HOURS_12Y..HOURS_15Y => &self._12y_to_15y,
+            _ => &self.over_15y,
+        }
+    }
+
+    pub fn from_array(arr: [T; 21]) -> Self {
+        let [
+            a0,
+            a1,
+            a2,
+            a3,
+            a4,
+            a5,
+            a6,
+            a7,
+            a8,
+            a9,
+            a10,
+            a11,
+            a12,
+            a13,
+            a14,
+            a15,
+            a16,
+            a17,
+            a18,
+            a19,
+            a20,
+        ] = arr;
+        Self {
+            under_1h: a0,
+            _1h_to_1d: a1,
+            _1d_to_1w: a2,
+            _1w_to_1m: a3,
+            _1m_to_2m: a4,
+            _2m_to_3m: a5,
+            _3m_to_4m: a6,
+            _4m_to_5m: a7,
+            _5m_to_6m: a8,
+            _6m_to_1y: a9,
+            _1y_to_2y: a10,
+            _2y_to_3y: a11,
+            _3y_to_4y: a12,
+            _4y_to_5y: a13,
+            _5y_to_6y: a14,
+            _6y_to_7y: a15,
+            _7y_to_8y: a16,
+            _8y_to_10y: a17,
+            _10y_to_12y: a18,
+            _12y_to_15y: a19,
+            over_15y: a20,
+        }
+    }
+
+    pub fn new<F>(mut create: F) -> Self
+    where
+        F: FnMut(Filter, &'static str) -> T,
+    {
+        let f = AGE_RANGE_FILTERS;
+        let n = AGE_RANGE_NAMES;
+        Self {
+            under_1h: create(f.under_1h.clone(), n.under_1h.id),
+            _1h_to_1d: create(f._1h_to_1d.clone(), n._1h_to_1d.id),
+            _1d_to_1w: create(f._1d_to_1w.clone(), n._1d_to_1w.id),
+            _1w_to_1m: create(f._1w_to_1m.clone(), n._1w_to_1m.id),
+            _1m_to_2m: create(f._1m_to_2m.clone(), n._1m_to_2m.id),
+            _2m_to_3m: create(f._2m_to_3m.clone(), n._2m_to_3m.id),
+            _3m_to_4m: create(f._3m_to_4m.clone(), n._3m_to_4m.id),
+            _4m_to_5m: create(f._4m_to_5m.clone(), n._4m_to_5m.id),
+            _5m_to_6m: create(f._5m_to_6m.clone(), n._5m_to_6m.id),
+            _6m_to_1y: create(f._6m_to_1y.clone(), n._6m_to_1y.id),
+            _1y_to_2y: create(f._1y_to_2y.clone(), n._1y_to_2y.id),
+            _2y_to_3y: create(f._2y_to_3y.clone(), n._2y_to_3y.id),
+            _3y_to_4y: create(f._3y_to_4y.clone(), n._3y_to_4y.id),
+            _4y_to_5y: create(f._4y_to_5y.clone(), n._4y_to_5y.id),
+            _5y_to_6y: create(f._5y_to_6y.clone(), n._5y_to_6y.id),
+            _6y_to_7y: create(f._6y_to_7y.clone(), n._6y_to_7y.id),
+            _7y_to_8y: create(f._7y_to_8y.clone(), n._7y_to_8y.id),
+            _8y_to_10y: create(f._8y_to_10y.clone(), n._8y_to_10y.id),
+            _10y_to_12y: create(f._10y_to_12y.clone(), n._10y_to_12y.id),
+            _12y_to_15y: create(f._12y_to_15y.clone(), n._12y_to_15y.id),
+            over_15y: create(f.over_15y.clone(), n.over_15y.id),
+        }
+    }
+
+    pub fn try_new<F, E>(mut create: F) -> Result<Self, E>
+    where
+        F: FnMut(Filter, &'static str) -> Result<T, E>,
+    {
+        let f = AGE_RANGE_FILTERS;
+        let n = AGE_RANGE_NAMES;
+        Ok(Self {
+            under_1h: create(f.under_1h.clone(), n.under_1h.id)?,
+            _1h_to_1d: create(f._1h_to_1d.clone(), n._1h_to_1d.id)?,
+            _1d_to_1w: create(f._1d_to_1w.clone(), n._1d_to_1w.id)?,
+            _1w_to_1m: create(f._1w_to_1m.clone(), n._1w_to_1m.id)?,
+            _1m_to_2m: create(f._1m_to_2m.clone(), n._1m_to_2m.id)?,
+            _2m_to_3m: create(f._2m_to_3m.clone(), n._2m_to_3m.id)?,
+            _3m_to_4m: create(f._3m_to_4m.clone(), n._3m_to_4m.id)?,
+            _4m_to_5m: create(f._4m_to_5m.clone(), n._4m_to_5m.id)?,
+            _5m_to_6m: create(f._5m_to_6m.clone(), n._5m_to_6m.id)?,
+            _6m_to_1y: create(f._6m_to_1y.clone(), n._6m_to_1y.id)?,
+            _1y_to_2y: create(f._1y_to_2y.clone(), n._1y_to_2y.id)?,
+            _2y_to_3y: create(f._2y_to_3y.clone(), n._2y_to_3y.id)?,
+            _3y_to_4y: create(f._3y_to_4y.clone(), n._3y_to_4y.id)?,
+            _4y_to_5y: create(f._4y_to_5y.clone(), n._4y_to_5y.id)?,
+            _5y_to_6y: create(f._5y_to_6y.clone(), n._5y_to_6y.id)?,
+            _6y_to_7y: create(f._6y_to_7y.clone(), n._6y_to_7y.id)?,
+            _7y_to_8y: create(f._7y_to_8y.clone(), n._7y_to_8y.id)?,
+            _8y_to_10y: create(f._8y_to_10y.clone(), n._8y_to_10y.id)?,
+            _10y_to_12y: create(f._10y_to_12y.clone(), n._10y_to_12y.id)?,
+            _12y_to_15y: create(f._12y_to_15y.clone(), n._12y_to_15y.id)?,
+            over_15y: create(f.over_15y.clone(), n.over_15y.id)?,
+        })
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = &T> {
+        [
+            &self.under_1h,
+            &self._1h_to_1d,
+            &self._1d_to_1w,
+            &self._1w_to_1m,
+            &self._1m_to_2m,
+            &self._2m_to_3m,
+            &self._3m_to_4m,
+            &self._4m_to_5m,
+            &self._5m_to_6m,
+            &self._6m_to_1y,
+            &self._1y_to_2y,
+            &self._2y_to_3y,
+            &self._3y_to_4y,
+            &self._4y_to_5y,
+            &self._5y_to_6y,
+            &self._6y_to_7y,
+            &self._7y_to_8y,
+            &self._8y_to_10y,
+            &self._10y_to_12y,
+            &self._12y_to_15y,
+            &self.over_15y,
+        ]
+        .into_iter()
+    }
+
+    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        [
+            &mut self.under_1h,
+            &mut self._1h_to_1d,
+            &mut self._1d_to_1w,
+            &mut self._1w_to_1m,
+            &mut self._1m_to_2m,
+            &mut self._2m_to_3m,
+            &mut self._3m_to_4m,
+            &mut self._4m_to_5m,
+            &mut self._5m_to_6m,
+            &mut self._6m_to_1y,
+            &mut self._1y_to_2y,
+            &mut self._2y_to_3y,
+            &mut self._3y_to_4y,
+            &mut self._4y_to_5y,
+            &mut self._5y_to_6y,
+            &mut self._6y_to_7y,
+            &mut self._7y_to_8y,
+            &mut self._8y_to_10y,
+            &mut self._10y_to_12y,
+            &mut self._12y_to_15y,
+            &mut self.over_15y,
+        ]
+        .into_iter()
+    }
+
+    pub fn par_iter_mut(&mut self) -> impl ParallelIterator<Item = &mut T>
+    where
+        T: Send + Sync,
+    {
+        [
+            &mut self.under_1h,
+            &mut self._1h_to_1d,
+            &mut self._1d_to_1w,
+            &mut self._1w_to_1m,
+            &mut self._1m_to_2m,
+            &mut self._2m_to_3m,
+            &mut self._3m_to_4m,
+            &mut self._4m_to_5m,
+            &mut self._5m_to_6m,
+            &mut self._6m_to_1y,
+            &mut self._1y_to_2y,
+            &mut self._2y_to_3y,
+            &mut self._3y_to_4y,
+            &mut self._4y_to_5y,
+            &mut self._5y_to_6y,
+            &mut self._6y_to_7y,
+            &mut self._7y_to_8y,
+            &mut self._8y_to_10y,
+            &mut self._10y_to_12y,
+            &mut self._12y_to_15y,
+            &mut self.over_15y,
+        ]
+        .into_par_iter()
+    }
+}
@@ -0,0 +1,36 @@
+use std::ops::Range;
+
+use brk_types::Sats;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AmountFilter {
+    LowerThan(Sats),
+    Range(Range<Sats>),
+    GreaterOrEqual(Sats),
+}
+
+impl AmountFilter {
+    pub fn contains(&self, sats: Sats) -> bool {
+        match self {
+            AmountFilter::LowerThan(max) => sats < *max,
+            AmountFilter::Range(r) => sats >= r.start && sats < r.end,
+            AmountFilter::GreaterOrEqual(min) => sats >= *min,
+        }
+    }
+
+    pub fn includes(&self, other: &AmountFilter) -> bool {
+        match self {
+            AmountFilter::LowerThan(max) => match other {
+                AmountFilter::LowerThan(max2) => max >= max2,
+                AmountFilter::Range(range) => range.end <= *max,
+                AmountFilter::GreaterOrEqual(_) => false,
+            },
+            AmountFilter::GreaterOrEqual(min) => match other {
+                AmountFilter::Range(range) => range.start >= *min,
+                AmountFilter::GreaterOrEqual(min2) => min <= min2,
+                AmountFilter::LowerThan(_) => false,
+            },
+            AmountFilter::Range(_) => false,
+        }
+    }
+}
@@ -0,0 +1,415 @@
+use std::ops::{Add, AddAssign, Range};
+
+use brk_traversable::Traversable;
+use brk_types::Sats;
+use rayon::prelude::*;
+use serde::Serialize;
+
+use super::{AmountFilter, CohortName, Filter};
+
+/// Bucket index for amount ranges. Use for cheap comparisons and direct lookups.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AmountBucket(u8);
+
+impl AmountBucket {
+    /// Returns (self, other) if buckets differ, None if same.
+    /// Use with `AmountRange::get_mut_by_bucket` to avoid recomputing.
+    #[inline(always)]
+    pub fn transition_to(self, other: Self) -> Option<(Self, Self)> {
+        if self != other {
+            Some((self, other))
+        } else {
+            None
+        }
+    }
+
+    #[inline(always)]
+    pub fn index(self) -> u8 {
+        self.0
+    }
+}
+
+impl From<Sats> for AmountBucket {
+    #[inline(always)]
+    fn from(value: Sats) -> Self {
+        Self(match value {
+            v if v < Sats::_1 => 0,
+            v if v < Sats::_10 => 1,
+            v if v < Sats::_100 => 2,
+            v if v < Sats::_1K => 3,
+            v if v < Sats::_10K => 4,
+            v if v < Sats::_100K => 5,
+            v if v < Sats::_1M => 6,
+            v if v < Sats::_10M => 7,
+            v if v < Sats::_1BTC => 8,
+            v if v < Sats::_10BTC => 9,
+            v if v < Sats::_100BTC => 10,
+            v if v < Sats::_1K_BTC => 11,
+            v if v < Sats::_10K_BTC => 12,
+            v if v < Sats::_100K_BTC => 13,
+            _ => 14,
+        })
+    }
+}
+
+/// Check if two amounts are in different buckets. O(1).
+#[inline(always)]
+pub fn amounts_in_different_buckets(a: Sats, b: Sats) -> bool {
+    AmountBucket::from(a) != AmountBucket::from(b)
+}
+
+/// Amount range bounds
+pub const AMOUNT_RANGE_BOUNDS: AmountRange<Range<Sats>> = AmountRange {
+    _0sats: Sats::ZERO..Sats::_1,
+    _1sat_to_10sats: Sats::_1..Sats::_10,
+    _10sats_to_100sats: Sats::_10..Sats::_100,
+    _100sats_to_1k_sats: Sats::_100..Sats::_1K,
+    _1k_sats_to_10k_sats: Sats::_1K..Sats::_10K,
+    _10k_sats_to_100k_sats: Sats::_10K..Sats::_100K,
+    _100k_sats_to_1m_sats: Sats::_100K..Sats::_1M,
+    _1m_sats_to_10m_sats: Sats::_1M..Sats::_10M,
+    _10m_sats_to_1btc: Sats::_10M..Sats::_1BTC,
+    _1btc_to_10btc: Sats::_1BTC..Sats::_10BTC,
+    _10btc_to_100btc: Sats::_10BTC..Sats::_100BTC,
+    _100btc_to_1k_btc: Sats::_100BTC..Sats::_1K_BTC,
+    _1k_btc_to_10k_btc: Sats::_1K_BTC..Sats::_10K_BTC,
+    _10k_btc_to_100k_btc: Sats::_10K_BTC..Sats::_100K_BTC,
+    over_100k_btc: Sats::_100K_BTC..Sats::MAX,
+};
+
+/// Amount range names
+pub const AMOUNT_RANGE_NAMES: AmountRange<CohortName> = AmountRange {
+    _0sats: CohortName::new("0sats", "0 sats", "0 Sats"),
+    _1sat_to_10sats: CohortName::new("1sat_to_10sats", "1-10 sats", "1-10 Sats"),
+    _10sats_to_100sats: CohortName::new("10sats_to_100sats", "10-100 sats", "10-100 Sats"),
+    _100sats_to_1k_sats: CohortName::new("100sats_to_1k_sats", "100-1k sats", "100-1K Sats"),
+    _1k_sats_to_10k_sats: CohortName::new("1k_sats_to_10k_sats", "1k-10k sats", "1K-10K Sats"),
+    _10k_sats_to_100k_sats: CohortName::new(
+        "10k_sats_to_100k_sats",
+        "10k-100k sats",
+        "10K-100K Sats",
+    ),
+    _100k_sats_to_1m_sats: CohortName::new("100k_sats_to_1m_sats", "100k-1M sats", "100K-1M Sats"),
+    _1m_sats_to_10m_sats: CohortName::new("1m_sats_to_10m_sats", "1M-10M sats", "1M-10M Sats"),
+    _10m_sats_to_1btc: CohortName::new("10m_sats_to_1btc", "0.1-1 BTC", "0.1-1 BTC"),
+    _1btc_to_10btc: CohortName::new("1btc_to_10btc", "1-10 BTC", "1-10 BTC"),
+    _10btc_to_100btc: CohortName::new("10btc_to_100btc", "10-100 BTC", "10-100 BTC"),
+    _100btc_to_1k_btc: CohortName::new("100btc_to_1k_btc", "100-1k BTC", "100-1K BTC"),
+    _1k_btc_to_10k_btc: CohortName::new("1k_btc_to_10k_btc", "1k-10k BTC", "1K-10K BTC"),
+    _10k_btc_to_100k_btc: CohortName::new("10k_btc_to_100k_btc", "10k-100k BTC", "10K-100K BTC"),
+    over_100k_btc: CohortName::new("over_100k_btc", "100k+ BTC", "100K+ BTC"),
+};
+
+/// Amount range filters
+pub const AMOUNT_RANGE_FILTERS: AmountRange<Filter> = AmountRange {
+    _0sats: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._0sats)),
+    _1sat_to_10sats: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._1sat_to_10sats)),
+    _10sats_to_100sats: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._10sats_to_100sats)),
+    _100sats_to_1k_sats: Filter::Amount(AmountFilter::Range(
+        AMOUNT_RANGE_BOUNDS._100sats_to_1k_sats,
+    )),
+    _1k_sats_to_10k_sats: Filter::Amount(AmountFilter::Range(
+        AMOUNT_RANGE_BOUNDS._1k_sats_to_10k_sats,
+    )),
+    _10k_sats_to_100k_sats: Filter::Amount(AmountFilter::Range(
+        AMOUNT_RANGE_BOUNDS._10k_sats_to_100k_sats,
+    )),
+    _100k_sats_to_1m_sats: Filter::Amount(AmountFilter::Range(
+        AMOUNT_RANGE_BOUNDS._100k_sats_to_1m_sats,
+    )),
+    _1m_sats_to_10m_sats: Filter::Amount(AmountFilter::Range(
+        AMOUNT_RANGE_BOUNDS._1m_sats_to_10m_sats,
+    )),
+    _10m_sats_to_1btc: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._10m_sats_to_1btc)),
+    _1btc_to_10btc: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._1btc_to_10btc)),
+    _10btc_to_100btc: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._10btc_to_100btc)),
+    _100btc_to_1k_btc: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._100btc_to_1k_btc)),
+    _1k_btc_to_10k_btc: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS._1k_btc_to_10k_btc)),
+    _10k_btc_to_100k_btc: Filter::Amount(AmountFilter::Range(
+        AMOUNT_RANGE_BOUNDS._10k_btc_to_100k_btc,
+    )),
+    over_100k_btc: Filter::Amount(AmountFilter::Range(AMOUNT_RANGE_BOUNDS.over_100k_btc)),
+};
+
+#[derive(Debug, Default, Clone, Traversable, Serialize)]
+pub struct AmountRange<T> {
+    pub _0sats: T,
+    pub _1sat_to_10sats: T,
+    pub _10sats_to_100sats: T,
+    pub _100sats_to_1k_sats: T,
+    pub _1k_sats_to_10k_sats: T,
+    pub _10k_sats_to_100k_sats: T,
+    pub _100k_sats_to_1m_sats: T,
+    pub _1m_sats_to_10m_sats: T,
+    pub _10m_sats_to_1btc: T,
+    pub _1btc_to_10btc: T,
+    pub _10btc_to_100btc: T,
+    pub _100btc_to_1k_btc: T,
+    pub _1k_btc_to_10k_btc: T,
+    pub _10k_btc_to_100k_btc: T,
+    pub over_100k_btc: T,
+}
+
+impl AmountRange<CohortName> {
+    pub const fn names() -> &'static Self {
+        &AMOUNT_RANGE_NAMES
+    }
+}
+
+impl<T> AmountRange<T> {
+    pub fn new<F>(mut create: F) -> Self
+    where
+        F: FnMut(Filter, &'static str) -> T,
+    {
+        let f = AMOUNT_RANGE_FILTERS;
+        let n = AMOUNT_RANGE_NAMES;
+        Self {
+            _0sats: create(f._0sats.clone(), n._0sats.id),
+            _1sat_to_10sats: create(f._1sat_to_10sats.clone(), n._1sat_to_10sats.id),
+            _10sats_to_100sats: create(f._10sats_to_100sats.clone(), n._10sats_to_100sats.id),
+            _100sats_to_1k_sats: create(f._100sats_to_1k_sats.clone(), n._100sats_to_1k_sats.id),
+            _1k_sats_to_10k_sats: create(f._1k_sats_to_10k_sats.clone(), n._1k_sats_to_10k_sats.id),
+            _10k_sats_to_100k_sats: create(
+                f._10k_sats_to_100k_sats.clone(),
+                n._10k_sats_to_100k_sats.id,
+            ),
+            _100k_sats_to_1m_sats: create(
+                f._100k_sats_to_1m_sats.clone(),
+                n._100k_sats_to_1m_sats.id,
+            ),
+            _1m_sats_to_10m_sats: create(f._1m_sats_to_10m_sats.clone(), n._1m_sats_to_10m_sats.id),
+            _10m_sats_to_1btc: create(f._10m_sats_to_1btc.clone(), n._10m_sats_to_1btc.id),
+            _1btc_to_10btc: create(f._1btc_to_10btc.clone(), n._1btc_to_10btc.id),
+            _10btc_to_100btc: create(f._10btc_to_100btc.clone(), n._10btc_to_100btc.id),
+            _100btc_to_1k_btc: create(f._100btc_to_1k_btc.clone(), n._100btc_to_1k_btc.id),
+            _1k_btc_to_10k_btc: create(f._1k_btc_to_10k_btc.clone(), n._1k_btc_to_10k_btc.id),
+            _10k_btc_to_100k_btc: create(f._10k_btc_to_100k_btc.clone(), n._10k_btc_to_100k_btc.id),
+            over_100k_btc: create(f.over_100k_btc.clone(), n.over_100k_btc.id),
+        }
+    }
+
+    pub fn try_new<F, E>(mut create: F) -> Result<Self, E>
+    where
+        F: FnMut(Filter, &'static str) -> Result<T, E>,
+    {
+        let f = AMOUNT_RANGE_FILTERS;
+        let n = AMOUNT_RANGE_NAMES;
+        Ok(Self {
+            _0sats: create(f._0sats.clone(), n._0sats.id)?,
+            _1sat_to_10sats: create(f._1sat_to_10sats.clone(), n._1sat_to_10sats.id)?,
+            _10sats_to_100sats: create(f._10sats_to_100sats.clone(), n._10sats_to_100sats.id)?,
+            _100sats_to_1k_sats: create(f._100sats_to_1k_sats.clone(), n._100sats_to_1k_sats.id)?,
+            _1k_sats_to_10k_sats: create(
+                f._1k_sats_to_10k_sats.clone(),
+                n._1k_sats_to_10k_sats.id,
+            )?,
+            _10k_sats_to_100k_sats: create(
+                f._10k_sats_to_100k_sats.clone(),
+                n._10k_sats_to_100k_sats.id,
+            )?,
+            _100k_sats_to_1m_sats: create(
+                f._100k_sats_to_1m_sats.clone(),
+                n._100k_sats_to_1m_sats.id,
+            )?,
+            _1m_sats_to_10m_sats: create(
+                f._1m_sats_to_10m_sats.clone(),
+                n._1m_sats_to_10m_sats.id,
+            )?,
+            _10m_sats_to_1btc: create(f._10m_sats_to_1btc.clone(), n._10m_sats_to_1btc.id)?,
+            _1btc_to_10btc: create(f._1btc_to_10btc.clone(), n._1btc_to_10btc.id)?,
+            _10btc_to_100btc: create(f._10btc_to_100btc.clone(), n._10btc_to_100btc.id)?,
+            _100btc_to_1k_btc: create(f._100btc_to_1k_btc.clone(), n._100btc_to_1k_btc.id)?,
+            _1k_btc_to_10k_btc: create(f._1k_btc_to_10k_btc.clone(), n._1k_btc_to_10k_btc.id)?,
+            _10k_btc_to_100k_btc: create(
+                f._10k_btc_to_100k_btc.clone(),
+                n._10k_btc_to_100k_btc.id,
+            )?,
+            over_100k_btc: create(f.over_100k_btc.clone(), n.over_100k_btc.id)?,
+        })
+    }
+
+    #[inline(always)]
+    pub fn get(&self, value: Sats) -> &T {
+        match AmountBucket::from(value).0 {
+            0 => &self._0sats,
+            1 => &self._1sat_to_10sats,
+            2 => &self._10sats_to_100sats,
+            3 => &self._100sats_to_1k_sats,
+            4 => &self._1k_sats_to_10k_sats,
+            5 => &self._10k_sats_to_100k_sats,
+            6 => &self._100k_sats_to_1m_sats,
+            7 => &self._1m_sats_to_10m_sats,
+            8 => &self._10m_sats_to_1btc,
+            9 => &self._1btc_to_10btc,
+            10 => &self._10btc_to_100btc,
+            11 => &self._100btc_to_1k_btc,
+            12 => &self._1k_btc_to_10k_btc,
+            13 => &self._10k_btc_to_100k_btc,
+            _ => &self.over_100k_btc,
+        }
+    }
+
+    #[inline(always)]
+    pub fn get_mut(&mut self, value: Sats) -> &mut T {
+        self.get_mut_by_bucket(AmountBucket::from(value))
+    }
+
+    /// Get mutable reference by pre-computed bucket index.
+    /// Use with `AmountBucket::transition_to` to avoid recomputing bucket.
+    #[inline(always)]
+    pub fn get_mut_by_bucket(&mut self, bucket: AmountBucket) -> &mut T {
+        match bucket.0 {
+            0 => &mut self._0sats,
+            1 => &mut self._1sat_to_10sats,
+            2 => &mut self._10sats_to_100sats,
+            3 => &mut self._100sats_to_1k_sats,
+            4 => &mut self._1k_sats_to_10k_sats,
+            5 => &mut self._10k_sats_to_100k_sats,
+            6 => &mut self._100k_sats_to_1m_sats,
+            7 => &mut self._1m_sats_to_10m_sats,
+            8 => &mut self._10m_sats_to_1btc,
+            9 => &mut self._1btc_to_10btc,
+            10 => &mut self._10btc_to_100btc,
+            11 => &mut self._100btc_to_1k_btc,
+            12 => &mut self._1k_btc_to_10k_btc,
+            13 => &mut self._10k_btc_to_100k_btc,
+            _ => &mut self.over_100k_btc,
+        }
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = &T> {
+        [
+            &self._0sats,
+            &self._1sat_to_10sats,
+            &self._10sats_to_100sats,
+            &self._100sats_to_1k_sats,
+            &self._1k_sats_to_10k_sats,
+            &self._10k_sats_to_100k_sats,
+            &self._100k_sats_to_1m_sats,
+            &self._1m_sats_to_10m_sats,
+            &self._10m_sats_to_1btc,
+            &self._1btc_to_10btc,
+            &self._10btc_to_100btc,
+            &self._100btc_to_1k_btc,
+            &self._1k_btc_to_10k_btc,
+            &self._10k_btc_to_100k_btc,
+            &self.over_100k_btc,
+        ]
+        .into_iter()
+    }
+
+    pub fn iter_typed(&self) -> impl Iterator<Item = (Sats, &T)> {
+        [
+            (Sats::ZERO, &self._0sats),
+            (Sats::_1, &self._1sat_to_10sats),
+            (Sats::_10, &self._10sats_to_100sats),
+            (Sats::_100, &self._100sats_to_1k_sats),
+            (Sats::_1K, &self._1k_sats_to_10k_sats),
+            (Sats::_10K, &self._10k_sats_to_100k_sats),
+            (Sats::_100K, &self._100k_sats_to_1m_sats),
+            (Sats::_1M, &self._1m_sats_to_10m_sats),
+            (Sats::_10M, &self._10m_sats_to_1btc),
+            (Sats::_1BTC, &self._1btc_to_10btc),
+            (Sats::_10BTC, &self._10btc_to_100btc),
+            (Sats::_100BTC, &self._100btc_to_1k_btc),
+            (Sats::_1K_BTC, &self._1k_btc_to_10k_btc),
+            (Sats::_10K_BTC, &self._10k_btc_to_100k_btc),
+            (Sats::_100K_BTC, &self.over_100k_btc),
+        ]
+        .into_iter()
+    }
+
+    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        [
+            &mut self._0sats,
+            &mut self._1sat_to_10sats,
+            &mut self._10sats_to_100sats,
+            &mut self._100sats_to_1k_sats,
+            &mut self._1k_sats_to_10k_sats,
+            &mut self._10k_sats_to_100k_sats,
+            &mut self._100k_sats_to_1m_sats,
+            &mut self._1m_sats_to_10m_sats,
+            &mut self._10m_sats_to_1btc,
+            &mut self._1btc_to_10btc,
+            &mut self._10btc_to_100btc,
+            &mut self._100btc_to_1k_btc,
+            &mut self._1k_btc_to_10k_btc,
+            &mut self._10k_btc_to_100k_btc,
+            &mut self.over_100k_btc,
+        ]
+        .into_iter()
+    }
+
+    pub fn par_iter_mut(&mut self) -> impl ParallelIterator<Item = &mut T>
+    where
+        T: Send + Sync,
+    {
+        [
+            &mut self._0sats,
+            &mut self._1sat_to_10sats,
+            &mut self._10sats_to_100sats,
+            &mut self._100sats_to_1k_sats,
+            &mut self._1k_sats_to_10k_sats,
+            &mut self._10k_sats_to_100k_sats,
+            &mut self._100k_sats_to_1m_sats,
+            &mut self._1m_sats_to_10m_sats,
+            &mut self._10m_sats_to_1btc,
+            &mut self._1btc_to_10btc,
+            &mut self._10btc_to_100btc,
+            &mut self._100btc_to_1k_btc,
+            &mut self._1k_btc_to_10k_btc,
+            &mut self._10k_btc_to_100k_btc,
+            &mut self.over_100k_btc,
+        ]
+        .into_par_iter()
+    }
+}
+
+impl<T> Add for AmountRange<T>
+where
+    T: Add<Output = T>,
+{
+    type Output = Self;
+    fn add(self, rhs: Self) -> Self::Output {
+        Self {
+            _0sats: self._0sats + rhs._0sats,
+            _1sat_to_10sats: self._1sat_to_10sats + rhs._1sat_to_10sats,
+            _10sats_to_100sats: self._10sats_to_100sats + rhs._10sats_to_100sats,
+            _100sats_to_1k_sats: self._100sats_to_1k_sats + rhs._100sats_to_1k_sats,
+            _1k_sats_to_10k_sats: self._1k_sats_to_10k_sats + rhs._1k_sats_to_10k_sats,
+            _10k_sats_to_100k_sats: self._10k_sats_to_100k_sats + rhs._10k_sats_to_100k_sats,
+            _100k_sats_to_1m_sats: self._100k_sats_to_1m_sats + rhs._100k_sats_to_1m_sats,
+            _1m_sats_to_10m_sats: self._1m_sats_to_10m_sats + rhs._1m_sats_to_10m_sats,
+            _10m_sats_to_1btc: self._10m_sats_to_1btc + rhs._10m_sats_to_1btc,
+            _1btc_to_10btc: self._1btc_to_10btc + rhs._1btc_to_10btc,
+            _10btc_to_100btc: self._10btc_to_100btc + rhs._10btc_to_100btc,
+            _100btc_to_1k_btc: self._100btc_to_1k_btc + rhs._100btc_to_1k_btc,
+            _1k_btc_to_10k_btc: self._1k_btc_to_10k_btc + rhs._1k_btc_to_10k_btc,
+            _10k_btc_to_100k_btc: self._10k_btc_to_100k_btc + rhs._10k_btc_to_100k_btc,
+            over_100k_btc: self.over_100k_btc + rhs.over_100k_btc,
+        }
+    }
+}
+
+impl<T> AddAssign for AmountRange<T>
+where
+    T: AddAssign,
+{
+    fn add_assign(&mut self, rhs: Self) {
+        self._0sats += rhs._0sats;
+        self._1sat_to_10sats += rhs._1sat_to_10sats;
+        self._10sats_to_100sats += rhs._10sats_to_100sats;
+        self._100sats_to_1k_sats += rhs._100sats_to_1k_sats;
+        self._1k_sats_to_10k_sats += rhs._1k_sats_to_10k_sats;
+        self._10k_sats_to_100k_sats += rhs._10k_sats_to_100k_sats;
+        self._100k_sats_to_1m_sats += rhs._100k_sats_to_1m_sats;
+        self._1m_sats_to_10m_sats += rhs._1m_sats_to_10m_sats;
+        self._10m_sats_to_1btc += rhs._10m_sats_to_1btc;
+        self._1btc_to_10btc += rhs._1btc_to_10btc;
+        self._10btc_to_100btc += rhs._10btc_to_100btc;
+        self._100btc_to_1k_btc += rhs._100btc_to_1k_btc;
+        self._1k_btc_to_10k_btc += rhs._1k_btc_to_10k_btc;
+        self._10k_btc_to_100k_btc += rhs._10k_btc_to_100k_btc;
+        self.over_100k_btc += rhs.over_100k_btc;
+    }
+}
--- a/Show More
+++ b/Show More