compat: cross-backend determinism and score-equivalence contract #127

Summary

Document and test the determinism contract across scalar/SIMD backends and architectures.

This is an ecosystem compatibility issue. Host systems should know whether backend choice can affect scores, ordering, and ties. ordvec should be a good neighbor by making that contract explicit while staying a primitive scoring library.

Current gap

The code has deterministic tie-breaking in important paths, but there is no single compatibility document or fixture suite stating what is guaranteed across scalar, AVX2, AVX-512, NEON, wasm SIMD, serial, and parallel execution.

Proposed scope

• Add docs/determinism.md.
• Add small deterministic fixtures with tie-heavy corpora and fixed expected results.
• Add backend-forcing test hooks where practical.
• State bit-exact vs tolerance-based expectations per primitive.
• Scope RankQuantFastscan separately if its stability level differs.

Acceptance criteria

• Docs state ordering, score, and tie-break guarantees per public search primitive.
• Golden tests assert top-k ordering and sentinel behavior on fixed corpora.
• CI covers scalar plus at least one SIMD path where available.
• Parallel and serial modes produce identical ordering where both are supported.
• Any intentional golden-output change requires a compatibility note.

Non-goals

• No distributed consistency layer.
• No replication protocol.
• No claim that all hardware has identical latency.