static_embeddings 0.1.1 → 0.1.3

data/Rakefile

@@ -0,0 +1,95 @@
+require "bundler/gem_tasks" rescue nil
+require "rake/testtask"
+
+begin
+  require "rake/extensiontask"
+  Rake::ExtensionTask.new("static_embeddings") do |ext|
+    ext.lib_dir = "lib/static_embeddings"
+    ext.ext_dir = "ext/static_embeddings"
+  end
+rescue LoadError
+  desc "Compile the extension without rake-compiler"
+  task :compile do
+    ext = File.expand_path("ext/static_embeddings", __dir__)
+    lib = File.expand_path("lib/static_embeddings", __dir__)
+    build = File.expand_path("tmp/build", __dir__)
+    FileUtils.mkdir_p(build)
+    Dir.chdir(build) do
+      sh "ruby #{ext}/extconf.rb --with-cflags=-I#{ext}"
+      sh "make -j4"
+    end
+    FileUtils.cp(File.join(build, "static_embeddings.so"), lib)
+  end
+end
+
+desc "Regenerate the synthetic source model used by the test suite"
+task :fixtures do
+  ruby "tools/make_fixture_model.rb"
+end
+
+desc "Build the demo .semb shipped inside the gem"
+task demo_model: %i[fixtures compile] do
+  ruby "tools/build_demo_model.rb"
+end
+
+desc "Check the C runtime against the Python model2vec.StaticModel oracle"
+task parity: :compile do
+  model = ENV["MODEL"] || File.expand_path("~/.cache/static_embeddings/models/potion-retrieval-32m.semb")
+  oracle = ENV["ORACLE"] || "tmp/model2vec_oracle.json"
+
+  unless File.file?(oracle)
+    abort <<~MSG
+      oracle not found: #{oracle}
+
+      Generate it first (needs Python and the model2vec package):
+
+        python3 -m venv .venv-model2vec && . .venv-model2vec/bin/activate
+        pip install -U model2vec numpy
+        python tools/model2vec_oracle.py /path/to/source-model --out #{oracle}
+    MSG
+  end
+  abort "model not found: #{model}" unless File.file?(model)
+
+  ruby "-Ilib tools/check_model2vec_parity.rb --model #{model.inspect} --oracle #{oracle.inspect}"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/cancellation_timing_test.rb")
+  t.warning = false
+end
+
+Rake::TestTask.new(:gc_compaction) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = ["test/gc_compaction_test.rb"]
+  t.warning = false
+end
+
+Rake::TestTask.new(:cancellation_timing) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = ["test/cancellation_timing_test.rb"]
+  t.warning = false
+end
+
+task test: %i[compile fixtures]
+task cancellation_timing: %i[compile fixtures]
+task gc_compaction: %i[compile fixtures]
+
+namespace :benchmark do
+  Dir[File.join(__dir__, "benchmark", "*.rb")].sort.each do |path|
+    name = File.basename(path, ".rb")
+    next if name.start_with?("_")
+
+    desc "Run benchmark/#{name}.rb (BENCH_MODEL=... to pick a model)"
+    task name => %i[compile fixtures] do
+      ruby path
+    end
+  end
+end
+
+desc "Run every benchmark"
+task benchmark: Dir[File.join(__dir__, "benchmark", "*.rb")]
+  .sort.map { |p| File.basename(p, ".rb") }
+  .reject { |n| n.start_with?("_") }
+  .map { |n| "benchmark:#{n}" }
+task default: %i[compile fixtures test]

data/benchmark/_support.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+ROOT = File.expand_path("..", __dir__)
+$LOAD_PATH.unshift(File.join(ROOT, "lib")) unless $LOAD_PATH.include?(File.join(ROOT, "lib"))
+$stdout.sync = true
+$stderr.sync = true
+
+begin
+  require "static_embeddings"
+rescue LoadError
+  warn "Native extension is not built. Run: bundle exec rake compile"
+  raise
+end
+
+module SEBench
+  module_function
+
+  DEFAULT_REPEATS = 7
+  DEFAULT_MIN_SECONDS = 0.25
+  DEFAULT_WARMUP_SECONDS = 0.05
+  MAX_ITERATIONS = 100_000_000
+  CANDIDATE_WORDS = %w[
+    hello world ruby gem static embedding vector search text token
+    the a of and for local fast model cafe naive
+    postgres pipeline database query batch matrix cosine kernel window prefix runtime memory latency
+  ].freeze
+  CANDIDATE_SUFFIXES = (0..15).map(&:to_s).freeze
+
+  def env_integer(name, default, min: 1)
+    value = Integer(ENV.fetch(name, default.to_s))
+    raise ArgumentError, "#{name} must be >= #{min}, got #{value}" if value < min
+
+    value
+  end
+
+  def env_float(name, default, min: 0.0)
+    value = Float(ENV.fetch(name, default.to_s))
+    raise ArgumentError, "#{name} must be >= #{min}, got #{value}" if value < min
+
+    value
+  end
+
+  def repeats = env_integer("BENCH_REPEATS", DEFAULT_REPEATS)
+  def min_seconds = env_float("BENCH_MIN_SECONDS", DEFAULT_MIN_SECONDS)
+  def warmup_seconds = env_float("BENCH_WARMUP_SECONDS", DEFAULT_WARMUP_SECONDS)
+  def adaptive? = ENV.fetch("BENCH_ADAPTIVE", "1") != "0"
+  def kv? = ENV["BENCH_FORMAT"] == "kv"
+  def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  def realtime
+    started = monotonic
+    yield
+    monotonic - started
+  end
+
+  def median(values)
+    sorted = values.sort
+    return 0.0 if sorted.empty?
+
+    mid = sorted.length / 2
+    sorted.length.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+  end
+
+  def model
+    @model ||= begin
+      path = ENV["BENCH_MODEL"]
+      m =
+        if path
+          StaticEmbeddings.load(path)
+        elsif StaticEmbeddings.builtin_available?
+          StaticEmbeddings.load_builtin
+        else
+          abort "No model. Set BENCH_MODEL=/path/to/model.semb or run: bundle exec rake demo_model"
+        end
+      m.warmup!
+      m
+    end
+  end
+
+  def candidate_pool
+    @candidate_pool ||= begin
+      suffixed = CANDIDATE_WORDS.flat_map do |word|
+        CANDIDATE_SUFFIXES.map { |suffix| "#{word}#{suffix}" }
+      end
+      (CANDIDATE_WORDS + suffixed).uniq.freeze
+    end
+  end
+
+  def nonzero_vector?(blob)
+    blob.unpack("e*").any? { |value| value != 0.0 }
+  end
+
+  def in_vocabulary?(word)
+    stats = model.embed_with_stats(word)
+    stats[:token_count].positive? && stats[:unk_count].zero? && nonzero_vector?(stats[:vector])
+  end
+
+  def words
+    @words ||= begin
+      pool = candidate_pool.select { |word| in_vocabulary?(word) }
+      if pool.empty?
+        abort "No benchmark candidate word is in this model's vocabulary with a non-zero vector. " \
+              "Set BENCH_MODEL to a larger model or extend SEBench::CANDIDATE_WORDS."
+      end
+      pool.freeze
+    end
+  end
+
+  def text(word_count, rng)
+    Array.new(word_count) { words[rng.rand(words.length)] }.join(" ")
+  end
+
+  def corpus(count, word_count, seed: 20_260_829)
+    rng = Random.new(seed)
+    Array.new(count) { text(word_count, rng) }.each(&:valid_encoding?).freeze
+  end
+
+  def calibrate(initial, &block)
+    iterations = initial
+    return iterations unless adaptive?
+    return iterations if min_seconds <= 0.0
+
+    loop do
+      GC.start
+      elapsed = realtime { block.call(iterations) }
+      break iterations if elapsed >= min_seconds || iterations >= MAX_ITERATIONS
+
+      scale = elapsed <= 0.0 ? 10 : (min_seconds / elapsed * 1.5).ceil
+      iterations = [[iterations * scale, iterations * 2].max, MAX_ITERATIONS].min
+    end
+  end
+
+  def measure(initial_iterations: 1, operations_per_iteration: 1, &block)
+    iterations = calibrate(initial_iterations, &block)
+
+    deadline = monotonic + warmup_seconds
+    block.call(iterations) while monotonic < deadline
+
+    samples = Array.new(repeats) do
+      GC.start
+      before = GC.stat(:total_allocated_objects)
+      seconds = realtime { block.call(iterations) }
+      [seconds, GC.stat(:total_allocated_objects) - before]
+    end
+
+    times = samples.map(&:first)
+    best = times.min
+    worst = times.max
+    operations = iterations * operations_per_iteration
+
+    {
+      iterations: iterations,
+      repeats: repeats,
+      operations: operations,
+      median_sec: median(times),
+      best_sec: best,
+      worst_sec: worst,
+      spread_pct: best.positive? ? ((worst - best) / best * 100.0) : 0.0,
+      ops_per_sec: operations / median(times),
+      ns_per_op: median(times) / operations * 1e9,
+      allocations_per_op: median(samples.map(&:last)) / operations.to_f
+    }
+  end
+
+  def header(title)
+    m = model
+    puts
+    puts "== #{title} =="
+    puts "ruby=#{RUBY_VERSION} platform=#{RUBY_PLATFORM} backend=#{StaticEmbeddings.simd_backend}"
+    puts "model=#{m.model_id} dim=#{m.dim} vocab=#{m.vocab_size} max_tokens=#{m.max_tokens}"
+    puts "repeats=#{repeats} min_seconds=#{min_seconds} adaptive=#{adaptive? ? "yes" : "no"}"
+    puts "corpus_vocabulary=#{words.length} distinct in-vocabulary words " \
+         "(small pools keep matrix rows cached and overstate throughput)"
+    puts "input_coderange=cached unless a row says otherwise"
+    puts "spread_pct is best-to-worst across repeats; treat smaller differences as noise."
+    puts
+    return if kv?
+
+    printf("%-34s %12s %12s %10s %10s\n", "case", "ns/op", "ops/sec", "spread%", "alloc/op")
+  end
+
+  def report(name, stats, **fields)
+    if kv?
+      payload = { benchmark: name, ruby: RUBY_VERSION, platform: RUBY_PLATFORM,
+                  backend: StaticEmbeddings.simd_backend, dim: model.dim }
+                .merge(fields).merge(stats)
+      puts payload.map { |k, v| "#{k}=#{v.is_a?(Float) ? format("%.6g", v) : v}" }.join(" ")
+    else
+      label = fields.empty? ? name : "#{name} #{fields.map { |k, v| "#{k}=#{v}" }.join(" ")}"
+      printf("%-34s %12.1f %12.0f %9.1f%% %10.2f\n", label[0, 34], stats[:ns_per_op],
+             stats[:ops_per_sec], stats[:spread_pct], stats[:allocations_per_op])
+    end
+  end
+end

data/benchmark/core_paths.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+require_relative "_support"
+
+SEBench.header("core_paths")
+
+model = SEBench.model
+short = SEBench.corpus(2_000, 20)
+one = short.first
+ids = model.tokenize(one)
+
+SEBench.report("tokenize", SEBench.measure(initial_iterations: 500) { |n| n.times { model.tokenize(one) } },
+               words: 20, coderange: "cached")
+
+SEBench.report("embed", SEBench.measure(initial_iterations: 500) { |n| n.times { model.embed(one) } },
+               words: 20, coderange: "cached")
+
+SEBench.report("embed rotating corpus",
+               SEBench.measure(initial_iterations: 1, operations_per_iteration: short.length) { |n|
+                 n.times { short.each { |t| model.embed(t) } }
+               }, texts: short.length, coderange: "cached")
+
+SEBench.report("embed_batch",
+               SEBench.measure(initial_iterations: 1, operations_per_iteration: short.length) { |n|
+                 n.times { model.embed_batch(short) }
+               }, texts: short.length, coderange: "cached")
+
+SEBench.report("embed_batch f16",
+               SEBench.measure(initial_iterations: 1, operations_per_iteration: short.length) { |n|
+                 n.times { model.embed_batch(short, format: :f16) }
+               }, texts: short.length, coderange: "cached")
+
+SEBench.report("embed_token_ids",
+               SEBench.measure(initial_iterations: 500) { |n| n.times { model.embed_token_ids(ids) } },
+               tokens: ids.length)
+
+query = model.embed(one)
+abort "Benchmark query pooled to a zero vector; cosine_top_k requires a non-zero query" unless SEBench.nonzero_vector?(query)
+matrix = model.embed_batch(short).freeze
+rows = matrix.bytesize / (model.dim * 4)
+
+SEBench.report("dot_top_k", SEBench.measure(initial_iterations: 5) { |n| n.times { model.dot_top_k(query, matrix, 10) } },
+               rows: rows)
+SEBench.report("cosine_top_k", SEBench.measure(initial_iterations: 5) { |n| n.times { model.cosine_top_k(query, matrix, 10) } },
+               rows: rows)
+
+query16 = model.embed(one, format: :f16)
+matrix16 = model.embed_batch(short, format: :f16).freeze
+SEBench.report("dot_top_k f16",
+               SEBench.measure(initial_iterations: 5) { |n|
+                 n.times { StaticEmbeddings.dot_top_k(query16, matrix16, 10, dim: model.dim, format: :f16) }
+               }, rows: rows)
+
+large = (SEBench.corpus(1, 200_000).first).freeze
+large.valid_encoding?
+SEBench.report("embed large truncated",
+               SEBench.measure(initial_iterations: 20) { |n| n.times { model.embed(large) } },
+               logical_bytes: large.bytesize, coderange: "cached")

data/benchmark/gvl_threshold.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+require_relative "_support"
+
+SEBench.header("gvl_threshold")
+
+THRESHOLD_BYTES = [512, 1_024, 2_040, 2_048, 2_056, 4_096, 8_192, 16_384, 65_536].freeze
+PROGRESS_BYTES = [1_024, 2_048, 8_192, 65_536].freeze
+PROGRESS_ITERATIONS = SEBench.env_integer("BENCH_GVL_PROGRESS_ITERATIONS", 200)
+PROGRESS_THREAD_YIELD_EVERY = 4_096
+
+def text_with_bytes(target_bytes)
+  rng = Random.new(target_bytes)
+  text = +""
+  text << SEBench.words[rng.rand(SEBench.words.length)] << " " while text.bytesize < target_bytes
+  text = text.byteslice(0, target_bytes).freeze
+  text.valid_encoding?
+  text
+end
+
+THRESHOLD_BYTES.each do |target_bytes|
+  text = text_with_bytes(target_bytes)
+  stats = SEBench.measure(initial_iterations: 200) { |n| n.times { SEBench.model.embed(text) } }
+  SEBench.report("embed", stats, bytes: text.bytesize, coderange: "cached")
+end
+
+puts
+puts "second-thread progress during repeated embed calls (higher is better for the caller's neighbours)"
+PROGRESS_BYTES.each do |target_bytes|
+  text = text_with_bytes(target_bytes)
+  counter = 0
+  running = true
+  neighbour = Thread.new do
+    while running
+      counter += 1
+      Thread.pass if (counter % PROGRESS_THREAD_YIELD_EVERY).zero?
+    end
+  end
+
+  elapsed =
+    begin
+      SEBench.realtime { PROGRESS_ITERATIONS.times { SEBench.model.embed(text) } }
+    ensure
+      running = false
+      neighbour.join
+    end
+
+  printf("%-34s %12d ticks %9.3f s\n", "bytes=#{target_bytes}", counter, elapsed)
+end

data/docs/ARCHITECTURE.md

@@ -24,6 +24,15 @@ Everything expensive, fragile or security-sensitive about reading third-party
 model files happens once, offline, in a language where it is easy to get
 right. What remains in C is a bounds-checked mmap and three loops.
 
+The C side is `se_format.c` (mmap and validation), `se_tokenizer.c`,
+`se_embed.c`, `se_unicode.c`, `se_f16.c` (half-precision codec and kernels),
+`se_topk.c`, `se_alloc_stats.c` (optional allocation counters), and
+`static_embeddings.c` for the Ruby bindings. Shared size arithmetic,
+`static_assert`s on the mmapped struct layouts and the big-endian rejection live
+in `se_internal.h`: the header fields are decoded little-endian explicitly, but
+the mmapped structures and the float matrix are read in native order, so a
+big-endian host is refused at load rather than silently misread.
+
 ## `.semb` v2
 
 Little-endian throughout. 320-byte header, then sections aligned to 64 bytes.
@@ -90,10 +99,23 @@ tries inspired by double-array trie libraries such as libdatrie:
 - `root_trie` for tokens that can start a word;
 - `continuation_trie` for `##token` entries stored without the `##` prefix.
 
-At runtime `append_wordpiece` walks the relevant trie once, records the longest
-terminal node and emits that token id. This matches the shape of WordPiece much
-better than exact hash lookup: longest-prefix matching is one forward pass
-rather than many candidate hashes and memcmps.
+At runtime `append_wordpiece` first tries the hash table for the whole word,
+which is the common case for in-vocabulary text, and falls back to walking the
+relevant trie once, recording the longest terminal node. Both halves earn their
+place: removing the hash pre-check made tokenization several times slower on
+ordinary text, and replacing the trie with repeated hash lookups by decreasing
+length made out-of-vocabulary words several times slower still.
+
+Normalization has an ASCII fast path. Below `0x80` the CJK, NFD, combining-mark
+and case-folding branches always resolve the same way, so those runs go through
+a 128-entry classification table instead of the full
+`emit_cleaned -> emit_stripped -> emit_lowered -> feed_token_cp` chain, and a
+word reserves its codepoint buffer once rather than once per character. The
+table is generated to agree with `is_control`, `se_is_ascii_whitespace` and
+`se_is_ascii_punct`, and `test/ascii_parity_test.rb` sweeps every byte in
+`0x00..0x7F` against the Ruby reference to keep it that way. That test exists
+because `U+007F DEL` was misclassified through 0.1.1 and every sampled test in
+the suite passed anyway.
 
 Loading a model still performs **zero runtime insertions**. It is `mmap` plus a
 validation pass over the hash table, trie node ranges and trie edge ordering.
@@ -224,6 +246,33 @@ not triple the cost.
 With `max_tokens: false` there is nothing to truncate and the whole input is
 copied.
 
+The window bounds tokenizing, not the whole call. Ruby has to answer whether the
+`String` is valid UTF-8, and `rb_enc_str_coderange` answers it for the whole
+`String` — an O(bytes) scan when Ruby has not computed a coderange yet, running
+before the prefix is even chosen. `validate_encoding: :prefix` skips that scan
+and leans on the fact that the C side already validates what it reads:
+`decode_one` rejects malformed UTF-8, and `se_prefix_boundary_len` returns 0
+when it cannot decode, which degrades to a full copy rather than reading out of
+bounds. So `:prefix` is memory-safe in every case; what it gives up is noticing
+invalid bytes the tokenizer never reaches. A cached coderange is always
+honoured, which keeps the cheap answer authoritative when Ruby already has one.
+
+## Mapping the model file
+
+POSIX uses `mmap` with `PROT_READ`/`MAP_PRIVATE`; Windows uses
+`CreateFileMapping` plus `MapViewOfFile`. Both give the same three properties
+the format was designed around: pages fault in lazily instead of being read up
+front, the page cache is shared between forked or sibling processes, and the
+runtime never owns a writable copy of the matrix. Windows previously read the
+file into the heap, which cost every process a private copy of the model and a
+full read before the first query.
+
+Windows keeps the heap path as a fallback when mapping fails, since some network
+filesystems refuse it, and `model->mapped` records which one was taken so
+`se_model_close` unmaps or frees correctly. `verify` is separate from loading and
+streams the file through SHA-256 in chunks, so checking an artifact never
+materialises it either.
+
 ## Concurrency
 
 Small calls run inline. Large `embed_batch` calls copy Ruby input into C-owned
@@ -239,8 +288,9 @@ job/application layer.
 
 Cancellation is cooperative: the tokenizer checks a flag every 1024 codepoints
 (counted by iteration, not by byte offset, so the interval does not depend on
-how wide the input's codepoints are), the pooling loop checks every 256 rows,
-and the top-k scan every 1024 rows. `unblock_cancel` sets that flag when Ruby
+how wide the input's codepoints are), and the ASCII fast path checks on the same
+cadence in bytes so a long ASCII run is no less interruptible. The pooling loop
+checks every 256 rows, and the top-k scan every 1024 rows. `unblock_cancel` sets that flag when Ruby
 interrupts a GVL-free region.
 
 No global mutable state exists in C. The model is immutable after load and

data/docs/BENCHMARKING.md

@@ -0,0 +1,87 @@
+# Benchmarking
+
+Two different tools, for two different questions.
+
+`benchmark/` answers "how fast is this, and is the difference I am looking at
+real". `samples/` answers "where does the time go" by keeping a process alive
+for a profiler to attach to. Do not use one for the other's job.
+
+```bash
+bundle exec rake benchmark                 # everything
+bundle exec rake benchmark:core_paths
+bundle exec rake benchmark:gvl_threshold
+
+BENCH_MODEL="$HOME/.cache/static_embeddings/models/potion-retrieval-32m.semb" \
+  bundle exec rake benchmark:core_paths
+```
+
+Without `BENCH_MODEL` the demo model is used, which has `dim=8` and a 176-token
+vocabulary. It proves the harness runs; it says nothing about production speed.
+
+## Reading the output
+
+```text
+case                                      ns/op      ops/sec    spread%   alloc/op
+embed words=20                           8540.5       117089       3.0%       1.00
+```
+
+`spread_pct` is the distance between the fastest and slowest repeat. **A
+difference smaller than `spread_pct` is not a result.** On a laptop or a shared
+CI runner it is routinely 5-10%, which is wider than most changes worth making.
+If you want to claim an improvement, either get the spread down or show the
+change across several independent runs.
+
+`alloc/op` is Ruby object allocations per operation. It moves for different
+reasons than time does, and it is the more stable signal of the two.
+
+Generated text inputs are primed with `valid_encoding?` before timing, so these
+benchmarks measure the cached-coderange hot path. Fresh strings from disk or the
+database can pay an extra whole-string UTF-8 scan; see `docs/PERFORMANCE.md`.
+
+Iteration counts are calibrated automatically so every measurement runs for at
+least `BENCH_MIN_SECONDS`. Knobs:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `BENCH_MODEL` | demo model | model to load |
+| `BENCH_REPEATS` | 7 | repeats per case, median reported |
+| `BENCH_MIN_SECONDS` | 0.25 | minimum duration of one repeat |
+| `BENCH_WARMUP_SECONDS` | 0.05 | warmup before timing |
+| `BENCH_ADAPTIVE` | 1 | set to 0 to use the literal iteration count |
+| `BENCH_FORMAT` | table | set to `kv` for machine-readable lines |
+
+## What the two benchmarks are for
+
+`core_paths` covers tokenize, single embed, batch embed, pooling in isolation
+and top-k in both formats. The `embed` and `embed rotating corpus` rows are
+deliberately both present: the first repeats one string and keeps its matrix
+rows in cache, the second rotates through 2000 texts and does not. The gap
+between them is the cache effect, and quoting the first as throughput is how you
+end up with a number nobody can reproduce.
+
+`gvl_threshold` sweeps input sizes around `SE_GVL_UNLOCK_THRESHOLD`, the point
+where a single `embed` stops running under the GVL and is handed to the batch
+machinery. Look for the step, not the slope. On one x86-64 run the step cost
+about 32% latency and four extra allocations, and it is also the point where a
+second Ruby thread starts making progress at all. Both halves of that trade have
+to be measured on your hardware before the constant is worth changing.
+
+## Traps this repository has already fallen into
+
+**Quoting noise.** An `embed_batch f16` change was reported as a 6% speedup; it
+was inside the run-to-run spread and the next run showed the opposite sign. The
+memory result from the same change was real and reproducible. Report the one you
+can reproduce.
+
+**Cache-resident working sets.** Embedding the same text in a loop keeps a tiny
+slice of the matrix hot. Real corpora do not.
+
+**Logical vs processed bytes.** With truncation active, a 3 MB document is
+tokenized only until `max_tokens` is reached. Any MB/s figure computed from the
+string length divides by bytes that were never read.
+
+**GC state.** `GC.disable` does not stop an in-flight incremental cycle from
+sweeping. The harness leaves GC on and reports allocations instead.
+
+See `docs/PERFORMANCE.md` for the budget itself and where the time actually
+goes.

data/docs/LIMITATIONS.md

@@ -0,0 +1,91 @@
+# Limitations
+
+`static_embeddings` is a runtime for one narrow thing: turning text into a
+vector with a converted Model2Vec / potion model, and scanning a matrix of such
+vectors. It is not a vector database, not a general embedding library, and not a
+tokenizer toolkit.
+
+This page is the answer to "does it do X". If X is here, the answer is no, and
+the entry says whether that is a decision or just unfinished work.
+
+## Models
+
+- **Only `.semb` files from this repository's converter.** Loading a
+  HuggingFace directory at runtime is not supported and will not be. The
+  converter is the only thing that reads third-party files, and it runs offline.
+- **Only the `BERT_WORDPIECE_V1` tokenizer profile.** SentencePiece, BPE, Unigram
+  and byte-level tokenizers are rejected at conversion time rather than
+  approximated.
+- **No model training, distillation or fine-tuning.** Produce the model with
+  upstream `model2vec`, then convert it.
+- **No transformer inference.** Static embeddings have no attention and no
+  context; a word contributes the same row wherever it appears. If you need
+  contextual embeddings, this is the wrong tool.
+
+## Runtime
+
+- **No internal parallelism.** `threads:` is rejected rather than ignored. Split
+  work at the job level and run more application workers.
+- **No Ractor support.** Model, and everything holding native state, are not
+  shareable; `Ractor.make_shareable` raises.
+- **No GPU, no BLAS, no external SIMD library.** The kernels are plain C with
+  compiler autovectorisation, plus a hand-written half-precision path.
+- **No streaming input.** `embed` and `embed_batch` take Ruby `String`s that are
+  already in memory.
+- **`embed_batch` peaks at roughly twice the returned blob**, because the result
+  is built in C memory and then copied into a Ruby `String`. Chunk large
+  corpora.
+- **Big-endian hosts are refused at load.** The header is decoded
+  little-endian explicitly, but the mmapped structures and the float matrix are
+  read in native order.
+
+## Search
+
+- **No index.** `dot_top_k` and `cosine_top_k` are exhaustive scans. There is no
+  ANN, no IVF, no HNSW, no clustering.
+- **No batched queries.** One query per scan; N queries stream the matrix N
+  times.
+- **No candidate filtering.** You cannot restrict a scan to a subset of rows.
+- **No precomputed row norms.** `cosine_top_k` recomputes each row's norm on
+  every query. Normalise your rows once and use `dot_top_k` instead.
+- **No persistence, no ids, no updates.** A matrix is a frozen `String`; mapping
+  rows to documents, appending, and deleting are the caller's problem. If you
+  want that, use pgvector and keep this gem for producing the vectors.
+- **No metric other than dot product and cosine.** No Euclidean, no Manhattan,
+  no Hamming.
+
+## Storage formats
+
+- **`f32` and `f16` only.** No int8, no binary quantisation.
+- **`f16` is a storage trade-off, not a speed feature.** See
+  `docs/PERFORMANCE.md`; it wins on some CPUs and loses on others.
+- **`f16` rounding is half-up, not ties-to-even.** Blobs written by this gem can
+  differ from NumPy or PyTorch by one ULP on exact halfway values.
+
+## Platforms
+
+- **Windows is built and smoke-tested by cross-compilation under wine, not on a
+  real Windows runner.** The loader uses `CreateFileMapping`, with a
+  read-into-heap fallback.
+- **No JRuby or TruffleRuby.** The gem is a CRuby C extension.
+
+## Verification
+
+- **`load` does not check the SHA-256.** Structural validation always runs, but
+  a bit flip inside the matrix is only caught by `verify: true` or
+  `StaticEmbeddings.verify`.
+- **Parity is per model and per runtime version.** A converted model is not
+  trusted until it has a record in `docs/MODEL_AUDIT.md`, and that record
+  expires when the tokenizer changes.
+
+## Known open questions
+
+These are not decisions, just work that has not been done or measured:
+
+- The `SE_GVL_UNLOCK_THRESHOLD` value has a benchmark now
+  (`rake benchmark:gvl_threshold`) but has not been retuned from it.
+- Top-k keeps its candidates in a sorted array, which degrades for large `k`; a
+  heap would be better somewhere above a few dozen.
+- `madvise(MADV_RANDOM)` and huge pages for the embedding section are untested.
+- The C allocation counters cover the runtime's own allocations only; Ruby heap,
+  fragmentation and mmap residency are outside them.