@flighthq/spatial 0.3.0-next.906.07cea63 → 0.3.0

package/dist/contract.d.ts

@@ -1,3 +1,5 @@
+export * from './explainSpatialIndexing';
+export * from './formatSpatialIndexingNotice';
 export * from './spatialIndex';
 export * from './uniformGrid';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/contract.js

@@ -1,3 +1,5 @@
+export * from './explainSpatialIndexing';
+export * from './formatSpatialIndexingNotice';
 export * from './spatialIndex';
 export * from './uniformGrid';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/explainSpatialIndexing.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,14 @@
+// Reports how the index is currently holding `id`, as plain data. Pure: reads only, indexes nothing,
+// never throws on an unknown id, and retains no reference to the backend. Import it to answer "why is
+// this object not in my query results?" — `absent` means it was never inserted or was removed,
+// `declined` means its bounds were non-finite or inverted and it is deliberately not held, `overflow`
+// means it is held but cannot be usefully bucketed, and `cells` reports the bucket count the
+// per-object bound caps.
+//
+// This is the pull half of the diagnostics convention, and the measurement seam a regression test
+// asserts the cost bound against: `bucketCount` is the number that goes unbounded when the bound is
+// removed, so a test can pin it without timing anything.
+export function explainSpatialIndexing(index, id) {
+    return index.runtime.backend.explainSpatialIndexing(id);
+}
+//# sourceMappingURL=explainSpatialIndexing.js.map

package/dist/explainSpatialIndexing.js.map

@@ -0,0 +1 @@
+{"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/dist/formatSpatialIndexingNotice.d.ts

@@ -0,0 +1,3 @@
+import type { SpatialIndexingNotice } from '@flighthq/types/contract';
+export declare function formatSpatialIndexingNotice(notice: Readonly<SpatialIndexingNotice>): string;
+//# sourceMappingURL=formatSpatialIndexingNotice.d.ts.map

package/dist/formatSpatialIndexingNotice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatSpatialIndexingNotice.d.ts","sourceRoot":"","sources":["../src/formatSpatialIndexingNotice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AActE,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,MAAM,CAsB3F"}

package/dist/formatSpatialIndexingNotice.js

@@ -0,0 +1,35 @@
+import { MAX_INDEXED_CELLS_PER_OBJECT } from './uniformGrid';
+// Renders an indexing notice as a caller-facing sentence, and is the only place in this package that
+// holds one. Import it to turn the structured record a SpatialIndexingGuard receives into something a
+// developer reads; leave it unimported and neither the text nor its cost reaches a bundle.
+//
+// The text lives here rather than inside an `enableSpatialGuards` that logs for you because
+// `@flighthq/spatial` is a core-layer package and may not depend on `@flighthq/log` — the same shape
+// `@flighthq/importdiagnostics` uses, where core carries the record and a separate module carries the
+// words. Wiring the two together is three lines at the application layer, which can reach both:
+//
+//   setSpatialIndexingGuard((notice) => logWarn({ message: formatSpatialIndexingNotice(notice) }, 'spatial'));
+export function formatSpatialIndexingNotice(notice) {
+    if (notice.reason === 'invalid-cell-size') {
+        return `createUniformGridSpatialBackend(${notice.cellSize}): cellSize must be a positive finite number. ${notice.operation}SpatialObject(${notice.id}) used the bounded overflow path instead, so results remain correct but queries scan this object.`;
+    }
+    if (notice.reason === 'inverted-bounds') {
+        return `${notice.operation}SpatialObject(${notice.id}): minX/minY must not exceed maxX/maxY, so the object was not indexed and no query will return it. The operation returns false for this — normalize or correct the bounds upstream.`;
+    }
+    if (notice.reason === 'missing-id') {
+        if (notice.operation === 'remove') {
+            return `removeSpatialObject(${notice.id}): the id was not indexed, so removal was a no-op. Check the object's indexing lifecycle if this was unexpected.`;
+        }
+        return `updateSpatialObject(${notice.id}): the id was not indexed, so update used its documented insert behavior and left the object in '${notice.mode}' mode. Use insertSpatialObject for a new id, or check the object's indexing lifecycle.`;
+    }
+    if (notice.mode === 'declined') {
+        return `${notice.operation}SpatialObject(${notice.id}): the bounds are not finite, so the object was not indexed and no query will return it. The operation returns false for this — check the sentinel, and check what produced NaN/Infinity bounds upstream.`;
+    }
+    if (notice.mode === 'overflow') {
+        return `${notice.operation}SpatialObject(${notice.id}): the bounds span ${notice.wouldOccupyBucketCount} cells, over the ${MAX_INDEXED_CELLS_PER_OBJECT} per-object budget, so the object is held in the flat overflow list instead of the grid. Results are unaffected. If this is not a one-off outlier, the grid's cellSize is too small for the objects being indexed — size it to a typical object.`;
+    }
+    // `cells` and `absent` are ordinary outcomes no guard reports, so reaching here means a backend
+    // notified about something this text does not cover. Say exactly that rather than inventing advice.
+    return `${notice.operation}SpatialObject(${notice.id}): indexed as '${notice.mode}', which carries no caller-facing advice.`;
+}
+//# sourceMappingURL=formatSpatialIndexingNotice.js.map

package/dist/formatSpatialIndexingNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatSpatialIndexingNotice.js","sourceRoot":"","sources":["../src/formatSpatialIndexingNotice.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAE7D,qGAAqG;AACrG,sGAAsG;AACtG,2FAA2F;AAC3F,EAAE;AACF,4FAA4F;AAC5F,qGAAqG;AACrG,sGAAsG;AACtG,gGAAgG;AAChG,EAAE;AACF,+GAA+G;AAC/G,MAAM,UAAU,2BAA2B,CAAC,MAAuC;IACjF,IAAI,MAAM,CAAC,MAAM,KAAK,mBAAmB,EAAE,CAAC;QAC1C,OAAO,mCAAmC,MAAM,CAAC,QAAQ,iDAAiD,MAAM,CAAC,SAAS,iBAAiB,MAAM,CAAC,EAAE,mGAAmG,CAAC;IAC1P,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;QACxC,OAAO,GAAG,MAAM,CAAC,SAAS,iBAAiB,MAAM,CAAC,EAAE,qLAAqL,CAAC;IAC5O,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;QACnC,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YAClC,OAAO,uBAAuB,MAAM,CAAC,EAAE,kHAAkH,CAAC;QAC5J,CAAC;QACD,OAAO,uBAAuB,MAAM,CAAC,EAAE,oGAAoG,MAAM,CAAC,IAAI,yFAAyF,CAAC;IAClP,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,GAAG,MAAM,CAAC,SAAS,iBAAiB,MAAM,CAAC,EAAE,2MAA2M,CAAC;IAClQ,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,GAAG,MAAM,CAAC,SAAS,iBAAiB,MAAM,CAAC,EAAE,sBAAsB,MAAM,CAAC,sBAAsB,oBAAoB,4BAA4B,kPAAkP,CAAC;IAC5Y,CAAC;IACD,gGAAgG;IAChG,oGAAoG;IACpG,OAAO,GAAG,MAAM,CAAC,SAAS,iBAAiB,MAAM,CAAC,EAAE,kBAAkB,MAAM,CAAC,IAAI,2CAA2C,CAAC;AAC/H,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { clearSpatialIndex, createSpatialIndex, createUniformGridSpatialBackend, insertSpatialObject, querySpatialPairs, querySpatialPoint, querySpatialRay, querySpatialRegion, removeSpatialObject, updateSpatialObject, } from './contract';
+export { MAX_INDEXED_CELLS_PER_OBJECT, clearSpatialIndex, createSpatialIndex, createUniformGridSpatialBackend, explainSpatialIndexing, formatSpatialIndexingNotice, insertSpatialObject, querySpatialPairs, querySpatialPoint, querySpatialRay, querySpatialRegion, removeSpatialObject, setSpatialIndexingGuard, updateSpatialObject, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,+BAA+B,EAC/B,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,EACjB,kBAAkB,EAClB,+BAA+B,EAC/B,sBAAsB,EACtB,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { clearSpatialIndex, createSpatialIndex, createUniformGridSpatialBackend, insertSpatialObject, querySpatialPairs, querySpatialPoint, querySpatialRay, querySpatialRegion, removeSpatialObject, updateSpatialObject, } from './contract';
+export { MAX_INDEXED_CELLS_PER_OBJECT, clearSpatialIndex, createSpatialIndex, createUniformGridSpatialBackend, explainSpatialIndexing, formatSpatialIndexingNotice, insertSpatialObject, querySpatialPairs, querySpatialPoint, querySpatialRay, querySpatialRegion, removeSpatialObject, setSpatialIndexingGuard, updateSpatialObject, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,+BAA+B,EAC/B,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,EACjB,kBAAkB,EAClB,+BAA+B,EAC/B,sBAAsB,EACtB,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/spatialIndex.d.ts

@@ -1,11 +1,11 @@
 import type { SpatialAabb, SpatialIndex, SpatialIndexBackend, SpatialObjectId, SpatialPair } from '@flighthq/types/contract';
 export declare function clearSpatialIndex(index: Readonly<SpatialIndex>): void;
 export declare function createSpatialIndex(backend?: SpatialIndexBackend): SpatialIndex;
-export declare function insertSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId, bounds: Readonly<SpatialAabb>): void;
+export declare function insertSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId, bounds: Readonly<SpatialAabb>): boolean;
 export declare function querySpatialPairs(index: Readonly<SpatialIndex>, out: SpatialPair[]): void;
 export declare function querySpatialPoint(index: Readonly<SpatialIndex>, x: number, y: number, out: SpatialObjectId[]): void;
 export declare function querySpatialRay(index: Readonly<SpatialIndex>, x: number, y: number, dx: number, dy: number, out: SpatialObjectId[]): void;
 export declare function querySpatialRegion(index: Readonly<SpatialIndex>, region: Readonly<SpatialAabb>, out: SpatialObjectId[]): void;
 export declare function removeSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId): void;
-export declare function updateSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId, bounds: Readonly<SpatialAabb>): void;
+export declare function updateSpatialObject(index: Readonly<SpatialIndex>, id: SpatialObjectId, bounds: Readonly<SpatialAabb>): boolean;
 //# sourceMappingURL=spatialIndex.d.ts.map

package/dist/spatialIndex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spatialIndex.d.ts","sourceRoot":"","sources":["../src/spatialIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAKlC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI,CAErE;AAMD,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAM9E;AAID,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC5B,IAAI,CAEN;AAKD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,IAAI,CAEzF;AAGD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,GAAG,IAAI,CAEnH;AAID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,eAAe,EAAE,GACrB,IAAI,CAEN;AAGD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,GAAG,EAAE,eAAe,EAAE,GACrB,IAAI,CAEN;AAGD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,eAAe,GAAG,IAAI,CAE5F;AAGD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC5B,IAAI,CAEN"}
+{"version":3,"file":"spatialIndex.d.ts","sourceRoot":"","sources":["../src/spatialIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAKlC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI,CAErE;AAMD,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAM9E;AAOD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC5B,OAAO,CAET;AAKD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,IAAI,CAEzF;AAGD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,GAAG,IAAI,CAEnH;AAID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,eAAe,EAAE,GACrB,IAAI,CAEN;AAGD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,GAAG,EAAE,eAAe,EAAE,GACrB,IAAI,CAEN;AAGD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,eAAe,GAAG,IAAI,CAE5F;AAMD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC7B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC5B,OAAO,CAET"}

package/dist/spatialIndex.js

@@ -15,9 +15,12 @@ export function createSpatialIndex(backend) {
     };
 }
 // Adds an object to the index under `id` with its current bounds. The bounds are copied; the caller
-// may reuse its own value afterward.
+// may reuse its own value afterward. Returns false when the bounds cannot be indexed at all
+// (non-finite or inverted) — the object is then absent from every query rather than present at a
+// nonsense position. Oversized-but-valid bounds return true and stay fully queryable; the backend
+// decides how to hold them. explainSpatialIndexing reports which happened.
 export function insertSpatialObject(index, id, bounds) {
-    index.runtime.backend.insertSpatialObject(id, bounds);
+    return index.runtime.backend.insertSpatialObject(id, bounds);
 }
 // Fills `out` (cleared first) with every deduplicated candidate pair — each unordered pair at most
 // once, never an object with itself. A pair is a broadphase candidate: the two objects are close
@@ -43,8 +46,11 @@ export function removeSpatialObject(index, id) {
     index.runtime.backend.removeSpatialObject(id);
 }
 // Moves an already-inserted object to new bounds. Inserting a not-yet-present id behaves as insert.
+// Returns the same sentinel as insertSpatialObject. A declined update removes the object rather than
+// leaving it at its old bounds, so a caller that ignores the sentinel can never read a stale position
+// as a current one.
 export function updateSpatialObject(index, id, bounds) {
-    index.runtime.backend.updateSpatialObject(id, bounds);
+    return index.runtime.backend.updateSpatialObject(id, bounds);
 }
 // The default uniform-grid cell size when createSpatialIndex is called without an explicit backend —
 // a middle-of-the-road choice; a workload with a known typical object size should pass its own grid.

package/dist/spatialIndex.js.map

@@ -1 +1 @@
-{"version":3,"file":"spatialIndex.js","sourceRoot":"","sources":["../src/spatialIndex.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAEhE,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;AAC5C,CAAC;AAED,yFAAyF;AACzF,kGAAkG;AAClG,mGAAmG;AACnG,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAAC,OAA6B;IAC9D,OAAO;QACL,OAAO,EAAE;YACP,OAAO,EAAE,OAAO,IAAI,+BAA+B,CAAC,yBAAyB,CAAC;SAC/E;KACF,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,qCAAqC;AACrC,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,EAAmB,EACnB,MAA6B;IAE7B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,mGAAmG;AACnG,iGAAiG;AACjG,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,KAA6B,EAAE,GAAkB;IACjF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,KAA6B,EAAE,CAAS,EAAE,CAAS,EAAE,GAAsB;IAC3G,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,iGAAiG;AACjG,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAC7B,KAA6B,EAC7B,CAAS,EACT,CAAS,EACT,EAAU,EACV,EAAU,EACV,GAAsB;IAEtB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAChC,KAA6B,EAC7B,MAA6B,EAC7B,GAAsB;IAEtB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACxD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,mBAAmB,CAAC,KAA6B,EAAE,EAAmB;IACpF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,EAAmB,EACnB,MAA6B;IAE7B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,qGAAqG;AACrG,qGAAqG;AACrG,MAAM,yBAAyB,GAAG,GAAG,CAAC"}
+{"version":3,"file":"spatialIndex.js","sourceRoot":"","sources":["../src/spatialIndex.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAEhE,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;AAC5C,CAAC;AAED,yFAAyF;AACzF,kGAAkG;AAClG,mGAAmG;AACnG,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAAC,OAA6B;IAC9D,OAAO;QACL,OAAO,EAAE;YACP,OAAO,EAAE,OAAO,IAAI,+BAA+B,CAAC,yBAAyB,CAAC;SAC/E;KACF,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,4FAA4F;AAC5F,iGAAiG;AACjG,kGAAkG;AAClG,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,EAAmB,EACnB,MAA6B;IAE7B,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC;AAED,mGAAmG;AACnG,iGAAiG;AACjG,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,KAA6B,EAAE,GAAkB;IACjF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,KAA6B,EAAE,CAAS,EAAE,CAAS,EAAE,GAAsB;IAC3G,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,iGAAiG;AACjG,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAC7B,KAA6B,EAC7B,CAAS,EACT,CAAS,EACT,EAAU,EACV,EAAU,EACV,GAAsB;IAEtB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAChC,KAA6B,EAC7B,MAA6B,EAC7B,GAAsB;IAEtB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACxD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,mBAAmB,CAAC,KAA6B,EAAE,EAAmB;IACpF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,oGAAoG;AACpG,qGAAqG;AACrG,sGAAsG;AACtG,oBAAoB;AACpB,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,EAAmB,EACnB,MAA6B;IAE7B,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC;AAED,qGAAqG;AACrG,qGAAqG;AACrG,MAAM,yBAAyB,GAAG,GAAG,CAAC"}

package/dist/uniformGrid.d.ts

@@ -1,3 +1,5 @@
-import type { SpatialIndexBackend } from '@flighthq/types/contract';
+import type { SpatialIndexBackend, SpatialIndexingGuard } from '@flighthq/types/contract';
+export declare const MAX_INDEXED_CELLS_PER_OBJECT = 1024;
 export declare function createUniformGridSpatialBackend(cellSize: number): SpatialIndexBackend;
+export declare function setSpatialIndexingGuard(guard: SpatialIndexingGuard | null): void;
 //# sourceMappingURL=uniformGrid.d.ts.map

package/dist/uniformGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uniformGrid.d.ts","sourceRoot":"","sources":["../src/uniformGrid.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,mBAAmB,EAGpB,MAAM,0BAA0B,CAAC;AASlC,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA0CrF"}
+{"version":3,"file":"uniformGrid.d.ts","sourceRoot":"","sources":["../src/uniformGrid.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,mBAAmB,EAGnB,oBAAoB,EAMrB,MAAM,0BAA0B,CAAC;AAiBlC,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAejD,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAkDrF;AAKD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAEhF"}

package/dist/uniformGrid.js

@@ -1,39 +1,70 @@
 import { containsRectanglePointXY, intersectsRectangle } from '@flighthq/geometry/contract';
+// The per-object cell budget. An object whose AABB covers more cells than this is held in the flat
+// overflow list instead of being written into every cell it spans.
+//
+// This bound is what makes insert cost independent of object size. Without it the cell walk is
+// proportional to extent ÷ cellSize *squared*, so cost is set by the largest object rather than by
+// the object count: measured on this grid at one cell per unit, a 200-unit box costs 40k cell writes
+// (~28 ms) and a 2000-unit box costs 4M (~4.7 s), while an AABB a trillion units wide — reachable
+// from any diverging simulation — never returns at all. A hang is worse than a throw because it is
+// uncatchable and takes the caller with it.
+//
+// Overflow is not a degraded result: an object that spans a thousand cells is a co-occupant of nearly
+// everything, so the cell index tells the queries almost nothing and a linear scan answers the same
+// question at a bounded cost. 1024 cells is a 32×32 block — an object 32× the cell size on each axis,
+// far past the "cell size ≈ typical object size" the grid is built around. An object over the budget
+// is a signal the cell size is wrong for the workload, which the indexing guard reports.
+export const MAX_INDEXED_CELLS_PER_OBJECT = 1024;
 // Builds a uniform-grid (spatial-hash) backend: an object's AABB is mapped to the rectangular block
 // of fixed-size cells it covers, and each cell holds the ids overlapping it. Co-located objects share
 // a cell, so candidate pairs and region/point/ray hits are found by looking only at the relevant
 // cells instead of scanning every object. `cellSize` is the world-space side length of one cell; a
-// good value is roughly the size of a typical object (too small over-spans large objects across many
-// cells, too large lumps unrelated objects together). No import-time side effect — the caller
-// constructs a grid explicitly, and createSpatialIndex uses this as its default index.
+// good value is a positive finite number roughly the size of a typical object (too small over-spans
+// large objects across many cells, too large lumps unrelated objects together). An invalid size uses
+// the bounded overflow path to keep results correct and reports through the indexing guard. No
+// import-time side effect — the caller constructs a grid explicitly, and createSpatialIndex uses
+// this as its default index.
+//
+// Object size does not set the cost: an AABB spanning more than MAX_INDEXED_CELLS_PER_OBJECT cells
+// goes to a flat overflow list that every query scans, and non-finite or inverted bounds are declined
+// outright with a false sentinel. Both are visible through explainSpatialIndexing.
 export function createUniformGridSpatialBackend(cellSize) {
     const grid = {
         cellSize,
         cells: new Map(),
         bounds: new Map(),
+        overflow: new Set(),
+        declined: new Map(),
         minCellX: 0,
         minCellY: 0,
         maxCellX: 0,
         maxCellY: 0,
-        empty: true,
         seen: new Set(),
+        pairIds: [],
     };
     return {
         insertSpatialObject(id, bounds) {
-            _insertIntoGrid(grid, id, bounds);
+            return _insertIntoGrid(grid, id, bounds, 'insert');
         },
         updateSpatialObject(id, bounds) {
-            _removeFromGrid(grid, id);
-            _insertIntoGrid(grid, id, bounds);
+            return _updateGridObject(grid, id, bounds);
         },
         removeSpatialObject(id) {
+            const wasMissing = !grid.bounds.has(id) && !grid.declined.has(id);
             _removeFromGrid(grid, id);
+            if (wasMissing)
+                _reportGridIndexing(grid, id, 'absent', 'remove', 'missing-id', 0);
         },
         clearSpatialIndex() {
             grid.cells.clear();
             grid.bounds.clear();
+            grid.overflow.clear();
+            grid.declined.clear();
             grid.seen.clear();
-            grid.empty = true;
+            grid.pairIds.length = 0;
+        },
+        explainSpatialIndexing(id) {
+            return _explainGridIndexing(grid, id);
         },
         querySpatialPairs(out) {
             _queryGridPairs(grid, out);
@@ -49,6 +80,12 @@ export function createUniformGridSpatialBackend(cellSize) {
         },
     };
 }
+// Installs the indexing guard consulted for invalid configuration or bounds, missing-id operations,
+// and overflow routing; null uninstalls it. Module-scoped rather than per-grid: it is a development
+// diagnostic, and an application debugging an index wants it on for every grid at once.
+export function setSpatialIndexingGuard(guard) {
+    _indexingGuard = guard;
+}
 // Maps a world coordinate to its cell index along one axis. Uses floor so negative coordinates map
 // to consistently decreasing cell indices (world 0 is the boundary between cell -1 and cell 0).
 function _cellIndex(coord, cellSize) {
@@ -61,23 +98,79 @@ function _cellKey(cx, cy) {
 }
 // Fills a scratch RectangleLike (x/y/width/height) from a SpatialAabb (min/max corners) so the
 // geometry rectangle-overlap and point-containment helpers can be reused instead of re-deriving the
-// AABB math here. Assumes a normalized AABB (max >= min); a flipped AABB yields a negative extent,
-// which the geometry helpers still normalize internally.
+// AABB math here. Stored AABBs are normalized because insert declines inverted bounds.
 function _fillRectFromAabb(out, aabb) {
     out.x = aabb.minX;
     out.y = aabb.minY;
     out.width = aabb.maxX - aabb.minX;
     out.height = aabb.maxY - aabb.minY;
 }
-// Adds an object to every cell its AABB covers, storing a private copy of the bounds and expanding
-// the occupied cell range. The caller may safely mutate or reuse the passed bounds afterward.
-function _insertIntoGrid(grid, id, bounds) {
+// Reports how `id` is currently held. Pure: reads only, allocates only the returned record.
+function _explainGridIndexing(grid, id) {
+    const declineReason = grid.declined.get(id);
+    if (declineReason !== undefined)
+        return { bucketCount: 0, id, mode: 'declined', reason: declineReason };
+    if (grid.overflow.has(id))
+        return { bucketCount: 0, id, mode: 'overflow', reason: null };
+    const bounds = grid.bounds.get(id);
+    if (bounds === undefined)
+        return { bucketCount: 0, id, mode: 'absent', reason: null };
+    return { bucketCount: _spannedCellCount(grid.cellSize, bounds), id, mode: 'cells', reason: null };
+}
+// Adds an object to the index, storing a private copy of the bounds; the caller may safely mutate or
+// reuse the passed bounds afterward. Returns false only for bounds that cannot be indexed at all.
+//
+// Five outcomes, and which one applies is decided *before* any cell is touched — that ordering is
+// the whole point, since deciding afterward would mean walking the cells to find out they were too
+// many:
+//   - non-finite bounds are declined. There is no cell range to compute, and storing them would let a
+//     NaN leak into every later overlap test, so the object is left out of the index entirely and the
+//     caller gets a false sentinel rather than an exception or a silent no-op.
+//   - inverted bounds are likewise declined because min/max corners do not describe an AABB.
+//   - a non-positive or non-finite cell size routes valid objects to overflow, preserving query
+//     correctness through the bounded flat scan while the indexing guard reports the configuration.
+//   - bounds spanning more than MAX_INDEXED_CELLS_PER_OBJECT cells go to the overflow list, which
+//     every query scans. Bounded by the object count instead of the object's size.
+//   - everything else takes the ordinary path: one entry in each cell it covers.
+function _insertIntoGrid(grid, id, bounds, operation) {
+    if (!Number.isFinite(bounds.minX) ||
+        !Number.isFinite(bounds.minY) ||
+        !Number.isFinite(bounds.maxX) ||
+        !Number.isFinite(bounds.maxY)) {
+        grid.declined.set(id, 'non-finite-bounds');
+        _reportGridIndexing(grid, id, 'declined', operation, 'non-finite-bounds', 0);
+        return false;
+    }
+    if (bounds.maxX < bounds.minX || bounds.maxY < bounds.minY) {
+        grid.declined.set(id, 'inverted-bounds');
+        _reportGridIndexing(grid, id, 'declined', operation, 'inverted-bounds', 0);
+        return false;
+    }
     const cs = grid.cellSize;
-    const cx0 = _cellIndex(bounds.minX, cs);
-    const cx1 = _cellIndex(bounds.maxX, cs);
-    const cy0 = _cellIndex(bounds.minY, cs);
-    const cy1 = _cellIndex(bounds.maxY, cs);
-    grid.bounds.set(id, { minX: bounds.minX, minY: bounds.minY, maxX: bounds.maxX, maxY: bounds.maxY });
+    const copy = { minX: bounds.minX, minY: bounds.minY, maxX: bounds.maxX, maxY: bounds.maxY };
+    if (!(cs > 0 && Number.isFinite(cs))) {
+        grid.bounds.set(id, copy);
+        grid.overflow.add(id);
+        _reportGridIndexing(grid, id, 'overflow', operation, 'invalid-cell-size', 0);
+        return true;
+    }
+    const spanned = _spannedCellCount(cs, copy);
+    // Written as a negated `<=` so an unrepresentable span falls to overflow rather than through to a
+    // loop that cannot index it.
+    if (!(spanned <= MAX_INDEXED_CELLS_PER_OBJECT)) {
+        grid.bounds.set(id, copy);
+        grid.overflow.add(id);
+        _reportGridIndexing(grid, id, 'overflow', operation, null, spanned);
+        return true;
+    }
+    const cx0 = _cellIndex(copy.minX, cs);
+    const cx1 = _cellIndex(copy.maxX, cs);
+    const cy0 = _cellIndex(copy.minY, cs);
+    const cy1 = _cellIndex(copy.maxY, cs);
+    // Whether a cell range exists yet, read *before* this object's cells are added. A first celled
+    // object seeds the range; a later one widens it.
+    const hadCells = grid.cells.size !== 0;
+    grid.bounds.set(id, copy);
     for (let cy = cy0; cy <= cy1; cy++) {
         for (let cx = cx0; cx <= cx1; cx++) {
             const key = _cellKey(cx, cy);
@@ -89,12 +182,11 @@ function _insertIntoGrid(grid, id, bounds) {
             cell.ids.add(id);
         }
     }
-    if (grid.empty) {
+    if (!hadCells) {
         grid.minCellX = cx0;
         grid.maxCellX = cx1;
         grid.minCellY = cy0;
         grid.maxCellY = cy1;
-        grid.empty = false;
     }
     else {
         if (cx0 < grid.minCellX)
@@ -106,6 +198,44 @@ function _insertIntoGrid(grid, id, bounds) {
         if (cy1 > grid.maxCellY)
             grid.maxCellY = cy1;
     }
+    return true;
+}
+// Updates an object's private AABB copy without touching its cell sets when both the old and new
+// bounds take the ordinary indexing path and cover exactly the same cells. Small per-frame movement
+// usually stays inside this range, so its dominant cost becomes four field writes instead of a
+// remove-and-reinsert walk. Every mode or range transition keeps using the shared slow path below.
+function _updateGridObject(grid, id, bounds) {
+    const wasMissing = !grid.bounds.has(id) && !grid.declined.has(id);
+    const previous = grid.bounds.get(id);
+    if (previous !== undefined &&
+        !grid.overflow.has(id) &&
+        Number.isFinite(bounds.minX) &&
+        Number.isFinite(bounds.minY) &&
+        Number.isFinite(bounds.maxX) &&
+        Number.isFinite(bounds.maxY) &&
+        bounds.minX <= bounds.maxX &&
+        bounds.minY <= bounds.maxY) {
+        const cs = grid.cellSize;
+        const spanned = _spannedCellCount(cs, bounds);
+        if (spanned <= MAX_INDEXED_CELLS_PER_OBJECT &&
+            _cellIndex(previous.minX, cs) === _cellIndex(bounds.minX, cs) &&
+            _cellIndex(previous.minY, cs) === _cellIndex(bounds.minY, cs) &&
+            _cellIndex(previous.maxX, cs) === _cellIndex(bounds.maxX, cs) &&
+            _cellIndex(previous.maxY, cs) === _cellIndex(bounds.maxY, cs)) {
+            previous.minX = bounds.minX;
+            previous.minY = bounds.minY;
+            previous.maxX = bounds.maxX;
+            previous.maxY = bounds.maxY;
+            return true;
+        }
+    }
+    _removeFromGrid(grid, id);
+    const inserted = _insertIntoGrid(grid, id, bounds, 'update');
+    if (wasMissing) {
+        const explanation = _explainGridIndexing(grid, id);
+        _reportGridIndexing(grid, id, explanation.mode, 'update', 'missing-id', 0);
+    }
+    return inserted;
 }
 // Reports whether an AABB contains the point (`x`,`y`), reusing the geometry rectangle helper.
 function _isSpatialAabbContainsPoint(aabb, x, y) {
@@ -165,11 +295,18 @@ function _rayBoxEntryT(ox, oy, dx, dy, minX, minY, maxX, maxY) {
 }
 // Removes an object from every cell its stored AABB covered and drops now-empty cells. The occupied
 // cell range is intentionally not shrunk (only reset when the grid fully empties). A no-op for an
-// unknown id.
+// unknown id. Overflowed and declined ids leave through their own sets without a cell walk — remove
+// re-derives the cell range from the stored bounds, so an overflowed object taking the ordinary path
+// here would reintroduce exactly the unbounded walk the insert bound removed.
 function _removeFromGrid(grid, id) {
+    grid.declined.delete(id);
     const bounds = grid.bounds.get(id);
     if (bounds === undefined)
         return;
+    if (grid.overflow.delete(id)) {
+        grid.bounds.delete(id);
+        return;
+    }
     const cs = grid.cellSize;
     const cx0 = _cellIndex(bounds.minX, cs);
     const cx1 = _cellIndex(bounds.maxX, cs);
@@ -187,8 +324,30 @@ function _removeFromGrid(grid, id) {
         }
     }
     grid.bounds.delete(id);
-    if (grid.bounds.size === 0)
-        grid.empty = true;
+}
+// Appends the pairs involving overflowed objects. An overflowed object occupies no cell, so the cell
+// walk in _queryGridPairs can never emit a pair for it and no dedup against that walk is needed. Its
+// pairs are enumerated here instead: against every other indexed object, which is what "spans nearly
+// the whole world" already means. Unlike the cell path these are filtered by a real AABB overlap test
+// rather than emitted as bare locality candidates — the result stays a superset of the true overlaps
+// either way, and an object this large would otherwise nominate every other object every frame.
+function _queryGridOverflowPairs(grid, out) {
+    for (const id of grid.overflow) {
+        const bounds = grid.bounds.get(id);
+        if (bounds === undefined)
+            continue;
+        for (const [otherId, otherBounds] of grid.bounds) {
+            if (otherId === id)
+                continue;
+            // Each overflow×overflow pair would otherwise be emitted from both sides; taking it only from
+            // the lower id emits it once. An overflow×celled pair reaches this test from one side only.
+            if (grid.overflow.has(otherId) && otherId < id)
+                continue;
+            if (!_isSpatialAabbOverlapping(bounds, otherBounds))
+                continue;
+            out.push(id < otherId ? { a: id, b: otherId } : { a: otherId, b: id });
+        }
+    }
 }
 // Enumerates candidate pairs. Within each cell every co-occupant pair is a candidate, but a pair may
 // share several cells; to emit it exactly once, a pair is emitted only from its canonical cell — the
@@ -198,11 +357,14 @@ function _removeFromGrid(grid, id) {
 function _queryGridPairs(grid, out) {
     out.length = 0;
     const cs = grid.cellSize;
+    const list = grid.pairIds;
     for (const cell of grid.cells.values()) {
         const ids = cell.ids;
         if (ids.size < 2)
             continue;
-        const list = [...ids];
+        list.length = 0;
+        for (const id of ids)
+            list.push(id);
         for (let i = 0; i < list.length; i++) {
             for (let j = i + 1; j < list.length; j++) {
                 let a = list[i];
@@ -223,16 +385,30 @@ function _queryGridPairs(grid, out) {
             }
         }
     }
+    if (grid.overflow.size !== 0)
+        _queryGridOverflowPairs(grid, out);
+}
+function _reportGridIndexing(grid, id, mode, operation, reason, wouldOccupyBucketCount) {
+    if (_indexingGuard === null)
+        return;
+    _indexingGuard({ cellSize: grid.cellSize, id, mode, operation, reason, wouldOccupyBucketCount });
 }
 // Gathers the ids in the cell containing the point, then confirms each against its real bounds. A
-// single cell holds each id at most once, so no dedup pass is needed.
+// single cell holds each id at most once, so no dedup pass is needed. Overflowed objects hold no cell
+// and are tested directly; they cannot collide with the cell gather, so no dedup is needed there
+// either.
 function _queryGridPoint(grid, x, y, out) {
     out.length = 0;
     const cs = grid.cellSize;
     const cell = grid.cells.get(_cellKey(_cellIndex(x, cs), _cellIndex(y, cs)));
-    if (cell === undefined)
-        return;
-    for (const id of cell.ids) {
+    if (cell !== undefined) {
+        for (const id of cell.ids) {
+            const bounds = grid.bounds.get(id);
+            if (bounds !== undefined && _isSpatialAabbContainsPoint(bounds, x, y))
+                out.push(id);
+        }
+    }
+    for (const id of grid.overflow) {
         const bounds = grid.bounds.get(id);
         if (bounds !== undefined && _isSpatialAabbContainsPoint(bounds, x, y))
             out.push(id);
@@ -244,8 +420,6 @@ function _queryGridPoint(grid, x, y, out) {
 // point query at the origin. An empty grid returns nothing.
 function _queryGridRay(grid, ox, oy, dx, dy, out) {
     out.length = 0;
-    if (grid.empty)
-        return;
     const cs = grid.cellSize;
     const seen = grid.seen;
     seen.clear();
@@ -253,6 +427,23 @@ function _queryGridRay(grid, ox, oy, dx, dy, out) {
         _queryGridPoint(grid, ox, oy, out);
         return;
     }
+    // Overflowed objects are outside the cell range the DDA walks — deliberately, so one huge AABB
+    // cannot stretch that range and make every ray traverse it — so they are slab-tested directly.
+    for (const id of grid.overflow) {
+        const bounds = grid.bounds.get(id);
+        if (bounds !== undefined &&
+            _rayBoxEntryT(ox, oy, dx, dy, bounds.minX, bounds.minY, bounds.maxX, bounds.maxY) >= 0) {
+            out.push(id);
+        }
+    }
+    // The cell range describes the CELLS, so the cells decide whether it means anything. Reading a
+    // separately-maintained `empty` flag here was the defect: it was set from `bounds.size`, which counts
+    // overflowed objects too, so removing the last CELLED object while any overflowed object remained
+    // left the flag false and the min/max range stale — and this walk then stepped across that stale
+    // range, unbounded, with no cells left to find. Deriving the fact removes the class: there is no
+    // longer a flag that can disagree with the structure it describes, at any transition.
+    if (grid.cells.size === 0)
+        return;
     const boxMinX = grid.minCellX * cs;
     const boxMinY = grid.minCellY * cs;
     const boxMaxX = (grid.maxCellX + 1) * cs;
@@ -316,12 +507,25 @@ function _queryGridRay(grid, ox, oy, dx, dy, out) {
 }
 // Gathers the ids in every cell the region covers (deduplicated via the reused scratch set), then
 // confirms each against the region's real bounds — so a false cell-mate whose bounds miss the region
-// is dropped.
+// is dropped. Overflowed objects hold no cell and are tested directly.
+//
+// The region is caller-supplied, so it carries the same unbounded-walk hazard the insert bound closes
+// and needs its own guard: a query region wider than the world costs extent ÷ cellSize squared cell
+// lookups against a grid that may hold one object. When the region spans more cells than the grid has
+// occupied, walking the objects is both cheaper and exact, so the walk flips — a region query is
+// never more expensive than a full scan.
 function _queryGridRegion(grid, region, out) {
     out.length = 0;
     const cs = grid.cellSize;
     const seen = grid.seen;
     seen.clear();
+    if (!(_spannedCellCount(cs, region) <= grid.cells.size)) {
+        for (const [id, bounds] of grid.bounds) {
+            if (_isSpatialAabbOverlapping(bounds, region))
+                out.push(id);
+        }
+        return;
+    }
     const cx0 = _cellIndex(region.minX, cs);
     const cx1 = _cellIndex(region.maxX, cs);
     const cy0 = _cellIndex(region.minY, cs);
@@ -341,7 +545,26 @@ function _queryGridRegion(grid, region, out) {
             }
         }
     }
+    for (const id of grid.overflow) {
+        const bounds = grid.bounds.get(id);
+        if (bounds !== undefined && _isSpatialAabbOverlapping(bounds, region))
+            out.push(id);
+    }
+}
+// How many cells an AABB's span covers, as a count rather than a walk — the number the per-object
+// budget is compared against, computed before any cell is touched. Returns NaN for bounds or a cell
+// size that make the cell indices non-finite; callers test it with a negated `<=` so NaN falls to the
+// bounded path rather than through it.
+function _spannedCellCount(cellSize, aabb) {
+    const cx0 = _cellIndex(aabb.minX, cellSize);
+    const cx1 = _cellIndex(aabb.maxX, cellSize);
+    const cy0 = _cellIndex(aabb.minY, cellSize);
+    const cy1 = _cellIndex(aabb.maxY, cellSize);
+    return (cx1 - cx0 + 1) * (cy1 - cy0 + 1);
 }
+// Diagnostics seam filled by setSpatialIndexingGuard. Caller-facing text stays in the separate
+// formatSpatialIndexingNotice module, so production pays only the null checks at noteworthy sites.
+let _indexingGuard = null;
 // Reused scratch rectangles for the geometry overlap/containment helpers. Only ever read+written
 // within a single non-nested helper call, so sharing them across the module allocates nothing per
 // query without aliasing hazard.