PipeWhy CPU Kernel Contract CPU-1 version 1.0
October 30, 2026 | PW-05.01

CPU-1 refines C1-C3 and C7's CPU buffer requirements. It does not replace C7,
which remains the architectural contract for views, queries and exports.

The first compiled CPU engine implements exactly experimental C3
blake2b-sum256-v1. It introduces no replacement hash or normalization semantics.
Its purpose is accidental drift/corruption detection; C3 suitability limitations
and unresolved independent production collision review remain unchanged.

Inputs are C1 native little-endian, one-dimensional contiguous uint64 buffers:
one C2 word pool plus aligned uint64 record offsets and lengths. Each slice contains
one complete C2 record under the explicit FingerprintContext. Input buffers remain
stable during a call. No object dtype, DataFrame, nested record graph or per-value
Python object is part of the kernel boundary. CPU byte-safe unaligned buffers may
be copied into aligned temporary storage; zero-copy/SIMD alignment is not promised.
The dispatcher validates dtype, lengths, nonoverflowing slice bounds, every C2
field frame/type/association, context and ordered start/count before native entry.
Canonical scalar payload semantics remain C2 producer responsibility, as in C3.

Kernel primitives implement unsigned uint64 rotation/mixing, BLAKE2b compression,
complete-record context/personalization framing, and four-limb uint256 addition
with carries. Digest limbs and accumulators are little-endian. The aggregate is
exact uint64 record count plus a sum modulo 2^256. Empty/duplicate/ordered records
and partition merges obey C3; an overflowing count is an error, never wraparound.
Ordered global positions cannot be reset at partition or batch boundaries.

Serial and parallel kernels use bounded flat workspaces. Parallel partitions write
only private states, then reduce deterministically with the same carry operator.
Worker count/chunking must not affect bits. Bounded batch processing consumes a
stream of validated flat batches without retaining the full source. Failure stops
the operation; no partial successful aggregate is returned after a bad batch.
Caller-owned writable aliases must not change while native work releases the GIL.

NumPy supplies typed views/temporary buffers; Numba supplies LLVM nopython JIT and
parallel scheduling. They are optional runtime dependencies in the cpu extra, not
mandatory core imports. Core installation, import and reference use work without
the extra. Requesting native CPU work without it raises an actionable ImportError;
compilation/runtime failures propagate rather than silently falling back to Python.
The first implementation targets the verified CPython 3.14 x86-64 Windows/Linux
matrix. Other platforms and free-threaded execution are not automatically qualified.
The selected compiler is Numba 0.68.1. CPU and CUDA extras both select NumPy 2.4.6
so the qualified Numba-CUDA plugin can share one environment. Earlier CPU evidence
used NumPy 2.5.4; that remains historical evidence, not the current package profile.
The complete CPU unit/native and installed-distribution checks are repeated after
this constraint change. Do not add a second numeric framework or dependency manager.

Qualification separates Python instrumentation and native correctness. Coverage.py
measures all owned Python without excluding kernel functions; executable Python
forms are tested against independent integer/BLAKE2 vectors. Real nopython compiled
signatures and native parity against hashlib/C3 are independently required. Native
instruction coverage is not measured by Coverage.py and must never be claimed as
95%. Thread/batch invariants, normalization golden fixtures and arithmetic boundary
tests remain required. Cold compilation, warm execution and process peak memory
are measured separately with environment/input sizes, without a speedup promise.

Packaging keeps both core-only isolated distribution checks and an installed cpu
extra smoke check. CI installs the cpu extra for native unit/integration qualification;
it must still validate wheel/sdist imports without NumPy/Numba in core-only runtimes.

Primary compatibility evidence (checked October 30, 2026):
https://numba.readthedocs.io/en/stable/user/installing.html#version-support-information
https://pypi.org/project/numba/0.68.1/
https://pypi.org/project/numpy/2.5.4/
CPython 3.14 Windows amd64 and Linux x86-64 wheels exist for both selected releases.

Implemented streaming boundary (PW-05.07):
pipewhy.fingerprint.cpu.RecordBatch contains profile_id, words, offsets and lengths;
the three buffers are uint64 C2 storage with the ownership rules above. Each batch
must declare the context's exact profile identity. fingerprint_batches consumes an
Iterable[RecordBatch] once, hashes one batch before requesting the next and returns
one C3 FingerprintState only after the source completes successfully. A bad later
batch, count/position overflow or source iterator error propagates; no partial
successful aggregate is returned. An empty stream has the C3 empty identity.

partitions defaults to 1 (serial); larger values run private parallel partitions
up to the actual batch record count. Numba controls its thread pool; this API does
not mutate the caller's thread mask. record_limit defaults to 65536 records and
word_limit to 1048576 uint64 words (8 MiB) per supplied batch. All limits must be
positive integers. Oversized batches fail explicitly so the producer can yield
smaller bounded batches; the engine does not collect/materialize the full source.
Limits include the whole supplied word pool, including unused words. Scratch space
is 41 uint64 words per active partition plus four-limb states and flat index arrays;
unaligned input buffers require aligned copies bounded by the accepted batch sizes.
Callers must bound their own producer buffering and respect input lifetime/stability.

Adapter/storage handoff (PW-05.15): separate integration tests reframe C4 captured
normalized value batches into flat C2 RecordBatch inputs, run native bounded streams,
assert exact reference states, publish/reopen C5 observation arrays and consume them
through C6. Baseline, mutation and failed-read variants retain expected SAME/CHANGED/
UNKNOWN states at two batch sizes. Failed reads do not become empty native successes.
The test producer is specific to C4's two-field fixture schema; it is not a generic
enterprise scan coordinator. CLI orchestration remains PW-12. Installed-extra smoke
checks exercise actual digest, parallel aggregation and cross-batch ordered streaming
from the wheel and sdist-rebuilt wheel in fresh runtime environments.

The canonical RecordBatch and C2 framing/batch validator now live in
pipewhy.normalize.batches. The cpu module preserves its RecordBatch import alias.
Both native dispatch and reference hashing consume this shared backend-neutral
validation; this relocation changes no C2 words, C3 framing or fingerprint algorithm.