Fix unaligned distance metadata loads [MOD-15303]

[dor-forer]

Summary

• load SQ8, INT8, and UINT8 trailing FP32 metadata through alignment-safe helpers in scalar and SIMD kernels
• make integer normalization and test/reference metadata access alignment-safe
• repair the SQ8-FP32 benchmark's storage/query argument order and array teardown
• add explicit odd-dimension SQ8-FP32 regression coverage

Root cause

Trailing FP32 metadata follows byte-width vector payloads. For dimensions not divisible by four, casting payload + dimension to float * creates a misaligned pointer and undefined behavior. The SQ8-FP32 benchmark also supplied its FP32 query and SQ8 storage in reverse order, producing an out-of-bounds read.

Impact

Odd-dimensional SQ8/SQ8-FP32 and INT8/UINT8 cosine distance calculations no longer rely on misaligned FP32 loads, including dispatched SIMD implementations and strict-alignment architectures.

Validation

• ./check-format.sh
• alignment/undefined sanitizer: 520 SQ8/SQ8-FP32/INT8/UINT8 distance tests
• alignment/undefined sanitizer: affected component, INT8, UINT8, and index utility tests
• AddressSanitizer + undefined sanitizer: SQ8-FP32 dimension-100 benchmark matrix (available AVX2-FMA, AVX2, SSE4, and scalar paths)

Deterministic alignment regression proof

Built the regression test with Clang 18.1.8 and fatal AddressSanitizer/alignment sanitization:

• PR c724d32b: exited 0; SpacesTest.SQ8_FP32_odd_dim_unaligned_metadata_test passed.
• Main dd6879e8, with only the test and safe reference-helper changes applied: exited 1.
• UBSan reported the old production load in SQ8_FP32_InnerProduct_Impl:

src/VecSim/spaces/IP/IP.cpp:61:27:
runtime error: load of misaligned address 0x503000025691
for type 'const float', which requires 4 byte alignment

The forced address ends in ...691, proving it is not four-byte aligned. The sanitizer stack traces the failure from SQ8_FP32_InnerProduct_Impl directly to the odd-dimension regression test.

Jira: MOD-15303

---

Note

Medium Risk
Touches hot-path distance math across many SIMD backends; behavior should be equivalent but incorrect offset math would skew all SQ8/integer cosine results for affected dimensions.

Overview
Fixes undefined behavior when VecSim reads trailing FP32 metadata (SQ8 min/delta/sum, INT8/UINT8 cosine norms) after byte-sized payloads: odd dimensions leave metadata at addresses that are not 4-byte aligned, so reinterpret_cast<const float *> loads were unsafe.

Scalar and SIMD inner product / L2 paths for SQ8↔FP32, SQ8↔SQ8, and INT8/UINT8 cosine now use load_unaligned with byte offsets (sq8::* * sizeof(float)). Integer normalization writes the stored norm via memcpy instead of a misaligned float store. Reference helpers, unit tests, and the SQ8-FP32 benchmark follow the same pattern; the benchmark also swaps storage vs query to match API argument order and fixes delete[].

Adds SQ8_FP32_odd_dim_unaligned_metadata_test to exercise deliberately misaligned storage blobs against scalar and dispatched kernels.

^{Reviewed by Cursor Bugbot for commit c724d32. Bugbot is set up for automated code reviews on this repo. Configure here.}

[dor-forer]

@GuyAv46 @ofiryanai

Performance benchmark results

I compared PR #1001 against its exact base:

• Baseline: dd6879e82d9d0167d5b2403b9356372c10732edd
• PR Fix unaligned distance metadata loads [MOD-15303] #1001: c724d32bc1e68c33e680bbe566bd9e1c1e38ad3a

Summary

I found no meaningful alignment-specific performance regression.

The important comparison is:

• Aligned dimensions: 0.63% slower
• Unaligned dimensions: 0.52% slower

Unaligned dimensions were therefore not affected more than the aligned controls.

The benchmark covered every modulo-4 remainder—not only odd dimensions—because the unaligned condition is dimension % 4 != 0.

Main results

Group	Cases	PR versus baseline	95% confidence interval
All affected kernels	101	0.57% slower	0.22% to 2.46% slower
Aligned controls (dim % 4 == 0)	42	0.63% slower	0.44% to 1.77% slower
Unaligned (dim % 4 != 0)	59	0.52% slower	0.01% to 2.94% slower
Remainder 1	17	0.52% slower	0.20% to 3.53% slower
Remainder 2	17	0.65% slower	0.07% to 3.50% slower
Remainder 3	25	0.43% slower	0.11% faster to 2.28% slower

The small overall difference appears in both aligned and unaligned cases. There is no indication that the safe unaligned metadata load added measurable overhead.

Outlier follow-up

The first pass showed several apparent 4–5% SSE4 slowdowns. I ran eight additional alternating baseline/PR pairs covering those cases and related controls.

Combined across 14 launches per revision:

Targeted group	Result	95% confidence interval
All 20 targeted cases	0.11% faster	1.37% faster to 1.39% slower
Aligned targeted controls	0.12% faster	1.30% faster to 0.32% slower
Unaligned targeted cases	0.10% faster	1.42% faster to 1.96% slower
SSE4 SQ8-to-FP32	0.21% faster	0.61% faster to 1.83% slower

The initial SSE4 slowdowns did not reproduce.

Two tiny scalar SQ8-to-SQ8 functions moved in opposite directions: L2 was approximately 3.4% slower, while inner product was approximately 3.4% faster. Their combined result was 0.06% faster.

This occurred identically for aligned and unaligned dimensions. Disassembly showed linked code-placement and instruction-scheduling differences, consistent with tiny-function layout sensitivity rather than alignment-dependent overhead.

Benchmark details

• Direct distance-kernel microbenchmarks, not HNSW query benchmarks
• SQ8-to-FP32, SQ8-to-SQ8, INT8, and UINT8 paths
• AVX-512 VNNI, AVX2 FMA, AVX2, SSE4, and scalar implementations where applicable
• Dimensions 256, 513, 514, and 515, 516, plus scalar controls
• Six broad alternating measured rounds
• Eight additional alternating outlier-follow-up rounds
• Every process pinned to the same physical CPU
• 100,000 execution-order-stratified paired bootstrap resamples

PR #1001 also fixes the SQ8-to-FP32 benchmark harness. I applied only that harness correction to the baseline so that both revisions used byte-identical benchmark code. The baseline production distance code remained exactly at the base commit.

Conclusion

• No alignment-specific regression was found.
• No modulo-4 remainder was worse than the aligned controls.
• No slowdown above 5% reproduced.
• The initial SSE4 outliers disappeared in the follow-up.

I do not see a performance reason to block PR #1001.

Full methodology, environment details, per-case results, and raw JSON are available in Jira:

MOD-15303 benchmark results