@flighthq/spatial 0.3.1-next.975.01aea94 → 0.4.0-edge.1908.751021c

package/src/uniformGrid.test.ts

@@ -1,7 +1,8 @@
-import type { SpatialAabb, SpatialIndexingNotice, SpatialObjectId, SpatialPair } from '@flighthq/types/contract';
+import type { SpatialAabb2D, SpatialObjectId, SpatialPair } from '@flighthq/types/contract';
 import { afterEach, describe, expect, it } from 'vitest';
 
-import { MAX_INDEXED_CELLS_PER_OBJECT, createUniformGridSpatialBackend, setSpatialIndexingGuard } from './uniformGrid';
+import { setSpatialIndexingGuard } from './spatialIndexingGuard';
+import { MAX_INDEXED_CELLS_PER_OBJECT, createUniformGridSpatialBackend2D } from './uniformGrid';
 
 afterEach(() => {
   setSpatialIndexingGuard(null);
@@ -9,7 +10,7 @@ afterEach(() => {
 
 // A plain AABB-overlap confirmation used to turn broadphase candidate pairs into confirmed pairs (the
 // narrow-phase stand-in): exactly the check the caller would apply downstream.
-function boundsOverlap(a: Readonly<SpatialAabb>, b: Readonly<SpatialAabb>): boolean {
+function boundsOverlap(a: Readonly<SpatialAabb2D>, b: Readonly<SpatialAabb2D>): boolean {
   return a.minX < b.maxX && a.maxX > b.minX && a.minY < b.maxY && a.maxY > b.minY;
 }
 
@@ -17,7 +18,10 @@ function pairKeys(pairs: readonly SpatialPair[]): string[] {
   return pairs.map((p) => `${Math.min(p.a, p.b)}-${Math.max(p.a, p.b)}`).sort();
 }
 
-function bruteForcePairKeys(objects: ReadonlyMap<SpatialObjectId, Readonly<SpatialAabb>>, cellSize: number): string[] {
+function bruteForcePairKeys(
+  objects: ReadonlyMap<SpatialObjectId, Readonly<SpatialAabb2D>>,
+  cellSize: number,
+): string[] {
   const entries = [...objects];
   const pairs: string[] = [];
   for (let i = 0; i < entries.length; i++) {
@@ -36,11 +40,11 @@ function bruteForcePairKeys(objects: ReadonlyMap<SpatialObjectId, Readonly<Spati
   return pairs.sort();
 }
 
-function boundsContainPoint(bounds: Readonly<SpatialAabb>, x: number, y: number): boolean {
+function boundsContainPoint(bounds: Readonly<SpatialAabb2D>, x: number, y: number): boolean {
   return x >= bounds.minX && x <= bounds.maxX && y >= bounds.minY && y <= bounds.maxY;
 }
 
-function boundsIntersectRay(bounds: Readonly<SpatialAabb>, ox: number, oy: number, dx: number, dy: number): boolean {
+function boundsIntersectRay(bounds: Readonly<SpatialAabb2D>, ox: number, oy: number, dx: number, dy: number): boolean {
   let tMin = -Infinity;
   let tMax = Infinity;
   if (dx === 0) {
@@ -62,7 +66,7 @@ function boundsIntersectRay(bounds: Readonly<SpatialAabb>, ox: number, oy: numbe
   return tMax >= tMin && tMax >= 0;
 }
 
-function boundsShareCell(a: Readonly<SpatialAabb>, b: Readonly<SpatialAabb>, cellSize: number): boolean {
+function boundsShareCell(a: Readonly<SpatialAabb2D>, b: Readonly<SpatialAabb2D>, cellSize: number): boolean {
   return (
     Math.max(Math.floor(a.minX / cellSize), Math.floor(b.minX / cellSize)) <=
       Math.min(Math.floor(a.maxX / cellSize), Math.floor(b.maxX / cellSize)) &&
@@ -81,7 +85,7 @@ function createTestRandom(seed: number): () => number {
   };
 }
 
-function isOverflowBounds(bounds: Readonly<SpatialAabb>, cellSize: number): boolean {
+function isOverflowBounds(bounds: Readonly<SpatialAabb2D>, cellSize: number): boolean {
   const width = Math.floor(bounds.maxX / cellSize) - Math.floor(bounds.minX / cellSize) + 1;
   const height = Math.floor(bounds.maxY / cellSize) - Math.floor(bounds.minY / cellSize) + 1;
   return width * height > MAX_INDEXED_CELLS_PER_OBJECT;
@@ -96,10 +100,10 @@ describe('brute-force property coverage', () => {
     const cellSize = 4;
     for (const seed of [0x1357_9bdf, 0x2468_ace0, 0x5eed_f00d, 0xc0ff_ee42]) {
       const random = createTestRandom(seed);
-      const grid = createUniformGridSpatialBackend(cellSize);
-      const objects = new Map<SpatialObjectId, SpatialAabb>();
+      const grid = createUniformGridSpatialBackend2D(cellSize);
+      const objects = new Map<SpatialObjectId, SpatialAabb2D>();
 
-      function randomBounds(overflow: boolean): SpatialAabb {
+      function randomBounds(overflow: boolean): SpatialAabb2D {
         const minX = Math.floor(random() * 160) - 80 + random();
         const minY = Math.floor(random() * 160) - 80 + random();
         const width = overflow ? cellSize * (34 + Math.floor(random() * 12)) : 0.25 + random() * 12;
@@ -114,7 +118,7 @@ describe('brute-force property coverage', () => {
 
         const regionMinX = random() * 240 - 120;
         const regionMinY = random() * 240 - 120;
-        const region: SpatialAabb = {
+        const region: SpatialAabb2D = {
           minX: regionMinX,
           minY: regionMinY,
           maxX: regionMinX + 1 + random() * 80,
@@ -202,7 +206,7 @@ describe('cell range across every transition that can strand it', () => {
 
   // Correctness only. Used where the occupied cell range is legitimately wide, so the walk is
   // genuinely proportional to it — that is the documented conservative over-walk, not the defect.
-  function rayIds(grid: ReturnType<typeof createUniformGridSpatialBackend>): SpatialObjectId[] {
+  function rayIds(grid: ReturnType<typeof createUniformGridSpatialBackend2D>): SpatialObjectId[] {
     const out: SpatialObjectId[] = [];
     grid.querySpatialRay(-5, 0.5, 1, 0, out);
     return out.sort((a, b) => a - b);
@@ -212,7 +216,7 @@ describe('cell range across every transition that can strand it', () => {
   // empty or tight, so any millions-of-cells walk means the range was stranded. Keeping these two
   // helpers apart is the point: a single budgeted helper made two honest cases fail, because their
   // titles claimed a seeding/removal property while the assertion silently demanded O(1).
-  function rayIdsFast(grid: ReturnType<typeof createUniformGridSpatialBackend>): SpatialObjectId[] {
+  function rayIdsFast(grid: ReturnType<typeof createUniformGridSpatialBackend2D>): SpatialObjectId[] {
     const started = performance.now();
     const ids = rayIds(grid);
     expect(performance.now() - started).toBeLessThan(RAY_BUDGET_MS);
@@ -220,8 +224,8 @@ describe('cell range across every transition that can strand it', () => {
   }
 
   // Two small objects placed FAR apart, so any stranded range spans millions of cells.
-  function gridWithWideRange(): ReturnType<typeof createUniformGridSpatialBackend> {
-    const grid = createUniformGridSpatialBackend(1);
+  function gridWithWideRange(): ReturnType<typeof createUniformGridSpatialBackend2D> {
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     grid.insertSpatialObject(2, { minX: FAR, minY: 0, maxX: FAR + 1, maxY: 1 });
     return grid;
@@ -266,7 +270,7 @@ describe('cell range across every transition that can strand it', () => {
 
   it('updates the last celled object into overflow, emptying the cells', () => {
     // The overflow *transition* proper: no remove call, the object simply stops being celled.
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     grid.insertSpatialObject(2, { minX: FAR, minY: 0, maxX: FAR + 1, maxY: 1 });
     grid.updateSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
@@ -275,7 +279,7 @@ describe('cell range across every transition that can strand it', () => {
   });
 
   it('updates an overflowed object back into cells, re-seeding rather than widening', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     grid.insertSpatialObject(2, { minX: FAR, minY: 0, maxX: FAR + 1, maxY: 1 });
     grid.updateSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
@@ -314,14 +318,14 @@ describe('cell range across every transition that can strand it', () => {
   });
 });
 
-describe('createUniformGridSpatialBackend', () => {
+describe('createUniformGridSpatialBackend2D', () => {
   it('keeps region comparisons reentrant when a bounds getter starts a nested query', () => {
-    const grid = createUniformGridSpatialBackend(0);
+    const grid = createUniformGridSpatialBackend2D(0);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     grid.insertSpatialObject(2, { minX: 100, minY: 100, maxX: 101, maxY: 101 });
     let minXReads = 0;
     let nestedCalls = 0;
-    const region: SpatialAabb = {
+    const region: SpatialAabb2D = {
       get minX() {
         minXReads++;
         if (minXReads === 2) {
@@ -343,7 +347,7 @@ describe('createUniformGridSpatialBackend', () => {
   });
 
   it('emits a pair spanning several shared cells exactly once', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     // Both objects cover the same 3x3 block of cells (0..2, 0..2), so they co-occupy nine cells.
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 25, maxY: 25 });
     grid.insertSpatialObject(2, { minX: 5, minY: 5, maxX: 29, maxY: 29 });
@@ -356,7 +360,7 @@ describe('createUniformGridSpatialBackend', () => {
   });
 
   it('never pairs an object with itself', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 4, maxY: 4 });
 
     const pairs: SpatialPair[] = [];
@@ -365,7 +369,7 @@ describe('createUniformGridSpatialBackend', () => {
   });
 
   it('returns nothing from every query on an empty grid', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
 
     const pairs: SpatialPair[] = [];
     grid.querySpatialPairs(pairs);
@@ -385,7 +389,7 @@ describe('createUniformGridSpatialBackend', () => {
   });
 
   it('indexes objects at negative coordinates', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: -8, minY: -8, maxX: -4, maxY: -4 });
     grid.insertSpatialObject(2, { minX: -6, minY: -6, maxX: -2, maxY: -2 });
 
@@ -399,7 +403,7 @@ describe('createUniformGridSpatialBackend', () => {
   });
 
   it('gives the same confirmed pairs across different cell sizes', () => {
-    const objects: { id: SpatialObjectId; bounds: SpatialAabb }[] = [
+    const objects: { id: SpatialObjectId; bounds: SpatialAabb2D }[] = [
       { id: 1, bounds: { minX: 0, minY: 0, maxX: 10, maxY: 10 } },
       { id: 2, bounds: { minX: 5, minY: 5, maxX: 15, maxY: 15 } },
       { id: 3, bounds: { minX: 12, minY: 12, maxX: 20, maxY: 20 } },
@@ -408,7 +412,7 @@ describe('createUniformGridSpatialBackend', () => {
     const boundsOf = new Map(objects.map((o) => [o.id, o.bounds]));
 
     function confirmedPairs(cellSize: number): string[] {
-      const grid = createUniformGridSpatialBackend(cellSize);
+      const grid = createUniformGridSpatialBackend2D(cellSize);
       for (const o of objects) grid.insertSpatialObject(o.id, o.bounds);
       const candidates: SpatialPair[] = [];
       grid.querySpatialPairs(candidates);
@@ -426,7 +430,7 @@ describe('createUniformGridSpatialBackend', () => {
 
 describe('MAX_INDEXED_CELLS_PER_OBJECT', () => {
   it('is the per-object cell budget the oversized path is chosen by', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     // A square block of exactly the budget stays on the ordinary path; one cell more does not. The
     // budget is a count of cells, not an extent, so it is asserted through the count.
     const side = Math.sqrt(MAX_INDEXED_CELLS_PER_OBJECT);
@@ -446,7 +450,7 @@ describe('MAX_INDEXED_CELLS_PER_OBJECT', () => {
 
 describe('non-finite bounds', () => {
   it('declines rather than indexing, and answers with the false sentinel', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     expect(grid.insertSpatialObject(1, { minX: NaN, minY: 0, maxX: 10, maxY: 10 })).toBe(false);
     expect(grid.insertSpatialObject(2, { minX: 0, minY: 0, maxX: Infinity, maxY: 10 })).toBe(false);
     expect(grid.insertSpatialObject(3, { minX: 0, minY: -Infinity, maxX: 10, maxY: 10 })).toBe(false);
@@ -459,12 +463,12 @@ describe('non-finite bounds', () => {
   });
 
   it('returns true for finite bounds, so the sentinel distinguishes decline from success', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     expect(grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 10, maxY: 10 })).toBe(true);
   });
 
   it('keeps a declined object out of every query rather than out of some', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: NaN, minY: NaN, maxX: NaN, maxY: NaN });
     grid.insertSpatialObject(2, { minX: 0, minY: 0, maxX: 10, maxY: 10 });
 
@@ -486,7 +490,7 @@ describe('non-finite bounds', () => {
   });
 
   it('drops an object that updates to non-finite bounds instead of stranding it at its old ones', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 10, maxY: 10 });
     expect(grid.updateSpatialObject(1, { minX: NaN, minY: NaN, maxX: NaN, maxY: NaN })).toBe(false);
     expect(grid.explainSpatialIndexing(1).mode).toBe('declined');
@@ -496,7 +500,7 @@ describe('non-finite bounds', () => {
   });
 
   it('lets a declined object recover on a later finite update', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: NaN, minY: NaN, maxX: NaN, maxY: NaN });
     expect(grid.updateSpatialObject(1, { minX: 0, minY: 0, maxX: 10, maxY: 10 })).toBe(true);
     expect(grid.explainSpatialIndexing(1).mode).toBe('cells');
@@ -511,7 +515,7 @@ describe('oversized region query', () => {
   // wider than the world would walk extent-squared cells against a grid holding almost nothing.
   // Measured at 69 ms for a 1000x1000-cell region over a one-object grid before the bound.
   it('answers a region far wider than the grid without walking it cell by cell', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     const out: SpatialObjectId[] = [];
     grid.querySpatialRegion({ minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 }, out);
@@ -519,7 +523,7 @@ describe('oversized region query', () => {
   });
 
   it('returns the same objects either way it walks', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     for (let i = 0; i < 40; i++) grid.insertSpatialObject(i, { minX: i, minY: 0, maxX: i + 0.5, maxY: 1 });
     const wide: SpatialObjectId[] = [];
     grid.querySpatialRegion({ minX: -1e9, minY: -1e9, maxX: 1e9, maxY: 1e9 }, wide);
@@ -530,7 +534,7 @@ describe('oversized region query', () => {
   });
 
   it('still excludes objects the wide region misses', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     grid.insertSpatialObject(2, { minX: 5e11, minY: 0, maxX: 5e11 + 1, maxY: 1 });
     const out: SpatialObjectId[] = [];
@@ -548,7 +552,7 @@ describe('oversized-extent bound', () => {
   // wide, which is what a diverging rigid-body simulation actually produces) would be 1e24 cells and
   // would never return, which is exactly why the bound cannot be tested at its motivating scale.
   it('holds an oversized object without writing a cell per unit of its extent', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 200, maxY: 200 });
     const explanation = grid.explainSpatialIndexing(1);
     expect(explanation.mode).toBe('overflow');
@@ -559,13 +563,13 @@ describe('oversized-extent bound', () => {
     // Unreachable for an unbounded build (1e24 cells), so this one cannot be written as a
     // before/after assertion — it is the proof that the motivating case is now O(1). Safe to run only
     // because the assertion above fails first if the bound is ever removed.
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     expect(grid.insertSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 })).toBe(true);
     expect(grid.explainSpatialIndexing(1).mode).toBe('overflow');
   });
 
   it('keeps an oversized object queryable — the bound is a cost decision, not a dropped object', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
     grid.insertSpatialObject(2, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
 
@@ -587,7 +591,7 @@ describe('oversized-extent bound', () => {
   });
 
   it('emits each overflow pair once, including overflow against overflow', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: -1e9, minY: -1e9, maxX: 1e9, maxY: 1e9 });
     grid.insertSpatialObject(2, { minX: -1e9, minY: -1e9, maxX: 1e9, maxY: 1e9 });
     grid.insertSpatialObject(3, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
@@ -597,7 +601,7 @@ describe('oversized-extent bound', () => {
   });
 
   it('does not pair an overflow object with a disjoint object', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 100000, maxY: 100000 });
     grid.insertSpatialObject(2, { minX: -50, minY: -50, maxX: -40, maxY: -40 });
     const pairs: SpatialPair[] = [];
@@ -606,7 +610,7 @@ describe('oversized-extent bound', () => {
   });
 
   it('removes an oversized object without walking its extent, and stops returning it', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
     grid.removeSpatialObject(1);
     expect(grid.explainSpatialIndexing(1).mode).toBe('absent');
@@ -616,7 +620,7 @@ describe('oversized-extent bound', () => {
   });
 
   it('moves an object between the celled and overflow paths as it grows and shrinks', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 2, maxY: 2 });
     expect(grid.explainSpatialIndexing(1).mode).toBe('cells');
     grid.updateSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
@@ -631,7 +635,7 @@ describe('oversized-extent bound', () => {
   });
 
   it('clears overflow with the rest of the index', () => {
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
     grid.clearSpatialIndex();
     expect(grid.explainSpatialIndexing(1).mode).toBe('absent');
@@ -644,7 +648,7 @@ describe('oversized-extent bound', () => {
     // Without the bound the occupied cell range stretches to the oversized object's span, and every
     // subsequent ray walks it. Two small objects far apart bound the range; the oversized one must
     // not widen it, which shows up as the ray still resolving correctly and promptly.
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 1, maxY: 1 });
     grid.insertSpatialObject(2, { minX: -1e12, minY: -1e12, maxX: 1e12, maxY: 1e12 });
     const out: SpatialObjectId[] = [];
@@ -655,7 +659,7 @@ describe('oversized-extent bound', () => {
 
 describe('ray edge cases', () => {
   it('finds objects along a ray that passes exactly through cell corners', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 10, minY: 10, maxX: 12, maxY: 12 });
     grid.insertSpatialObject(2, { minX: 20, minY: 20, maxX: 22, maxY: 22 });
     const out: SpatialObjectId[] = [];
@@ -664,7 +668,7 @@ describe('ray edge cases', () => {
   });
 
   it('finds an object when the ray starts inside its bounds', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 5, minY: 5, maxX: 15, maxY: 15 });
     const out: SpatialObjectId[] = [];
     grid.querySpatialRay(10, 10, -1, 0, out);
@@ -672,7 +676,7 @@ describe('ray edge cases', () => {
   });
 
   it('clips a ray entering the occupied range from far outside', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 100, minY: 30, maxX: 110, maxY: 40 });
     const out: SpatialObjectId[] = [];
     grid.querySpatialRay(-1e9, 35, 1, 0, out);
@@ -680,141 +684,9 @@ describe('ray edge cases', () => {
   });
 });
 
-describe('setSpatialIndexingGuard', () => {
-  it('reports a decline with its reason, and no span', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
-    grid.insertSpatialObject(7, { minX: NaN, minY: 0, maxX: 10, maxY: 10 });
-    expect(notices).toEqual([
-      {
-        cellSize: 10,
-        id: 7,
-        mode: 'declined',
-        operation: 'insert',
-        reason: 'non-finite-bounds',
-        wouldOccupyBucketCount: 0,
-      },
-    ]);
-  });
-
-  it('reports an overflow with the span the bound refused to walk', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(1);
-    grid.insertSpatialObject(7, { minX: 0, minY: 0, maxX: 199, maxY: 199 });
-    expect(notices).toEqual([
-      {
-        cellSize: 1,
-        id: 7,
-        mode: 'overflow',
-        operation: 'insert',
-        reason: null,
-        wouldOccupyBucketCount: 40000,
-      },
-    ]);
-  });
-
-  it('reports an invalid cell size and keeps results correct through the bounded overflow path', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    for (const cellSize of [0, -1]) {
-      const grid = createUniformGridSpatialBackend(cellSize);
-      expect(grid.insertSpatialObject(7, { minX: 0, minY: 0, maxX: 10, maxY: 10 })).toBe(true);
-      const point: SpatialObjectId[] = [];
-      grid.querySpatialPoint(5, 5, point);
-      expect(point).toEqual([7]);
-    }
-    expect(notices).toEqual(
-      [0, -1].map((cellSize) => ({
-        cellSize,
-        id: 7,
-        mode: 'overflow',
-        operation: 'insert',
-        reason: 'invalid-cell-size',
-        wouldOccupyBucketCount: 0,
-      })),
-    );
-  });
-
-  it('declines and reports inverted bounds', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
-    expect(grid.insertSpatialObject(7, { minX: 10, minY: 0, maxX: 0, maxY: 10 })).toBe(false);
-    expect(grid.explainSpatialIndexing(7)).toEqual({
-      bucketCount: 0,
-      id: 7,
-      mode: 'declined',
-      reason: 'inverted-bounds',
-    });
-    expect(notices).toEqual([
-      {
-        cellSize: 10,
-        id: 7,
-        mode: 'declined',
-        operation: 'insert',
-        reason: 'inverted-bounds',
-        wouldOccupyBucketCount: 0,
-      },
-    ]);
-  });
-
-  it('reports update and remove operations whose id was never inserted', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
-    expect(grid.updateSpatialObject(7, { minX: 0, minY: 0, maxX: 5, maxY: 5 })).toBe(true);
-    grid.removeSpatialObject(8);
-    expect(notices).toEqual([
-      {
-        cellSize: 10,
-        id: 7,
-        mode: 'cells',
-        operation: 'update',
-        reason: 'missing-id',
-        wouldOccupyBucketCount: 0,
-      },
-      {
-        cellSize: 10,
-        id: 8,
-        mode: 'absent',
-        operation: 'remove',
-        reason: 'missing-id',
-        wouldOccupyBucketCount: 0,
-      },
-    ]);
-  });
-
-  it('stays silent on the ordinary path', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
-    grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 10, maxY: 10 });
-    grid.removeSpatialObject(1);
-    expect(notices).toEqual([]);
-  });
-
-  it('null uninstalls it', () => {
-    const notices: SpatialIndexingNotice[] = [];
-    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    setSpatialIndexingGuard(null);
-    const grid = createUniformGridSpatialBackend(10);
-    grid.insertSpatialObject(1, { minX: NaN, minY: 0, maxX: 10, maxY: 10 });
-    expect(notices).toEqual([]);
-  });
-
-  it('does not change what insert returns', () => {
-    setSpatialIndexingGuard(() => {});
-    const grid = createUniformGridSpatialBackend(10);
-    expect(grid.insertSpatialObject(1, { minX: NaN, minY: 0, maxX: 10, maxY: 10 })).toBe(false);
-    expect(grid.insertSpatialObject(2, { minX: 0, minY: 0, maxX: 10, maxY: 10 })).toBe(true);
-  });
-});
-
-describe('updateSpatialObject', () => {
+describe('updateSpatialObject2D', () => {
   it('refreshes exact bounds without retaining the caller object when the covered cells stay unchanged', () => {
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 1, minY: 1, maxX: 18, maxY: 18 });
     const updated = { minX: 4, minY: 4, maxX: 19, maxY: 19 };