@flighthq/spatial 0.4.0-next.1663.d9c5746 → 0.4.0-next.1694.598ef6f

package/src/uniformGrid.test.ts

@@ -1,7 +1,11 @@
-import type { SpatialAabb, SpatialIndexingNotice, SpatialObjectId, SpatialPair } from '@flighthq/types/contract';
+import type { SpatialAabb2D, SpatialIndexingNotice, SpatialObjectId, SpatialPair } from '@flighthq/types/contract';
 import { afterEach, describe, expect, it } from 'vitest';
 
-import { MAX_INDEXED_CELLS_PER_OBJECT, createUniformGridSpatialBackend, setSpatialIndexingGuard } from './uniformGrid';
+import {
+  MAX_INDEXED_CELLS_PER_OBJECT,
+  createUniformGridSpatialBackend2D,
+  setSpatialIndexingGuard,
+} from './uniformGrid';
 
 afterEach(() => {
   setSpatialIndexingGuard(null);
@@ -9,7 +13,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 +21,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 +43,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 +69,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 +88,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 +103,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 +121,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 +209,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 +219,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 +227,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 +273,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 +282,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 +321,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 +350,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 +363,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 +372,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 +392,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 +406,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 +415,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 +433,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 +453,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 +466,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 +493,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 +503,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 +518,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 +526,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 +537,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 +555,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 +566,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 +594,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 +604,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 +613,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 +623,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 +638,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 +651,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 +662,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 +671,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 +679,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);
@@ -684,7 +691,7 @@ describe('setSpatialIndexingGuard', () => {
   it('reports a decline with its reason, and no span', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(7, { minX: NaN, minY: 0, maxX: 10, maxY: 10 });
     expect(notices).toEqual([
       {
@@ -701,7 +708,7 @@ describe('setSpatialIndexingGuard', () => {
   it('reports an overflow with the span the bound refused to walk', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(7, { minX: 0, minY: 0, maxX: 199, maxY: 199 });
     expect(notices).toEqual([
       {
@@ -719,7 +726,7 @@ describe('setSpatialIndexingGuard', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
     for (const cellSize of [0, -1]) {
-      const grid = createUniformGridSpatialBackend(cellSize);
+      const grid = createUniformGridSpatialBackend2D(cellSize);
       expect(grid.insertSpatialObject(7, { minX: 0, minY: 0, maxX: 10, maxY: 10 })).toBe(true);
       const point: SpatialObjectId[] = [];
       grid.querySpatialPoint(5, 5, point);
@@ -740,7 +747,7 @@ describe('setSpatialIndexingGuard', () => {
   it('declines and reports inverted bounds', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     expect(grid.insertSpatialObject(7, { minX: 10, minY: 0, maxX: 0, maxY: 10 })).toBe(false);
     expect(grid.explainSpatialIndexing(7)).toEqual({
       bucketCount: 0,
@@ -763,7 +770,7 @@ describe('setSpatialIndexingGuard', () => {
   it('reports update and remove operations whose id was never inserted', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     expect(grid.updateSpatialObject(7, { minX: 0, minY: 0, maxX: 5, maxY: 5 })).toBe(true);
     grid.removeSpatialObject(8);
     expect(notices).toEqual([
@@ -789,7 +796,7 @@ describe('setSpatialIndexingGuard', () => {
   it('stays silent on the ordinary path', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(10);
     grid.insertSpatialObject(1, { minX: 0, minY: 0, maxX: 10, maxY: 10 });
     grid.removeSpatialObject(1);
     expect(notices).toEqual([]);
@@ -799,22 +806,22 @@ describe('setSpatialIndexingGuard', () => {
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
     setSpatialIndexingGuard(null);
-    const grid = createUniformGridSpatialBackend(10);
+    const grid = createUniformGridSpatialBackend2D(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);
+    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: 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 };
 

package/dist/explainSpatialIndexing.d.ts

@@ -1,3 +0,0 @@
-import type { SpatialIndex, SpatialIndexingExplanation, SpatialObjectId } from '@flighthq/types/contract';
-export declare function explainSpatialIndexing(index: Readonly<SpatialIndex>, id: SpatialObjectId): SpatialIndexingExplanation;
-//# sourceMappingURL=explainSpatialIndexing.d.ts.map

package/dist/explainSpatialIndexing.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"explainSpatialIndexing.d.ts","sourceRoot":"","sources":["../src/explainSpatialIndexing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAY1G,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,eAAe,GAAG,0BAA0B,CAErH"}

package/dist/explainSpatialIndexing.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"explainSpatialIndexing.js","sourceRoot":"","sources":["../src/explainSpatialIndexing.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,sGAAsG;AACtG,+FAA+F;AAC/F,sGAAsG;AACtG,6FAA6F;AAC7F,yBAAyB;AACzB,EAAE;AACF,kGAAkG;AAClG,oGAAoG;AACpG,yDAAyD;AACzD,MAAM,UAAU,sBAAsB,CAAC,KAA6B,EAAE,EAAmB;IACvF,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;AAC1D,CAAC"}

package/src/explainSpatialIndexing.test.ts

@@ -1,76 +0,0 @@
-import type { SpatialObjectId } from '@flighthq/types/contract';
-import { describe, expect, it } from 'vitest';
-
-import { explainSpatialIndexing } from './explainSpatialIndexing';
-import { createSpatialIndex, insertSpatialObject, removeSpatialObject, updateSpatialObject } from './spatialIndex';
-import { MAX_INDEXED_CELLS_PER_OBJECT, createUniformGridSpatialBackend } from './uniformGrid';
-
-describe('explainSpatialIndexing', () => {
-  it('reports absent for an id that was never inserted', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(10));
-    expect(explainSpatialIndexing(index, 42)).toEqual({ bucketCount: 0, id: 42, mode: 'absent', reason: null });
-  });
-
-  it('reports the bucket count of an ordinary object', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(10));
-    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 25, maxY: 25 });
-    // Covers cells 0..2 on each axis.
-    expect(explainSpatialIndexing(index, 1)).toEqual({ bucketCount: 9, id: 1, mode: 'cells', reason: null });
-  });
-
-  it('reports overflow with no buckets for an oversized object', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(1));
-    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 1e6, maxY: 1e6 });
-    expect(explainSpatialIndexing(index, 1)).toEqual({ bucketCount: 0, id: 1, mode: 'overflow', reason: null });
-  });
-
-  it('reports declined with the reason for non-finite bounds', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(10));
-    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: Infinity, maxY: 10 });
-    expect(explainSpatialIndexing(index, 1)).toEqual({
-      bucketCount: 0,
-      id: 1,
-      mode: 'declined',
-      reason: 'non-finite-bounds',
-    });
-  });
-
-  it('returns to absent after a remove', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(10));
-    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 5, maxY: 5 });
-    removeSpatialObject(index, 1);
-    expect(explainSpatialIndexing(index, 1).mode).toBe('absent');
-  });
-
-  it('tracks the mode across updates', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(1));
-    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 2, maxY: 2 });
-    expect(explainSpatialIndexing(index, 1).mode).toBe('cells');
-    updateSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 1e9, maxY: 1e9 });
-    expect(explainSpatialIndexing(index, 1).mode).toBe('overflow');
-    updateSpatialObject(index, 1, { minX: NaN, minY: 0, maxX: 2, maxY: 2 });
-    expect(explainSpatialIndexing(index, 1).mode).toBe('declined');
-  });
-
-  it('never exceeds the per-object bucket budget it exists to measure', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(1));
-    const ids: SpatialObjectId[] = [];
-    for (let i = 0; i < 8; i++) {
-      const extent = 10 ** i;
-      insertSpatialObject(index, i, { minX: 0, minY: 0, maxX: extent, maxY: extent });
-      ids.push(i);
-    }
-    for (const id of ids) {
-      expect(explainSpatialIndexing(index, id).bucketCount).toBeLessThanOrEqual(MAX_INDEXED_CELLS_PER_OBJECT);
-    }
-  });
-
-  it('mutates nothing — repeated calls report the same thing', () => {
-    const index = createSpatialIndex(createUniformGridSpatialBackend(10));
-    insertSpatialObject(index, 1, { minX: 0, minY: 0, maxX: 5, maxY: 5 });
-    const first = explainSpatialIndexing(index, 1);
-    expect(explainSpatialIndexing(index, 1)).toEqual(first);
-    expect(explainSpatialIndexing(index, 99).mode).toBe('absent');
-    expect(explainSpatialIndexing(index, 1)).toEqual(first);
-  });
-});