Files
aevolution/docs/architecture/SPATIAL_CONTRACT.md
T

2.9 KiB

Local spatial contract

M1.7 implements ADR-0023.

// 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. 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.