tg_geometry 0.1.0

data/docs/ERROR_HANDLING.md

@@ -0,0 +1,55 @@
+# Error handling
+
+## Exception hierarchy
+
+```ruby
+module TG
+  module Geometry
+    class Error < StandardError; end
+    class ParseError < Error; end
+    class ArgumentError < ::ArgumentError; end
+    class FrozenIndexError < Error; end
+  end
+end
+```
+
+`TG::Geometry::ArgumentError` inherits from Ruby `::ArgumentError` so invalid user arguments remain rescuable through the standard Ruby error class.
+
+## Mapping
+
+Condition | Ruby exception | Cleanup rule
+--- | --- | ---
+TG parse error | `TG::Geometry::ParseError` | copy error string, free TG error geometry, then raise
+invalid symbol option | `TG::Geometry::ArgumentError` | no native state if validated before allocation; otherwise dispose partial state
+nil id | `TG::Geometry::ArgumentError` | partial Index disposed immediately
+wrong object class/type | `TypeError` | use Ruby type checks / `TypedData_Get_Struct`
+non-finite coordinate | `TG::Geometry::ArgumentError` | reject before point or rect work where possible
+entries allocation failure | `NoMemoryError` | no entries state installed, or partial wrapper left empty
+rtree allocation failure | `NoMemoryError` | dispose rtree/entries/owned geometries immediately
+match buffer allocation failure | `NoMemoryError` | free any candidate buffer / query point before raising
+internal writer size mismatch | `TG::Geometry::Error` | no native ownership change
+
+## Parse errors
+
+TG parser failures return a geometry object that carries an error string. That object owns resources and must be freed.
+
+The implementation copies the error string before `tg_geom_free`, then raises `TG::Geometry::ParseError` from the copied Ruby string. It never reads `tg_geom_error` after freeing the error geometry.
+
+## Build failure atomicity
+
+`TG::Geometry::Index.build` is atomic: users either receive a frozen fully built Index or an exception. They never observe a partially built Index.
+
+The build body is protected with `rb_protect`. If it raises, `index_dispose` runs immediately and frees:
+
+1. rtree internals;
+2. initialized owned geometries;
+3. entries array;
+4. byte counters.
+
+## Rtree callbacks
+
+Rtree allocator callbacks return `NULL` on OOM. Rtree search callbacks record failure in C state or avoid failure by preallocating local mark buffers before search. Ruby exceptions do not longjmp through `rtree.c` traversal.
+
+## Writer safety
+
+Text writers allocate Ruby strings with one extra byte for the null terminator, call the TG writer with that capacity, then set the Ruby string length back to the required content length. WKB allocates exactly the required binary length and associates `ASCII-8BIT` encoding.

data/docs/EXPANSION_E_TO_H_STATUS.md

@@ -0,0 +1,51 @@
+# Expansion Blocks E–H status
+
+## Expansion Block E — Low-level Ring / Line / Polygon APIs
+
+Implemented as read-only borrowed wrappers:
+
+- `TG::Geometry::Geom#point`
+- `TG::Geometry::Geom#line`
+- `TG::Geometry::Geom#polygon`
+- `TG::Geometry::Line`
+- `TG::Geometry::Ring`
+- `TG::Geometry::Polygon`
+
+Invariant satisfied: child pointers are borrowed from the parent TG geometry and the wrapper keeps the parent Ruby `TG::Geometry::Geom` alive through `geom_owner` with compaction-aware marking.
+
+Tests: `spec/expansion_e_low_level_geometry_spec.rb` covers accessors, private allocation, out-of-range errors, and parent survival after `GC.start` / `GC.compact`.
+
+## Expansion Block F — Callback/search APIs
+
+OPEN QUESTION: not implemented.
+
+Reason: the roadmap allows callback/search APIs only with a new callback safety contract. The current contract still forbids public callback/block APIs in the first release. No `geom.search`, `index.search`, or `each_match` method is exposed.
+
+Required before implementation:
+
+- explicit callback exception propagation semantics;
+- GVL behavior for Ruby callbacks inside C loops;
+- proof that borrowed pointers cannot be invalidated by callback reentrancy;
+- benchmark of callback overhead;
+- tests for exceptions raised from callbacks.
+
+## Expansion Block G — Fast no-allocation point query optimization
+
+OPEN QUESTION: not implemented.
+
+Reason: the current implementation intentionally constructs a temporary TG point geometry for `covers` / `contains` correctness. Replacing this with `tg_geom_intersects_xy` or a specialized helper requires proof of exact boundary semantics and a benchmark proving benefit.
+
+Current invariant: point query semantics remain exact and boundary behavior is covered by existing tests.
+
+## Expansion Block H — Geodesic helpers or projection integration
+
+OPEN QUESTION: not implemented.
+
+Reason: TG core remains planar XY. No optional geodesic/projection dependency has been approved. The gem continues to document that `length`, `area`, and `perimeter` are in input coordinate units, not meters for lon/lat.
+
+Required before implementation:
+
+- explicit optional dependency decision;
+- public API shape;
+- tests separating planar TG behavior from geodesic/projection helpers;
+- documentation that TG itself does not handle geodesics.

data/docs/FORMAT_COVERAGE.md

@@ -0,0 +1,23 @@
+# Format coverage
+
+Expansion Block D exposes additional TG format helpers without changing ownership rules.
+
+## Parse helpers
+
+- `TG::Geometry.parse_hex(str, index: :ystripes)`
+- `TG::Geometry.parse_geobin(bytes, index: :ystripes)`
+
+These are shortcuts over `TG::Geometry.parse(..., format: :hex)` and `TG::Geometry.parse(..., format: :geobin)`.
+
+## Writer helpers
+
+- `TG::Geometry::Geom#to_hex` -> UTF-8 String
+- `TG::Geometry::Geom#to_geobin` -> ASCII-8BIT String
+
+Writers use the same direct Ruby string buffer pattern as existing writers. Hex is text and GeoBIN is binary.
+
+## Raw extra_json
+
+- `TG::Geometry::Geom#extra_json` -> UTF-8 String or nil
+
+This returns a copied Ruby String from TG's raw extra JSON pointer. It does not parse JSON into Hashes and does not expose borrowed child wrappers. This follows the constraint that raw `extra_json` is safer than implicit `JSON.parse`.

data/docs/FULL_TG_API_COVERAGE.md

@@ -0,0 +1,109 @@
+# Full TG API coverage status
+
+This document covers Expansion Block J as implemented in grouped, safe increments.
+
+Block J does not mean exposing every upstream TG function in one change. The rule is: implement in groups, define ownership for each group, add tests, and avoid environment allocator overrides or global mutable settings.
+
+## Implemented group: predicates
+
+`TG::Geometry::Geom` now exposes additional read-only predicates:
+
+- `equals?(other)`
+- `disjoint?(other)`
+- `within?(other)`
+- `covers?(other)`
+- `covered_by?(other)`
+- `touches?(other)`
+- `intersects_xy?(x, y)`
+- `intersects_rect?(rect)`
+- `intersects_rect?(min_x, min_y, max_x, max_y)`
+
+Existing methods remain:
+
+- `contains?(other)`
+- `intersects?(other)`
+- `covers_xy?(x, y)`
+
+`equals?` intentionally does not change Ruby `==`, `eql?`, or `hash`. Ruby equality remains identity-based until that open API decision is explicitly made.
+
+## Implemented group: geometry accessors
+
+`TG::Geometry::Geom` now exposes safe read-only accessors for upstream geometry collections and coordinate metadata:
+
+- `feature?`
+- `feature_collection?`
+- `empty?`
+- `dims`
+- `has_z?`
+- `has_m?`
+- `z`
+- `m`
+- `extra_coords`
+- `num_points`
+- `point_at(index)`
+- `points`
+- `num_lines`
+- `line_at(index)`
+- `lines`
+- `num_polygons`
+- `polygon_at(index)`
+- `polygons`
+- `num_geometries`
+- `geometry_at(index)`
+- `geometries`
+
+`geometry_at` and `geometries` return borrowed immutable `TG::Geometry::Geom` wrappers. They keep the parent wrapper alive through `geom_owner`, mark it for GC, update it during compaction, and do not call `tg_geom_free` for the borrowed child pointer.
+
+## Implemented group: point and empty constructors
+
+Safe constructors are exposed only where ownership is simple and the returned object owns exactly one `struct tg_geom *`:
+
+- `TG::Geometry.point(x, y)`
+- `TG::Geometry.point_z(x, y, z)`
+- `TG::Geometry.point_m(x, y, m)`
+- `TG::Geometry.point_zm(x, y, z, m)`
+- `TG::Geometry.empty_point`
+- `TG::Geometry.empty_linestring`
+- `TG::Geometry.empty_polygon`
+- `TG::Geometry.empty_multipoint`
+- `TG::Geometry.empty_multilinestring`
+- `TG::Geometry.empty_multipolygon`
+- `TG::Geometry.empty_geometrycollection`
+
+Numeric coordinates are converted with `NUM2DBL` and rejected if NaN or Infinity.
+
+## Implemented group: segments
+
+`TG::Geometry::Segment` is a frozen value wrapper over one copied `struct tg_segment`.
+
+Created by:
+
+- `TG::Geometry::Line#segment_at(index)`
+- `TG::Geometry::Line#segments`
+- `TG::Geometry::Ring#segment_at(index)`
+- `TG::Geometry::Ring#segments`
+
+Methods:
+
+- `a -> [Float, Float]`
+- `b -> [Float, Float]`
+- `points -> [[Float, Float], [Float, Float]]`
+- `bbox -> TG::Geometry::Rect`
+- `intersects?(other_segment)`
+
+`TG::Geometry::Segment.allocate` is disabled. Segment wrappers do not borrow parent TG memory and do not call any TG free function.
+
+## Still not implemented
+
+The following remain outside this grouped implementation:
+
+- Line/Ring/Polygon public constructors from Ruby arrays;
+- MultiLineString / MultiPolygon constructors from low-level wrappers;
+- callback/search APIs;
+- nearest segment APIs;
+- environment configuration functions;
+- global allocator override;
+- mutable settings;
+- user callbacks inside C loops.
+
+Those require separate ownership and callback-safety contracts before implementation.

data/docs/LIMITATIONS.md

@@ -0,0 +1,61 @@
+# Limitations
+
+`tg_geometry` is a small in-process geometry predicate and geofencing-oriented Index gem. It is not a full GIS system.
+
+## Not included
+
+The first release does not provide:
+
+- geocoding;
+- routing;
+- projections;
+- geodesic distance or area;
+- buffer / union / difference / intersection-result geometry operations;
+- nearest POI index;
+- full PostGIS / GEOS replacement behavior;
+- parsed GeoJSON Feature properties as Ruby Hashes;
+- Line/Ring/Polygon public constructors from Ruby coordinate arrays;
+- user callback APIs;
+- Ractor support claim;
+- no-allocation point query shortcuts;
+- geodesic/projection helpers;
+- mutable coordinate APIs;
+- global TG environment configuration or allocator override APIs.
+
+## Planar XY only
+
+TG works in planar XY coordinates. If users pass lon/lat, area, length, and perimeter concepts are in input coordinate units, not meters. Real-world distance and area need explicit projection/geodesic tooling outside this first-release core.
+
+## Boundary semantics
+
+Geofencing defaults to `predicate: :covers` because boundary points should count as inside. `predicate: :contains` is stricter and may exclude boundary points.
+
+## Point query performance
+
+The current implementation allocates a temporary TG point geometry per point query. This is intentional for exact `covers` and `contains` semantics. A no-allocation point path can be added later only after tests prove equivalent boundary behavior and benchmarks prove value.
+
+## Build peak memory
+
+`TG::Geometry::Index.build` is atomic and immutable. During reload, memory peak can include both the old Index and the new Index, plus original Ruby entry arrays and temporary build state. This is deliberate: exception safety and read-only concurrency are more important than streaming mutation in the first release.
+
+## IDs are returned by reference
+
+Index query methods return the same Ruby id objects stored in entries. They are not duplicated, frozen, stringified, or copied. If an id object is mutable, user code owns that mutability risk.
+
+## Windows
+
+Windows is not supported in the first release. The intended first-release platforms are Linux and macOS on x86_64 and arm64.
+
+## Expansion limitations
+
+No automatic strategy resolver is enabled in the first public release. For unusual datasets, especially heavily overlapping zones or workloads dominated by first-entry hits, choose `:flat` or `:rtree` explicitly after benchmarking.
+
+`TG::Geometry::Registry` is application sugar, not a distributed registry. It has no Redis dependency, no background reload thread, and no hidden global singleton.
+
+`TG::Geometry::ActiveRecordSource` is optional Ruby helper code. It does not install Rails reload hooks, generators, or background jobs.
+
+`TG::Geometry::Geom#extra_json` returns raw copied JSON text. It does not parse properties and does not expose Feature child objects. Z/M metadata is readable and point Z/M constructors exist, but broad Line/Ring/Polygon/Multi* construction remains out of scope until a separate ownership model is specified.
+
+## Expansion Blocks F-H
+
+Callback/search APIs, no-allocation point query optimization, and geodesic/projection helpers remain OPEN QUESTION scope. See `docs/EXPANSION_E_TO_H_STATUS.md`.

data/docs/LOW_LEVEL_GEOMETRY.md

@@ -0,0 +1,121 @@
+# Low-level geometry wrappers
+
+This document covers Expansion Block E.
+
+## Scope
+
+The first low-level API exposes borrowed read-only views over TG child types:
+
+- `TG::Geometry::Line`
+- `TG::Geometry::Ring`
+- `TG::Geometry::Polygon`
+- `TG::Geometry::Segment`
+
+These wrappers are created only from `TG::Geometry::Geom`, `TG::Geometry::Polygon`, `TG::Geometry::Line`, and `TG::Geometry::Ring` methods. Public `.allocate` is disabled for all four classes.
+
+## Ownership model
+
+TG child accessors return borrowed pointers owned by the parent `struct tg_geom`. The Line/Ring/Polygon Ruby wrappers therefore store:
+
+- `geom_owner`: the original `TG::Geometry::Geom` Ruby object;
+- a borrowed `const struct tg_line *`, `const struct tg_ring *`, or `const struct tg_poly *` pointer.
+
+The wrappers mark `geom_owner` with `rb_gc_mark_movable` and update it in `dcompact` with `rb_gc_location`. They do not call `tg_line_free`, `tg_ring_free`, or `tg_poly_free` for borrowed children.
+
+`TG::Geometry::Segment` is a value wrapper over a copied `struct tg_segment`, so it does not store `geom_owner` and does not free any TG-owned pointer.
+
+Allocator pairs:
+
+Resource | Allocator | Deallocator | Owner | Notes
+--- | --- | --- | --- | ---
+`tg_line_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | borrowed pointer, marks parent `geom_owner`
+`tg_ring_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | borrowed pointer, marks parent `geom_owner`
+`tg_polygon_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | borrowed pointer, marks parent `geom_owner`
+`tg_segment_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | owns copied `struct tg_segment` value
+TG child pointers | parent `struct tg_geom` | parent `TG::Geometry::Geom` dfree | parent geometry | never freed by child wrappers
+
+## Public API
+
+### `TG::Geometry::Geom#point`
+
+Returns `[x, y]` for point geometries. Returns `nil` for non-point geometries.
+
+### `TG::Geometry::Geom#line`
+
+Returns a frozen `TG::Geometry::Line` for LineString geometries. Returns `nil` otherwise.
+
+### `TG::Geometry::Geom#polygon`
+
+Returns a frozen `TG::Geometry::Polygon` for Polygon geometries. Returns `nil` otherwise.
+
+### `TG::Geometry::Line`
+
+Methods:
+
+- `bbox -> TG::Geometry::Rect`
+- `num_points -> Integer`
+- `point_at(index) -> [Float, Float]`
+- `points -> Array<[Float, Float]>`
+- `num_segments -> Integer`
+- `segment_at(index) -> TG::Geometry::Segment`
+- `segments -> Array<TG::Geometry::Segment>`
+- `length -> Float`
+- `clockwise? -> Boolean`
+
+`length` is measured in input coordinate units. For lon/lat data this is not meters.
+
+### `TG::Geometry::Ring`
+
+Methods:
+
+- `bbox -> TG::Geometry::Rect`
+- `num_points -> Integer`
+- `point_at(index) -> [Float, Float]`
+- `points -> Array<[Float, Float]>`
+- `num_segments -> Integer`
+- `segment_at(index) -> TG::Geometry::Segment`
+- `segments -> Array<TG::Geometry::Segment>`
+- `area -> Float`
+- `perimeter -> Float`
+- `clockwise? -> Boolean`
+- `convex? -> Boolean`
+
+`area` and `perimeter` are measured in input coordinate units. For lon/lat data these are not square meters or meters.
+
+### `TG::Geometry::Polygon`
+
+Methods:
+
+- `bbox -> TG::Geometry::Rect`
+- `exterior_ring -> TG::Geometry::Ring`
+- `num_holes -> Integer`
+- `hole_at(index) -> TG::Geometry::Ring`
+- `holes -> Array<TG::Geometry::Ring>`
+- `clockwise? -> Boolean`
+
+`hole_at` rejects out-of-range indexes with `TG::Geometry::ArgumentError`.
+
+### `TG::Geometry::Segment`
+
+Methods:
+
+- `a -> [Float, Float]`
+- `b -> [Float, Float]`
+- `points -> [[Float, Float], [Float, Float]]`
+- `bbox -> TG::Geometry::Rect`
+- `intersects?(other_segment) -> Boolean`
+
+Segments are copied by value from a line or ring. They do not keep or free borrowed TG pointers.
+
+## Error paths
+
+- Wrong wrapper type is handled by `TypedData_Get_Struct` and raises `TypeError`.
+- Out-of-range child indexes raise `TG::Geometry::ArgumentError`.
+- Child wrappers are immutable and cannot be constructed directly from Ruby.
+
+## Not implemented in this block
+
+- Low-level constructors for Ring, Line, or Polygon.
+- Mutable coordinate access.
+- Polygon `area` / `perimeter` convenience aggregation. Ring-level values are exposed first to avoid undocumented assumptions about hole orientation and aggregation semantics.
+- Geodesic length/area.

data/docs/MEMORY_OWNERSHIP.md

@@ -0,0 +1,94 @@
+# Memory ownership
+
+This document describes allocator pairs, ownership, cleanup, and GC accounting for `tg_geometry`.
+
+## Ownership table
+
+Resource | Allocator | Deallocator | Owner | Notes
+--- | --- | --- | --- | ---
+`tg_index_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | freed in `index_free`
+entries array | `calloc` | `free` | `TG::Geometry::Index` | exact-size, stable after build; accounted in `entries_bytes`
+rtree internals | `tg_rtree_malloc` / plain `malloc` + header | `tg_rtree_free` / plain `free` | rtree | exact `rtree_bytes`; strict non-NULL current owner
+TG geometry owned | `tg_parse_*_ix` | `tg_geom_free` | `TG::Geometry::Index` | `via: :geojson` / `via: :wkb`; accounted in `owned_geom_bytes_total`
+TG geometry borrowed | `TG::Geometry::Geom` wrapper | `TG::Geometry::Geom` dfree | `TG::Geometry::Geom` | Index holds `geom_owner`; Index does not free borrowed geometry
+TG parse error geometry | `tg_parse_*` | `tg_geom_free` | local parse scope | copy error string before free
+Ruby id | Ruby VM | Ruby GC | `TG::Geometry::Index` entry | mark movable + compact
+`geom_owner` | Ruby VM | Ruby GC | `TG::Geometry::Index` entry | mark movable + compact
+`tg_geom_wrapper_t` owned | `TypedData_Make_Struct` | `ruby_xfree` | Ruby object | owns one `struct tg_geom *`; `geom_free` calls `tg_geom_free`
+`tg_geom_wrapper_t` borrowed | `TypedData_Make_Struct` | `ruby_xfree` | Ruby object | borrowed child `struct tg_geom *`; marks/compacts parent `geom_owner`; does not call `tg_geom_free`
+TG geometry inside owned wrapper | `tg_parse_*` / constructor | `tg_geom_free` in `geom_free` | `TG::Geometry::Geom` wrapper | one `tg_geom_free` per parse/constructor
+query point geometry | `tg_geom_new_point` | `tg_geom_free` | local query scope | one point allocation per point query in first release
+match mark buffer | `calloc` | `free` | local query scope | rtree callback writes C marks only; no Ruby objects touched
+`tg_line_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | borrowed child pointer; marks/compacts parent `geom_owner`; does not call `tg_line_free`
+`tg_ring_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | borrowed child pointer; marks/compacts parent `geom_owner`; does not call `tg_ring_free`
+`tg_polygon_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | borrowed child pointer; marks/compacts parent `geom_owner`; does not call `tg_poly_free`
+`tg_segment_wrapper_t` | `TypedData_Make_Struct` / Ruby allocator | `ruby_xfree` | Ruby object | owns a by-value `struct tg_segment`; no borrowed pointer and no TG free call
+TG child pointers | parent `struct tg_geom` | parent `TG::Geometry::Geom` dfree | parent geometry | borrowed by Geom/Line/Ring/Polygon wrappers; never freed directly
+
+## GC memory pressure
+
+Native memory that is invisible to Ruby object slots is reported through `rb_gc_adjust_memory_usage` and exposed diagnostically through `ObjectSpace.memsize_of` where Ruby asks the data type for native size.
+
+Tracked state:
+
+- `TG::Geometry::Geom`: `geom_bytes` only for owned wrappers; borrowed child wrappers report only wrapper size;
+- `TG::Geometry::Index`: `entries_bytes`, `owned_geom_bytes_total`, `rtree_bytes`.
+
+Every successful `+N` adjustment has one matching `-N` in the relevant dispose/free path. Dispose is idempotent: after freeing, pointers and byte counters are zeroed.
+
+## Partial build cleanup
+
+`TG::Geometry::Index.build` uses an explicit `initialized` counter. Only fully written entries are marked, compacted, queried, or disposed.
+
+Entry write order:
+
+1. validate id and value type;
+2. parse or borrow the native geometry into a local variable;
+3. build a complete local `tg_index_entry_t`;
+4. write the local entry into the entries array;
+5. increment `initialized`;
+6. update bbox and byte accounting.
+
+If build raises after native allocation starts, `index_dispose` runs immediately. Failed builds do not wait for Ruby GC to eventually clean large partial native state.
+
+## Rtree allocator
+
+`rtree.c` expects malloc-style allocation callbacks, so the rtree allocator uses plain `malloc` and returns `NULL` on OOM. It must not call `ruby_xmalloc` and must not raise Ruby exceptions from inside rtree callbacks.
+
+Each rtree allocation stores this header before the returned pointer:
+
+```c
+typedef struct {
+    tg_index_t *owner;
+    size_t size;
+} tg_rtree_alloc_header_t;
+```
+
+The current owner is `_Thread_local`. It is saved before rtree build, set for `rtree_new_with_allocator` and every `rtree_insert`, then restored with `rb_ensure`.
+
+Allocator calls use `rb_gc_adjust_memory_usage`, so rtree build and free must run with the GVL held.
+
+## Borrowed geometry path
+
+For `via: :geom`, the Index does not clone or copy the native geometry. It stores:
+
+- `geom_owner = original TG::Geometry::Geom Ruby object`;
+- `geom = borrowed native pointer`;
+- `owned = false`;
+- `geom_bytes = 0`.
+
+The Index marks and compacts `geom_owner`, which keeps the owning Ruby wrapper alive after the caller drops its local variable. Borrowed geometry memory is not double-counted in `ObjectSpace.memsize_of(index)`.
+
+## Owned geometry path
+
+For `via: :geojson` and `via: :wkb`, the Index owns each parsed TG geometry. The Index calls `tg_geom_free` during dispose/free and subtracts exactly the bytes previously added to `owned_geom_bytes_total` and Ruby GC pressure.
+
+## Low-level child wrappers
+
+Expansion Block E exposes read-only borrowed wrappers for selected TG child types. `TG::Geometry::Line`, `TG::Geometry::Ring`, and `TG::Geometry::Polygon` keep the original parent `TG::Geometry::Geom` Ruby object in `geom_owner`. Their GC callbacks use `rb_gc_mark_movable` and `rb_gc_location`, matching the Index borrowed-geometry model.
+
+Expansion Block J extends this model to borrowed `TG::Geometry::Geom` wrappers returned from GeometryCollection accessors. A borrowed `Geom` stores `owned = false`, `geom_bytes = 0`, and a `geom_owner` reference to the parent wrapper. Its free path only releases the Ruby wrapper struct; it never calls `tg_geom_free` on the borrowed child pointer. This keeps `ObjectSpace.memsize_of` from double-counting parent-owned native geometry.
+
+`TG::Geometry::Segment` is different: it stores a `struct tg_segment` by value, not a borrowed pointer. It has no parent owner to mark and no TG deallocator to call.
+
+Line/Ring/Polygon wrappers own only their small Ruby-allocated wrapper structs. They do not own the underlying `const struct tg_line *`, `const struct tg_ring *`, or `const struct tg_poly *`. Cleanup therefore only calls `ruby_xfree` for the wrapper; the parent `TG::Geometry::Geom` remains responsible for the single `tg_geom_free`.

data/docs/RACTOR.md

@@ -0,0 +1,40 @@
+# Ractor investigation
+
+This document covers Expansion Block I.
+
+## Current result
+
+`tg_geometry` does not claim Ractor support.
+
+The current native wrappers are frozen and immutable for normal Ruby thread reads, but they are not Ractor-shareable Ruby objects. The test suite records this boundary with `Ractor.shareable?` and `Ractor.make_shareable` checks for:
+
+- `TG::Geometry::Geom`
+- `TG::Geometry::Rect`
+- `TG::Geometry::Index`
+
+This is an explicit unsupported boundary, not a partial support claim.
+
+## Shareability rules
+
+Current rule for public docs and code comments:
+
+- Normal Ruby thread read-only use is supported by immutable object design and tests.
+- Ractor support is not supported and not advertised.
+- Do not use `TG::Geometry::Geom`, `TG::Geometry::Rect`, `TG::Geometry::Index`, or borrowed low-level wrappers as cross-Ractor shareable objects.
+- Do not add Ractor-specific code paths without a new explicit design and tests.
+
+## Why no support claim is made
+
+The extension stores native pointers and Ruby `VALUE` references inside TypedData wrappers. The current contract validates GC marking, compaction, ownership, and normal thread read-only access. It does not define or validate cross-Ractor transfer/share semantics for those wrappers.
+
+## Required before changing this status
+
+Before any future Ractor support claim:
+
+1. Define shareability rules for owned and borrowed `TG::Geometry::Geom` wrappers.
+2. Define shareability rules for `TG::Geometry::Index` entries and id `VALUE`s.
+3. Define behavior for borrowed Line/Ring/Polygon/Segment wrappers.
+4. Add Ractor tests that pass on the supported Ruby matrix.
+5. Document whether objects are shareable directly, require duplication, or are unsupported.
+
+Until those items exist, Ractor remains unsupported.

data/docs/REGISTRY.md

@@ -0,0 +1,37 @@
+# Registry
+
+`TG::Geometry::Registry` is Ruby-side application sugar over immutable `TG::Geometry::Index`.
+
+It does not add a mutable native index. `reload!` always builds a new Index and then swaps a Ruby reference:
+
+```ruby
+class DeliveryZones < TG::Geometry::Registry
+  source do
+    [
+      [:zone_a, '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}']
+    ]
+  end
+end
+
+registry = DeliveryZones.new(via: :geojson, strategy: :rtree)
+registry.reload!
+registry.find_covering(5, 5)
+```
+
+Readers capture the current immutable Index. An active reader can continue using the old Index while `reload!` builds and swaps a new one.
+
+## API
+
+- `source { ... }` on a subclass defines the entry source.
+- `index_options(...)` on a subclass sets default Index options.
+- `reload!` builds and swaps a new Index.
+- `find_covering`, `covering_ids`, `intersecting_rect`, and `covering_ids_batch_packed` delegate to the current Index.
+- `index`, `size`, `bbox`, and `loaded?` expose current state.
+
+The source must return the strict first-release entry format:
+
+```ruby
+[[id, object], [id, object], ...]
+```
+
+No Redis dependency, no Rails dependency, no global native singleton, and no in-place Index mutation are introduced.

data/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,39 @@
+# First public release checklist
+
+This checklist is intentionally conservative. Do not publish until every required item is satisfied.
+
+## Required state before release
+
+- [ ] All release-core specs pass locally.
+- [ ] GC.stress specs pass.
+- [ ] GC.compact specs pass.
+- [ ] ASAN status is documented.
+- [ ] Valgrind status is documented.
+- [ ] Benchmark scripts exist and have been run for the full scenario matrix.
+- [ ] README and docs are complete.
+- [ ] Gem metadata is final:
+  - gem name: `tg_geometry`;
+  - author: `Roman Haydarov`;
+  - email: `romnhajdarov@gmail.com`;
+  - repository: `https://github.com/roman-haidarov/tg_geometry`.
+- [ ] Vendored TG and rtree versions are pinned in `VERSION` files.
+- [ ] Upstream license files are included under `ext/tg_geometry/vendor/*/LICENSE`.
+- [ ] `CHANGELOG.md` exists.
+
+## Do not release if any of these are true
+
+- [ ] Any OPEN QUESTION affects correctness.
+- [ ] Any memory accounting path is approximate.
+- [ ] Any failed build path waits for GC instead of immediate dispose.
+- [ ] `strategy: :auto` is enabled without benchmark-derived threshold.
+- [ ] Public API differs from the contract without Roman approval.
+- [ ] Ractor support is claimed.
+- [ ] Performance claims are present without project-owned benchmark output.
+
+## OPEN QUESTION: ASAN setup
+
+ASAN setup is not fully specified in the contract and the worker must not research it independently. The repository contains a placeholder CI job that fails with an explicit message until Roman approves the exact ASAN approach.
+
+## OPEN QUESTION: Valgrind setup
+
+Valgrind setup can vary by CI image and Ruby build. The repository contains a placeholder CI job that installs/runs nothing by default and asks for approval before adding a final Valgrind configuration.