tg_geometry 0.1.0

data/script/vendor_libs.rb

@@ -0,0 +1,264 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "open3"
+require "optparse"
+require "tmpdir"
+
+VENDOR_DIR = File.expand_path("../ext/tg_geometry/vendor", __dir__)
+MANIFEST_PATH = File.join(VENDOR_DIR, ".vendored")
+
+PINS = {
+  tg: {
+    repo: "https://github.com/tidwall/tg.git",
+    ref: "main",
+    commit: "caf840504eaab4563280cf4ab16d618f69a23720",
+    sha256: "f8e0d904055c209b2a23a2200456f9374ab95cadb69e61b5721d7f8e2500e705",
+    target: "tg",
+    files: %w[tg.c tg.h LICENSE README.md]
+  },
+  rtree: {
+    repo: "https://github.com/tidwall/rtree.c.git",
+    ref: "v0.5.3",
+    commit: "5717a8a1eb373428ebaae8c1c623f186ec46461f",
+    sha256: "4afc86cbd3abe03730206031a5aff5b8b29d37b055fc356052f6f06e1d1f9a61",
+    target: "rtree",
+    files: %w[rtree.c rtree.h LICENSE README.md]
+  }
+}.freeze
+
+NORMALIZED_MTIME = Time.utc(2000, 1, 1).freeze
+MANIFEST_HEADER = "# tg_geometry vendor manifest. Do not edit by hand. Regenerate with: ruby script/vendor_libs.rb --sync"
+
+options = { mode: :sync }
+OptionParser.new do |opts|
+  opts.banner = "Usage: vendor_libs.rb [--verify | --sync] [--force]"
+  opts.on("--verify", "Verify existing vendor tree against pinned files, VERSION metadata, and tree SHA256") { options[:mode] = :verify }
+  opts.on("--sync", "Rebuild the vendor tree only when pinned content is missing or changed") { options[:mode] = :sync }
+  opts.on("--force", "Force a fresh clone and rebuild even when the vendor tree is current") { options[:force] = true }
+end.parse!
+
+def sh!(cmd)
+  system(*cmd) || abort("command failed: #{cmd.join(" ")}")
+end
+
+def capture!(*cmd)
+  out, status = Open3.capture2(*cmd)
+  abort("command failed: #{cmd.join(" ")}") unless status.success?
+
+  out.strip
+end
+
+def vendor_candidate?(path)
+  return false if File.symlink?(path)
+  return false unless File.file?(path)
+  return false if path.split(File::SEPARATOR).any? { |seg| seg.start_with?(".") && seg != "." && seg != ".." }
+
+  true
+end
+
+def normalize_tree!(directory)
+  Dir.glob(File.join(directory, "**", "*"), File::FNM_DOTMATCH).each do |path|
+    base = File.basename(path)
+    next if base == "." || base == ".."
+    next if File.symlink?(path)
+
+    if File.file?(path)
+      File.chmod(0o644, path)
+      File.utime(NORMALIZED_MTIME, NORMALIZED_MTIME, path)
+    elsif File.directory?(path)
+      File.chmod(0o755, path)
+    end
+  end
+  File.utime(NORMALIZED_MTIME, NORMALIZED_MTIME, directory) if File.directory?(directory)
+end
+
+def copy_entry!(source_root, target_root, relative)
+  src = File.join(source_root, relative)
+  abort "missing required upstream file: #{src}" unless File.file?(src)
+  abort "refusing to vendor symlink: #{src}" if File.symlink?(src)
+
+  dest = File.join(target_root, relative)
+  FileUtils.mkdir_p(File.dirname(dest))
+  FileUtils.cp(src, dest, preserve: false)
+end
+
+def write_version!(target, pin)
+  version = [
+    "repo=#{pin.fetch(:repo)}",
+    "ref=#{pin.fetch(:ref)}",
+    "commit=#{pin.fetch(:commit)}"
+  ].join("\n") + "\n"
+  File.write(File.join(target, "VERSION"), version)
+end
+
+def tree_sha256_for(directory)
+  entries = Dir.glob(File.join(directory, "**", "*"), File::FNM_DOTMATCH)
+               .reject { |path| File.directory?(path) || File.symlink?(path) || %w[. ..].include?(File.basename(path)) }
+               .sort
+
+  digest = Digest::SHA256.new
+  entries.each do |path|
+    relative = path.sub(/\A#{Regexp.escape(directory)}\/?/, "")
+    digest << relative << "\0"
+    digest << File.binread(path)
+    digest << "\0"
+  end
+  digest.hexdigest
+end
+
+def vendor_one!(name, pin)
+  target = File.join(VENDOR_DIR, pin.fetch(:target))
+  FileUtils.rm_rf(target)
+  FileUtils.mkdir_p(target)
+
+  Dir.mktmpdir("tg-geometry-#{name}-") do |tmpdir|
+    clone_dir = File.join(tmpdir, pin.fetch(:target))
+    sh!(["git", "clone", "--filter=blob:none", pin.fetch(:repo), clone_dir])
+    sh!(["git", "-C", clone_dir, "fetch", "--depth", "1", "origin", pin.fetch(:commit)])
+    sh!(["git", "-C", clone_dir, "checkout", "--detach", pin.fetch(:commit)])
+
+    actual_commit = capture!("git", "-C", clone_dir, "rev-parse", "HEAD")
+    abort "commit mismatch for #{name}: expected #{pin.fetch(:commit)}, got #{actual_commit}" unless actual_commit == pin.fetch(:commit)
+
+    pin.fetch(:files).each { |relative| copy_entry!(clone_dir, target, relative) }
+  end
+
+  write_version!(target, pin)
+  normalize_tree!(target)
+
+  pin.merge(tree_sha256: tree_sha256_for(target))
+end
+
+def manifest_body_lines(results)
+  lines = ["gem=tg_geometry", "libraries=#{PINS.keys.join(",")}"]
+  results.each do |name, data|
+    prefix = name.to_s
+    lines << "#{prefix}_repo=#{data.fetch(:repo)}"
+    lines << "#{prefix}_ref=#{data.fetch(:ref)}"
+    lines << "#{prefix}_commit=#{data.fetch(:commit)}"
+    lines << "#{prefix}_target=#{data.fetch(:target)}"
+    lines << "#{prefix}_files=#{(data.fetch(:files) + ["VERSION"]).join(",")}"
+    lines << "#{prefix}_tree_sha256=#{data.fetch(:tree_sha256)}"
+  end
+  lines
+end
+
+def manifest_signature(body_lines)
+  Digest::SHA256.hexdigest(body_lines.join("\n") + "\n")
+end
+
+def write_manifest(results)
+  body = manifest_body_lines(results)
+  sig = manifest_signature(body)
+  content = ([MANIFEST_HEADER] + body + ["manifest_sha256=#{sig}"]).join("\n") + "\n"
+  FileUtils.mkdir_p(File.dirname(MANIFEST_PATH))
+  File.write(MANIFEST_PATH, content)
+  File.chmod(0o644, MANIFEST_PATH)
+  File.utime(NORMALIZED_MTIME, NORMALIZED_MTIME, MANIFEST_PATH)
+end
+
+def expected_vendor_results
+  PINS.each_with_object({}) do |(name, pin), results|
+    results[name] = pin.merge(tree_sha256: pin.fetch(:sha256))
+  end
+end
+
+def print_results(prefix, results)
+  puts prefix
+  results.each do |name, data|
+    puts "  #{name}: commit=#{data.fetch(:commit)} tree_sha256=#{data.fetch(:tree_sha256)}"
+  end
+end
+
+def parse_kv_file(path)
+  return {} unless File.file?(path)
+
+  File.readlines(path, chomp: true).each_with_object({}) do |line, hash|
+    next if line.empty? || line.start_with?("#")
+
+    key, value = line.split("=", 2)
+    hash[key] = value if key && value
+  end
+end
+
+def verify_vendor_tree
+  failures = []
+
+  PINS.each do |name, pin|
+    target = File.join(VENDOR_DIR, pin.fetch(:target))
+    unless Dir.exist?(target)
+      failures << "#{name}: vendor directory missing (#{target})"
+      next
+    end
+
+    (pin.fetch(:files) + ["VERSION"]).each do |relative|
+      path = File.join(target, relative)
+      failures << "#{name}: missing vendored file #{relative}" unless File.file?(path)
+    end
+
+    version = parse_kv_file(File.join(target, "VERSION"))
+    failures << "#{name}: VERSION repo mismatch" unless version["repo"] == pin.fetch(:repo)
+    failures << "#{name}: VERSION ref mismatch" unless version["ref"] == pin.fetch(:ref)
+    failures << "#{name}: VERSION commit mismatch" unless version["commit"] == pin.fetch(:commit)
+
+    next unless failures.none? { |failure| failure.start_with?("#{name}:") }
+
+    actual_sha256 = tree_sha256_for(target)
+    expected_sha256 = pin.fetch(:sha256)
+    failures << "#{name}: tree_sha256 mismatch: expected #{expected_sha256}, got #{actual_sha256}" unless actual_sha256 == expected_sha256
+  end
+
+  expected_results = expected_vendor_results
+  manifest = parse_kv_file(MANIFEST_PATH)
+  if manifest.empty?
+    failures << "manifest: missing #{MANIFEST_PATH}"
+  else
+    expected_body = manifest_body_lines(expected_results)
+    expected_signature = manifest_signature(expected_body)
+
+    expected_body.each do |line|
+      key, expected_value = line.split("=", 2)
+      failures << "manifest: #{key} mismatch" unless manifest[key] == expected_value
+    end
+
+    failures << "manifest: manifest_sha256 mismatch" unless manifest["manifest_sha256"] == expected_signature
+  end
+
+  failures
+end
+
+case options.fetch(:mode)
+when :verify
+  failures = verify_vendor_tree
+  if failures.empty?
+    print_results("vendor verify: ok", expected_vendor_results)
+    exit 0
+  end
+
+  failures.each { |failure| warn failure }
+  exit 1
+when :sync
+  unless options[:force]
+    failures = verify_vendor_tree
+    if failures.empty?
+      print_results("vendor sync: up to date", expected_vendor_results)
+      exit 0
+    end
+  end
+
+  FileUtils.rm_rf(VENDOR_DIR)
+  FileUtils.mkdir_p(VENDOR_DIR)
+
+  results = {}
+  PINS.each do |name, pin|
+    results[name] = vendor_one!(name, pin)
+  end
+
+  write_manifest(results)
+  print_results("vendor sync: ok", results)
+else
+  abort "unknown mode: #{options.fetch(:mode)}"
+end

data/spec/block_10_rtree_strategy_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Release Core Block 10 exact rtree accounting" do
+  let(:zone_a) { TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))") }
+  let(:zone_b) { TG::Geometry.parse_wkt("POLYGON ((20 20, 30 20, 30 30, 20 30, 20 20))") }
+
+  it "builds an rtree index and reports rtree native bytes in debug builds" do
+    index = TG::Geometry::Index.build([[:a, zone_a], [:b, zone_b]], via: :geom, strategy: :rtree)
+
+    expect(index.strategy).to eq(:rtree)
+    if index.respond_to?(:_rtree_bytes_for_test)
+      expect(index._rtree_bytes_for_test).to be > 0
+    end
+  end
+
+  it "does not build an rtree for empty indexes" do
+    index = TG::Geometry::Index.build([], via: :geojson, strategy: :rtree)
+
+    expect(index.strategy).to eq(:rtree)
+    expect(index.size).to eq(0)
+    expect(index._rtree_bytes_for_test).to eq(0) if index.respond_to?(:_rtree_bytes_for_test)
+  end
+
+  it "returns rtree bytes to zero after dispose in debug builds" do
+    index = TG::Geometry::Index.build([[:a, zone_a]], via: :geom, strategy: :rtree)
+
+    skip "TG_DEBUG_TEST hooks are not enabled" unless index.respond_to?(:_force_dispose_for_test!)
+
+    expect(index._rtree_bytes_for_test).to be > 0
+    index._force_dispose_for_test!
+    index._force_dispose_for_test!
+    expect(index._rtree_bytes_for_test).to eq(0)
+    expect(index._entries_bytes_for_test).to eq(0)
+    expect(index._initialized_entries_for_test).to eq(0)
+  end
+
+  it "cleans up after rtree allocation failure in debug builds" do
+    skip "TG_DEBUG_TEST hooks are not enabled" unless TG::Geometry.respond_to?(:_debug_fail_next_rtree_alloc!)
+
+    TG::Geometry._debug_reset_test_hooks!
+    TG::Geometry._debug_fail_next_rtree_alloc!
+
+    expect do
+      TG::Geometry::Index.build([[:a, zone_a], [:b, zone_b]], via: :geom, strategy: :rtree)
+    end.to raise_error(NoMemoryError)
+  ensure
+    TG::Geometry._debug_reset_test_hooks! if TG::Geometry.respond_to?(:_debug_reset_test_hooks!)
+  end
+
+  it "cleans up after rtree insert allocation failure in debug builds" do
+    skip "TG_DEBUG_TEST hooks are not enabled" unless TG::Geometry.respond_to?(:_debug_fail_rtree_alloc_after!)
+
+    TG::Geometry._debug_reset_test_hooks!
+    TG::Geometry._debug_fail_rtree_alloc_after!(1)
+
+    expect do
+      TG::Geometry::Index.build([[:a, zone_a], [:b, zone_b]], via: :geom, strategy: :rtree)
+    end.to raise_error(NoMemoryError)
+  ensure
+    TG::Geometry._debug_reset_test_hooks! if TG::Geometry.respond_to?(:_debug_reset_test_hooks!)
+  end
+
+  it "allows two threads to build separate rtree indexes without cross-accounting" do
+    indexes = Queue.new
+
+    threads = 2.times.map do |i|
+      Thread.new do
+        geom = TG::Geometry.parse_wkt("POLYGON ((#{i * 20} 0, #{i * 20 + 10} 0, #{i * 20 + 10} 10, #{i * 20} 10, #{i * 20} 0))")
+        indexes << TG::Geometry::Index.build([[i, geom]], via: :geom, strategy: :rtree)
+      end
+    end
+    threads.each(&:join)
+
+    built = 2.times.map { indexes.pop }
+    expect(built.map(&:size)).to eq([1, 1])
+    if built.all? { |idx| idx.respond_to?(:_rtree_bytes_for_test) }
+      expect(built.map(&:_rtree_bytes_for_test)).to all(be > 0)
+    end
+  end
+end

data/spec/block_11_rtree_order_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Release Core Block 11 rtree ordered results" do
+  let(:entries) do
+    [
+      [:first, TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))")],
+      [:second, TG::Geometry.parse_wkt("POLYGON ((2 2, 12 2, 12 12, 2 12, 2 2))")],
+      [:third, TG::Geometry.parse_wkt("POLYGON ((4 4, 14 4, 14 14, 4 14, 4 4))")]
+    ]
+  end
+
+  it "matches flat result order for point queries" do
+    flat = TG::Geometry::Index.build(entries, via: :geom, strategy: :flat)
+    rtree = TG::Geometry::Index.build(entries, via: :geom, strategy: :rtree)
+
+    expect(rtree.find_covering(5, 5)).to eq(flat.find_covering(5, 5))
+    expect(rtree.covering_ids(5, 5)).to eq(flat.covering_ids(5, 5))
+    expect(rtree.covering_ids(100, 100)).to eq([])
+  end
+
+  it "matches flat result order for rect queries" do
+    flat = TG::Geometry::Index.build(entries, via: :geom, strategy: :flat)
+    rtree = TG::Geometry::Index.build(entries, via: :geom, strategy: :rtree)
+
+    expect(rtree.intersecting_rect(3, 3, 6, 6)).to eq(flat.intersecting_rect(3, 3, 6, 6))
+    expect(rtree.intersecting_rect(100, 100, 101, 101)).to eq([])
+  end
+
+  it "handles many overlapping matches deterministically" do
+    many = 50.times.map do |i|
+      [i, TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))")]
+    end
+
+    index = TG::Geometry::Index.build(many, via: :geom, strategy: :rtree)
+
+    expect(index.find_covering(5, 5)).to eq(0)
+    expect(index.covering_ids(5, 5)).to eq((0...50).to_a)
+  end
+
+  it "handles match buffer allocation failure in debug builds" do
+    skip "TG_DEBUG_TEST hooks are not enabled" unless TG::Geometry.respond_to?(:_debug_fail_next_match_buffer_alloc!)
+
+    index = TG::Geometry::Index.build(entries, via: :geom, strategy: :rtree)
+    TG::Geometry._debug_reset_test_hooks!
+    TG::Geometry._debug_fail_next_match_buffer_alloc!
+
+    expect { index.covering_ids(5, 5) }.to raise_error(NoMemoryError)
+  ensure
+    TG::Geometry._debug_reset_test_hooks! if TG::Geometry.respond_to?(:_debug_reset_test_hooks!)
+  end
+end

data/spec/block_12_batch_packed_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Release Core Block 12 packed batch API" do
+  let(:zone_a) { TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))") }
+  let(:zone_b) { TG::Geometry.parse_wkt("POLYGON ((20 20, 30 20, 30 30, 20 30, 20 20))") }
+
+  def pack_points(points)
+    points.flatten.pack("d*")
+  end
+
+  it "returns one result per input point" do
+    index = TG::Geometry::Index.build([[:a, zone_a], [:b, zone_b]], via: :geom, strategy: :flat)
+
+    packed = pack_points([[1.0, 1.0], [25.0, 25.0], [100.0, 100.0]])
+    expect(index.covering_ids_batch_packed(packed)).to eq([:a, :b, nil])
+  end
+
+  it "supports empty input" do
+    index = TG::Geometry::Index.build([[:a, zone_a]], via: :geom, strategy: :flat)
+
+    expect(index.covering_ids_batch_packed("".b)).to eq([])
+  end
+
+  it "rejects invalid input type, length, and non-finite values" do
+    index = TG::Geometry::Index.build([[:a, zone_a]], via: :geom, strategy: :flat)
+
+    expect { index.covering_ids_batch_packed(Object.new) }.to raise_error(TypeError)
+    expect { index.covering_ids_batch_packed("123".b) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { index.covering_ids_batch_packed([Float::NAN, 1.0].pack("d*")) }
+      .to raise_error(TG::Geometry::ArgumentError)
+  end
+
+  it "matches scalar find_covering for flat and rtree strategies" do
+    points = [[1.0, 1.0], [25.0, 25.0], [100.0, 100.0], [0.0, 5.0]]
+
+    %i[flat rtree].each do |strategy|
+      index = TG::Geometry::Index.build([[:a, zone_a], [:b, zone_b]],
+                                        via: :geom,
+                                        strategy: strategy)
+      packed = pack_points(points)
+      expected = points.map { |lon, lat| index.find_covering(lon, lat) }
+
+      expect(index.covering_ids_batch_packed(packed)).to eq(expected)
+    end
+  end
+
+  it "returns the same VALUE ids, including mutable ids" do
+    id = +"zone-a"
+    index = TG::Geometry::Index.build([[id, zone_a]], via: :geom, strategy: :flat)
+
+    expect(index.covering_ids_batch_packed(pack_points([[1.0, 1.0]])).first).to equal(id)
+  end
+end

data/spec/block_13_error_hardening_spec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Release Core Block 13 error hardening" do
+  let(:geojson) { '{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1],[0,1],[0,0]]]}' }
+  let(:wkb) { TG::Geometry.parse_geojson(geojson).to_wkb }
+
+  it "raises ParseError for malformed GeoJSON at first, middle, and last positions" do
+    bad = "not geojson"
+
+    [
+      [[1, bad], [2, geojson], [3, geojson]],
+      [[1, geojson], [2, bad], [3, geojson]],
+      [[1, geojson], [2, geojson], [3, bad]]
+    ].each do |entries|
+      expect { TG::Geometry::Index.build(entries, via: :geojson, strategy: :flat) }
+        .to raise_error(TG::Geometry::ParseError)
+    end
+  end
+
+  it "raises ParseError for malformed WKB at first, middle, and last positions" do
+    bad = "not wkb".b
+
+    [
+      [[1, bad], [2, wkb], [3, wkb]],
+      [[1, wkb], [2, bad], [3, wkb]],
+      [[1, wkb], [2, wkb], [3, bad]]
+    ].each do |entries|
+      expect { TG::Geometry::Index.build(entries, via: :wkb, strategy: :flat) }
+        .to raise_error(TG::Geometry::ParseError)
+    end
+  end
+
+  it "supports debug OOM simulation for entries allocation" do
+    skip "TG_DEBUG_TEST hooks are not enabled" unless TG::Geometry.respond_to?(:_debug_fail_next_entries_alloc!)
+
+    geom = TG::Geometry.parse_geojson(geojson)
+    TG::Geometry._debug_reset_test_hooks!
+    TG::Geometry._debug_fail_next_entries_alloc!
+
+    expect do
+      TG::Geometry::Index.build([[1, geom]], via: :geom, strategy: :flat)
+    end.to raise_error(NoMemoryError)
+  ensure
+    TG::Geometry._debug_reset_test_hooks! if TG::Geometry.respond_to?(:_debug_reset_test_hooks!)
+  end
+
+  it "keeps dispose idempotent and clears byte counters in debug builds" do
+    skip "TG_DEBUG_TEST hooks are not enabled" unless TG::Geometry::Index.method_defined?(:_force_dispose_for_test!)
+
+    index = TG::Geometry::Index.build([[1, geojson]], via: :geojson, strategy: :rtree)
+
+    expect(index._entries_bytes_for_test).to be > 0
+    expect(index._owned_geom_bytes_for_test).to be > 0
+    expect(index._rtree_bytes_for_test).to be > 0
+
+    index._force_dispose_for_test!
+    index._force_dispose_for_test!
+
+    expect(index._entries_bytes_for_test).to eq(0)
+    expect(index._owned_geom_bytes_for_test).to eq(0)
+    expect(index._rtree_bytes_for_test).to eq(0)
+  end
+end

data/spec/block_14_memory_gc_hardening_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "objspace"
+
+RSpec.describe "Release Core Block 14 memory, GC, and compaction hardening" do
+  let(:small_polygon_wkt) { "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))" }
+  let(:small_polygon_geojson) { '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}' }
+  let(:malformed_geojson) { '{"type":"Polygon","coordinates":[' }
+
+  def compact_if_supported
+    GC.start
+    GC.compact if GC.respond_to?(:compact)
+  end
+
+  it "survives a parse/free loop under GC.stress" do
+    old_stress = GC.stress
+    GC.stress = true
+
+    50.times do
+      geom = TG::Geometry.parse_wkt(small_polygon_wkt)
+      expect(geom).to be_frozen
+      expect(geom.covers_xy?(5.0, 5.0)).to be(true)
+    end
+  ensure
+    GC.stress = old_stress
+  end
+
+  it "survives index build/free loops for owned and borrowed geometry" do
+    geom = TG::Geometry.parse_wkt(small_polygon_wkt)
+
+    25.times do
+      owned = TG::Geometry::Index.build([["owned", small_polygon_geojson]], via: :geojson, strategy: :rtree)
+      borrowed = TG::Geometry::Index.build([["borrowed", geom]], via: :geom, strategy: :rtree)
+
+      expect(owned.find_covering(5, 5)).to eq("owned")
+      expect(borrowed.find_covering(5, 5)).to eq("borrowed")
+    end
+
+    compact_if_supported
+  end
+
+  it "survives failed build loops without leaving initialized native state observable" do
+    20.times do
+      expect do
+        TG::Geometry::Index.build([[1, small_polygon_geojson], [2, malformed_geojson]], via: :geojson, strategy: :rtree)
+      end.to raise_error(TG::Geometry::ParseError)
+    end
+
+    compact_if_supported
+  end
+
+  it "survives repeated query loops for flat and rtree strategies" do
+    entries = [
+      [:a, TG::Geometry.parse_wkt(small_polygon_wkt)],
+      [:b, TG::Geometry.parse_wkt("POLYGON ((20 20, 30 20, 30 30, 20 30, 20 20))")]
+    ]
+
+    %i[flat rtree].each do |strategy|
+      index = TG::Geometry::Index.build(entries, via: :geom, strategy: strategy)
+
+      250.times do
+        expect(index.find_covering(5, 5)).to eq(:a)
+        expect(index.covering_ids(25, 25)).to eq([:b])
+        expect(index.intersecting_rect(0, 0, 1, 1)).to eq([:a])
+      end
+    end
+  end
+
+  it "keeps via: :geom borrowed owners alive through GC.compact" do
+    geom = TG::Geometry.parse_wkt(small_polygon_wkt)
+    index = TG::Geometry::Index.build([["zone", geom]], via: :geom, strategy: :rtree)
+
+    geom = nil
+    compact_if_supported
+
+    expect(index.find_covering(5, 5)).to eq("zone")
+    expect(index.covering_ids(0, 5)).to eq(["zone"])
+  end
+
+  it "keeps via: :geojson owned geometries usable through GC.compact" do
+    index = TG::Geometry::Index.build([["zone", small_polygon_geojson]], via: :geojson, strategy: :rtree)
+
+    compact_if_supported
+
+    expect(index.find_covering(5, 5)).to eq("zone")
+    expect(index.covering_ids(10, 10)).to eq(["zone"])
+  end
+
+  it "reports native memory through ObjectSpace.memsize_of for geom and index" do
+    geom = TG::Geometry.parse_wkt(small_polygon_wkt)
+    borrowed = TG::Geometry::Index.build([["zone", geom]], via: :geom, strategy: :flat)
+    owned = TG::Geometry::Index.build([["zone", small_polygon_geojson]], via: :geojson, strategy: :rtree)
+
+    expect(ObjectSpace.memsize_of(geom)).to be > ObjectSpace.memsize_of(Object.new)
+    expect(ObjectSpace.memsize_of(borrowed)).to be > ObjectSpace.memsize_of(Object.new)
+    expect(ObjectSpace.memsize_of(owned)).to be > ObjectSpace.memsize_of(borrowed)
+  end
+
+  it "returns rtree, owned geometry, and entries bytes to zero after dispose in debug builds" do
+    skip "TG_DEBUG_TEST hooks are not enabled" unless TG::Geometry::Index.method_defined?(:_force_dispose_for_test!)
+
+    index = TG::Geometry::Index.build([["zone", small_polygon_geojson]], via: :geojson, strategy: :rtree)
+
+    expect(index._entries_bytes_for_test).to be > 0
+    expect(index._owned_geom_bytes_for_test).to be > 0
+    expect(index._rtree_bytes_for_test).to be > 0
+
+    index._force_dispose_for_test!
+
+    expect(index._entries_bytes_for_test).to eq(0)
+    expect(index._owned_geom_bytes_for_test).to eq(0)
+    expect(index._rtree_bytes_for_test).to eq(0)
+    expect(index._initialized_entries_for_test).to eq(0)
+  end
+end

data/spec/block_1_skeleton_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Release Core Block 1 skeleton" do
+  it "compiles the native extension" do
+    expect(File.file?(EXT_SO)).to be(true)
+  end
+
+  it "loads through the canonical require path" do
+    expect(defined?(TG::Geometry)).to eq("constant")
+    expect(TG::Geometry::VERSION).to be_a(String)
+  end
+
+  it "defines the required error hierarchy" do
+    expect(TG::Geometry::Error).to be < StandardError
+    expect(TG::Geometry::ParseError).to be < TG::Geometry::Error
+    expect(TG::Geometry::ArgumentError).to be < ::ArgumentError
+    expect(TG::Geometry::FrozenIndexError).to be < TG::Geometry::Error
+  end
+
+  it "defines required public classes under TG::Geometry" do
+    expect(TG::Geometry::Geom).to be_a(Class)
+    expect(TG::Geometry::Rect).to be_a(Class)
+    expect(TG::Geometry::Index).to be_a(Class)
+  end
+
+  it "does not expose forbidden top-level TG API classes or methods" do
+    expect(TG).not_to respond_to(:parse)
+    expect(TG.const_defined?(:Geom, false)).to be(false)
+    expect(TG.const_defined?(:Rect, false)).to be(false)
+    expect(TG.const_defined?(:Index, false)).to be(false)
+    expect(TG.const_defined?(:Error, false)).to be(false)
+    expect(TG.const_defined?(:ParseError, false)).to be(false)
+  end
+
+  it "disables manual allocation for Geom and Index" do
+    expect { TG::Geometry::Geom.allocate }.to raise_error(TypeError)
+    expect { TG::Geometry::Index.allocate }.to raise_error(TypeError)
+  end
+
+  it "keeps Rect constructible with explicit coordinates" do
+    expect(TG::Geometry::Rect.new(0, 0, 0, 0)).to be_a(TG::Geometry::Rect)
+  end
+end