Skip to content

feat(proximity): add native TurboQuant accelerator - #112

Merged
forhappy merged 96 commits into
mainfrom
feat/native-turboquant-proximity
Sep 13, 2026
Merged

feat(proximity): add native TurboQuant accelerator#112
forhappy merged 96 commits into
mainfrom
feat/native-turboquant-proximity

Conversation

@forhappy

@forhappy forhappy commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add an independently implemented native TurboQuant-MSE proximity accelerator with deterministic structured rotation, canonical 2/3/4-bit encoding, exact authoritative reranking, sync/async execution, proofs, content walking/copy/GC, bounded caches, and all maintained language bindings.
  • Keep Auto disabled and expose TurboQuant only through explicit backend selection while mandatory release gates remain open.
  • Correct L2, cosine, and inner-product reconstruction-norm scoring and fuse dot/norm accumulation into one packed-code traversal.
  • Correct the qualification harness to use an authoritative exact ProximityMap search over persisted canonical vectors. Benchmark schema 4 rejects all older recall evidence.

Correctness and verification

Passed locally:

  • cargo fmt --all -- --check
  • git diff --check
  • cargo clippy --all-targets --all-features -- -D warnings
  • complete all-feature Rust suite and 74 doctests
  • 23 TurboQuant integration tests and 24 focused algorithm tests
  • 17 qualification runner/summarizer tests
  • bounded decode/lifecycle fuzz smoke, WASM/browser-WASM, Miri, and maintained binding suites
  • schema-4 exact-resume and digest validation for all eleven retained cells

Schema-4 evidence

Eleven focused cells at implementation revision 729c2ffa cover 10K/100K × 768, all metrics at four bits and 8× reranking, matching 16× cosine/product diagnostics, and exhaustive 10K cosine.

Records Metric TQ recall 8× PQ recall 8× TQ/PQ p95
10K L2 squared 1.00 1.00 6.23×
10K Cosine 0.00 1.00 2.90×
10K Inner product 1.00 0.00 8.01×
100K L2 squared 1.00 0.00 9.54×
100K Cosine 0.00 0.00 7.36×
100K Inner product 0.00 0.00 9.48×

Exhaustive 10K cosine returns 1.00 recall for both implementations. A qualification-scale Rust regression proves the default failure is unavoidable under the frozen contract: the authoritative exact top 10 all share one packed code with 222 lower-key records, while the shortlist cap is 80 and ties order by key. The approved 16× window still returns 0.00 at 10K; 100K cosine and inner product reach 1.00 at 16×.

TurboQuant builds faster than PQ in every sampled row, but search and sidecar-size gates fail. Full details and raw artifacts are in the schema-4 report.

Release status

This PR remains a draft. Open gates are:

  • approved resolution for the incompatible 10K cosine packed-code/shortlist contract
  • complete 45,360-cell single-revision matrix
  • pinned-host qualification
  • repository-wide binding inventory with 2,998 pre-existing incomplete mappings
  • legal/patent release disposition

The feature-specific proximity and fuzz checks pass. Current unrelated DynamoDB/S3 workflow failures are inherited repository issues and are not hidden by this PR.

@forhappy

Copy link
Copy Markdown
Contributor Author

Qualification update (0d1b3a9): fixed the cross-target conformance failure by replacing host-libm-generated fixture inputs with frozen IEEE-754 bit inputs; added an independent dense Gaussian-QR development oracle with retained 128/200/768/1536/3072 × 2/3/4-bit distortion and recall evidence; and added ordinal fault injection over every discovered TurboQuant publication, cold verification, forced search/rerank, and proof/closure store boundary. Focused tests and warnings-denied Clippy pass locally. Auto remains intentionally disabled and production-scale qualification/legal gates remain open.

@forhappy

Copy link
Copy Markdown
Contributor Author

Retained qualification update (379463d): corrected accelerator sidecar accounting to exclude referenced authoritative source objects; regenerated the 1K × five-dimension × three-metric default-path runs from committed harness revision d734772; and checked in the raw CSVs plus a bounded-tier report. All 15 TurboQuant recall@10 rows are 1.0 and match PQ, but TurboQuant search and derived size are worse on this fixture, so Auto remains disabled. Production-scale, cross-host/release-command, and legal gates remain open.

@forhappy

Copy link
Copy Markdown
Contributor Author

Performance and conformance update: 60dfaa7 replaces per-coordinate generic unpacking with canonical width-specialized 2/3/4-bit decoding. On the retained 1K L2 arm64 tier, scalar scan improved about 33–44% across dimensions (36–37% at 768/1536) with unchanged 1.0 recall. c701192 refreshes the raw evidence, and e3cd7df adds a browser-WASM test that reproduces the checked-in Rust descriptor and TurboQuant manifest CIDs. Auto remains disabled because current scan/size results still do not meet its comparative gates.

@forhappy
forhappy marked this pull request as ready for review September 12, 2026 23:52
@forhappy
forhappy merged commit 6ee959e into main Sep 13, 2026
32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant