tg_geometry 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f50a6c3b237bc983741eaf46a6440220c023dde0d91e8a1e64debb0dd8cf9e
-  data.tar.gz: e07214e6f201842029f415e1dc4c39f77cd9c003187cc9068013f72300f5398a
+  metadata.gz: fdc6ab78992bee6ba1708b13adfdb0e4eec26fef04c4fc8eae87df21fbfed5fa
+  data.tar.gz: ada3eff77de10cb101cbedbd35e2d40e119fe37c5a09003afe9df1ab266827fe
 SHA512:
-  metadata.gz: c80efd671c29339c6023a4b7b616eb0f4eba73513aecea5dea1f239797a8c8c3c4b9a9fd12a1bc69d359a599b3dfc3c4891a8a2073d29e5525083538379b3dea
-  data.tar.gz: '0508a2a6f736791048212c214b75533131c83d0e38029a9b2a13d7860991f882868faeb6237f6305645fc0b4a4819ac0fd21b2c3968006e2a85d2b736425a7ff'
+  metadata.gz: 87200faec4b6d0442eab7df12f768807193aed725bb75b25502a64cc5b2e24e97f2f9d98cf9254c54e3f62d9b0481f39dc2287818f69a740e9728a33e97d9f0b
+  data.tar.gz: 3e14f4563facef36fc109e1c8006b707502bb384f67c1c27da05faa7dcec7b7a7970d82a22d39ac99c00595c74944c7a6467fa81a5cdd1d14129df70f4d3675a

data/CHANGELOG.md

@@ -1,103 +1,79 @@
 # Changelog
 
+## 0.3.0 - 27.05.2026
+
+### Added
+
+- `TG::Geometry.line_string`, `TG::Geometry.polygon`, and `TG::Geometry.multi_polygon` constructors from Ruby arrays.
+- `TG::Geometry::Geom#srid` with automatic EWKB SRID extraction in `parse_wkb` and `parse_hex`.
+- `TG::Geometry::Geom#to_ewkb` writer with explicit `srid:` override.
+- `TG::Geometry::Index#intersecting_geom_ids`, `#covering_geom_ids`, and `#containing_geom_ids`.
+- `TG::Geometry::Line#nearest_segment` and `TG::Geometry::Ring#nearest_segment` with `TG::Geometry::NearestSegment` result objects.
+- `TG::Geometry::ActiveRecordType` read-only optional require.
+- PostGIS/EWKB fixture suite in `spec/fixtures/postgis/`.
+
+### Fixed
+
+- Reject unsupported/unknown keywords on v0.3.0 APIs instead of silently ignoring them, including non-goals such as `release_gvl:`, `parse_wkb(srid:)`, and `parse_wkb(ewkb:)`.
+- Harden constructor cleanup paths so intermediate C `tg_ring` / `tg_poly` objects are released when Ruby exceptions occur during nested polygon construction.
+- Keep geometry-index query collection in a C-only status-returning phase before Ruby result materialization, preserving the intended no-GVL-safe internal shape.
+
+### Clarified
+
+- `Index.build(predicate:)` affects only legacy point query methods: `find_covering`, `covering_ids(x, y)`, and `covering_ids_batch_packed`.
+
+### Not included
+
+- Geodesic / Haversine distance.
+- Projection / reprojection.
+- Buffer / union / difference / convex hull.
+- Index nearest_ids (KNN).
+- GeoBIN bbox helpers.
+- Streaming FeatureSource.
+- Index serialization / mmap.
+- Ractor support.
+- Windows / JRuby.
+- Write-side ActiveRecordType / AR scopes / migrations.
+- Z/M variants of constructors.
+- Public `release_gvl:` option.
+
 ## 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.
-
-### 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
+- `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.
 
-- 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,50 @@ TG::Geometry.parse_hex(str, index: :ystripes)
 TG::Geometry.parse_geobin(bytes, index: :ystripes)
 ```
 
-Accepted `format:` values for `parse` are:
+`TG::Geometry::Geom` objects are immutable and cannot be manually allocated or manually freed from Ruby.
 
-- `:auto`
-- `:geojson`
-- `:wkt`
-- `:wkb`
-- `:hex`
-- `:geobin`
+## Constructors
 
-Accepted TG internal polygon index values are:
+Construct simple planar geometries directly from Ruby arrays without parsing strings or bytes:
 
-- `:default`
-- `:none`
-- `:natural`
-- `:ystripes`
+```ruby
+line = TG::Geometry.line_string([[0.0, 0.0], [10.0, 0.0]], index: :natural, srid: 4326)
+poly = TG::Geometry.polygon(
+  [[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]],
+  holes: [[[2, 2], [4, 2], [4, 4], [2, 4], [2, 2]]],
+  index: :ystripes,
+  srid: 4326
+)
+mp = TG::Geometry.multi_polygon([
+  { exterior: [[0, 0], [1, 0], [1, 1], [0, 0]], holes: [] },
+  [[10, 10], [11, 10], [11, 11], [10, 10]]
+])
+```
 
-Parse failures raise `TG::Geometry::ParseError`. Invalid options raise
-`TG::Geometry::ArgumentError`, which inherits from Ruby's `::ArgumentError`.
+Constructors are strict: rings must already be closed, invalid coordinates raise `TG::Geometry::ArgumentError`, and no winding/self-intersection fixes are performed. `srid:` is metadata on the wrapper; it does not alter coordinates or perform reprojection.
 
-## Geom API
+## SRID and EWKB
 
-Release-core methods:
+`parse_wkb` and `parse_hex` preserve EWKB SRID metadata when the EWKB SRID flag is present:
 
 ```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
+geom = TG::Geometry.parse_wkb(postgis_bytea)
+geom.srid # => 4326, 3857, 0, or nil for plain WKB
 ```
 
-Expanded methods include additional predicates, format writers, metadata
-accessors, and read-only borrowed child wrappers. See:
+`to_wkb` always writes plain WKB. Use `to_ewkb` when a PostGIS-compatible SRID-bearing payload is required:
 
-- `docs/FORMAT_COVERAGE.md`
-- `docs/LOW_LEVEL_GEOMETRY.md`
-- `docs/FULL_TG_API_COVERAGE.md`
+```ruby
+ewkb = geom.to_ewkb              # uses geom.srid
+ewkb = geom.to_ewkb(srid: 4326)  # explicit override
+```
 
-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.
+SRID is metadata only. `tg_geometry` does not check SRID compatibility, transform coordinates, or calculate geodesic distances.
 
-## 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 +107,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 +134,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 +145,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 +160,82 @@ 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
+The `predicate:` option affects only the legacy point-based query methods (`find_covering`, `covering_ids(x, y)`, `covering_ids_batch_packed`). The geometry-based query methods (`intersecting_geom_ids`, `covering_geom_ids`, `containing_geom_ids`) use their own predicates based on the method name.
+
+`strategy: :auto` is intentionally not exposed. Choose the strategy explicitly and benchmark on your own data.
+
+## Geometry-based index queries
+
+```ruby
+query = TG::Geometry.polygon([[1, 1], [2, 1], [2, 2], [1, 1]])
+index.intersecting_geom_ids(query)
+index.covering_geom_ids(query)
+index.containing_geom_ids(query)
+```
+
+Predicate direction is explicit:
+
+| Method | Predicate direction | Boundary semantics |
+| --- | --- | --- |
+| `intersecting_geom_ids(query)` | stored geom intersects query | any intersection |
+| `covering_geom_ids(query)` | stored geom covers query | boundary included |
+| `containing_geom_ids(query)` | stored geom contains query | strict interior; boundary excluded |
+
+Results are ids only and preserve insertion order. Duplicate ids remain possible if duplicate ids were inserted.
+
+## 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 high-throughput same-process point lookups, the index supports a packed
-native-endian double input format:
+For direct file-to-index loading:
+
+```ruby
+index = TG::Geometry::FeatureSource.build_index_file(
+  "zones.geojson",
+  id: ["properties", "@id"],
+  strategy: :rtree,
+  predicate: :covers
+)
+```
+
+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 +243,23 @@ index.covering_ids_batch_packed(points)
 # => [:zone_a, :zone_b]
 ```
 
-Input format:
+Input is a Ruby String containing native-endian doubles in `lon, lat` pairs. Length must be a multiple of 16 bytes. Empty string returns `[]`.
+
+## Nearest segment
+
+`Line#nearest_segment(x, y)` and `Ring#nearest_segment(x, y)` return a frozen `TG::Geometry::NearestSegment`:
 
-- Ruby String treated as raw bytes.
-- Native-endian doubles.
-- Pairs of `lon, lat`.
-- Length must be a multiple of 16 bytes.
-- Empty string returns `[]`.
+```ruby
+nearest = polygon.polygon.exterior_ring.nearest_segment(5, 5)
+nearest.segment   # => TG::Geometry::Segment
+nearest.index     # => segment index
+nearest.distance  # => Float
+nearest.point     # => [x, y] projection on the segment
+```
 
-This format is intentionally native-endian for same-process speed and simplicity.
-Do not use it as a cross-platform serialized file format.
+Distance is planar Euclidean distance in input coordinate units. It is not meters unless your input coordinates are already meters. Equal-distance tie-breaks follow tg iteration order and are not API-stable.
 
-## Registry reload pattern
+## Registry helper
 
 `Registry` is Ruby-level sugar over immutable indexes:
 
@@ -266,53 +279,32 @@ 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`.
+Reload builds a new immutable index first and swaps the reference only after a successful build. Existing readers keep using the previous index safely.
 
-See `docs/REGISTRY.md` and `docs/ACTIVE_RECORD.md` for the expanded helpers.
+## ActiveRecord integration — read-only
 
-## Memory ownership model
+`TG::Geometry::ActiveRecordType` is an optional read-only convenience type for PostGIS columns. It is not required by `tg/geometry`; load it explicitly:
 
-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` |
+```ruby
+require "tg/geometry/active_record_type"
 
-`ObjectSpace.memsize_of(index)` includes entries, owned TG geometries, and exact
-rtree allocation bytes. Borrowed geometries are not double-counted by the index.
+class Zone < ApplicationRecord
+  attribute :geom, TG::Geometry::ActiveRecordType.new
+end
 
-See `docs/MEMORY_OWNERSHIP.md` for the full table and cleanup rules.
+zone.geom.srid
+zone.geom.covers_xy?(lon, lat)
+```
 
-## Concurrency model
+It can deserialize EWKB bytes, hex EWKB, `\x`-prefixed hex EWKB, GeoJSON, and WKT. Writing `Geom` values is intentionally unsupported in v0.3.0. User applications need `activemodel >= 6.0`; `activerecord` is not a gem dependency.
 
-`Index` and `Geom` are immutable after construction. Concurrent read-only use
-from normal Ruby threads is supported by design and covered by tests.
+## Memory and concurrency
 
-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.
+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.
 
-No Ractor support is claimed.
+`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.
 
-See `docs/CONCURRENCY.md` and `docs/RACTOR.md`.
+No Ractor support and no universal performance claim are advertised.
 
 ## Benchmarks
 
@@ -326,37 +318,34 @@ 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
+bundle exec ruby benchmark/geom_query.rb
+bundle exec ruby benchmark/nearest_segment.rb
+bundle exec ruby benchmark/ewkb_roundtrip.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:
-
-- 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.
+Not included:
+
+- Geodesic / Haversine distance;
+- Projection / reprojection;
+- Buffer / union / difference / convex hull;
+- Index nearest_ids (KNN);
+- GeoBIN bbox helpers;
+- Streaming FeatureSource;
+- Index serialization / mmap;
+- Ractor support;
+- Windows / JRuby;
+- Write-side ActiveRecordType / AR scopes / migrations;
+- Z/M variants of array constructors;
+- Public `release_gvl:` option.
+
+TG works in planar XY coordinates. If lon/lat coordinates are passed in, length, area, perimeter, and nearest-segment distances are in input coordinate units, not meters.
 
 ## Development
 
@@ -369,17 +358,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/`.