tg_geometry 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f50a6c3b237bc983741eaf46a6440220c023dde0d91e8a1e64debb0dd8cf9e
-  data.tar.gz: e07214e6f201842029f415e1dc4c39f77cd9c003187cc9068013f72300f5398a
+  metadata.gz: f3b2fd9ecb971425116e95aed147c0467eba4105b151ff15ba128ef35b10ad6a
+  data.tar.gz: e87484d1ab62a0c21b19c79603ed7da3f0017962543c32b5cd5095cc353a044e
 SHA512:
-  metadata.gz: c80efd671c29339c6023a4b7b616eb0f4eba73513aecea5dea1f239797a8c8c3c4b9a9fd12a1bc69d359a599b3dfc3c4891a8a2073d29e5525083538379b3dea
-  data.tar.gz: '0508a2a6f736791048212c214b75533131c83d0e38029a9b2a13d7860991f882868faeb6237f6305645fc0b4a4819ac0fd21b2c3968006e2a85d2b736425a7ff'
+  metadata.gz: e82e6a1729a0e076fdd16e6c378b3e363a744fddb0b41216d1371a4a7e320234772f829cb38e024b5b397bca630dcb787ae9d31e0cc114e84836ae7cb0bb904e
+  data.tar.gz: '0529e7db75d831d0fa39877ca0ddd4f43d9138c985471f2827bbd92abefc9fec07ad9bba881ec9ba1c157f14a8c5c99be229d2c0fa9c08db73904620e043a029'

data/CHANGELOG.md

@@ -2,102 +2,41 @@
 
 ## 0.1.0 - unreleased
 
-Initial release-core implementation for `tg_geometry`.
+Initial public release candidate 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.
+- Vendored `tidwall/tg`, `tidwall/rtree.c`, and `tidwall/json.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`
+- Index ingestion modes: `via: :geom`, `via: :geojson`, and `via: :wkb`.
+- Index strategies: `:flat` and `:rtree`.
 - Deterministic insertion-order results for flat and rtree queries.
-- Exact rtree memory accounting through a custom malloc/free allocator with headers.
+- Exact rtree memory accounting through a custom malloc/free allocator with allocation 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`
+- GeoJSON FeatureSource APIs for reading FeatureCollection entries/features and building an Index directly from file, JSON string, or IO.
+- FeatureSource bulk execution now runs file read, JSON traversal, and TG geometry parsing in a C-only no-GVL phase before Ruby materialization / Index ownership transfer. The implementation uses Ruby VM no-GVL APIs only: `RB_NOGVL_OFFLOAD_SAFE` when available, otherwise `rb_thread_call_without_gvl`. It does not use a manual Fiber scheduler block/unblock worker path.
+- Ruby-level `TG::Geometry::Registry` reload helper.
+- Optional `TG::Geometry::ActiveRecordSource` helper without a Rails runtime dependency.
+- Benchmark scripts under `benchmark/`.
+- Minimal documentation under `docs/`.
 
 ### 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.
+- `strategy: :auto`.
+- Ractor support claim.
+- no general no-GVL claim for short query/parse/write paths.
+- Full GIS functionality such as routing, projections, geodesics, overlay result geometries, or nearest POI search.
+- Public callback/search APIs.
+- Universal performance claims.
 
-### 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.
+- Suppressed known GCC diagnostics from vendored tidwall/tg wrapper on Linux CI without muting warnings from tg_geometry's own C code.

data/README.md

@@ -1,39 +1,17 @@
 # tg_geometry
 
-`tg_geometry` is a Ruby C extension around the vendored `tidwall/tg` geometry
-library and `tidwall/rtree.c`.
+`tg_geometry` is a Ruby C extension around vendored `tidwall/tg`, `tidwall/rtree.c`, and pinned `tidwall/json.c`.
 
-It exposes the public Ruby namespace `TG::Geometry` and the canonical require
-path:
+It exposes the public Ruby namespace `TG::Geometry`:
 
 ```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.
+The gem is focused on fast in-process planar geometry parsing, predicates, format conversion, GeoJSON FeatureCollection imports, and immutable geofencing indexes. It is not a full GIS system.
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem "tg_geometry"
 ```
@@ -44,17 +22,13 @@ Then run:
 bundle install
 ```
 
-The extension is built from vendored C sources. There is no GEOS, PostGIS,
-PROJ, GDAL, system TG, or system rtree dependency.
+The extension builds from vendored C sources. It does not require GEOS, PostGIS, PROJ, GDAL, system TG, or system rtree.
 
-Supported first-release platforms are Linux and macOS on x86_64/aarch64.
-Windows is not supported in this release.
+Supported platforms: Linux and macOS on x86_64/aarch64. Windows is not supported for the first release.
 
-## Basic parsing and predicates
+## Parsing and predicates
 
 ```ruby
-require "tg/geometry"
-
 zone = TG::Geometry.parse_geojson(<<~JSON)
   {
     "type": "Polygon",
@@ -67,16 +41,11 @@ 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
+zone.to_wkt
+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
+Parse shortcuts:
 
 ```ruby
 TG::Geometry.parse(str, format: :auto, index: :ystripes)
@@ -87,62 +56,12 @@ 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`
+`TG::Geometry::Geom` objects are immutable and cannot be manually allocated or manually freed from Ruby.
 
-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
+## Rect
 
 ```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)
@@ -150,16 +69,10 @@ 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?`.
+`Rect` rejects non-finite coordinates and invalid coordinate order. It is frozen after construction.
 
 ## 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]]]}'],
@@ -183,7 +96,7 @@ index.covering_ids(5, 5)    # => [:zone_a]
 index.intersecting_rect(0, 0, 25, 25)
 ```
 
-Accepted input format:
+Accepted input shape:
 
 ```ruby
 [[id1, object1], [id2, object2], ...]
@@ -194,17 +107,13 @@ 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.
+- Returned ids are the same Ruby objects stored in the index.
 - 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.
+- `:geom` — borrow an existing `TG::Geometry::Geom` and keep its owner alive.
 - `:geojson` — parse and own native TG geometries inside the index.
 - `:wkb` — parse and own native TG geometries inside the index.
 
@@ -213,21 +122,61 @@ 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.
+- `:contains` — stricter containment semantics.
 
-## Packed batch point queries
+`strategy: :auto` is intentionally not exposed. Choose the strategy explicitly and benchmark on your own data.
+
+## GeoJSON FeatureSource
+
+`TG::Geometry::FeatureSource` reads GeoJSON `FeatureCollection` sources without `JSON.parse` of the whole document into Ruby Hash/Array objects.
+
+```ruby
+entries = TG::Geometry::FeatureSource.read_entries_file(
+  "zones.geojson",
+  id: ["properties", "@id"],
+  only: [:polygon, :multipolygon]
+)
+
+index = TG::Geometry::Index.build(
+  entries,
+  via: :geojson,
+  strategy: :rtree,
+  predicate: :covers
+)
+```
+
+For imports that also need raw properties JSON:
+
+```ruby
+features = TG::Geometry::FeatureSource.read_features_file(
+  "zones.geojson",
+  id: ["properties", "@id"],
+  report: true,
+  on_invalid: :skip
+)
+
+features[:features].each do |id, geometry_json, properties_json|
+  # Store geometry_json and parse properties_json in application code if needed.
+end
+```
+
+For direct file-to-index loading:
+
+```ruby
+index = TG::Geometry::FeatureSource.build_index_file(
+  "zones.geojson",
+  id: ["properties", "@id"],
+  strategy: :rtree,
+  predicate: :covers
+)
+```
 
-For high-throughput same-process point lookups, the index supports a packed
-native-endian double input format:
+FeatureSource methods are explicit: use `_file` for paths, `_json` for raw content strings, and `_io` for IO objects. There is no path/content auto-detection.
+
+## Packed batch point queries
 
 ```ruby
 points = [5.0, 5.0, 25.0, 25.0].pack("d*")
@@ -235,18 +184,9 @@ 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 `[]`.
+Input is a Ruby String containing native-endian doubles in `lon, lat` pairs. 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 helper
 
 `Registry` is Ruby-level sugar over immutable indexes:
 
@@ -266,53 +206,15 @@ 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.
+Reload builds a new immutable index first and swaps the reference only after a successful build. Existing readers keep using the previous index safely.
 
-## Memory ownership model
+## Memory and concurrency
 
-The implementation uses explicit allocator pairs and GC accounting:
+The implementation uses explicit allocator pairs and Ruby GC accounting for native memory. `ObjectSpace.memsize_of(index)` includes entries, owned TG geometries, and exact rtree allocation bytes. Borrowed geometries are not double-counted by the index.
 
-| 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` |
+`Index` and `Geom` are immutable after construction. Concurrent read-only use from normal Ruby threads is supported. Short query/parse/write paths keep the GVL. FeatureSource bulk loading uses a C-only no-GVL heavy phase for file read, JSON traversal, and TG geometry parsing, then reacquires the GVL to create Ruby objects or transfer ownership into the final Index. On Ruby versions that expose `RB_NOGVL_OFFLOAD_SAFE`, that no-GVL phase is marked offload-safe for the Ruby VM. On older Rubies it still releases the GVL for other Ruby threads, but no explicit Fiber scheduler friendliness is claimed.
 
-`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`.
+No Ractor support and no universal performance claim are advertised.
 
 ## Benchmarks
 
@@ -326,19 +228,16 @@ 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
+bundle exec ruby benchmark/feature_source.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.
+The benchmarks are engineering tools, not marketing claims.
 
 ## Limitations
 
 `tg_geometry` is not a full GIS system.
 
-Not included in this release:
+Not included:
 
 - geocoding;
 - routing;
@@ -346,17 +245,14 @@ Not included in this release:
 - geodesic distance/area;
 - buffer / union / difference / overlay result geometry operations;
 - nearest POI index;
-- Rails dependency in the core extension;
+- Rails dependency in the native 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.
+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.
 
 ## Development
 
@@ -369,17 +265,12 @@ 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
+bundle exec rspec spec/batch_packed_spec.rb
+bundle exec rspec spec/memory_gc_spec.rb
+bundle exec rspec spec/concurrency_spec.rb
+bundle exec rspec spec/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/`.
+MIT. Vendored upstream license files for `tidwall/tg`, `tidwall/rtree.c`, and `tidwall/json.c` are included under `ext/tg_geometry/vendor/`.

data/Rakefile

@@ -82,7 +82,7 @@ begin
     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"
+      task.pattern = "spec/geom_parse_spec.rb spec/index_build_spec.rb spec/index_borrowed_geometry_spec.rb spec/memory_gc_spec.rb"
     end
   end
 rescue LoadError
@@ -109,12 +109,12 @@ namespace :benchmark do
 end
 
 namespace :vendor do
-  desc "Sync vendored tidwall/tg and rtree.c sources to pinned commits"
+  desc "Sync vendored 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"
+  desc "Verify vendored C sources against pinned tree SHA256"
   task :verify do
     ruby "script/vendor_libs.rb", "--verify"
   end

data/benchmark/falcon_concurrency.rb

@@ -4,7 +4,7 @@ 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."
+puts "Falcon/Async behavior remains an Pending decision until Roman approves a dedicated dependency/setup."
 
 entries = TGGeometryBench.compact_entries(1_000)
 index = TGGeometryBench.build_index(entries, strategy: :rtree)

data/benchmark/feature_source.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+require "json"
+require "tempfile"
+
+module FeatureSourceBenchData
+  module_function
+
+  def feature_collection(count)
+    features = Array.new(count) do |i|
+      x = i % 250
+      y = i / 250
+      <<~JSON.chomp
+        {"type":"Feature","properties":{"@id":"zone/#{i}","name":"Zone #{i}"},"geometry":#{TGGeometryBench.box_geojson(x, y, x + 0.8, y + 0.8)}}
+      JSON
+    end
+
+    %({"type":"FeatureCollection","features":[#{features.join(",")}]} )
+  end
+
+  def write_temp_geojson(json)
+    file = Tempfile.new(["tg_geometry_feature_source", ".geojson"])
+    file.binmode
+    file.write(json)
+    file.flush
+    file
+  end
+
+  def ruby_json_parse_entries(path)
+    parsed = JSON.parse(File.binread(path))
+    parsed.fetch("features").filter_map do |feature|
+      geometry = feature["geometry"]
+      next unless %w[Polygon MultiPolygon].include?(geometry["type"])
+
+      [feature.fetch("properties").fetch("@id"), JSON.generate(geometry)]
+    end
+  end
+end
+
+TGGeometryBench.say_header("feature_source")
+
+sizes = ENV["TGEOMETRY_BENCH_FULL"] == "1" ? [100, 1_000, 10_000, 50_000] : [100, 1_000]
+
+sizes.each do |size|
+  json = FeatureSourceBenchData.feature_collection(size)
+  file = FeatureSourceBenchData.write_temp_geojson(json)
+  path = file.path
+
+  begin
+    ruby_entries = nil
+    feature_entries = nil
+    feature_rows = nil
+    direct_index = nil
+    roundtrip_index = nil
+
+    ruby_time = Benchmark.realtime do
+      ruby_entries = FeatureSourceBenchData.ruby_json_parse_entries(path)
+    end
+
+    read_entries_time = Benchmark.realtime do
+      feature_entries = TG::Geometry::FeatureSource.read_entries_file(path, id: ["properties", "@id"])
+    end
+
+    read_features_time = Benchmark.realtime do
+      feature_rows = TG::Geometry::FeatureSource.read_features_file(path, id: ["properties", "@id"])
+    end
+
+    direct_index_time = Benchmark.realtime do
+      direct_index = TG::Geometry::FeatureSource.build_index_file(path, id: ["properties", "@id"], strategy: :rtree)
+    end
+
+    roundtrip_index_time = Benchmark.realtime do
+      roundtrip_index = TG::Geometry::Index.build(feature_entries, via: :geojson, strategy: :rtree)
+    end
+
+    puts "n=#{size} ruby_json_parse_sec=%.6f read_entries_sec=%.6f read_features_sec=%.6f build_index_direct_sec=%.6f build_index_from_entries_sec=%.6f entries=%d features=%d direct_size=%d roundtrip_size=%d rss_kb=%d" % [
+      ruby_time,
+      read_entries_time,
+      read_features_time,
+      direct_index_time,
+      roundtrip_index_time,
+      ruby_entries.length,
+      feature_rows.length,
+      direct_index.size,
+      roundtrip_index.size,
+      TGGeometryBench.rss_kb
+    ]
+  ensure
+    file.close!
+  end
+end