tg_geometry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01f50a6c3b237bc983741eaf46a6440220c023dde0d91e8a1e64debb0dd8cf9e
+  data.tar.gz: e07214e6f201842029f415e1dc4c39f77cd9c003187cc9068013f72300f5398a
+SHA512:
+  metadata.gz: c80efd671c29339c6023a4b7b616eb0f4eba73513aecea5dea1f239797a8c8c3c4b9a9fd12a1bc69d359a599b3dfc3c4891a8a2073d29e5525083538379b3dea
+  data.tar.gz: '0508a2a6f736791048212c214b75533131c83d0e38029a9b2a13d7860991f882868faeb6237f6305645fc0b4a4819ac0fd21b2c3968006e2a85d2b736425a7ff'

data/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## 0.1.0 - unreleased
+
+Initial release-core implementation for `tg_geometry`.
+
+### Added
+
+- Canonical public require path: `require "tg/geometry"`.
+- Public namespace: `TG::Geometry`.
+- Native extension build through `ext/tg_geometry/extconf.rb`.
+- Vendored `tidwall/tg` and `tidwall/rtree.c` sources with pinned `VERSION` files and upstream license files.
+- Error classes:
+  - `TG::Geometry::Error`
+  - `TG::Geometry::ParseError`
+  - `TG::Geometry::ArgumentError < ::ArgumentError`
+  - `TG::Geometry::FrozenIndexError`
+- Immutable `TG::Geometry::Geom` parsing for GeoJSON, WKT, WKB, Hex, GeoBIN, and auto format detection.
+- `TG::Geometry::Geom` methods:
+  - `#type`
+  - `#bbox`
+  - `#covers_xy?`
+  - `#contains?`
+  - `#intersects?`
+  - `#to_geojson`
+  - `#to_wkt`
+  - `#to_wkb`
+- Immutable `TG::Geometry::Rect` API.
+- Immutable `TG::Geometry::Index.build` with strict `[[id, object], ...]` entry format.
+- Index ingestion modes:
+  - `via: :geom` borrowed geometry with `geom_owner` lifetime protection;
+  - `via: :geojson` owned geometry;
+  - `via: :wkb` owned geometry.
+- Index strategies:
+  - `:flat`
+  - `:rtree`
+- Deterministic insertion-order results for flat and rtree queries.
+- Exact rtree memory accounting through a custom malloc/free allocator with headers.
+- Native-endian packed point batch API: `TG::Geometry::Index#covering_ids_batch_packed`.
+- Debug-only test hooks under `TG_DEBUG_TEST=1` for allocation failure simulation and byte counter inspection.
+- Block 14 memory/GC/compaction hardening specs.
+- Benchmark harnesses:
+  - `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`
+- Documentation:
+  - `docs/ARCHITECTURE.md`
+  - `docs/MEMORY_OWNERSHIP.md`
+  - `docs/CONCURRENCY.md`
+  - `docs/ERROR_HANDLING.md`
+  - `docs/BENCHMARKING.md`
+  - `docs/LIMITATIONS.md`
+  - `docs/RELEASE_CHECKLIST.md`
+
+### Not included
+
+- `strategy: :auto` is not part of the release-core contract; it is tracked as Expansion Block A below.
+- No Ractor support claim.
+- No no-GVL execution.
+- No full GIS, routing, geocoding, projections, geodesic helpers, nearest POI index, or result-geometry overlay operations.
+- No public performance claims until benchmark results are produced by this gem.
+
+### OPEN QUESTION
+
+- Final ASAN setup requires Roman approval before replacing the placeholder CI job.
+- Final Valgrind setup requires Roman approval before replacing the placeholder CI job.
+
+## Unreleased
+
+### Added
+
+- Expansion Block A status: `strategy: :auto` remains postponed for the first public release; explicit `:flat` / `:rtree` strategies are required.
+- Expansion Block B: `TG::Geometry::Registry` Ruby helper for immutable Index reload/swap workflows.
+- Expansion Block C: optional `TG::Geometry::ActiveRecordSource` helper that converts relation-like records into strict `[[id, object], ...]` entries without adding a Rails dependency.
+- Expansion Block D: `TG::Geometry.parse_hex`, `TG::Geometry.parse_geobin`, `TG::Geometry::Geom#to_hex`, `#to_geobin`, and `#extra_json`.
+- Expansion Block E: read-only borrowed low-level wrappers: `TG::Geometry::Line`, `TG::Geometry::Ring`, `TG::Geometry::Polygon`, plus `TG::Geometry::Geom#point`, `#line`, and `#polygon`.
+- Expansion Block I: Ractor unsupported-boundary investigation documented in `docs/RACTOR.md` with specs asserting native wrappers are not treated as shareable Ractor objects.
+- Expansion Block J grouped API coverage:
+  - safe point and empty geometry constructors;
+  - additional `TG::Geometry::Geom` predicates;
+  - geometry metadata and Z/M read accessors;
+  - MultiPoint/MultiLineString/MultiPolygon and GeometryCollection accessors;
+  - borrowed child `TG::Geometry::Geom` wrappers with `geom_owner`;
+  - value `TG::Geometry::Segment` wrappers from Line/Ring segment accessors.
+
+### Fixed
+
+- Corrected `benchmark/gvl_threshold.rb` so each target size uses a valid WKT payload near that size instead of repeatedly benchmarking the same tiny polygon.
+
+### Documentation
+
+- Added docs for Registry, ActiveRecord source helper, additional format coverage, low-level borrowed geometry wrappers, Ractor unsupported-boundary status, grouped full TG API coverage, Auto Strategy postponed status, and Expansion Blocks E–H status.
+
+### OPEN QUESTION
+
+- Expansion Block F callback/search APIs remain blocked until a callback safety contract, exception semantics, GVL rules, and callback overhead benchmarks are approved.
+- Expansion Block G no-allocation point query optimization remains blocked until boundary/hole-boundary equivalence tests and benchmarks prove it preserves `:covers` / `:contains` semantics.
+- Expansion Block H geodesic/projection helpers remain blocked until an explicit optional dependency/API decision is approved.
+- Remaining Expansion Block J scope such as Line/Ring/Polygon constructors, callback/search APIs, nearest segment APIs, global environment configuration, and allocator override APIs remains blocked until separate ownership/thread-safety contracts are approved.

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Haydarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,385 @@
+# tg_geometry
+
+`tg_geometry` is a Ruby C extension around the vendored `tidwall/tg` geometry
+library and `tidwall/rtree.c`.
+
+It exposes the public Ruby namespace `TG::Geometry` and the canonical require
+path:
+
+```ruby
+require "tg/geometry"
+```
+
+The gem targets fast in-process planar geometry parsing, predicates,
+format conversion, and geofencing-oriented immutable indexes. It does not try
+to be a full GIS system.
+
+## Status
+
+This repository is prepared as a first public release candidate with an
+expanded API surface:
+
+- release-core `Geom`, `Rect`, and immutable `Index` APIs;
+- expanded format coverage for Hex and GeoBIN;
+- read-only borrowed wrappers for lower-level TG geometry components;
+- `Registry` reload/swap sugar;
+- optional ActiveRecord-style source helpers that do not add a Rails runtime
+  dependency.
+
+`strategy: :auto`, Ractor support, callback/search APIs, no-allocation point
+query optimization, geodesic helpers, projections, and no-GVL execution are not
+claimed in this release.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "tg_geometry"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+The extension is built from vendored C sources. There is no GEOS, PostGIS,
+PROJ, GDAL, system TG, or system rtree dependency.
+
+Supported first-release platforms are Linux and macOS on x86_64/aarch64.
+Windows is not supported in this release.
+
+## Basic parsing and predicates
+
+```ruby
+require "tg/geometry"
+
+zone = TG::Geometry.parse_geojson(<<~JSON)
+  {
+    "type": "Polygon",
+    "coordinates": [[[0,0], [10,0], [10,10], [0,10], [0,0]]]
+  }
+JSON
+
+zone.frozen?          # => true
+zone.type             # => :polygon
+zone.covers_xy?(5, 5) # => true
+zone.covers_xy?(0, 0) # => true, boundary is covered
+zone.bbox             # => #<TG::Geometry::Rect ...>
+
+wkt = zone.to_wkt
+wkb = zone.to_wkb
+```
+
+`TG::Geometry::Geom` objects are immutable. They cannot be manually allocated or
+manually freed from Ruby. Native memory is released by Ruby GC through the typed
+data wrapper.
+
+## Parse API
+
+```ruby
+TG::Geometry.parse(str, format: :auto, index: :ystripes)
+TG::Geometry.parse_geojson(str, index: :ystripes)
+TG::Geometry.parse_wkt(str, index: :ystripes)
+TG::Geometry.parse_wkb(bytes, index: :ystripes)
+TG::Geometry.parse_hex(str, index: :ystripes)
+TG::Geometry.parse_geobin(bytes, index: :ystripes)
+```
+
+Accepted `format:` values for `parse` are:
+
+- `:auto`
+- `:geojson`
+- `:wkt`
+- `:wkb`
+- `:hex`
+- `:geobin`
+
+Accepted TG internal polygon index values are:
+
+- `:default`
+- `:none`
+- `:natural`
+- `:ystripes`
+
+Parse failures raise `TG::Geometry::ParseError`. Invalid options raise
+`TG::Geometry::ArgumentError`, which inherits from Ruby's `::ArgumentError`.
+
+## Geom API
+
+Release-core methods:
+
+```ruby
+geom.type
+geom.bbox
+geom.covers_xy?(x, y)
+geom.contains?(other_geom)
+geom.intersects?(other_geom)
+geom.to_geojson
+geom.to_wkt
+geom.to_wkb
+```
+
+Expanded methods include additional predicates, format writers, metadata
+accessors, and read-only borrowed child wrappers. See:
+
+- `docs/FORMAT_COVERAGE.md`
+- `docs/LOW_LEVEL_GEOMETRY.md`
+- `docs/FULL_TG_API_COVERAGE.md`
+
+For point predicates, this release prioritizes exact `covers` / `contains`
+semantics over the fastest possible no-allocation path. Query methods construct
+a temporary TG point geometry and free it before returning. A future optimized
+point path requires boundary and hole-boundary equivalence tests plus benchmark
+proof.
+
+## Rect API
+
+```ruby
+rect = TG::Geometry::Rect.new(0, 0, 10, 10)
+
+rect.min_x
+rect.min_y
+rect.max_x
+rect.max_y
+rect.center                  # => [5.0, 5.0]
+rect.contains_point?(5, 5)   # => true
+rect.intersects?(other_rect)
+rect.expand_to_include(other_rect)
+rect.expand_to_include_point(x, y)
+```
+
+`Rect` rejects non-finite coordinates and invalid coordinate order. It is frozen
+after construction.
+
+There is intentionally no first-release `Rect#contains?` method because the name
+is ambiguous. Use `contains_point?`.
+
+## Immutable Index
+
+`TG::Geometry::Index` is built once and then read-only forever.
+
+```ruby
+entries = [
+  [:zone_a, '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}'],
+  [:zone_b, '{"type":"Polygon","coordinates":[[[20,20],[30,20],[30,30],[20,30],[20,20]]]}']
+]
+
+index = TG::Geometry::Index.build(
+  entries,
+  via: :geojson,
+  strategy: :rtree,
+  predicate: :covers,
+  geometry_index: :ystripes
+)
+
+index.frozen?               # => true
+index.size                  # => 2
+index.strategy              # => :rtree
+index.predicate             # => :covers
+index.find_covering(5, 5)   # => :zone_a
+index.covering_ids(5, 5)    # => [:zone_a]
+index.intersecting_rect(0, 0, 25, 25)
+```
+
+Accepted input format:
+
+```ruby
+[[id1, object1], [id2, object2], ...]
+```
+
+Rules:
+
+- `entries` must be an Array.
+- Every entry must be a two-element Array.
+- `id` may be any Ruby object except `nil`.
+- `false` ids are accepted, but discouraged because `find_covering` uses `nil`
+  for no match.
+- Duplicate ids are allowed.
+- Returned ids are the same Ruby objects stored in the index; they are not
+  copied, frozen, stringified, or duplicated.
+- Result order is insertion order for both `:flat` and `:rtree`.
+
+Accepted `via:` modes:
+
+- `:geom` — borrow an existing `TG::Geometry::Geom`; the index marks the owner
+  wrapper so the borrowed native pointer remains valid.
+- `:geojson` — parse and own native TG geometries inside the index.
+- `:wkb` — parse and own native TG geometries inside the index.
+
+Accepted strategies:
+
+- `:flat`
+- `:rtree`
+
+`strategy: :auto` is not exposed in this release. The benchmark output does not
+support a single universal threshold: flat scan may win for early insertion-order
+hits or heavily overlapping datasets, while rtree may win for misses, later hits,
+or selective rectangle queries. Choose the strategy explicitly and benchmark on
+your own data.
+
+Accepted predicates:
+
+- `:covers` — default for geofencing; boundary points are included.
+- `:contains` — stricter OGC-style containment semantics.
+
+## Packed batch point queries
+
+For high-throughput same-process point lookups, the index supports a packed
+native-endian double input format:
+
+```ruby
+points = [5.0, 5.0, 25.0, 25.0].pack("d*")
+index.covering_ids_batch_packed(points)
+# => [:zone_a, :zone_b]
+```
+
+Input format:
+
+- Ruby String treated as raw bytes.
+- Native-endian doubles.
+- Pairs of `lon, lat`.
+- Length must be a multiple of 16 bytes.
+- Empty string returns `[]`.
+
+This format is intentionally native-endian for same-process speed and simplicity.
+Do not use it as a cross-platform serialized file format.
+
+## Registry reload pattern
+
+`Registry` is Ruby-level sugar over immutable indexes:
+
+```ruby
+class DeliveryZones < TG::Geometry::Registry
+  source do
+    [
+      [:zone_a, '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}']
+    ]
+  end
+
+  index_options via: :geojson, strategy: :rtree, predicate: :covers
+end
+
+registry = DeliveryZones.new
+registry.reload!
+registry.find_covering(5, 5)
+```
+
+Reload builds a new full immutable index first and swaps the reference only after
+successful build:
+
+```ruby
+new_index = TG::Geometry::Index.build(entries, via: :geojson, strategy: :rtree)
+@index = new_index
+```
+
+Old indexes remain alive while existing readers hold references to them. There
+is no in-place mutation, no public `add`, `delete`, `clear`, or `rebuild!` API on
+`Index`.
+
+See `docs/REGISTRY.md` and `docs/ACTIVE_RECORD.md` for the expanded helpers.
+
+## Memory ownership model
+
+The implementation uses explicit allocator pairs and GC accounting:
+
+| Resource | Allocator | Deallocator | Owner |
+|---|---|---|---|
+| `tg_geom_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby `Geom` object |
+| TG geometry in `Geom` | TG parser/constructor | `tg_geom_free` | `Geom` wrapper |
+| `tg_index_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby `Index` object |
+| Index entries array | `calloc` | `free` | `Index` |
+| TG geometry via `:geojson` / `:wkb` | TG parser | `tg_geom_free` | `Index` |
+| TG geometry via `:geom` | Existing `Geom` wrapper | Existing `Geom` wrapper | Borrowed by `Index` through `geom_owner` |
+| rtree internals | custom `tg_rtree_malloc` with header | custom `tg_rtree_free` | rtree / `Index` accounting |
+| Ruby ids | Ruby VM | Ruby GC | Marked and compacted by `Index` |
+
+`ObjectSpace.memsize_of(index)` includes entries, owned TG geometries, and exact
+rtree allocation bytes. Borrowed geometries are not double-counted by the index.
+
+See `docs/MEMORY_OWNERSHIP.md` for the full table and cleanup rules.
+
+## Concurrency model
+
+`Index` and `Geom` are immutable after construction. Concurrent read-only use
+from normal Ruby threads is supported by design and covered by tests.
+
+The first release keeps GVL for parse, write, query, batch, and rtree build/free
+paths. This is intentional: the rtree allocator calls Ruby GC accounting APIs,
+and no-GVL execution would require separate input-copying and allocator-accounting
+design.
+
+No Ractor support is claimed.
+
+See `docs/CONCURRENCY.md` and `docs/RACTOR.md`.
+
+## Benchmarks
+
+Benchmark scripts live in `benchmark/`:
+
+```bash
+bundle exec ruby benchmark/parse_throughput.rb
+bundle exec ruby benchmark/flat_vs_rtree.rb
+bundle exec ruby benchmark/batch_packed_vs_loop.rb
+bundle exec ruby benchmark/objectspace_memsize.rb
+bundle exec ruby benchmark/rss_stability.rb
+bundle exec ruby benchmark/gvl_threshold.rb
+bundle exec ruby benchmark/falcon_concurrency.rb
+```
+
+By default, benchmarks use a fast local matrix. Set `TGEOMETRY_BENCH_FULL=1` for
+the larger matrix where supported.
+
+The repository benchmarks are engineering tools, not universal marketing claims.
+Do not copy upstream TG C benchmark numbers as Ruby gem performance claims.
+
+## Limitations
+
+`tg_geometry` is not a full GIS system.
+
+Not included in this release:
+
+- geocoding;
+- routing;
+- projections;
+- geodesic distance/area;
+- buffer / union / difference / overlay result geometry operations;
+- nearest POI index;
+- Rails dependency in the core extension;
+- Redis or external service dependency;
+- public callback/search APIs;
+- Ractor support claim;
+- no-GVL execution claim;
+- universal `:auto` strategy.
+
+TG works in planar XY coordinates. If lon/lat coordinates are passed in, length,
+area, and perimeter-style values are in input coordinate units, not meters.
+Use PostGIS, GEOS, PROJ, or other GIS tooling when full GIS functionality is
+needed.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake compile
+bundle exec rake spec
+```
+
+Useful targeted checks:
+
+```bash
+bundle exec rspec spec/block_12_batch_packed_spec.rb
+bundle exec rspec spec/block_14_memory_gc_hardening_spec.rb
+bundle exec rspec spec/block_20_concurrency_spec.rb
+bundle exec rspec spec/block_20_fuzz_spec.rb
+```
+
+Memory-tool CI jobs for ASAN and Valgrind are intentionally left as OPEN QUESTION
+placeholders until the exact setup is approved. Do not replace them with guessed
+configuration.
+
+## License
+
+MIT. Vendored upstream license files for `tidwall/tg` and `tidwall/rtree.c` are
+included under `ext/tg_geometry/vendor/`.

data/Rakefile

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "fileutils"
+require "rbconfig"
+require "rake/clean"
+
+EXT_NAME = "tg_geometry_ext_geometry_ext"
+EXT_DIR = File.expand_path("ext/tg_geometry", __dir__)
+LIB_DIR = File.expand_path("lib", __dir__)
+DLEXT = RbConfig::CONFIG.fetch("DLEXT")
+PLATFORM = RbConfig::CONFIG.fetch("arch")
+BUILD_RUBY_VERSION = RUBY_VERSION
+BUILD_DIR = File.expand_path(File.join("tmp", PLATFORM, EXT_NAME, BUILD_RUBY_VERSION), __dir__)
+EXT_SO = File.join(EXT_DIR, "#{EXT_NAME}.#{DLEXT}")
+LIB_SO = File.join(LIB_DIR, "#{EXT_NAME}.#{DLEXT}")
+
+EXT_BUILD_GLOBS = [
+  File.join(EXT_DIR, "Makefile"),
+  File.join(EXT_DIR, "mkmf.log"),
+  File.join(EXT_DIR, "*.o"),
+  File.join(EXT_DIR, "*.so"),
+  File.join(EXT_DIR, "*.bundle"),
+  File.join(EXT_DIR, "*.dll"),
+  File.join(EXT_DIR, "*.dylib")
+].freeze
+
+CLEAN.include(
+  "tmp",
+  "lib/*.so",
+  "lib/*.bundle",
+  "lib/*.dll",
+  "lib/*.dylib",
+  *EXT_BUILD_GLOBS
+)
+
+# Keep the source tree clean like pq_crypto: ext/tg_geometry contains the checked-in
+# extension sources and ext/tg_geometry/vendor contains the checked-in vendored C
+# sources, while Makefile/mkmf.log/object/shared-library build outputs live in tmp/.
+def remove_in_place_extension_artifacts!
+  EXT_BUILD_GLOBS.each { |pattern| FileUtils.rm_f(Dir[pattern]) }
+end
+
+def build_extension!(debug: false)
+  remove_in_place_extension_artifacts!
+  FileUtils.rm_rf(BUILD_DIR)
+  FileUtils.mkdir_p(BUILD_DIR)
+
+  env = debug ? { "TG_DEBUG_TEST" => "1" } : {}
+  Dir.chdir(BUILD_DIR) do
+    sh(env, RbConfig.ruby, File.join(EXT_DIR, "extconf.rb"))
+    sh "make"
+  end
+
+  FileUtils.mkdir_p(LIB_DIR)
+  FileUtils.cp(File.join(BUILD_DIR, "#{EXT_NAME}.#{DLEXT}"), LIB_SO)
+end
+
+desc "Compile the native extension into tmp/ and copy it to lib/"
+task "compile" do
+  build_extension!(debug: false)
+end
+
+desc "Compile the native extension with test-only debug hooks"
+task "compile:test" do
+  build_extension!(debug: true)
+end
+
+begin
+  require "rspec/core/rake_task"
+
+  RSpec::Core::RakeTask.new(:spec => "compile:test")
+
+  task :gc_stress_env do
+    ENV["RUBY_GC_STRESS"] = "1"
+  end
+
+  namespace :spec do
+    RSpec::Core::RakeTask.new(:gc_stress => ["compile:test", "gc_stress_env"]) do |task|
+      task.rspec_opts = ["--tag", "~skip"]
+      task.verbose = true
+    end
+
+    RSpec::Core::RakeTask.new(:gc_compact => "compile:test") do |task|
+      task.pattern = "spec/block_3_geom_parse_spec.rb spec/block_6_index_build_spec.rb spec/block_8_index_borrowed_geometry_spec.rb spec/block_14_memory_gc_hardening_spec.rb"
+    end
+  end
+rescue LoadError
+  task :spec do
+    abort "RSpec is required to run the test suite. Install development dependencies with bundle install."
+  end
+
+  namespace :spec do
+    task :gc_stress => :spec
+    task :gc_compact => :spec
+  end
+end
+
+namespace :benchmark do
+  Dir[File.join(__dir__, "benchmark", "*.rb")].sort.each do |path|
+    next if File.basename(path).start_with?("_")
+
+    name = File.basename(path, ".rb")
+    desc "Run benchmark/#{name}.rb"
+    task name => :compile do
+      ruby path
+    end
+  end
+end
+
+namespace :vendor do
+  desc "Sync vendored tidwall/tg and rtree.c sources to pinned commits"
+  task :sync do
+    ruby "script/vendor_libs.rb", "--sync"
+  end
+
+  desc "Verify vendored tidwall/tg and rtree.c sources against pinned tree SHA256"
+  task :verify do
+    ruby "script/vendor_libs.rb", "--verify"
+  end
+end
+
+desc "Alias for vendor:sync"
+task vendor: "vendor:sync"
+
+desc "Vendor sources, compile, run specs"
+task full_build: ["vendor:verify", "compile", "spec"]
+
+task default: :spec