@@ -65,7 +65,10 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.target }}
-          args: --release --out dist
+          # macOS wheels ship the Metal GPU path. CLI `--features` replaces pyproject's
+          # `features=["python"]`, so list both. `gpu` is macOS-only; degrades to CPU at runtime
+          # when no Metal device is present.
+          args: --release --features python,gpu --out dist
           sccache: "true"
       - uses: actions/upload-artifact@v4
         with:
 
@@ -1,6 +1,6 @@
 [package]
 name = "difflib-fast"
-version = "0.1.2"
+version = "0.2.0"
 description = "Fast, byte-for-byte exact difflib Ratcliff–Obershelp (gestalt) similarity ratio + single-linkage clustering, via a suffix automaton."
 keywords = ["difflib", "similarity", "ratcliff-obershelp", "suffix-automaton", "fuzzy"]
 categories = ["algorithms", "text-processing"]
@@ -21,24 +21,52 @@ rayon = "1"
 # Optional Python bindings (the `python` feature, built by maturin). `abi3-py39` → one wheel per
 # platform works on CPython 3.9+. The pure-Rust crate has zero Python dependency by default.
 pyo3 = { version = "0.28", optional = true, features = ["extension-module", "abi3-py39"] }
-# Used ONLY as the bench binary's global allocator (libraries must not set one) — gated so the
-# published library never pulls it in. macOS's default malloc madvise churn cost ~25% once parallel.
+# Used ONLY as the `bench` binary's global allocator (libraries must not set one) — gated behind the
+# `bench` feature so the published library never pulls it in. macOS's default malloc madvise churn
+# cost ~25% once parallel, hence the override for benchmarking.
 mimalloc = { version = "0.1", default-features = false, optional = true }
+# Apple Metal compute bindings — used by the `gpu` feature to run the SAM matching_stats walk on
+# the M3 GPU in parallel with the CPU SAM walker (heterogeneous CPU+GPU exact RO). Apple-only;
+# the feature does not compile on non-Apple targets, and `cluster_canonicals` falls back to the
+# CPU-only path automatically when the GPU device cannot be acquired at runtime.
+[target.'cfg(target_os = "macos")'.dependencies]
+metal = { version = "0.33", optional = true }
 
 [features]
 default = []
 python = ["dep:pyo3"]
 bench = ["dep:mimalloc"] # enables the `bench` binary's mimalloc global allocator
+# Heterogeneous CPU+GPU exact RO — Metal compute shader port of the SAM matching_stats walker.
+# macOS-only; the feature wires up automatically on Apple Silicon and is a no-op on other targets.
+# The kernel reads the corpus SAMs out of unified shared memory (Apple Silicon's UMA = zero copy
+# between CPU and GPU), so there is no host↔device transfer cost. `Rationer` degrades to CPU when
+# this is off or no Metal device can be acquired at runtime.
+gpu = ["dep:metal"]
+# `instrument` adds atomic counters inside `gestalt::longest_in` and its endpos range queries plus
+# the RO recursion, plus a `gestalt::instrument::dump()` API that prints histograms of chain-walk
+# depth, recursion depth, fmatch distribution, the linear-vs-segtree split, and per-call scan
+# lengths. Costs ~10-20% wall when active (relaxed-ordered atomics on the hot path); the
+# `cfg(feature)` gate compiles to a no-op in default builds so production stays untouched.
+instrument = []
 
-[[bin]]
-name = "bench"
-required-features = ["bench"]
+# `objc`'s `sel!`/`msg_send!` macros (pulled in transitively by the `metal` crate under the `gpu`
+# feature) expand to `cfg(feature = "cargo-clippy")` checks — whitelist that cfg so the lint stays
+# on for genuinely-unexpected cfgs without flooding gpu builds with dependency-macro noise.
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(feature, values("cargo-clippy"))'] }
 
 # Strict clippy: all + pedantic denied (priority -1 so crate-local `#[allow]`s on hot paths override).
 [lints.clippy]
 all = { level = "deny", priority = -1 }
 pedantic = { level = "deny", priority = -1 }
 
+# Gold CPU baseline bench (raw ratio / threshold qualify / cluster). Gated behind `bench` so the
+# published library never builds it. The GPU / PMC / cross-impl harness lives outside the tracked
+# tree (see perf-local/).
+[[bin]]
+name = "bench"
+required-features = ["bench"]
+
 # Keep symbols + line tables in release so an external sampler (samply) can resolve frames.
 [profile.release]
 debug = "line-tables-only"
 
@@ -93,16 +93,56 @@ pairwise ratio.
 
 ## API
 
+Two tiers. The **free functions** are the stateless CPU drop-in:
+
 | function | what |
 |---|---|
 | `ratio(a, b) -> f64` | exact `difflib` ratio (dispatches automaton ⇄ `b2j` per input) |
 | `ratio_many(&[(String, String)]) -> Vec<f64>` | exact `ratio` for a batch of pairs, in parallel (rayon) |
 | `gestalt::gestalt_ratio(a, b) -> f64` | the suffix-automaton path directly |
-| `ratio_reference(a, b) -> f64` | the `b2j` reference port (slow; the test oracle) |
 | `cluster_canonicals(&[String], threshold) -> Vec<(Vec<usize>, f64)>` | exact single-linkage clusters + min pairwise ratio |
-| `cluster_canonicals_chars(&[Vec<char>], threshold)` | same, over pre-collected `char` vectors |
 | `cluster_canonicals_lsh(&[String], threshold, num_perm, band_rows)` | scalable MinHash-LSH variant (candidate-gen + exact verify) for very large corpora |
 
+And `Rationer` is the **stateful handle** that owns long-lived resources (rayon pool, and on
+macOS the Metal device) once and reuses them across calls — same exact output, with an optional GPU
+path:
+
+```rust
+use difflib_fast::Rationer;
+
+let r = Rationer::new();                          // builder().build(); default GpuPlusCpu
+let clusters = r.cluster_canonicals(&corpus, 0.6); // GPU-accelerated on macOS (see below)
+let ratios   = r.ratio_many(&pairs);               // CPU
+```
+
+`Rationer::builder().concurrency(Concurrency::Cpu | Gpu | GpuPlusCpu).threads(n).delta(d).build()`
+configures it; `PreparedRationer` (`r.prepare(&strings)`) amortizes SAM-build over many index-pair
+queries.
+
+### GPU (macOS + Metal)
+
+Behind the `gpu` cargo feature on Apple Silicon, `Rationer::cluster_canonicals` offloads the
+suffix-automaton `matching_stats` walk to a Metal compute kernel — **byte-for-byte identical output**,
+**~1.1–1.4×** end-to-end vs the (already fast) CPU path on a single large group:
+
+| corpus | `cluster_canonicals` GPU vs CPU |
+|---|---|
+| mypy | **1.38×** |
+| ha | 1.25× |
+| sympy | 1.17× |
+| django | 1.14× |
+| transformers | 1.08× |
+
+It's a modest, honest win: the GPU only does `matching_stats` (~⅓ of the per-pair cost); the
+`longest_in` recursion, filtering and assembly stay on CPU, so Amdahl caps it. `ratio_many` and
+`cluster_canonicals_multi` measured *slower* on the GPU at every size tested, so they stay on CPU by
+default (the GPU paths remain opt-in via `DFGPU_RATIO_MANY_THRESHOLD` / `DFGPU_MULTI_THRESHOLD`). With
+the feature off, on non-macOS, or with no Metal device, every call quietly runs on CPU.
+
+```toml
+difflib-fast = { version = "0.1", features = ["gpu"] }   # macOS only
+```
+
 ---
 
 ## Correctness
@@ -178,7 +218,7 @@ pick the wheel for you — grab the one for your platform from the
 
 ```bash
 # macOS Apple Silicon — swap the filename for your platform (see below):
-pip install https://github.com/prostomarkeloff/difflib-fast/releases/download/v0.1.2/difflib_fast-0.1.2-cp39-abi3-macosx_11_0_arm64.whl
+pip install https://github.com/prostomarkeloff/difflib-fast/releases/download/v0.2.0/difflib_fast-0.2.0-cp39-abi3-macosx_11_0_arm64.whl
 ```
 
 | platform | wheel suffix |
@@ -236,6 +276,26 @@ The package is **typed** (`py.typed` + `.pyi` stubs — pyright/mypy see the ove
 [maturin](https://github.com/PyO3/maturin) (mixed layout: compiled `_difflib_fast` +
 `python/difflib_fast/` package); build locally into a venv with `maturin develop --release --features python`.
 
+### GPU from Python (macOS)
+
+The **macOS wheels ship the Metal GPU path**. Use the `Rationer` handle — its `cluster_canonicals`
+runs on the GPU when the group is large enough to pay for the dispatch, otherwise CPU; same
+byte-for-byte answer either way:
+
+```python
+import difflib_fast as df
+
+r = df.Rationer(concurrency="gpu+cpu")        # "cpu" | "gpu" | "gpu+cpu" (default)
+r.concurrency                                  # "gpu+cpu" if Metal came up, else "cpu"
+r.cluster_canonicals(corpus, 0.6)              # GPU-accelerated (~1.1–1.4× on Apple Silicon)
+r.ratio_many(pairs)                            # CPU (the GPU offload loses here)
+```
+
+On Linux/Windows wheels, or with no Metal device, a `Rationer` transparently runs everything on CPU.
+Build a GPU wheel locally on macOS with
+`maturin develop --release --features python,gpu` (the CLI `--features` **replaces** the pyproject
+default, so list both).
+
 ---
 
 ## How it works
 
@@ -22,7 +22,8 @@ per second. Speedups (`Nx`) are **difflib-fast ÷ competitor**.
 
 - **Metric:** exact RO, `autojunk=False`. Every "exact RO" comparison below is **byte-for-byte
   verified** against difflib-fast (mismatch counts / max|Δ| reported per section).
-- **Harnesses** (all in [`benchmarks/`](benchmarks/), driver: [`run_all.sh`](benchmarks/run_all.sh)):
+- **Harnesses** (in [`benchmarks/`](benchmarks/); the `run_all.sh` / `profile.sh` runners are local
+  perf tooling, not tracked):
   - `cargo run --release --features bench --bin bench` — difflib-fast self (raw / threshold / cluster).
   - `cargo run --release --example compare` — vs the Rust crates `difflib` + `gestalt_ratio`.
   - `bench_vs_cydifflib.py` — vs CyDifflib, single thread.
@@ -55,6 +56,36 @@ code has unusually long functions, and per-pair RO is `O(L·log L)`.)
 
 ---
 
+## 1b. GPU (Metal) — heterogeneous `cluster_canonicals`
+
+Behind the `gpu` feature on Apple Silicon, `Rationer::cluster_canonicals` runs the suffix-automaton
+`matching_stats` walk on the M3 GPU (Metal compute) while the CPU keeps the filters + `longest_in`
+recursion + assembly. **Byte-for-byte identical** to the CPU path (cluster counts equal across all
+backends, every run). Measured via the `Rationer` API across its three `Concurrency` backends, one
+group, threshold 0.6, N=1500, M3 Pro, best-of-2:
+
+| corpus | CPU | GPU | GPU+CPU | GPU speedup |
+|---|---|---|---|---|
+| mypy | 2.25 s | 1.62 s | 1.63 s | **1.38×** |
+| ha | 2.64 s | 2.10 s | 2.13 s | **1.25×** |
+| sympy | 1.57 s | 1.34 s | 1.31 s | **1.17×** |
+| django | 1.09 s | 0.95 s | 0.98 s | **1.14×** |
+| transformers | 2.69 s | 2.49 s | 2.35 s | **1.08×** |
+
+**Honest read.** The GPU only offloads `matching_stats` — ~⅓ of the per-pair cycle budget; the
+`longest_in` chain walk (the dominant cost), the `quick_ratio` filters, the SAM build and the
+union-find assembly all stay on CPU. By Amdahl that caps the end-to-end win even before the
+fixed per-dispatch overhead, so cluster lands at **1.1–1.4×** and does *not* scale up with N
+(at N≈2200 the single dispatch's `(fstate, fmatch)` output buffer grows and goes bandwidth-bound,
+dropping back toward ~1.15×). The other two operations measured **slower** on the GPU at every size
+tried — `ratio_many` 0.82–0.93× (61k–404k pairs; the CPU intern + prebuilt-SAM path is already
+efficient) and `cluster_canonicals_multi` 0.59–0.99× (the find-dup-defs many-small-groups shape never
+amortizes the dispatch) — so both stay on CPU by default (GPU opt-in via `DFGPU_RATIO_MANY_THRESHOLD`
+/ `DFGPU_MULTI_THRESHOLD`). A widely-quoted "1.5–1.7×" is a *kernel-only* `matching_stats` microbench
+(the kernel itself is ~3× CPU throughput); it does not survive end-to-end.
+
+---
+
 ## 2. vs CyDifflib (Python) — the fast byte-for-byte Cython difflib
 
 [CyDifflib](https://github.com/rapidfuzz/CyDifflib) (by the RapidFuzz author) is the fastest existing