PipeWhy Fingerprint Contract C3 version 1.0
October 30, 2026

PW-04.01 Threat model (D3)
User-selected first release scope: accidental drift and corruption detection.
Equality is probabilistic evidence under compatible metadata, never absolute proof
of equality, provenance, authorization or absence of malicious modification.
Tamper-resistant verification needs a separate reviewed protocol and algorithm ID.

PW-04.02 Candidate selection (D4)
Select blake2b-sum256-v1 as an experimental reference: complete-record BLAKE2b
digests with digest_size=32, summed modulo 2**256 with an exact uint64 record count.
Use Python hashlib.blake2b; do not truncate a BLAKE2b-512 digest to obtain BLAKE2b-256.
No runtime dependency is added. This is a scalar correctness baseline; native CPU
and CUDA implementations must later reproduce the exact bytes and metadata.

Alternatives considered: XOR loses duplicate multiplicity without further state;
sorted whole-dataset hashing needs retained sorting and lacks compact partition
addition; an original word mixer needs additional analysis and independent review.
The chosen aggregate is a PipeWhy composition of a standard primitive, not a
standardized cryptographic multiset hash or an authenticated integrity protocol.

PW-04.03 State layout
Metadata contains full algorithm, normalization-profile and source-schema identities
plus mode (multiset or ordered). Profile/schema identities are 32-byte lowercase
SHA-256 hex strings. Schema identity must cover selected field IDs, source types,
widths, exclusions and declared source schema semantics. The caller supplies that
identity; hashing records cannot discover omitted schema metadata.

State wire words are eight little-endian uint64 values:
[state_version=1, mode_code, start, count, sum_limb0, sum_limb1, sum_limb2, sum_limb3].
Mode codes: 0 multiset, 1 ordered. Limbs are least-significant first. Multiset start
is UINT64_MAX sentinel; ordered start is a global record offset. Count never wraps:
0 <= count <= UINT64_MAX. Ordered end=start+count must be <= UINT64_MAX. Empty
state has count=0 and sum=0; ordered empties retain their insertion offset.
Eight words alone are not a complete observation: retain and validate metadata.

PW-04.04 Exact mixing and arithmetic
ALGORITHM_DESCRIPTOR is these ASCII bytes, including embedded NULs:
b"pipewhy.fingerprint\0blake2b-sum256-v1\0wire=1\0record=c2-v1\0digest=32\0sum=mod2^256\0count=uint64\0ordered=global-position".
Algorithm identity is SHA-256(ALGORITHM_DESCRIPTOR), full lowercase hex.
Context header H is ALGORITHM_DESCRIPTOR followed by a NUL, 32 raw profile-ID
bytes, 32 raw schema-ID bytes and one mode-code byte. Context identity is SHA-256(H).

A record contribution uses a fresh hashlib.blake2b(digest_size=32,
person=b"PipeWhyRecordV1") with no key, salt or tree options. Feed H; then, for
ordered mode only, the record position as eight little-endian bytes; then all C2
record words as eight-byte little-endian unsigned integers. Interpret the 32 digest
bytes as one little-endian uint256 integer. All input words and positions are
validated before returning a contribution. There is no host-endian dependency.

Add digest integers modulo 2**256. Reduction applies to the complete uint256 sum,
not independently to four uint64 lanes; carries cross limb boundaries. Counts and
positions use exact integer arithmetic and raise on overflow instead of wrapping.

PW-04.05 Domains and compatibility
C2 carries scalar type, field ID, payload length and record framing. C3 H binds
algorithm, full profile identity, schema and container order mode. Personalization
separates record digests from other BLAKE2b uses. Unknown state versions/modes,
different contexts and mismatched record profiles fail visibly, never coerce or
compare as equal. An explicitly versioned future algorithm needs new metadata.

PW-04.06 Record contribution
Hash a whole C2 record before dataset accumulation, preserving field/row association.
Validate C2 wire/domain header, uint64 buffer type, ordered unique non-sentinel field
IDs, supported type tags, exact field count, payload boundaries and no trailing words.
Canonical scalar semantics are produced by C2 normalization, not decoded again in
C3. A complete record is the atomic contribution; never accumulate columns separately.

PW-04.07 Unordered combination
State addition combines counts exactly and sums modulo 2**256 under an identical
context. The empty multiset is the identity. Input record order and partition shape
cannot affect the result. Repeated records are repeated additions and increments;
the count distinguishes different cardinalities even when modular sums coincide.
This does not establish collision freedom for equal-cardinality multisets.

PW-04.08 Ordered contributions
Ordered positions are global offsets, independent of batch boundaries. A partition
starting at s uses positions s, s+1, ...; valid record positions are < UINT64_MAX.
Ordered merge requires left.start+left.count == right.start. Reject gaps, overlaps
and reversed ranges. Start and count remain part of the comparison identity. A
zero-length partition is an identity only at the adjacent insertion offset.
Changing order changes the hashed position/record pair; no collision-free guarantee
is implied. Ordered records must be repartitioned with original global positions.

PW-04.09 Removal
Multiset subtraction supports a caller-known contained submultiset, with matching
context and non-underflowing count; subtract sums modulo 2**256. Ordered removal
supports only a known contiguous suffix at the original global positions, retaining
the prefix's start. Reject interior/remapped/prefix removals; re-encode/recompute
when renumbering positions. Removal cannot prove membership from compact state.
The caller must retain authoritative source/update evidence; count/range checks are
necessary checks, not authentication. Zero residual count requires zero residual sum.

PW-04.10 Versioning and verification
Algorithm name/descriptor, state version and context identity are stable contract
inputs. Arithmetic, framing, digest parameters or order semantics changes require
a new algorithm identity. Schema/profile changes require a new context. Never
silently compare old/new contexts; the comparison layer reports INCOMPARABLE.
Golden fixtures contain complete metadata and decimal-string uint64 words.

Verification uses independent byte framing plus published BLAKE2 vectors, exact
integer arithmetic vectors, whole-record association swaps, duplicate/partition/
order/removal invariants and seeded update sequences. Native CPU/CUDA agreement
and installed-package checks remain separate evidence. Production suitability and
quantitative collision requirements remain review items in PW-04.21/.22. Passing
tests do not prove random-oracle behavior, a collision probability or security.

Primary primitive references:
https://www.rfc-editor.org/rfc/rfc7693.html
https://docs.python.org/3.14/library/hashlib.html#blake2
The RFC describes BLAKE2, not PipeWhy's additive aggregate. Python documents the
digest-size and personalization API. Neither is a proof about this aggregate.

PW-04.21 Collision limitations and implementation evidence
The digest sum has 256 bits plus an exact count; its limbs are one integer, not four
independent hashes. A finite state cannot distinguish every possible equal-count
dataset. Count detects cardinality differences, but it does not eliminate collisions
between different contents of the same cardinality. Modular addition also exposes
algebraic structure; the aggregate does not inherit a cryptographic multiset security
proof merely because individual contributions use BLAKE2b.

No numeric false-equality probability, collision-free claim, randomness assumption,
adversarial work factor or authentication guarantee is established. Known-member
removal cannot validate provenance or membership, and corrupted metadata can relabel
an otherwise well-formed state. Stored-byte checksums serve a separate corruption
boundary; trusted publication/authentication belongs to a separate protocol.

Evidence: portable record/dataset/arithmetic vectors, RFC7693 primitive vector,
independent byte-framing oracle, all multiset permutations of a duplicate-containing
fixture, cross-row association swaps, sequential/balanced partition trees, global
ordered offsets and 32 seeded mode/profile update sequences (60 updates each).
tests/unit/test_fingerprint_differential.py also consumes the C2 golden records,
completing the normalization-to-fingerprint consumer handoff. These checks would
catch plausible framing/arithmetic/state-update regressions. They are not collision
searches at meaningful security scale or a mathematical suitability proof.

PW-04.22 Suitability review record
Engineering review accepts this version as an experimental scalar reference for
the user-selected accidental-drift/corruption scope. Reviewed context boundaries,
wire framing, endian behavior, uint256 carry/borrow, count/range overflow, partition
composition, strict/logical isolation, ordered suffix restrictions and explicit
errors. No new runtime dependencies or source-authentication claims were introduced.

Independent mathematical/security review and quantitative production collision
requirements are UNRESOLVED. There is no external reviewer sign-off. Native CPU,
CUDA, realistic-scale performance and source/storage end-to-end qualification are
separate downstream tasks. Production release review must retain these limitations
and assess suitability for the actual workload; no completed reference subtask may
be cited as external production approval. PW-16 release evidence must carry this
review status until those requirements are explicitly resolved.
