# Optional native CPU contributions

Install `pipewhy[cpu]` for NumPy/Numba CPU compilation; development uses
`poetry sync --extras cpu`. The core/reference installation needs neither dependency.
`pipewhy.fingerprint.cpu.record_contributions(words, offsets, lengths, context)`
accepts flat uint64 C2 record buffers and returns four digest limbs per record in
input order. Ordered mode accepts the original global `start` position. Validation
finishes before native entry, and missing extras or compilation failures raise errors.

`fingerprint_batch` accepts the same buffers and returns a counted `FingerprintState`
using fused native hashing/accumulation with a constant-size serial workspace.
Set `partitions` above one for parallel work with private partition states and a
deterministic reduction; the count is capped at the number of records. Numba's
thread configuration controls the worker pool. `cpu.merge`
combines compatible partition states with native limb carries and checked counts.
Ordered partitions must be adjacent at their original offsets.

The first call includes compilation time. Inputs must stay stable during execution;
unaligned word storage may be copied. Native digest parity is tested separately from
Coverage.py's Python execution measurement. Performance qualification remains in
development.
See [blueprint/CPU_CONTRACT.txt](../development/architecture.rst) for the boundary and remaining qualification gates.

`cpu.fingerprint_batches` consumes an iterator of `cpu.RecordBatch` values containing
the profile ID and three flat buffers. It hashes one batch before requesting the
next, preserving global ordered positions. Defaults cap each supplied batch at
65,536 records and 1,048,576 words (8 MiB); oversized batches raise an error. Producers
can configure those positive limits and yield smaller batches. A failed later batch
or source iterator stops processing without returning a successful partial result.