Design: memory & ownership#

Status: describes the implemented system (0.1.0). Implements D10; consumes the ownership rules from GEOS research §4.

1. The two heaps#

JS objects live in JavaScriptCore's heap; GEOSGeometry/GEOSCoordSequence live in the C heap. JSC cannot see the C heap. Consequences:

• A million live geometries may occupy gigabytes while the JS wrappers look tiny → the GC never feels pressure and never runs.
• Finalizers exist but are unpredictable and hazardous at teardown.

Therefore: explicit disposal is the contract; the GC is insurance.

2. Ownership mapping#

Two hard rules enforced at the API layer:

1. Same-context destroy — a Geometry used with a different Geos throws TypeError (the Rust lifetime lesson, enforced structurally: D11).
2. Transfer semantics — construction functions take ownership exactly as GEOS does; the shim's builders free what they allocated and hand GEOS the rest.

3. Disposal discipline#

// One-off: explicit dispose
const g = geos.readWKT(wkt);
try { /* … */ } finally { g.dispose(); }       // or: using g = … (TS explicit resource mgmt)

// Hot loop: arena
using arena = geos.arena();
for (const w of wkts) {
  const g = arena.read(wkb);                   // registered, not individually freed
  results.push(geos.intersection(a, g));
}                                              // ← shim destroy_many: one FFI call

// Batch op outputs can be arena-allocated too:
const merged = geos.unionAll(parcels, { arena });  // caller frees `merged` or the arena does

• using / Symbol.dispose is the primary ergonomic path (Bun supports TS explicit resource management).
• Arenas never free geoms they didn't create (only registration counts).
• Nested arenas are allowed; child disposal is independent.

4. FinalizationRegistry — backstop only#

A registry maps Geometry → (ctx, ptr) and destroys orphans on collection. Constraints documented on the API:

• It is a leak net, not a strategy: collection timing is unspecified; at process teardown FFI calls may be unsafe, so orphans at exit are reported, not freed.
• Geometry finalization never touches the STRtree (borrowed-pointer rule): trees hold ids, and tree dispose() validates that registered geoms are still alive — stale ids are a GeosError, never a dangling pointer deref.

5. Making the invisible heap visible#

Each Geos maintains counters fed by JS-side registration plus shim crossings (D10; implemented per Phase 3's D24):

• geos.stats — live geometry count, floor byte estimate, finalizer reaps, peak live count, arena high-water mark (Phase 3). Pure JS counting, safe on hot paths.
• geos.statsPrecise() (Phase 3) — ONE shim crossing over the live pointer set: 64 bytes + vertices × coordinate dimension × 8 per geometry. Data-derived but still documented approximate (M ordinates are not per-geometry detectable on the C API).

Both are included in leak-test assertions (test/soak/, the CI nightly job, D24). This is the go-geos lesson (their README's "Memory management" warning) answered with instrumentation instead of apology.

6. Pitfall checklist (encoded in tests)#