• Add example/README.md for pub.dev's Example tab (it was empty). It walks through the core example — pairwise ops, top-k cosine search, and the binary round-trip — with its real output, and points at semantic_search.dart for the realistic-size version. Docs only.

• Add benchmark/quantization_benchmark.dart and a chart of what int8 quantization actually buys, measured on the same vectors: on 5,000 rows of 768 dimensions it holds the corpus in 3.7 MB instead of 14.6 MB (3.9x smaller) and keeps 99.3% of the float top-10, while search runs 4.1x slower because the byte rows cannot take the SIMD float path. The benchmark is seeded, so the memory and recall figures reproduce exactly; the README's numbers now come from it. Docs and benchmark only; no code change.

First stable release. The public API is frozen: a breaking change will not land without a major-version bump.

• Name both exports with show clauses, so a future symbol added to ops.dart or vector_matrix.dart cannot join the API by accident. The exported set is unchanged: the five free functions (cosineSimilarity, dot, euclideanDistance, normalized, normalizeInPlace) and the two classes (VectorMatrix, QuantizedMatrix, already final since 0.4.0).

The freeze follows an adversarial pass that ran the code against its failure modes rather than reading them. Every one is handled with a clear ArgumentError or FormatException, never a NaN leaking into a score, a hang, or silent corruption: a zero vector in cosine similarity, a NaN or infinite component, a length mismatch, k at or below zero, an empty matrix, a topK larger than the row count, a query in the wrong dimension, a dimension-zero matrix, truncated / empty / bad-magic bytes in fromBytes, a quantized search over an empty matrix or one with a zero row, and a row whose squared norm overflows single precision. The Float32List-only surface has no async, so there is no timer or zone for a failure to escape into.

• Mark VectorMatrix and QuantizedMatrix as final, ahead of a 1.0.0 freeze. Neither was designed to be subtyped: they are concrete data structures, cheap to construct, and nothing in the package, its tests, its examples or its benchmarks extends or implements either. Sealing them keeps the rest of 1.x additive, because the planned work (the QuantizedMatrix parity gaps, an ANN index) adds members to exactly these types, and every addition would otherwise break anyone who had implemented them. Adding final after 1.0.0 would require a major version; removing it later would not, so this is the direction that stays open. No behaviour change.

• QuantizedMatrix.topKCosine and topKDot now reject a query with a NaN or infinite component instead of returning a result list whose scores are all NaN. VectorMatrix already validated this; QuantizedMatrix only checked k and the query length, so the same bad query that throws on one matrix type silently poisoned the ranking on the other.

• The matrix search methods take a plain List<double> query, not only a Float32List. An embedding straight from a model is a List<double>, so building the index with fromRows and then calling topKCosine used to compile on the first line and fail on the second, which is exactly the kind of seam a caller trips on. The widening is source-compatible: a Float32List is a List<double>, so existing calls are unchanged. Applies to topKCosine, topKDot and topKEuclidean on both VectorMatrix and QuantizedMatrix.
• example/semantic_search.dart is the real use case: a 20,000-document index of 384-dim vectors, searched, with the result measured. A top-5 query is 1.4 ms against 15.9 ms for the hand-written cosine loop (11x), and the int8 QuantizedMatrix holds the index in a quarter of the memory, with the recall cost measured against the float ranking rather than assumed.

• Shorten the screenshot description. pub.dev accepts up to 200 characters but scores only those under 160, so the previous release published cleanly and quietly gave up the documentation points it was meant to earn.

• Declare the benchmark chart in pubspec.yaml so pub.dev renders it on the package page. The chart was already in the repository and the README, but pub.dev shows only what the screenshots: field points at, so the page a reader lands on from search opened with text where the measurement should have been.

• Add QuantizedMatrix, an int8 form of VectorMatrix for corpora that no longer fit comfortably in memory. Each row is scaled so its largest component maps to 127 and stored as one byte per dimension. Measured on 5,000 rows of 768 dimensions: 14.6 MB becomes 3.7 MB, 3.92x smaller, while a search goes from 0.63 ms to 2.50 ms a query, 3.96x the time, because the byte rows cannot use the SIMD path the float rows do. It buys memory and costs throughput, which is the trade to make only when the corpus is the problem.
• QuantizedMatrix.from leaves the source matrix usable, so recall can be measured against the exact ranking on real vectors. Recall@10 was 100% on the benchmark corpus, but that is an upper bound: uniformly random vectors sit far apart in high dimensions, and real embeddings cluster, which is where eight bits start confusing neighbours.

• Docs: tightened the README wording and visuals.

Changelog #

• Initial release.
• SIMD dot product, cosine similarity, Euclidean distance, and normalization over Float32List, with fail-fast validation of lengths and non-finite components.
• VectorMatrix: packed row-major storage with precomputed row norms, top-k cosine, dot product, and Euclidean search, and a VKT1 binary format for serialization.