> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bensevern.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Native acceleration

> GoldenMatch's optional compiled Rust/Arrow runtime — which components run native, the `GOLDENMATCH_NATIVE` gate, and how parity is enforced. Generated from the native loader; do not edit by hand.

GoldenMatch is pure-Python by default. An optional compiled kernel (Rust + PyO3/Arrow, crate `packages/rust/extensions/native`) accelerates the CPU-heavy components below. Under reference-mode the compiled path is the reference implementation and pure-Python is the byte-identical fallback — output is the same either way; native only changes wall-clock.

```bash theme={null}
pip install goldenmatch[native]
```

## The gate

One env var, `GOLDENMATCH_NATIVE`, read in `goldenmatch/goldenmatch/core/_native_loader.py`:

* `GOLDENMATCH_NATIVE=auto` (default, or unset) — run native for any component whose kernel symbol is present on the loaded wheel, except the known-divergent components below.
* `GOLDENMATCH_NATIVE=0` — force the pure-Python fallback everywhere.
* `GOLDENMATCH_NATIVE=1` — require native; raise if the kernel isn't importable (the CI parity lane).

The kernel is discovered two ways, in order: the in-tree build `goldenmatch._native` (local dev / parity lane), then the distributed `goldenmatch_native._native` wheel (`pip install goldenmatch[native]`). When neither is importable, every path runs pure-Python unchanged.

The Fellegi-Sunter block-scoring path has its own gate, `GOLDENMATCH_FS_NATIVE` (default-on; the Rust rapidfuzz path is the reference, `=0` forces the pure-Python fallback).

## Components

Each component maps to the native kernel symbol(s) its `auto` call site invokes (the *floor* symbol first — a component is native-capable when **any** listed symbol is present, so an older wheel stays wheel-skew safe). A ✓ in **Parity-signed** marks a component that cleared the byte-exact sign-off recorded in `_GATED_ON`.

| Component       | Kernel symbol(s)                                                                                                                                                                                                                                                   | Parity-signed |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `clustering`    | `connected_components`, `mst_split_components`                                                                                                                                                                                                                     | ✓             |
| `block_scoring` | `score_block_pairs_arrow`                                                                                                                                                                                                                                          | ✓             |
| `pairs`         | `canonicalize_pairs`, `dedup_pairs_max_score`                                                                                                                                                                                                                      | ✓             |
| `featurize`     | `char_ngram_features`                                                                                                                                                                                                                                              | ✓             |
| `hashing`       | `record_fingerprint`, `record_fingerprints_batch`                                                                                                                                                                                                                  | ✓             |
| `field_scoring` | `score_field_matrix`                                                                                                                                                                                                                                               | ✓             |
| `autoconfig`    | `autoconfig_decide_plan`                                                                                                                                                                                                                                           | ✓             |
| `sketch`        | `sketch_simhash_band_hashes_batch`                                                                                                                                                                                                                                 | ✓             |
| `simhash`       | `sketch_simhash_band_hashes_batch`                                                                                                                                                                                                                                 |               |
| `pprl_bloom`    | `bloom_clk_batch`                                                                                                                                                                                                                                                  |               |
| `perceptual`    | `perceptual_phash_image`                                                                                                                                                                                                                                           |               |
| `documents`     | `documents_parse_message_text`, `documents_schema_validate`, `documents_extract_instruction`, `documents_normalize_record`, `documents_template`, `documents_template_list`, `documents_classify_prompt`, `documents_parse_classify`, `documents_parse_structured` |               |
| `sail_scoring`  | `score_field_pairwise`                                                                                                                                                                                                                                             |               |
| `fs_em`         | `train_em_from_counts_native`, `estimate_u_from_counts_native`                                                                                                                                                                                                     |               |

## How parity stays honest

A component joins the native path only after a parity test proves its kernel is byte-identical (or integer-exact) to the pure-Python reference. CI runs a `GOLDENMATCH_NATIVE=1` lane that builds the wheel and asserts native == pure-Python, and `scripts/check_native_symbols.py` reconciles the host's kernel references against the crate's `wrap_pyfunction!` exports so a referenced-but-unregistered symbol fails loudly. Because output is identical with or without the wheel, toggling the gate never changes a result — only speed.