Module hypervector 

Vector Symbolic Architecture (VSA) primitives - bind + bundle on 10K-dim binary hypervectors. The same Programs serve retrieval, reasoning, and content-addressable Program fingerprint compositions. Vector Symbolic Architecture (VSA) primitives - bind + bundle on high-dimensional binary hypervectors.

VSAs (Plate 1995, Kanerva 2009) compute over 10K-dim ±1 / 0/1 hypervectors using two operations: binding (associates two vectors into a key-value pair) and bundling (superposes a set of vectors into a single representative). Recent ML work (Schlegel 2022, Hersche 2023) shows VSA + transformers > transformers alone on systematic-generalization benchmarks.

This file ships the binary spatter code (BSC) variant: each hypervector is a u32 bitset, binding is bitwise XOR, bundling is per-bit majority vote. Already GPU-trivial; the gravity gap is that no one has packaged it as a Tier-2.5 primitive.

Why this primitive is dual-use

Composition role	Use
retrieval	structured key-value lookup
symbolic reasoning	compositional symbol algebra
program fingerprints	bind op-kind, buffer signature, and region shape into one hypervector so semantically-equivalent regions can share cache entries even when byte-equal hashing misses

Operations

• hypervector_xor_bind(a, b, out, dim_words) - bitwise XOR. Each output word is a[i] ^ b[i]. XOR is its own inverse, so xor_bind(xor_bind(a, b), b) == a (unbinding by re-binding with the same key).
• hypervector_majority_bundle(stacked, out, dim_words, k) - per-bit majority over k stacked hypervectors. For each bit position, output bit = 1 iff > k/2 input bits are 1. Ties (k even, exactly k/2) round to 0 (callers typically use odd k).

Constants

BIND_OP_ID

Canonical op id for the binding primitive.

BUNDLE_OP_ID

Canonical op id for the bundling primitive.

STANDARD_DIM_BITS

Standard BSC hypervector dimensionality (in bits). 10240 bits = 320 u32 words. Plate / Kanerva established that dimensions in the 10K range give negligible chance-binding noise for practical vocabularies up to ~10⁶ items.

STANDARD_DIM_WORDS

Standard hypervector size in u32 words.

Functions

hamming_similarity

Cosine-style similarity over BSC hypervectors: 1 - 2 · hamming(a, b) / dim_bits. Returns f32 in roughly [-1, 1] (perfect match = 1.0, anti- correlation = -1.0, random = 0.0).

hypervector_majority_bundle

Emit per-bit majority vote over k hypervectors stacked row-major in stacked (size k * dim_words).

hypervector_xor_bind

Emit outw = aw ^ bw`` for each of dim_words lanes.

majority_bundle_cpu

CPU reference for hypervector_majority_bundle.

majority_bundle_cpu_into

CPU reference for hypervector_majority_bundle using a caller-owned buffer.

try_majority_bundle_cpu_into

Fallible CPU reference for hypervector_majority_bundle using a caller-owned buffer.

try_xor_bind_cpu_into

Fallible CPU reference for hypervector_xor_bind using a caller-owned buffer.

xor_bind_cpu

CPU reference for hypervector_xor_bind.

xor_bind_cpu_into

CPU reference for hypervector_xor_bind using a caller-owned buffer.