nx_token_merge.nx

nx_token_merge.nx -- H8 token merging plan (bits-up). Per NISHI_ELDER_AI_OFF_DOCKER_2026_05_20.md §2.1 H8: token merging (ToMe, Bolya 2022 "Token Merging: Your ViT But Faster") shortens the attention sequence by merging the top-K most similar token pairs at layer boundaries. Used in ViT and Stable Diffusion to drop 30-50% of tokens with minimal quality loss. Linear-time savings: shrinking seq from N to N*(1-r) at every L layers cuts overall attention FLOPs ~(1-r)^L. V1 mechanics: substrate primitive does NOT compute the similarity matrix. It accepts a pre-computed array of (left_idx, right_idx, score_q16) triples sorted by descending score, and a target_merges count. It greedily walks the sorted list, merging each pair where BOTH tokens are still "kept" (no prior merge), until target_merges is reached or the list is exhausted. Returns the actual merges executed (which can be less than requested if not enough non-conflicting pairs were available). Composition path: - Consumer kernel computes cosine sim between adjacent tokens (substrate Q16-mul + dot product primitives) - Consumer sorts the resulting (i, j, score) triples by score desc using shipped nx_mergesort - nx_token_merge_apply(plan, sorted_pairs, n_pairs, target) populates the assignment table - Downstream attention layer reads target_for(idx) to know which slot each token routes to; merged tokens are dropped from the active sequence Pure substrate logic. No Linux features. Composes with shipped nx_mergesort (consumer-side sort dependency). V1 honest scope: - Caller pre-sorts; substrate does NOT sort internally (would duplicate nx_mergesort and force a bigger primitive) - Greedy merge (top-down) -- the published ToMe paper proves this matches bipartite matching within a fraction of a percent on real model quality, at half the implementation