# Local spatial contract M1.7 implements [ADR-0023](../adr/0023-local-neighborhood-queries.md). ```cpp // include/evo/simulation/spatial.hpp auto ids = evo::query_neighbors(world, center, evo::Millimetres{16}); ``` | Input/result | Contract | |---|---| | Frame | Existing synthetic 2D torus, coordinates 0 through 1023 mm per axis | | Center | Out-of-domain coordinates return `Error::invalid_position`, even for an empty world | | Radius | Unsigned millimetres, zero through UINT32_MAX; no silent clamp or rejected large radius | | Geometry | Shortest periodic Euclidean distance; equality with radius is included | | Identity | Ascending unique IDs; coincident entities all included; caller explicitly excludes self if needed | | Lifetime | Returned vector owns IDs, not entity references; later removal may invalidate an identity | | Mutation | No state, tick, PRNG, snapshot or input changes; no clock/I/O/dependency | | Concurrency | Owner provides a stable world for the duration of the call | For each axis, `d = min(abs(a-b), 1024-abs(a-b))`; membership is `dx*dx + dy*dy <= radius*radius`, evaluated in u64. Maximum squared distance is 524,288. Thus radius 725 includes the entire domain; radius 724 can exclude the diagonal antipode. Exactly opposite points have an ambiguous direction but a unique distance; this API deliberately does not return displacement vectors. The scan observes current rows on each call, so scheduled creates/removals, movement and restored state need no invalidation hook. Snapshots serialize only authoritative state. Future indexes must preserve this query contract and measure update/rebuild costs, not just warm query timings. Cross-region ghosts and senses require separate ownership/perception contracts before integration. `evo-spatial-benchmark` reports seeded uniform and clustered worlds, 1k/10k/100k entities, 128 queries, radii 0/16/128/725, one warmup and three measured samples. Every result contributes to a checksum. Timing includes allocation/destruction, excludes world/query construction, and has no portable pass/fail threshold. Timing also includes result checksumming. This is a baseline measurement, not an index comparison or an MMO capacity claim. Windows MSVC 19.44 Release on Ryzen 7 9800X3D (uncontrolled desktop, 2026-09-19): median milliseconds for 128 queries over 100,000 entities: | Radius (mm) | Uniform | Clustered | |---|---:|---:| | 0 | 13.60 | 14.18 | | 16 | 17.73 | 59.31 | | 128 | 19.48 | 48.53 | | 725 | 53.35 | 48.36 | Raw three-sample results and compiler metadata are in [spatial-msvc1944.jsonl](../engineering/results/spatial-msvc1944.jsonl). Clustered query centers are inside the same 32 mm patch as the entities; uniform centers span the entire domain. Dense result allocation/checksumming matters as well as scanning. This does not justify querying all 100,000 entities every tick; measure an index against this baseline when interaction frequency is known. GCC 14.2 Release in Gitea run 1409 produced identical checksums and match counts for all 72 samples; raw output is retained in [spatial-gcc142.jsonl](../engineering/results/spatial-gcc142.jsonl). At 100,000 entities the corresponding Linux medians were 62.22/48.97/61.35/90.19 ms for uniform and 36.42/139.94/77.52/76.47 ms for clustered scenarios (radii in the table's order). Runner CPU allocation was not captured; these are within-runner observations, not a cross-platform performance comparison.