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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/spatial",
-  "version": "0.3.1-next.975.01aea94",
+  "version": "0.4.0-edge.1908.751021c",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/geometry": "0.3.1-next.975.01aea94",
-    "@flighthq/types": "0.3.1-next.975.01aea94"
+    "@flighthq/geometry": "0.4.0-edge.1908.751021c",
+    "@flighthq/types": "0.4.0-edge.1908.751021c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/bvh3D.test.ts

@@ -0,0 +1,294 @@
+import type { SpatialAabb3D, SpatialIndexBackend3D, SpatialObjectId, SpatialPair } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createBvhSpatialBackend3D } from './bvh3D';
+import { setSpatialIndexingGuard } from './spatialIndexingGuard';
+import { createUniformGridSpatialBackend3D } from './uniformGrid3D';
+
+// The BVH is tested against the UNIFORM GRID, not against itself. The grid is the proven incumbent and
+// the two are meant to be interchangeable behind one seam, so any disagreement is a defect in one of
+// them — which is a far stronger statement than "the tree returns something plausible".
+//
+// Sets are compared, never order: the seam promises which ids match, and two structures walk their
+// contents in different orders by construction.
+
+function createRandom(seed: number): () => number {
+  let state = seed | 0 || 1;
+  return () => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return ((state >>> 0) % 100000) / 100000;
+  };
+}
+
+function box(x: number, y: number, z: number, size: number): SpatialAabb3D {
+  return { maxX: x + size, maxY: y + size, maxZ: z + size, minX: x, minY: y, minZ: z };
+}
+
+function sorted(ids: readonly SpatialObjectId[]): SpatialObjectId[] {
+  return [...ids].sort((a, b) => a - b);
+}
+
+function sortedPairs(pairs: readonly SpatialPair[]): string[] {
+  return pairs.map((pair) => `${String(Math.min(pair.a, pair.b))}-${String(Math.max(pair.a, pair.b))}`).sort();
+}
+
+describe('createBvhSpatialBackend3D', () => {
+  it('retains pair objects across a steady-topology query', () => {
+    const bvh = createBvhSpatialBackend3D(1);
+    bvh.insertSpatialObject(1, box(0, 0, 0, 2));
+    bvh.insertSpatialObject(2, box(1, 1, 1, 2));
+    const out: SpatialPair[] = [];
+    bvh.querySpatialPairs(out);
+    const pair = out[0];
+
+    bvh.querySpatialPairs(out);
+
+    expect(out[0]).toBe(pair);
+  });
+
+  it('answers every query exactly as the uniform grid does, over a seeded scene', () => {
+    const random = createRandom(6112026);
+    const bvh = createBvhSpatialBackend3D(2);
+    const grid = createUniformGridSpatialBackend3D(16);
+
+    // Deliberately wide size variance — the case a uniform grid handles worst and a tree handles well.
+    // If the two agree here they agree anywhere.
+    for (let id = 0; id < 120; id += 1) {
+      const size = id % 12 === 0 ? 40 + random() * 30 : 0.5 + random() * 4;
+      const bounds = box((random() - 0.5) * 400, (random() - 0.5) * 400, (random() - 0.5) * 400, size);
+      expect(bvh.insertSpatialObject(id, bounds)).toBe(grid.insertSpatialObject(id, bounds));
+    }
+
+    const bvhOut: SpatialObjectId[] = [];
+    const gridOut: SpatialObjectId[] = [];
+
+    for (let probe = 0; probe < 60; probe += 1) {
+      const region = box((random() - 0.5) * 400, (random() - 0.5) * 400, (random() - 0.5) * 400, 10 + random() * 60);
+      bvh.querySpatialRegion(region, bvhOut);
+      grid.querySpatialRegion(region, gridOut);
+      expect(sorted(bvhOut), `region probe ${String(probe)}`).toEqual(sorted(gridOut));
+
+      const px = (random() - 0.5) * 400;
+      const py = (random() - 0.5) * 400;
+      const pz = (random() - 0.5) * 400;
+      bvh.querySpatialPoint(px, py, pz, bvhOut);
+      grid.querySpatialPoint(px, py, pz, gridOut);
+      expect(sorted(bvhOut), `point probe ${String(probe)}`).toEqual(sorted(gridOut));
+
+      const dx = random() - 0.5;
+      const dy = random() - 0.5;
+      const dz = random() - 0.5;
+      bvh.querySpatialRay(px, py, pz, dx, dy, dz, bvhOut);
+      grid.querySpatialRay(px, py, pz, dx, dy, dz, gridOut);
+      expect(sorted(bvhOut), `ray probe ${String(probe)}`).toEqual(sorted(gridOut));
+    }
+  });
+
+  it('reports every TRULY overlapping pair after inserts, moves, and removals', () => {
+    const random = createRandom(778291);
+    const bvh = createBvhSpatialBackend3D(1.5);
+    const grid = createUniformGridSpatialBackend3D(12);
+
+    // The oracle's own record of where everything ended up, kept alongside rather than read back out of
+    // either index — a truth set derived from the thing under test would prove nothing.
+    const live = new Map<number, SpatialAabb3D>();
+    for (let id = 0; id < 60; id += 1) {
+      const bounds = box((random() - 0.5) * 80, (random() - 0.5) * 80, (random() - 0.5) * 80, 1 + random() * 5);
+      bvh.insertSpatialObject(id, bounds);
+      grid.insertSpatialObject(id, bounds);
+      live.set(id, bounds);
+    }
+    for (let id = 0; id < 60; id += 3) {
+      const bounds = box((random() - 0.5) * 80, (random() - 0.5) * 80, (random() - 0.5) * 80, 1 + random() * 5);
+      bvh.updateSpatialObject(id, bounds);
+      grid.updateSpatialObject(id, bounds);
+      live.set(id, bounds);
+    }
+    for (let id = 1; id < 60; id += 7) {
+      bvh.removeSpatialObject(id);
+      grid.removeSpatialObject(id);
+      live.delete(id);
+    }
+
+    const bvhPairs: SpatialPair[] = [];
+    const gridPairs: SpatialPair[] = [];
+    bvh.querySpatialPairs(bvhPairs);
+    grid.querySpatialPairs(gridPairs);
+
+    // NOT set equality, and the difference is the contract rather than a defect. A pair is a CANDIDATE:
+    // the grid emits everything sharing a cell without testing bounds at all, so its answer is a strict
+    // superset, while the tree tests overlap at the leaf and returns the true set. Both are legal; what
+    // both owe is that no real overlap is missing. Asserting equality here would have been asserting that
+    // two backends make the same conservative approximation, which the seam never promised.
+    const truth = new Set<string>();
+    for (let a = 0; a < 60; a += 1) {
+      for (let b = a + 1; b < 60; b += 1) {
+        const boundsA = live.get(a);
+        const boundsB = live.get(b);
+        if (boundsA === undefined || boundsB === undefined) continue;
+        if (
+          boundsA.minX < boundsB.maxX &&
+          boundsA.maxX > boundsB.minX &&
+          boundsA.minY < boundsB.maxY &&
+          boundsA.maxY > boundsB.minY &&
+          boundsA.minZ < boundsB.maxZ &&
+          boundsA.maxZ > boundsB.minZ
+        ) {
+          truth.add(`${String(a)}-${String(b)}`);
+        }
+      }
+    }
+
+    const bvhSet = new Set(sortedPairs(bvhPairs));
+    const gridSet = new Set(sortedPairs(gridPairs));
+    expect(truth.size).toBeGreaterThan(0);
+    for (const pair of truth) {
+      expect(bvhSet.has(pair), `bvh missed ${pair}`).toBe(true);
+      expect(gridSet.has(pair), `grid missed ${pair}`).toBe(true);
+    }
+    // No self-pairs and no duplicates, which both backends do owe exactly.
+    expect(sortedPairs(bvhPairs)).toEqual([...bvhSet].sort());
+    expect(bvhPairs.every((pair) => pair.a !== pair.b)).toBe(true);
+  });
+
+  it('keeps answering correctly while objects move within their margin', () => {
+    // The fat-bounds fast path: a small move leaves the tree untouched, so only the exact bounds are
+    // refreshed. If they were not, the query would answer from where the object USED to be — the exact
+    // failure the margin risks introducing.
+    const bvh = createBvhSpatialBackend3D(10);
+    bvh.insertSpatialObject(1, box(0, 0, 0, 1));
+
+    const out: SpatialObjectId[] = [];
+    bvh.querySpatialPoint(0.5, 0.5, 0.5, out);
+    expect(out).toEqual([1]);
+
+    // Well inside the 10-unit margin, so no reinsertion happens.
+    bvh.updateSpatialObject(1, box(4, 0, 0, 1));
+    bvh.querySpatialPoint(0.5, 0.5, 0.5, out);
+    expect(out).toEqual([]);
+    bvh.querySpatialPoint(4.5, 0.5, 0.5, out);
+    expect(out).toEqual([1]);
+  });
+
+  it('declines non-finite and inverted bounds with the same sentinel as the grid', () => {
+    const bvh = createBvhSpatialBackend3D();
+    const grid = createUniformGridSpatialBackend3D(16);
+    const nonFinite: SpatialAabb3D = { maxX: 1, maxY: 1, maxZ: 1, minX: NaN, minY: 0, minZ: 0 };
+    const inverted: SpatialAabb3D = { maxX: -1, maxY: 1, maxZ: 1, minX: 0, minY: 0, minZ: 0 };
+
+    expect(bvh.insertSpatialObject(1, nonFinite)).toBe(grid.insertSpatialObject(1, nonFinite));
+    expect(bvh.insertSpatialObject(2, inverted)).toBe(grid.insertSpatialObject(2, inverted));
+    expect(bvh.explainSpatialIndexing(1).mode).toBe('declined');
+    expect(bvh.explainSpatialIndexing(1).reason).toBe('non-finite-bounds');
+    expect(bvh.explainSpatialIndexing(2).reason).toBe('inverted-bounds');
+
+    const out: SpatialObjectId[] = [];
+    bvh.querySpatialRegion(box(-100, -100, -100, 200), out);
+    expect(out).toEqual([]);
+  });
+
+  it('removes an object whose update is declined rather than leaving it at its old bounds', () => {
+    // The seam's contract: a declined update must not read as a current position. Kept identical to the
+    // grid's behaviour, since a caller ignoring the sentinel must not see the two backends differ.
+    const bvh = createBvhSpatialBackend3D();
+    bvh.insertSpatialObject(1, box(0, 0, 0, 4));
+    expect(bvh.updateSpatialObject(1, { maxX: 1, maxY: 1, maxZ: 1, minX: Infinity, minY: 0, minZ: 0 })).toBe(false);
+
+    const out: SpatialObjectId[] = [];
+    bvh.querySpatialRegion(box(-10, -10, -10, 40), out);
+    expect(out).toEqual([]);
+    expect(bvh.explainSpatialIndexing(1).mode).toBe('declined');
+  });
+
+  it('reports absent for an id it has never seen, and after a clear', () => {
+    const bvh = createBvhSpatialBackend3D();
+    expect(bvh.explainSpatialIndexing(99).mode).toBe('absent');
+    bvh.insertSpatialObject(99, box(0, 0, 0, 1));
+    expect(bvh.explainSpatialIndexing(99).mode).toBe('cells');
+    bvh.clearSpatialIndex();
+    expect(bvh.explainSpatialIndexing(99).mode).toBe('absent');
+  });
+
+  it('stays balanced under sorted insertion, which is the case that degenerates a naive tree', () => {
+    // A run of monotonically increasing boxes is the worst input for an unbalanced tree: it builds a
+    // linked list and every query goes linear. Measured indirectly through the query still being exact
+    // over a large sorted set, which a broken rotation would break outright rather than merely slow.
+    const bvh = createBvhSpatialBackend3D(0);
+    const grid = createUniformGridSpatialBackend3D(8);
+    for (let id = 0; id < 400; id += 1) {
+      const bounds = box(id * 3, 0, 0, 2);
+      bvh.insertSpatialObject(id, bounds);
+      grid.insertSpatialObject(id, bounds);
+    }
+    const bvhOut: SpatialObjectId[] = [];
+    const gridOut: SpatialObjectId[] = [];
+    bvh.querySpatialRegion(box(300, -5, -5, 60), bvhOut);
+    grid.querySpatialRegion(box(300, -5, -5, 60), gridOut);
+    expect(sorted(bvhOut)).toEqual(sorted(gridOut));
+    expect(bvhOut.length).toBeGreaterThan(5);
+  });
+
+  it('is interchangeable with the grid behind createSpatialIndex3D', () => {
+    // The seam's whole promise. Both are SpatialIndexBackend3D and neither is named in the call.
+    const backends: SpatialIndexBackend3D[] = [createBvhSpatialBackend3D(), createUniformGridSpatialBackend3D(16)];
+    const results = backends.map((backend) => {
+      backend.insertSpatialObject(1, box(0, 0, 0, 5));
+      backend.insertSpatialObject(2, box(100, 0, 0, 5));
+      const out: SpatialObjectId[] = [];
+      backend.querySpatialRegion(box(-1, -1, -1, 10), out);
+      return sorted(out);
+    });
+    expect(results[0]).toEqual(results[1]);
+  });
+
+  // The queries were compared against the grid from the start; the NOTICES were not, which is how a
+  // backend that reported every ordinary success shipped. Same differential method, applied to the
+  // other half of the seam.
+  it('reports the same indexing notices as the grid, for the same operations', () => {
+    const script = (backend: SpatialIndexBackend3D): void => {
+      backend.insertSpatialObject(1, box(0, 0, 0, 1));
+      backend.updateSpatialObject(1, box(0.1, 0, 0, 1));
+      backend.updateSpatialObject(1, box(50, 0, 0, 1));
+      backend.removeSpatialObject(1);
+      backend.removeSpatialObject(404);
+      backend.updateSpatialObject(505, box(0, 0, 0, 1));
+      backend.insertSpatialObject(2, box(NaN, 0, 0, 1));
+      const inverted: SpatialAabb3D = { minX: 5, minY: 0, minZ: 0, maxX: 1, maxY: 1, maxZ: 1 };
+      backend.insertSpatialObject(3, inverted);
+    };
+    // Mode and bucket count are structural — a tree has no cells to count — so this compares the part
+    // the seam does promise: which operation on which id was worth telling the caller about, and why.
+    const record = (backend: SpatialIndexBackend3D): string[] => {
+      const seen: string[] = [];
+      setSpatialIndexingGuard((notice) => seen.push(`${notice.operation}:${notice.id}:${notice.reason ?? 'null'}`));
+      script(backend);
+      setSpatialIndexingGuard(null);
+      return seen;
+    };
+    const bvh = record(createBvhSpatialBackend3D());
+    expect(bvh).toEqual(record(createUniformGridSpatialBackend3D(16)));
+    // Pinned literally too, so a change that made BOTH backends noisy could not pass by agreeing.
+    expect(bvh).toEqual([
+      'remove:404:missing-id',
+      'update:505:missing-id',
+      'insert:2:non-finite-bounds',
+      'insert:3:inverted-bounds',
+    ]);
+  });
+
+  it('says nothing at all while healthy objects are indexed and moved', () => {
+    // The cost of getting this wrong is not a wrong answer, it is a guard that fires once per object
+    // per step and buries the one notice that matters in thousands that do not.
+    const notices: string[] = [];
+    setSpatialIndexingGuard((notice) => notices.push(notice.operation));
+    const bvh = createBvhSpatialBackend3D();
+    for (let id = 0; id < 20; id += 1) bvh.insertSpatialObject(id, box(id * 4, 0, 0, 1));
+    for (let step = 0; step < 100; step += 1) {
+      for (let id = 0; id < 20; id += 1) bvh.updateSpatialObject(id, box(id * 4 + step * 0.5, 0, 0, 1));
+    }
+    setSpatialIndexingGuard(null);
+    expect(notices).toEqual([]);
+  });
+});

package/src/explainSpatialIndexing2D.test.ts

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

package/src/explainSpatialIndexing3D.test.ts

@@ -0,0 +1,59 @@
+import type { SpatialAabb3D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { explainSpatialIndexing3D } from './explainSpatialIndexing3D';
+import { createSpatialIndex3D, insertSpatialObject3D, removeSpatialObject3D } from './spatialIndex3D';
+import { MAX_INDEXED_CELLS_PER_OBJECT } from './uniformGrid';
+import { createUniformGridSpatialBackend3D } from './uniformGrid3D';
+
+function box(minX: number, minY: number, minZ: number, size: number): SpatialAabb3D {
+  return { minX, minY, minZ, maxX: minX + size, maxY: minY + size, maxZ: minZ + size };
+}
+
+describe('explainSpatialIndexing3D', () => {
+  it('reports absent for an id that was never inserted', () => {
+    const index = createSpatialIndex3D();
+    expect(explainSpatialIndexing3D(index, 42)).toEqual({
+      bucketCount: 0,
+      id: 42,
+      mode: 'absent',
+      reason: null,
+    });
+  });
+
+  it('reports absent after removal', () => {
+    const index = createSpatialIndex3D();
+    insertSpatialObject3D(index, 1, box(0, 0, 0, 10));
+    removeSpatialObject3D(index, 1);
+    expect(explainSpatialIndexing3D(index, 1).mode).toBe('absent');
+  });
+
+  it('reports declined with the reason the bounds were refused', () => {
+    const index = createSpatialIndex3D();
+    insertSpatialObject3D(index, 1, { minX: 0, minY: 0, minZ: NaN, maxX: 1, maxY: 1, maxZ: 1 });
+    insertSpatialObject3D(index, 2, { minX: 0, minY: 0, minZ: 9, maxX: 1, maxY: 1, maxZ: 0 });
+    expect(explainSpatialIndexing3D(index, 1).reason).toBe('non-finite-bounds');
+    expect(explainSpatialIndexing3D(index, 2).reason).toBe('inverted-bounds');
+  });
+
+  it('reports the cell count an ordinary object occupies', () => {
+    const index = createSpatialIndex3D(createUniformGridSpatialBackend3D(1));
+    insertSpatialObject3D(index, 1, box(0, 0, 0, 1.5));
+    // 0..1.5 spans cells 0 and 1 on each axis: a 2x2x2 block.
+    expect(explainSpatialIndexing3D(index, 1)).toEqual({
+      bucketCount: 8,
+      id: 1,
+      mode: 'cells',
+      reason: null,
+    });
+  });
+
+  it('pins the cost bound: an oversized object overflows rather than occupying unbounded buckets', () => {
+    const index = createSpatialIndex3D(createUniformGridSpatialBackend3D(1));
+    insertSpatialObject3D(index, 1, box(0, 0, 0, 5000));
+    const explanation = explainSpatialIndexing3D(index, 1);
+    expect(explanation.mode).toBe('overflow');
+    expect(explanation.bucketCount).toBe(0);
+    expect(explanation.bucketCount).toBeLessThanOrEqual(MAX_INDEXED_CELLS_PER_OBJECT);
+  });
+});

package/src/formatSpatialIndexingNotice.test.ts

@@ -2,7 +2,8 @@ import type { SpatialIndexingNotice } from '@flighthq/types/contract';
 import { afterEach, describe, expect, it } from 'vitest';
 
 import { formatSpatialIndexingNotice } from './formatSpatialIndexingNotice';
-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);
@@ -50,7 +51,7 @@ describe('formatSpatialIndexingNotice', () => {
         reason: 'invalid-cell-size',
         wouldOccupyBucketCount: 0,
       }),
-    ).toContain('cellSize must be a positive finite number');
+    ).toContain("the uniform grid's cellSize (0) must be a positive finite number");
     expect(
       formatSpatialIndexingNotice({
         cellSize: 10,
@@ -60,7 +61,7 @@ describe('formatSpatialIndexingNotice', () => {
         reason: 'inverted-bounds',
         wouldOccupyBucketCount: 0,
       }),
-    ).toContain('minX/minY must not exceed maxX/maxY');
+    ).toContain('no minimum may exceed its matching maximum');
     expect(
       formatSpatialIndexingNotice({
         cellSize: 10,
@@ -73,6 +74,31 @@ describe('formatSpatialIndexingNotice', () => {
     ).toContain('removal was a no-op');
   });
 
+  it('names no dimension, because a notice carries none to name', () => {
+    // One guard serves both dimensions, so nothing in a notice says which one produced it. A sentence
+    // naming `removeSpatialObject2D` was therefore misdescribing every 3D notice, and the unsuffixed
+    // backend method is the name that is true for both — and the one a caller greps.
+    const modes = ['cells', 'overflow', 'declined', 'absent'] as const;
+    const operations = ['insert', 'update', 'remove'] as const;
+    const reasons = [null, 'invalid-cell-size', 'inverted-bounds', 'missing-id', 'non-finite-bounds'] as const;
+    for (const mode of modes) {
+      for (const operation of operations) {
+        for (const reason of reasons) {
+          const message = formatSpatialIndexingNotice({
+            cellSize: 1,
+            id: 7,
+            mode,
+            operation,
+            reason,
+            wouldOccupyBucketCount: 2,
+          });
+          expect(message).not.toContain('2D');
+          expect(message).not.toContain('3D');
+        }
+      }
+    }
+  });
+
   it('says plainly that a mode it does not cover carries no advice', () => {
     expect(
       formatSpatialIndexingNotice({
@@ -90,7 +116,7 @@ describe('formatSpatialIndexingNotice', () => {
     // Pins the two halves together: a record produced by a real insert, rendered by this formatter.
     const notices: SpatialIndexingNotice[] = [];
     setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
-    const grid = createUniformGridSpatialBackend(1);
+    const grid = createUniformGridSpatialBackend2D(1);
     grid.insertSpatialObject(9, { minX: 0, minY: 0, maxX: 199, maxY: 199 });
     grid.insertSpatialObject(10, { minX: NaN, minY: 0, maxX: 1, maxY: 1 });
     expect(notices.map(formatSpatialIndexingNotice)).toEqual([