tg_geometry 0.1.0

data/benchmark/_support.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require "rbconfig"
+
+ROOT = File.expand_path("..", __dir__)
+EXT_DIR = File.join(ROOT, "ext", "tg_geometry")
+LIB_DIR = File.join(ROOT, "lib")
+
+$LOAD_PATH.unshift(LIB_DIR) unless $LOAD_PATH.include?(LIB_DIR)
+$LOAD_PATH.unshift(EXT_DIR) unless $LOAD_PATH.include?(EXT_DIR)
+
+begin
+  require "tg/geometry"
+rescue LoadError
+  warn "Native extension is not built. Run: bundle exec rake compile"
+  raise
+end
+
+module TGGeometryBench
+  module_function
+
+  SIZES = [100, 500, 1_000, 5_000, 50_000].freeze
+  FAST_SIZES = [100, 500, 1_000].freeze
+
+  def sizes
+    ENV["TGEOMETRY_BENCH_FULL"] == "1" ? SIZES : FAST_SIZES
+  end
+
+  def iterations(default)
+    Integer(ENV.fetch("TGEOMETRY_BENCH_ITERATIONS", default.to_s))
+  end
+
+  def box_wkt(min_x, min_y, max_x, max_y)
+    "POLYGON ((#{min_x} #{min_y}, #{max_x} #{min_y}, #{max_x} #{max_y}, #{min_x} #{max_y}, #{min_x} #{min_y}))"
+  end
+
+  def box_geojson(min_x, min_y, max_x, max_y)
+    %({"type":"Polygon","coordinates":[[[#{min_x},#{min_y}],[#{max_x},#{min_y}],[#{max_x},#{max_y}],[#{min_x},#{max_y}],[#{min_x},#{min_y}]]]})
+  end
+
+  def compact_entries(count)
+    Array.new(count) do |i|
+      x = i % 250
+      y = i / 250
+      [i, box_geojson(x, y, x + 0.8, y + 0.8)]
+    end
+  end
+
+  def long_thin_entries(count)
+    Array.new(count) do |i|
+      [i, box_geojson(i * 0.01, i, i * 0.01 + 1_000.0, i + 0.05)]
+    end
+  end
+
+  def overlapping_entries(count)
+    Array.new(count) do |i|
+      offset = i * 0.001
+      [i, box_geojson(offset, offset, 100.0 + offset, 100.0 + offset)]
+    end
+  end
+
+  def entries_for(kind, count)
+    case kind
+    when :compact then compact_entries(count)
+    when :long_thin then long_thin_entries(count)
+    when :overlapping then overlapping_entries(count)
+    else raise ArgumentError, "unknown benchmark kind: #{kind.inspect}"
+    end
+  end
+
+  def build_index(entries, strategy:)
+    TG::Geometry::Index.build(entries, via: :geojson, strategy: strategy)
+  end
+
+  def points_for(kind)
+    case kind
+    when :compact then [[0.4, 0.4], [10.4, 2.4], [10_000.0, 10_000.0]]
+    when :long_thin then [[1.0, 10.02], [500.0, 500.02], [-1.0, -1.0]]
+    when :overlapping then [[50.0, 50.0], [0.0, 0.0], [200.0, 200.0]]
+    else raise ArgumentError, "unknown benchmark kind: #{kind.inspect}"
+    end
+  end
+
+  def rects_for(kind)
+    case kind
+    when :compact then [[0, 0, 10, 10], [100, 100, 105, 105]]
+    when :long_thin then [[0, 10, 1_000, 10.05], [2_000, 2_000, 2_001, 2_001]]
+    when :overlapping then [[25, 25, 75, 75], [200, 200, 201, 201]]
+    else raise ArgumentError, "unknown benchmark kind: #{kind.inspect}"
+    end
+  end
+
+  def packed_points(points)
+    points.flatten.pack("d*")
+  end
+
+  def rss_kb
+    case RbConfig::CONFIG["host_os"]
+    when /linux/i
+      File.read("/proc/self/status")[/^VmRSS:\s+(\d+)\s+kB/, 1].to_i
+    when /darwin/i
+      Integer(`ps -o rss= -p #{Process.pid}`)
+    else
+      0
+    end
+  rescue StandardError
+    0
+  end
+
+  def say_header(title)
+    puts "\n== #{title} =="
+    puts "ruby=#{RUBY_VERSION} platform=#{RUBY_PLATFORM} full=#{ENV['TGEOMETRY_BENCH_FULL'] == '1'}"
+  end
+end

data/benchmark/batch_packed_vs_loop.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("batch_packed_vs_loop")
+iterations = TGGeometryBench.iterations(500)
+
+%i[compact long_thin overlapping].each do |kind|
+  TGGeometryBench.sizes.each do |size|
+    entries = TGGeometryBench.entries_for(kind, size)
+    points = Array.new(1_000) { |i| TGGeometryBench.points_for(kind)[i % TGGeometryBench.points_for(kind).length] }
+    packed = TGGeometryBench.packed_points(points)
+
+    %i[flat rtree].each do |strategy|
+      index = TGGeometryBench.build_index(entries, strategy: strategy)
+
+      scalar_time = Benchmark.realtime do
+        iterations.times { points.map { |lon, lat| index.find_covering(lon, lat) } }
+      end
+      batch_time = Benchmark.realtime do
+        iterations.times { index.covering_ids_batch_packed(packed) }
+      end
+
+      puts "kind=#{kind} n=#{size} strategy=#{strategy} points=#{points.length} scalar_sec=%.6f batch_sec=%.6f scalar_batches_per_sec=%.2f batch_batches_per_sec=%.2f" % [scalar_time, batch_time, iterations / scalar_time, iterations / batch_time]
+    end
+  end
+end

data/benchmark/falcon_concurrency.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("falcon_concurrency")
+puts "No Falcon dependency is used here. This is a thread-read baseline for the immutable Index model."
+puts "Falcon/Async behavior remains an OPEN QUESTION until Roman approves a dedicated dependency/setup."
+
+entries = TGGeometryBench.compact_entries(1_000)
+index = TGGeometryBench.build_index(entries, strategy: :rtree)
+threads = Integer(ENV.fetch("TGEOMETRY_BENCH_THREADS", "4"))
+iterations = TGGeometryBench.iterations(10_000)
+
+elapsed = Benchmark.realtime do
+  threads.times.map do
+    Thread.new do
+      iterations.times do |i|
+        lon, lat = TGGeometryBench.points_for(:compact)[i % 3]
+        index.find_covering(lon, lat)
+      end
+    end
+  end.each(&:join)
+end
+
+puts "threads=#{threads} iterations_per_thread=#{iterations} total_queries=#{threads * iterations} seconds=%.6f qps=%.2f" % [elapsed, (threads * iterations) / elapsed]

data/benchmark/flat_vs_rtree.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("flat_vs_rtree")
+iterations = TGGeometryBench.iterations(1_000)
+
+%i[compact long_thin overlapping].each do |kind|
+  TGGeometryBench.sizes.each do |size|
+    entries = TGGeometryBench.entries_for(kind, size)
+
+    build_flat = Benchmark.realtime { @flat = TGGeometryBench.build_index(entries, strategy: :flat) }
+    build_rtree = Benchmark.realtime { @rtree = TGGeometryBench.build_index(entries, strategy: :rtree) }
+
+    TGGeometryBench.points_for(kind).each do |lon, lat|
+      flat_time = Benchmark.realtime { iterations.times { @flat.find_covering(lon, lat) } }
+      rtree_time = Benchmark.realtime { iterations.times { @rtree.find_covering(lon, lat) } }
+      puts "kind=#{kind} n=#{size} query=point lon=#{lon} lat=#{lat} flat_sec=%.6f rtree_sec=%.6f flat_qps=%.2f rtree_qps=%.2f build_flat=%.6f build_rtree=%.6f" % [flat_time, rtree_time, iterations / flat_time, iterations / rtree_time, build_flat, build_rtree]
+    end
+
+    TGGeometryBench.rects_for(kind).each do |rect|
+      flat_time = Benchmark.realtime { iterations.times { @flat.intersecting_rect(*rect) } }
+      rtree_time = Benchmark.realtime { iterations.times { @rtree.intersecting_rect(*rect) } }
+      puts "kind=#{kind} n=#{size} query=rect rect=#{rect.join(',')} flat_sec=%.6f rtree_sec=%.6f flat_qps=%.2f rtree_qps=%.2f" % [flat_time, rtree_time, iterations / flat_time, iterations / rtree_time]
+    end
+  end
+end

data/benchmark/gvl_threshold.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("gvl_threshold")
+puts "First release intentionally performs parse/write/batch/query with GVL held."
+puts "This harness records baseline parse wall time only; it does not enable no-GVL execution."
+
+# Build one valid WKT polygon close to the requested byte size.  The previous
+# implementation accidentally benchmarked the same tiny 39-byte polygon for all
+# target sizes because it used Array(...).first.
+def polygon_wkt_at_least(target_bytes)
+  points_count = [4, target_bytes / 38].max
+
+  loop do
+    points = Array.new(points_count) do |i|
+      angle = (2.0 * Math::PI * i) / points_count
+      [Math.cos(angle) * 10.0, Math.sin(angle) * 10.0]
+    end
+    points << points.first
+
+    coordinates = points.map { |x, y| "#{x} #{y}" }.join(", ")
+    payload = "POLYGON ((#{coordinates}))"
+    return payload if payload.bytesize >= target_bytes
+
+    points_count = (points_count * 1.25).ceil
+  end
+end
+
+sizes = [128, 1_024, 16_384, 262_144]
+iterations = TGGeometryBench.iterations(2_000)
+
+sizes.each do |target_bytes|
+  payload = polygon_wkt_at_least(target_bytes)
+
+  time = Benchmark.realtime do
+    iterations.times { TG::Geometry.parse_wkt(payload) }
+  end
+
+  puts "target_bytes=#{target_bytes} payload_bytes=#{payload.bytesize} iterations=#{iterations} seconds=%.6f ops_per_sec=%.2f" % [time, iterations / time]
+end

data/benchmark/objectspace_memsize.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+require "objspace"
+
+TGGeometryBench.say_header("objectspace_memsize")
+
+%i[compact long_thin overlapping].each do |kind|
+  TGGeometryBench.sizes.each do |size|
+    entries = TGGeometryBench.entries_for(kind, size)
+    flat = TGGeometryBench.build_index(entries, strategy: :flat)
+    rtree = TGGeometryBench.build_index(entries, strategy: :rtree)
+    geom = TG::Geometry.parse_geojson(entries.first.last)
+
+    puts "kind=#{kind} n=#{size} geom_memsize=#{ObjectSpace.memsize_of(geom)} flat_memsize=#{ObjectSpace.memsize_of(flat)} rtree_memsize=#{ObjectSpace.memsize_of(rtree)}"
+  end
+end

data/benchmark/parse_throughput.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("parse_throughput")
+
+def polygon_with_points(count)
+  points = Array.new(count) do |i|
+    angle = (2.0 * Math::PI * i) / count
+    [Math.cos(angle) * 10.0, Math.sin(angle) * 10.0]
+  end
+  points << points.first
+  coordinates = points.map { |x, y| "#{x} #{y}" }.join(", ")
+  "POLYGON ((#{coordinates}))"
+end
+
+small = TGGeometryBench.box_wkt(0, 0, 10, 10)
+medium = polygon_with_points(250)
+large = polygon_with_points(2_500)
+geojson = '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}'
+wkb = TG::Geometry.parse_wkt(small).to_wkb
+
+cases = {
+  "wkt:small" => [small, :wkt],
+  "geojson:small" => [geojson, :geojson],
+  "wkb:small" => [wkb, :wkb],
+  "wkt:medium" => [medium, :wkt],
+  "wkt:large" => [large, :wkt]
+}
+
+iterations = TGGeometryBench.iterations(10_000)
+
+cases.each do |name, (payload, format)|
+  time = Benchmark.realtime do
+    iterations.times { TG::Geometry.parse(payload, format: format) }
+  end
+  puts "%s iterations=%d seconds=%.6f ops_per_sec=%.2f" % [name, iterations, time, iterations / time]
+end

data/benchmark/rss_stability.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("rss_stability")
+
+total_queries = Integer(ENV.fetch("TGEOMETRY_RSS_QUERIES", "10_000_000"))
+rebuilds = Integer(ENV.fetch("TGEOMETRY_RSS_REBUILDS", "100"))
+entries_count = Integer(ENV.fetch("TGEOMETRY_RSS_ENTRIES", "1_000"))
+max_drift_kb = Integer(ENV.fetch("TGEOMETRY_RSS_MAX_DRIFT_KB", "51_200"))
+
+queries_per_rebuild = (total_queries / rebuilds).clamp(1, total_queries)
+entries = TGGeometryBench.compact_entries(entries_count)
+points = TGGeometryBench.points_for(:compact)
+packed_batch = TGGeometryBench.packed_points(points * 10)
+
+GC.start
+GC.start
+start_rss = TGGeometryBench.rss_kb
+peak_rss = start_rss
+samples = []
+
+queries_executed = 0
+started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+rebuilds.times do |cycle|
+  index = TGGeometryBench.build_index(entries, strategy: (cycle.even? ? :flat : :rtree))
+
+  queries_per_rebuild.times do |q|
+    lon, lat = points[(q + cycle) % points.length]
+    index.find_covering(lon, lat)
+    queries_executed += 1
+
+    if (q & 0xff).zero?
+      index.covering_ids_batch_packed(packed_batch)
+      queries_executed += points.length * 10
+    end
+  end
+
+  index = nil
+
+  if (cycle % 10).zero?
+    GC.start
+    rss = TGGeometryBench.rss_kb
+    peak_rss = [peak_rss, rss].max
+    samples << [cycle, queries_executed, rss]
+  end
+end
+
+GC.start
+GC.start
+finish_rss = TGGeometryBench.rss_kb
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+drift_kb = finish_rss - start_rss
+
+puts format(
+  "queries=%d rebuilds=%d entries=%d elapsed_s=%.2f start_rss_kb=%d peak_rss_kb=%d finish_rss_kb=%d drift_kb=%d",
+  queries_executed, rebuilds, entries_count, elapsed,
+  start_rss, peak_rss, finish_rss, drift_kb
+)
+
+if samples.length > 1
+  puts "samples (cycle, queries, rss_kb):"
+  samples.each { |row| puts "  #{row.inspect}" }
+end
+
+if max_drift_kb.positive? && drift_kb > max_drift_kb
+  warn "[rss_stability] RSS drift #{drift_kb} KB exceeds threshold #{max_drift_kb} KB"
+  exit 1
+end

data/docs/ACTIVE_RECORD.md

@@ -0,0 +1,26 @@
+# ActiveRecord source helper
+
+`TG::Geometry::ActiveRecordSource` is an optional Ruby helper. It does not require Rails or ActiveRecord and is not loaded from a separate integration gem.
+
+It accepts any object that responds to `find_each`, or any Enumerable:
+
+```ruby
+entries = TG::Geometry::ActiveRecordSource.call(
+  Zone.where(active: true),
+  id: :id,
+  geometry: :geojson,
+  batch_size: 1_000
+)
+
+index = TG::Geometry::Index.build(entries, via: :geojson, strategy: :rtree)
+```
+
+It can also feed a Registry:
+
+```ruby
+class DeliveryZones < TG::Geometry::Registry
+  active_record_source Zone.where(active: true), id: :id, geometry: :geojson
+end
+```
+
+Field readers may be Symbols, Strings, or Procs. The helper only converts application records into `[[id, object], ...]`; it does not mutate records, keep database connections, create background jobs, install reload hooks, or add a Rails dependency to the native extension.

data/docs/ARCHITECTURE.md

@@ -0,0 +1,130 @@
+# tg_geometry architecture
+
+`tg_geometry` is a Ruby C extension for the public namespace `TG::Geometry`. It vendors the upstream `tidwall/tg` geometry engine and `tidwall/rtree.c`; it does not depend on GEOS, PostGIS, PROJ, GDAL, system TG, or system rtree libraries.
+
+The gem targets a small production-grade core:
+
+- parsing and writing TG geometries from Ruby;
+- exact planar geometry predicates;
+- immutable rectangles for bounding boxes and query windows;
+- immutable geofencing-oriented indexes that return user ids;
+- flat and rtree collection-level search strategies;
+- native-endian packed point batches for high-throughput same-process calls;
+- read-only borrowed low-level Line/Ring/Polygon wrappers;
+- grouped TG API coverage for predicates, accessors, point/empty constructors, Segment values, and GeometryCollection children.
+
+The gem is not a full GIS system. See `docs/LIMITATIONS.md`.
+
+## Public namespace
+
+The canonical require path is:
+
+```ruby
+require "tg/geometry"
+```
+
+The public API lives under `TG::Geometry`. The top-level `TG` module is only a namespace container, not the public gem API.
+
+## Native extension shape
+
+The current extension is built by `ext/tg_geometry/extconf.rb` and loaded as `tg_geometry_ext_geometry_ext`. The build requires Ruby >= 3.0 and a C11 compiler. Vendor sources are compiled into the extension through small wrapper files:
+
+- `ext/tg_geometry/tg_geometry_vendor_tg.c` includes `vendor/tg/tg.c`;
+- `ext/tg_geometry/tg_geometry_vendor_rtree.c` includes `vendor/rtree/rtree.c`.
+
+No visibility-hiding flag is enabled unless the Init symbol is explicitly exported. The Init function is exported with `RUBY_FUNC_EXPORTED`.
+
+## Immutable `TG::Geometry::Geom`
+
+`TG::Geometry::Geom` usually wraps one owned `struct tg_geom *`. Expansion Block J also allows internal borrowed `TG::Geometry::Geom` wrappers for GeometryCollection children. Borrowed wrappers keep a parent `geom_owner`, report no owned native bytes, and do not call `tg_geom_free` on the borrowed child pointer.
+
+Rules:
+
+- public `.allocate` is disabled;
+- objects are created only by parse APIs, safe constructors, or internal borrowed child wrappers;
+- the native pointer is never replaced;
+- there is no `close!`, `free!`, `detach!`, or mutation API;
+- parsed objects are frozen before being returned.
+
+This immutability is required because `TG::Geometry::Index` can borrow a native geometry pointer from a `TG::Geometry::Geom` and keep the Ruby owner alive.
+
+## Immutable `TG::Geometry::Rect`
+
+`TG::Geometry::Rect` is a small Ruby object around four finite coordinates. It is constructible from Ruby and frozen after initialization. The first release exposes only unambiguous rectangle APIs:
+
+- coordinate readers;
+- `center`;
+- `intersects?`;
+- `contains_point?`;
+- expansion methods returning new Rect objects.
+
+`Rect#contains?` is intentionally not exposed because the name is ambiguous.
+
+## Immutable `TG::Geometry::Index`
+
+`TG::Geometry::Index` is built once and read-only afterwards.
+
+```ruby
+index = TG::Geometry::Index.build(
+  [[id1, object1], [id2, object2]],
+  via: :geojson,
+  strategy: :rtree,
+  predicate: :covers,
+  geometry_index: :ystripes
+)
+```
+
+Accepted `via:` modes:
+
+- `:geom` borrows native geometry from existing `TG::Geometry::Geom` wrappers and marks the owner Ruby objects;
+- `:geojson` parses entry strings into Index-owned TG geometries;
+- `:wkb` parses entry strings as raw WKB bytes into Index-owned TG geometries.
+
+Accepted strategies:
+
+- `:flat` scans entries in insertion order with bbox prefiltering and exact TG geometry filtering;
+- `:rtree` uses vendored `rtree.c` over entry bboxes, then applies exact TG geometry filtering.
+
+`strategy: :auto` is not implemented in the first public release. Use explicit `:flat` or `:rtree` and validate with repository benchmarks.
+
+## Result order
+
+Insertion order is public behavior.
+
+Each entry stores a unique `ordinal`. Flat strategy naturally scans entries in ordinal order. Rtree strategy uses rtree only as a candidate prefilter; candidate marks are local to the query and results are emitted by scanning entries in ordinal order. Rtree traversal order never leaks into Ruby results.
+
+## Point predicate implementation
+
+Point queries allocate a temporary TG point geometry and use exact TG predicates:
+
+- `:covers` calls `tg_geom_covers(entry_geom, point_geom)`;
+- `:contains` calls `tg_geom_contains(entry_geom, point_geom)`.
+
+This is intentionally not the fastest possible point path. The first release chooses exact `covers` / `contains` semantics over a no-allocation shortcut. A faster path such as `tg_geom_intersects_xy` can only replace it after boundary and hole-boundary equivalence tests plus benchmarks are added.
+
+## Reload pattern
+
+The intended application reload pattern is atomic reference replacement:
+
+```ruby
+new_index = TG::Geometry::Index.build(entries, via: :geojson, strategy: :rtree)
+@index = new_index
+```
+
+Old readers keep using the old immutable object until they release it. New readers see the new object after the Ruby reference swap. There is no in-place reload, mutation, add, delete, or builder API in the first release.
+
+## Expansion Blocks A-E and I-J
+
+Expansion Block A (`strategy: :auto`) is not enabled in the first public release. The native Index stores only explicit concrete strategies (`:flat` or `:rtree`).
+
+Expansion Block B adds `TG::Geometry::Registry` in Ruby. Registry wraps an immutable Index reference and reloads by building a new Index before swapping the reference.
+
+Expansion Block C adds `TG::Geometry::ActiveRecordSource` as optional Ruby-only source sugar. The native extension does not depend on Rails or ActiveRecord.
+
+Expansion Block D adds Hex/GeoBIN parse/write helpers and raw `extra_json` copying. It does not parse properties into Ruby Hashes.
+
+Expansion Block E adds read-only borrowed wrappers for `TG::Geometry::Line`, `TG::Geometry::Ring`, and `TG::Geometry::Polygon`. These wrappers keep the parent `TG::Geometry::Geom` alive through `geom_owner`, mark it for GC, update it during compaction, and never free borrowed TG child pointers directly.
+
+Expansion Block I documents and tests the current Ractor boundary: native wrappers are not advertised as Ractor-shareable objects. Normal thread read-only access remains the supported concurrency model.
+
+Expansion Block J adds grouped TG API coverage without exposing global mutable environment settings or callback-based APIs. Implemented groups are additional predicates, geometry metadata/collection accessors, point and empty geometry constructors, value `TG::Geometry::Segment`, and borrowed GeometryCollection child `Geom` wrappers. See `docs/FULL_TG_API_COVERAGE.md`.

data/docs/AUTO_STRATEGY.md

@@ -0,0 +1,15 @@
+# Auto strategy status
+
+`strategy: :auto` is not exposed in the first public release.
+
+The release-core contract only enables explicit `strategy: :flat` and `strategy: :rtree`. Automatic threshold selection requires a complete project-owned benchmark matrix and explicit approval before it can become public API.
+
+Use `benchmark/flat_vs_rtree.rb` to compare strategies for a workload, then pass the chosen strategy explicitly:
+
+```ruby
+index = TG::Geometry::Index.build(entries, via: :geojson, strategy: :rtree)
+# or
+index = TG::Geometry::Index.build(entries, via: :geojson, strategy: :flat)
+```
+
+Do not infer a universal crossover from rtree internals or from a partial benchmark run.

data/docs/BENCHMARKING.md

@@ -0,0 +1,75 @@
+# Benchmarking
+
+Benchmarks are engineering tools for this gem. They are not marketing claims.
+
+Do not copy upstream TG C benchmark numbers into `tg_geometry` docs. Ruby C extension boundary cost, Ruby object handling, Index construction, batch result arrays, and GC behavior must be measured in this project.
+
+## Required scripts
+
+The repository includes these benchmark entry points:
+
+- `benchmark/parse_throughput.rb`
+- `benchmark/gvl_threshold.rb`
+- `benchmark/flat_vs_rtree.rb`
+- `benchmark/batch_packed_vs_loop.rb`
+- `benchmark/falcon_concurrency.rb`
+- `benchmark/objectspace_memsize.rb`
+- `benchmark/rss_stability.rb`
+
+Run after compiling the extension:
+
+```sh
+bundle exec rake compile
+ruby benchmark/flat_vs_rtree.rb
+```
+
+By default, scripts use a reduced local set of entry sizes so they can be run quickly while developing. Full first-release benchmark scenarios are enabled with:
+
+```sh
+TGEOMETRY_BENCH_FULL=1 ruby benchmark/flat_vs_rtree.rb
+```
+
+## Scenarios
+
+Benchmark generators cover:
+
+- entry counts: 100, 500, 1K, 5K, 50K;
+- compact bboxes;
+- long thin bboxes;
+- overlapping zones;
+- point queries;
+- viewport rect queries;
+- flat vs rtree;
+- scalar vs packed batch;
+- parse small/medium/large geometry strings;
+- RSS stability over repeated build/query/free.
+
+## Output format
+
+Scripts print line-oriented key/value records such as:
+
+```text
+kind=compact n=1000 query=point lon=0.4 lat=0.4 flat_sec=... rtree_sec=... flat_qps=... rtree_qps=...
+```
+
+These records are intentionally plain text so they can be redirected to files and compared across machines.
+
+## No `:auto` strategy yet
+
+The first release does not expose `strategy: :auto`. Choosing a threshold requires project-owned benchmark output across the required scenario matrix. Internal rtree constants such as leaf capacity are not a flat-vs-rtree crossover threshold.
+
+## GVL threshold
+
+`benchmark/gvl_threshold.rb` records baseline parse wall time for several valid WKT payload sizes while the first release keeps the GVL. It does not enable no-GVL execution. A future no-GVL implementation requires a separate design because Ruby C API calls and `RSTRING_PTR` lifetimes are not valid outside the GVL.
+
+## RSS stability
+
+`benchmark/rss_stability.rb` reports start, peak, finish, and delta RSS while repeatedly building, querying, and releasing indexes. CI thresholds should be chosen from observed baseline data on the target CI image, not guessed.
+
+## Falcon / Async
+
+The first release does not claim Falcon or Async behavior. A dedicated Falcon/Async benchmark remains an open setup item until the dependency and scenario are approved.
+
+## Expansion Block A: auto strategy threshold
+
+`strategy: :auto` remains postponed for the first public release. A future implementation must use a complete project-owned benchmark matrix and document the selected threshold before exposing the public option.