nx_cosine_similarity.nx

nx_cosine_similarity.nx -- signed Q10 cosine between two vectors. Universal vector-space similarity. Same primitive over any nx_int feature vectors of equal length: image-feature embeddings (for the "AI grows by ingesting image" textual-inversion roadmap), audio MFCC frames, token frequency histograms, latent embeddings, document term vectors, code AST-bag features. Math: cos(theta) = dot(a, b) / (||a|| * ||b||) dot(a, b) = sum a[i] * b[i] ||a|| = sqrt(dot(a, a)) All math nx_int. Newton-Raphson integer sqrt (O(log n) iterations, no f64). Output signed Q10 in [-Q, +Q]: +Q = parallel (same direction) 0 = orthogonal -Q = anti-parallel (opposite direction) Sealed-enum bands (substrate dual-reading cardinal): NX_COSINE_BAND_ANTIPARALLEL cos <= -921 (essentially -1) NX_COSINE_BAND_OPPOSED cos < -307 NX_COSINE_BAND_ORTHOGONAL -307 <= cos <= +307 NX_COSINE_BAND_ALIGNED cos > +307 NX_COSINE_BAND_PARALLEL cos >= +921 USE CASES (image-gen + general): - concept-embedding lookup: incoming "new outfit" image -> feature vector -> nearest concept in nishi-library concept store. - prompt similarity over learned embeddings (next layer above string-similarity). - clustering: pairwise cosine grid + hierarchical merge. - recommendation: user-liked-image features cosine-compared against gallery features. EDGE CASES: - empty vectors (n == 0) -> return 0 (orthogonal-by-vacuum) - zero vector (norm == 0) -> return 0 (cosine undefined) - length mismatch -> NX_COSINE_LENGTH_MISMATCH sentinel